Typesense Python Client

Install the typesense package using pip:

$ pip install typesense

Alternatively, you can add typesense to your project's requirements.txt file.

A successful search returns a SearchResponse containing:

• found: Total number of documents matching the query.
• hits: A list of Hit objects containing the document, highlights, and text_match_info.
• facet_counts: A list of SearchResponseFacetCountSchema providing counts and statistics for faceted fields.
• grouped_hits: If group_by was used, this contains GroupedHit objects.
• search_time_ms: Time taken for the search.
• page: The current page number.
• out_of: Total documents available in the dataset.
• parsed_nl_query: (Optional) Details if natural language processing was used.

The AsyncClient provides access to various specialized components for managing different aspects of Typesense. Key attributes include:

• collections: Manage collections and documents.
• multi_search: Perform multi-search operations.
• keys: Manage API keys.
• aliases: Manage collection aliases.
• analytics: Perform analytics operations (v30+).
• stemming: Manage stemming dictionary operations.
• stopwords: Manage stopwords.
• synonym_sets: Manage synonym sets.
• metrics: Retrieve system and Typesense metrics.
• curation_sets: Manage Curation Sets (v30+).
• conversations_models: Manage conversation models.
• nl_search_models: Manage natural language search models.
• operations: Perform various Typesense operations.
• debug: Access debug operations.

A curation rule defines the criteria used to trigger a curation item. A rule must be exactly one of the following three types:

1. Tags-based rule: Uses a list of tags.
   • Key: tags (List of strings)
2. Query-based rule: Uses a search query and a match mode.
   • Keys: query (string) and match (literal 'exact' or 'contains')
3. Filter-based rule: Uses a filter_by expression.
   • Key: filter_by (string)

In the Python client, these are represented by the CurationRuleSchema union type.

# Example of different rule types
tags_rule = {"tags": ["premium", "featured"]}
query_rule = {"query": "iphone", "match": "contains"}
filter_rule = {"filter_by": "category:=[electronics]"}

When working in an asynchronous Python environment (e.g., using asyncio), use the typesense.AsyncClient instead of the standard synchronous client. The AsyncClient requires a configuration dictionary containing the api_key, nodes (a list of host/port/protocol dictionaries), and optional settings like connection_timeout_seconds.

Always ensure you close the client connection using await client.api_call.aclose() to clean up resources.

import asyncio
import typesense


async def main() -> None:
    client = typesense.AsyncClient({
        "api_key": "abcd",
        "nodes": [{"host": "localhost", "port": "8108", "protocol": "http"}],
        "connection_timeout_seconds": 2,
    })

    print(await client.collections.retrieve())
    await client.api_call.aclose()


if __name__ == "__main__":
    asyncio.run(main())

When importing documents, you can control whether the response includes the document content or the document ID by using return_doc and return_id flags.

Import Parameters:

• return_id: Set to True to receive the ID of the imported document.
• return_doc: Set to True to receive the imported document content.
• action: Use create, upsert, update, or emplace (see Document Write Actions).

# Example usage of DocumentImportParameters
import_params = {
    "action": "create",
    "return_doc": True,
    "return_id": True
}

Ensure your typesense-python version is compatible with your running Typesense Server version.

The typed_collection method returns a Collection instance that is typed to a specific DocumentSchema model. This provides better type safety when interacting with documents in that collection.

If the name argument is not provided, the method defaults to using the lowercase name of the model class as the collection name.

class Company(DocumentSchema):
    name: str
    num_employees: int

client = Client(config)
# Returns a Collection[Company] instance
companies_collection = client.typed_collection(model=Company)

The CurationSet class provides an interface for performing asynchronous operations on a specific curation set in Typesense. You can use it to retrieve, create/update (upsert), or delete an entire curation set by its name.

Methods:

• retrieve(): Returns the CurationSetSchema for the set.
• upsert(payload: CurationSetUpsertSchema): Creates or updates the curation set using the provided payload.
• delete(): Deletes the curation set and returns a CurationSetDeleteSchema.

from typesense.sync.curation_set import CurationSet

# Assuming api_call is an initialized ApiCall instance
curation_set = CurationSet(api_call, "my_curation_set")

# Retrieve the set
set_details = await curation_set.retrieve()

# Upsert the set
await curation_set.upsert(payload=my_upsert_payload)

# Delete the set
await curation_set.delete()