Typesense Python Client

Warnings

• gotcha Client config requires 'nodes' as a list — not a URL string or flat host/port keys. Passing a URL string raises TypeError.
  Fix: Always: {'nodes': [{'host': '...', 'port': '8108', 'protocol': 'http'}], 'api_key': '...'}
• gotcha Typesense Cloud uses port 443 and protocol 'https'. Self-hosted defaults to port 8108 and 'http'. Mixing these up causes connection errors.
  Fix: Cloud: port='443', protocol='https'. Self-hosted: port='8108', protocol='http'.
• gotcha Collection schema is required before indexing — Typesense is schema-enforced unlike Elasticsearch. Indexing without creating collection first raises ObjectNotFound.
  Fix: Always call client.collections.create({...}) before indexing documents.
• gotcha document 'id' field must be a string — not an integer. Passing int raises validation error.
  Fix: Always stringify IDs: {'id': str(record_id), ...}
• gotcha AsyncClient (v2.0) requires await client.api_call.aclose() to close connections. Omitting this leaks HTTP connections.
  Fix: await client.api_call.aclose() when done, or use try/finally.
• gotcha Client version should match Typesense server version. Python client v2.0 targets Typesense server v26+. Check compatibility matrix.
  Fix: See https://github.com/typesense/typesense-python for compatibility matrix.

Install

• pip install typesense Python (sync + async)

Imports

• Client (sync)

  import typesense
  
  client = typesense.Client({
      'nodes': [{
          'host': 'localhost',
          'port': '8108',
          'protocol': 'http'
      }],
      'api_key': 'your-api-key',
      'connection_timeout_seconds': 2
  })
  
  # Create collection
  client.collections.create({
      'name': 'products',
      'fields': [
          {'name': 'name', 'type': 'string'},
          {'name': 'price', 'type': 'float'}
      ],
      'default_sorting_field': 'price'
  })
  
  # Index document
  client.collections['products'].documents.create({
      'id': '1',
      'name': 'Widget',
      'price': 9.99
  })
  
  # Search
  result = client.collections['products'].documents.search({
      'q': 'widget',
      'query_by': 'name'
  })

  Client takes a config dict with a 'nodes' list — not a URL string. nodes is always a list even for single-node setups.
• AsyncClient (v2.0+)

  import typesense
  import asyncio
  
  async def main():
      client = typesense.AsyncClient({
          'nodes': [{
              'host': 'localhost',
              'port': '8108',
              'protocol': 'http'
          }],
          'api_key': 'your-api-key',
          'connection_timeout_seconds': 2
      })
      result = await client.collections.retrieve()
      await client.api_call.aclose()  # must close
      return result
  
  asyncio.run(main())

  AsyncClient added in v2.0. Must call await client.api_call.aclose() when done to close HTTP connections.

Quickstart

Typesense Python client — collection creation, indexing, and search.

# pip install typesense
import typesense

# Self-hosted
client = typesense.Client({
    'nodes': [{'host': 'localhost', 'port': '8108', 'protocol': 'http'}],
    'api_key': 'your-api-key',
    'connection_timeout_seconds': 2
})

# Typesense Cloud
# client = typesense.Client({
#     'nodes': [{'host': 'xxx.a1.typesense.net', 'port': '443', 'protocol': 'https'}],
#     'api_key': 'your-cloud-api-key',
#     'connection_timeout_seconds': 2
# })

# Create collection with schema
client.collections.create({
    'name': 'books',
    'fields': [
        {'name': 'title', 'type': 'string'},
        {'name': 'author', 'type': 'string', 'facet': True},
        {'name': 'year', 'type': 'int32'}
    ]
})

# Index
client.collections['books'].documents.create({
    'id': '1', 'title': 'Dune', 'author': 'Herbert', 'year': 1965
})

# Search
result = client.collections['books'].documents.search({
    'q': 'dune',
    'query_by': 'title,author'
})
print(result['hits'])