topk_sdk - TopK

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

Parameter	Type
`api_key`	str
`region`	str
`host`	str
`https`	bool
`retry_config`	Optional[`RetryConfig` \| dict[str, Any]]

collection()

collection(self, collection: str, partition: Optional[str] = None) -> CollectionClient

Get a client for managing data operations on a specific collection such as querying, upserting, and deleting documents. Optionally, pass partition name to scope data operations to that partition. Parameters

Parameter	Type
`collection`	str
`partition`	Optional[str]

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

Parameter	Type
`api_key`	str
`region`	str
`host`	str
`https`	bool
`retry_config`	Optional[`RetryConfig` \| dict[str, Any]]

collection()

collection(self, collection: str, partition: Optional[str] = None) -> AsyncCollectionClient

Get an async client for a specific collection. Optionally, pass partition name to scope data operations to that partition. Parameters

Parameter	Type
`collection`	str
`partition`	Optional[str]

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 | Literal['indexed', 'strong']] = None
)

Get documents by their IDs. Parameters

Parameter	Type
`ids`	Sequence[str]
`fields`	Optional[Sequence[str]]
`lsn`	Optional[str]
`consistency`	Optional[`ConsistencyLevel` \| Literal[‘indexed’, ‘strong’]]

Returns dict[str, dict[str, Any]]

count()

count(
   self,
   lsn: Optional[str] = None,
   consistency: Optional[ConsistencyLevel | Literal['indexed', 'strong']] = None
)

Get the count of documents in the collection. Parameters

Parameter	Type
`lsn`	Optional[str]
`consistency`	Optional[`ConsistencyLevel` \| Literal[‘indexed’, ‘strong’]]

Returns int

query()

query(
   self,
   query: query.Query,
   lsn: Optional[str] = None,
   consistency: Optional[ConsistencyLevel | Literal['indexed', 'strong']] = None
)

Execute a query against the collection. Parameters

Parameter	Type
`query`	`query.Query`
`lsn`	Optional[str]
`consistency`	Optional[`ConsistencyLevel` \| Literal[‘indexed’, ‘strong’]]

Returns list[dict[str, Any]]

upsert()

upsert(self, documents: Sequence[Mapping[str, Any]]) -> str

Insert or update documents in the collection. Parameters

Parameter	Type
`documents`	Sequence[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

Parameter	Type
`documents`	Sequence[Mapping[str, Any]]
`fail_on_missing`	Optional[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

Parameter	Type
`expr`	Sequence[str] \| `query.LogicalExpr`

Returns str

list_partitions()

list_partitions(self, prefix: Optional[str] = None) -> PartitionListIterator

List partitions in the collection as an iterator. Parameters

Parameter	Type
`prefix`	Optional[str]

Returns PartitionListIterator

delete_partition()

delete_partition(self, name: str) -> None

Delete a partition and all documents within it. Parameters

Parameter	Type
`name`	str

Returns None

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 | Literal['indexed', 'strong']] = None
)

Get documents by their IDs asynchronously. Parameters

Parameter	Type
`ids`	Sequence[str]
`fields`	Optional[Sequence[str]]
`lsn`	Optional[str]
`consistency`	Optional[`ConsistencyLevel` \| Literal[‘indexed’, ‘strong’]]

Returns Awaitable[dict[str, dict[str, Any]]]

count()

count(
   self,
   lsn: Optional[str] = None,
   consistency: Optional[ConsistencyLevel | Literal['indexed', 'strong']] = None
)

Get the count of documents in the collection asynchronously. Parameters

Parameter	Type
`lsn`	Optional[str]
`consistency`	Optional[`ConsistencyLevel` \| Literal[‘indexed’, ‘strong’]]

Returns Awaitable[int]

query()

query(
   self,
   query: query.Query,
   lsn: Optional[str] = None,
   consistency: Optional[ConsistencyLevel | Literal['indexed', 'strong']] = None
)

Execute a query against the collection asynchronously. Parameters

Parameter	Type
`query`	`query.Query`
`lsn`	Optional[str]
`consistency`	Optional[`ConsistencyLevel` \| Literal[‘indexed’, ‘strong’]]

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

Parameter	Type
`documents`	Sequence[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

Parameter	Type
`documents`	Sequence[Mapping[str, Any]]
`fail_on_missing`	Optional[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

Parameter	Type
`expr`	Sequence[str] \| `query.LogicalExpr`

Returns Awaitable[str]

list_partitions()

list_partitions(self, prefix: Optional[str] = None) -> AsyncPartitionListIterator

List partitions in the collection as an async iterator. Parameters

Parameter	Type
`prefix`	Optional[str]

Returns AsyncPartitionListIterator

delete_partition()

delete_partition(self, name: str) -> Awaitable[None]

Delete a partition and all documents within it asynchronously. Parameters

Parameter	Type
`name`	str

Returns Awaitable[None]

Collection

Represents a collection in the TopK system. Properties

Property	Type
`name`	str
`org_id`	str
`project_id`	str
`region`	str
`schema`	dict[str, `schema.FieldSpec`]
`created_at`	str

Partition

Represents a partition in a collection. Properties

Property	Type
`name`	str
`created_at`	str

CollectionsClient

Synchronous client for managing collections. Methods

get()

get(self, collection_name: str) -> Collection

Get information about a specific collection. Parameters

Parameter	Type
`collection_name`	str

Returns Collection

list()

list(self) -> list[Collection]

List all collections. Returns list[Collection]

create()

create(self, collection_name: str, schema: Mapping[str, schema.SchemaFieldSpec]) -> Collection

Create a new collection with the specified schema. Parameters

Parameter	Type
`collection_name`	str
`schema`	Mapping[str, `schema.SchemaFieldSpec`]

Returns Collection

delete()

delete(self, collection_name: str) -> None

Delete a collection. Parameters

Parameter	Type
`collection_name`	str

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

Parameter	Type
`collection_name`	str

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.SchemaFieldSpec]
)

Create a new collection with the specified schema asynchronously. Parameters

Parameter	Type
`collection_name`	str
`schema`	Mapping[str, `schema.SchemaFieldSpec`]

Returns Awaitable[Collection]

delete()

delete(self, collection_name: str) -> Awaitable[None]

Delete a collection asynchronously. Parameters

Parameter	Type
`collection_name`	str

Returns Awaitable[None]

PartitionListIterator

Iterator for synchronous partition list responses.

AsyncPartitionListIterator

Iterator for asynchronous partition list responses.

ConsistencyLevel

Consistency level for read operations. Properties

Property	Type
`Indexed`	`ConsistencyLevel`
`Strong`	`ConsistencyLevel`

RetryConfig

Configuration for retry behavior. By default, retries occur in two situations:

When the server requests the client to reduce its request rate, resulting in a SlowDownError.
When using the query(..., lsn=N) to wait for writes to be available.

Properties

Property	Type
`max_retries`	Optional[int]	Maximum number of retries to attempt. Default is 3 retries.
`timeout`	Optional[int]	The total timetout for the retry chain in milliseconds. Default is 30,000 milliseconds (30 seconds)
`backoff`	Optional[`BackoffConfig`]	The backoff configuration for the client.

Methods Constructor

RetryConfig(
   max_retries: Optional[int] = None,
   timeout: Optional[int] = None,
   backoff: Optional[BackoffConfig] = None
)

Parameters

Parameter	Type
`max_retries`	Optional[int]
`timeout`	Optional[int]
`backoff`	Optional[`BackoffConfig`]

BackoffConfig

Configuration for backoff behavior in retries. Properties

Property	Type
`base`	Optional[int]	The base for the backoff. Default is 2x backoff.
`init_backoff`	Optional[int]	The initial backoff in milliseconds. Default is 100 milliseconds.
`max_backoff`	Optional[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

Parameter	Type
`base`	Optional[int]
`init_backoff`	Optional[int]
`max_backoff`	Optional[int]

​Classes

​Client

​collection()

​collections()

​AsyncClient

​collection()

​collections()

​CollectionClient

​get()

​count()

​query()

​upsert()

​update()

​delete()

​list_partitions()

​delete_partition()

​AsyncCollectionClient

​get()

​count()

​query()

​upsert()

​update()

​delete()

​list_partitions()

​delete_partition()

​Collection

​Partition

​CollectionsClient

​get()

​list()

​create()

​delete()

​AsyncCollectionsClient

​get()

​list()

​create()

​delete()

​PartitionListIterator

​AsyncPartitionListIterator

​ConsistencyLevel

​RetryConfig

​BackoffConfig

Classes

Client

collection()

collections()

AsyncClient

collection()

collections()

CollectionClient

get()

count()

query()

upsert()

update()

delete()

list_partitions()

delete_partition()

AsyncCollectionClient

get()

count()

query()

upsert()

update()

delete()

list_partitions()

delete_partition()

Collection

Partition

CollectionsClient

get()

list()

create()

delete()

AsyncCollectionsClient

get()

list()

create()

delete()

PartitionListIterator

AsyncPartitionListIterator

ConsistencyLevel

RetryConfig

BackoffConfig