Skip to main content

​
Classes

​
Client

Client for interacting with the TopK API. For available regions see regions Methods Constructor 
Client(
   api_key: str,
   region: str,
   host: str = "topk.io",
   https: bool = True,
   retry_config: Optional[RetryConfig | dict[str, Any]] = None
)
Parameters
ParameterType
api_keystr
regionstr
hoststr
httpsbool
retry_configOptional[RetryConfig | dict[str, Any]]

​
collection()

collection(self, collection: str) -> CollectionClient
Get a client for managing data operations on a specific collection such as querying, upserting, and deleting documents. Parameters
ParameterType
collectionstr
Returns CollectionClient

​
collections()

collections(self) -> CollectionsClient
Get a client for managing collections. Returns CollectionsClient

​
AsyncClient

Async client for interacting with the TopK API. For available regions see regions Methods Constructor 
AsyncClient(
   api_key: str,
   region: str,
   host: str = "topk.io",
   https: bool = True,
   retry_config: Optional[RetryConfig | dict[str, Any]] = None
)
Parameters
ParameterType
api_keystr
regionstr
hoststr
httpsbool
retry_configOptional[RetryConfig | dict[str, Any]]

​
collection()

collection(self, collection: str) -> AsyncCollectionClient
Get an async client for a specific collection. Parameters
ParameterType
collectionstr
Returns AsyncCollectionClient

​
collections()

collections(self) -> AsyncCollectionsClient
Get an async client for managing collections. Returns AsyncCollectionsClient

​
CollectionClient

Synchronous client for collection operations. Methods

​
get()

get(
   self,
   ids: Sequence[str],
   fields: Optional[Sequence[str]] = None,
   lsn: Optional[str] = None,
   consistency: Optional[ConsistencyLevel] = None
)
Get documents by their IDs. Parameters
ParameterType
idsSequence[str]
fieldsOptional[Sequence[str]]
lsnOptional[str]
consistencyOptional[ConsistencyLevel]
Returns dict[str, dict[str, Any]]

​
count()

count(self, lsn: Optional[str] = None, consistency: Optional[ConsistencyLevel] = None) -> int
Get the count of documents in the collection. Parameters
ParameterType
lsnOptional[str]
consistencyOptional[ConsistencyLevel]
Returns int

​
query()

query(
   self,
   query: query.Query,
   lsn: Optional[str] = None,
   consistency: Optional[ConsistencyLevel] = None
)
Execute a query against the collection. Parameters
ParameterType
queryquery.Query
lsnOptional[str]
consistencyOptional[ConsistencyLevel]
Returns list[dict[str, Any]]

​
upsert()

upsert(self, documents: Sequence[Mapping[str, Any]]) -> str
Insert or update documents in the collection. Parameters
ParameterType
documentsSequence[Mapping[str, Any]]
Returns str

​
update()

update(self, documents: Sequence[Mapping[str, Any]], fail_on_missing: Optional[bool] = None) -> str
Update documents in the collection. Existing documents will be merged with the provided fields. Missing documents will be ignored. Returns the LSN at which the update was applied. If no updates were applied, this will be empty. Parameters
ParameterType
documentsSequence[Mapping[str, Any]]
fail_on_missingOptional[bool]
Returns str

​
delete()

delete(self, expr: Sequence[str] | query.LogicalExpr) -> str
Delete documents by their IDs or using a filter expression. Example: Delete documents by their IDs: 
client.collection("books").delete(["id_1", "id_2"])
Delete documents by a filter expression: 
from topk_sdk.query import field

client.collection("books").delete(field("published_year").gt(1997))
Parameters
ParameterType
exprSequence[str] | query.LogicalExpr
Returns str

​
AsyncCollectionClient

Asynchronous client for collection operations. Methods

​
get()

get(
   self,
   ids: Sequence[str],
   fields: Optional[Sequence[str]] = None,
   lsn: Optional[str] = None,
   consistency: Optional[ConsistencyLevel] = None
)
Get documents by their IDs asynchronously. Parameters
ParameterType
idsSequence[str]
fieldsOptional[Sequence[str]]
lsnOptional[str]
consistencyOptional[ConsistencyLevel]
Returns Awaitable[dict[str, dict[str, Any]]]

​
count()

count(
   self,
   lsn: Optional[str] = None,
   consistency: Optional[ConsistencyLevel] = None
)
Get the count of documents in the collection asynchronously. Parameters
ParameterType
lsnOptional[str]
consistencyOptional[ConsistencyLevel]
Returns Awaitable[int]

​
query()

query(
   self,
   query: query.Query,
   lsn: Optional[str] = None,
   consistency: Optional[ConsistencyLevel] = None
)
Execute a query against the collection asynchronously. Parameters
ParameterType
queryquery.Query
lsnOptional[str]
consistencyOptional[ConsistencyLevel]
Returns Awaitable[list[dict[str, Any]]]

​
upsert()

upsert(self, documents: Sequence[Mapping[str, Any]]) -> Awaitable[str]
Insert or update documents in the collection asynchronously. Parameters
ParameterType
documentsSequence[Mapping[str, Any]]
Returns Awaitable[str]

​
update()

update(
   self,
   documents: Sequence[Mapping[str, Any]],
   fail_on_missing: Optional[bool] = None
)
Update documents in the collection asynchronously. Existing documents will be merged with the provided fields. Missing documents will be ignored. Returns the LSN at which the update was applied. If no updates were applied, this will be empty. Parameters
ParameterType
documentsSequence[Mapping[str, Any]]
fail_on_missingOptional[bool]
Returns Awaitable[str]

​
delete()

delete(self, expr: Sequence[str] | query.LogicalExpr) -> Awaitable[str]
Delete documents by their IDs or using a filter expression asynchronously. Example: Delete documents by their IDs: 
await client.collection("books").delete(["id_1", "id_2"])
Delete documents by a filter expression: 
from topk_sdk.query import field

await client.collection("books").delete(field("published_year").gt(1997))
Parameters
ParameterType
exprSequence[str] | query.LogicalExpr
Returns Awaitable[str]

​
Collection

Represents a collection in the TopK system. Properties
PropertyType
namestr
org_idstr
project_idstr
regionstr
schemadict[str, schema.FieldSpec]

​
CollectionsClient

Synchronous client for managing collections. Methods

​
get()

get(self, collection_name: str) -> Collection
Get information about a specific collection. Parameters
ParameterType
collection_namestr
Returns Collection

​
list()

list(self) -> list[Collection]
List all collections. Returns list[Collection]

​
create()

create(self, collection_name: str, schema: Mapping[str, schema.FieldSpec]) -> Collection
Create a new collection with the specified schema. Parameters
ParameterType
collection_namestr
schemaMapping[str, schema.FieldSpec]
Returns Collection

​
delete()

delete(self, collection_name: str) -> None
Delete a collection. Parameters
ParameterType
collection_namestr
Returns None

​
AsyncCollectionsClient

Asynchronous client for managing collections. Methods

​
get()

get(self, collection_name: str) -> Awaitable[Collection]
Get information about a specific collection asynchronously. Parameters
ParameterType
collection_namestr
Returns Awaitable[Collection]

​
list()

list(self) -> Awaitable[list[Collection]]
List all collections asynchronously. Returns Awaitable[list[Collection]]

​
create()

create(self, collection_name: str, schema: Mapping[str, schema.FieldSpec]) -> Awaitable[Collection]
Create a new collection with the specified schema asynchronously. Parameters
ParameterType
collection_namestr
schemaMapping[str, schema.FieldSpec]
Returns Awaitable[Collection]

​
delete()

delete(self, collection_name: str) -> Awaitable[None]
Delete a collection asynchronously. Parameters
ParameterType
collection_namestr
Returns Awaitable[None]

​
ConsistencyLevel

Enumeration of consistency levels for operations. Values
ValueDescription
Indexedindexed
Strongstrong

​
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 the query(..., lsn=N) to wait for writes to be available.
Properties
PropertyType
max_retriesOptional[int]Maximum number of retries to attempt. Default is 3 retries.
timeoutOptional[int]The total timetout for the retry chain in milliseconds. Default is 30,000 milliseconds (30 seconds)
backoffOptional[BackoffConfig]The backoff configuration for the client.
Methods Constructor 
RetryConfig(
   max_retries: Optional[int] = None,
   timeout: Optional[int] = None,
   backoff: Optional[BackoffConfig] = None
)
Parameters
ParameterType
max_retriesOptional[int]
timeoutOptional[int]
backoffOptional[BackoffConfig]

​
BackoffConfig

Configuration for backoff behavior in retries. Properties
PropertyType
baseOptional[int]The base for the backoff. Default is 2x backoff.
init_backoffOptional[int]The initial backoff in milliseconds. Default is 100 milliseconds.
max_backoffOptional[int]The maximum backoff in milliseconds. Default is 10,000 milliseconds (10 seconds).
Methods Constructor 
BackoffConfig(
   base: Optional[int] = None,
   init_backoff: Optional[int] = None,
   max_backoff: Optional[int] = None
)
Parameters
ParameterType
baseOptional[int]
init_backoffOptional[int]
max_backoffOptional[int]