Skip to main content

​
Client

The Client class is the main entry point for interacting with the TopK API. Use it to manage collections and perform data operations.

​
Constructor

from topk_sdk import Client

client = Client(
    api_key="YOUR_TOPK_API_KEY",
    region="aws-us-east-1-elastica"
)
​
api_key
str
required
Your TopK API key. Get one from the TopK Console.
​
region
str
required
The region where your data is stored. For available regions, see the regions documentation.
​
host
str
default:"topk.io"
The TopK API host. Typically this should not be changed.
​
https
bool
default:"true"
Whether to use HTTPS for connections.
​
retry_config
RetryConfig | dict
Configuration for retry behavior. See RetryConfig below.

​
Methods

​
collection()

Get a client for managing data operations on a specific collection such as querying, upserting, and deleting documents. 
collection_client = client.collection("books")
​
collection
str
required
The name of the collection to interact with.
​
return
CollectionClient
A client instance for the specified collection.

​
collections()

Get a client for managing collections (create, list, get, delete). 
collections_client = client.collections()
​
return
CollectionsClient
A client instance for managing collections.

​
AsyncClient

Asynchronous client for interacting with the TopK API. All operations return awaitables.

​
Constructor

from topk_sdk import AsyncClient

client = AsyncClient(
    api_key="YOUR_TOPK_API_KEY",
    region="aws-us-east-1-elastica"
)
Parameters are identical to the synchronous Client.

​
Methods

​
collection()

Get an async client for a specific collection. 
collection_client = client.collection("books")
​
collection
str
required
The name of the collection to interact with.
​
return
AsyncCollectionClient
An async client instance for the specified collection.

​
collections()

Get an async client for managing collections. 
collections_client = client.collections()
​
return
AsyncCollectionsClient
An async client instance for managing collections.

​
CollectionClient

Synchronous client for collection operations like querying, upserting, and deleting documents.

​
get()

Get documents by their IDs. 
documents = client.collection("books").get(
    ids=["gatsby", "1984"],
    fields=["title", "author"]
)
​
ids
Sequence[str]
required
List of document IDs to retrieve.
​
fields
Sequence[str]
Optional list of field names to return. If not provided, all fields are returned.
​
lsn
str
Log Sequence Number for consistency. Wait for writes up to this LSN to be available.
​
consistency
ConsistencyLevel
Consistency level for the operation. Can be ConsistencyLevel.Strong or ConsistencyLevel.Indexed.
​
return
dict[str, dict[str, Any]]
A dictionary mapping document IDs to their field values.

​
count()

Get the count of documents in the collection. 
total = client.collection("books").count()
​
lsn
str
Log Sequence Number for consistency.
​
consistency
ConsistencyLevel
Consistency level for the operation.
​
return
int
The number of documents in the collection.

​
query()

Execute a query against the collection. 
from topk_sdk.query import select, field, fn

results = client.collection("books").query(
    select(
        "title",
        similarity=fn.semantic_similarity("title", "classic novel")
    ).topk(field("similarity"), 10)
)
​
query
Query
required
The query to execute. See the Query documentation for details.
​
lsn
str
Log Sequence Number for consistency.
​
consistency
ConsistencyLevel
Consistency level for the operation.
​
return
list[dict[str, Any]]
A list of documents matching the query.

​
upsert()

Insert or update documents in the collection. Each document must have an _id field. 
lsn = client.collection("books").upsert([
    {"_id": "gatsby", "title": "The Great Gatsby", "year": 1925},
    {"_id": "1984", "title": "1984", "year": 1949}
])
​
documents
Sequence[Mapping[str, Any]]
required
List of documents to insert or update. Each document must contain an _id field.
​
return
str
The LSN (Log Sequence Number) at which the upsert was applied.

​
update()

Update documents in the collection. Existing documents will be merged with the provided fields. Missing documents will be ignored. 
lsn = client.collection("books").update(
    [{"_id": "gatsby", "year": 1926}],
    fail_on_missing=False
)
​
documents
Sequence[Mapping[str, Any]]
required
List of documents to update. Each document must contain an _id field.
​
fail_on_missing
bool
If true, the operation fails if any document IDs don’t exist.
​
return
str
The LSN at which the update was applied. If no updates were applied, this will be empty.

​
delete()

Delete documents by their IDs or using a filter expression. 
lsn = client.collection("books").delete(["id_1", "id_2"])
​
expr
Sequence[str] | LogicalExpr
required
Either a list of document IDs to delete, or a filter expression.
​
return
str
The LSN at which the delete was applied.

​
AsyncCollectionClient

Asynchronous client for collection operations. All methods are identical to CollectionClient but return awaitables. 
from topk_sdk import AsyncClient
from topk_sdk.query import select, field, fn

client = AsyncClient(api_key="YOUR_KEY", region="aws-us-east-1-elastica")

# All operations must be awaited
documents = await client.collection("books").get(["gatsby", "1984"])
results = await client.collection("books").query(
    select("title").topk(fn.semantic_similarity("title", "novel"), 10)
)

​
Collection

Represents a collection in the TopK system. Returned by CollectionsClient.get() and CollectionsClient.list().
​
name
str
The name of the collection.
​
org_id
str
The organization ID that owns the collection.
​
project_id
str
The project ID that owns the collection.
​
region
str
The region where the collection is stored.
​
schema
dict[str, FieldSpec]
The schema definition for the collection. See Schema documentation for details.

​
ConsistencyLevel

Enumeration of consistency levels for operations. 
from topk_sdk import ConsistencyLevel

# Use Strong consistency
client.collection("books").get(
    ["id_1"],
    consistency=ConsistencyLevel.Strong
)
​
Strong
ConsistencyLevel
Strong consistency ensures reads reflect all writes acknowledged before the read operation.
​
Indexed
ConsistencyLevel
Indexed consistency ensures reads reflect all indexed writes.

​
RetryConfig

Configuration for retry behavior. By default, retries occur in two situations:
  1. When the server requests the client to reduce its request rate, resulting in a SlowDownError.
  2. When using query(..., lsn=N) to wait for writes to be available.
from topk_sdk import Client, RetryConfig

client = Client(
    api_key="YOUR_KEY",
    region="aws-us-east-1-elastica",
    retry_config=RetryConfig(
        max_retries=5,
        timeout=60000,
        backoff=BackoffConfig(base=2, init_backoff=200)
    )
)
​
max_retries
int
default:"3"
Maximum number of retries to attempt.
​
timeout
int
default:"30000"
The total timeout for the retry chain in milliseconds. Default is 30,000 milliseconds (30 seconds).
​
backoff
BackoffConfig
The backoff configuration for the client. See BackoffConfig below.

​
BackoffConfig

Configuration for backoff behavior in retries. 
from topk_sdk import BackoffConfig

backoff = BackoffConfig(
    base=2,
    init_backoff=100,
    max_backoff=10000
)
​
base
int
default:"2"
The base for the exponential backoff. Default is 2x backoff.
​
init_backoff
int
default:"100"
The initial backoff in milliseconds. Default is 100 milliseconds.
​
max_backoff
int
default:"10000"
The maximum backoff in milliseconds. Default is 10,000 milliseconds (10 seconds).

Build docs developers (and LLMs) love

Get started for freeTalk to us