> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# topk_sdk

## Classes

### Client

Client for interacting with the TopK API. For available regions see [regions](/regions)

**Methods**

**Constructor**

```python theme={null}
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`](#retryconfig) \| dict\[str, Any]] |

#### collection()

```python theme={null}
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`](#collectionclient)

***

#### collections()

```python theme={null}
collections(self) -> CollectionsClient
```

Get a client for managing collections.

**Returns**

[`CollectionsClient`](#collectionsclient)

***

### AsyncClient

Async client for interacting with the TopK API. For available regions see [regions](/regions)

**Methods**

**Constructor**

```python theme={null}
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`](#retryconfig) \| dict\[str, Any]] |

#### collection()

```python theme={null}
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`](#asynccollectionclient)

***

#### collections()

```python theme={null}
collections(self) -> AsyncCollectionsClient
```

Get an async client for managing collections.

**Returns**

[`AsyncCollectionsClient`](#asynccollectionsclient)

***

### CollectionClient

Synchronous client for collection operations.

**Methods**

#### get()

```python theme={null}
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`](#consistencylevel) \| Literal\['indexed', 'strong']] |

**Returns**

dict\[str, dict\[str, Any]]

***

#### count()

```python theme={null}
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`](#consistencylevel) \| Literal\['indexed', 'strong']] |

**Returns**

int

***

#### query()

```python theme={null}
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`](/sdk/topk-py/query#query)                                           |
| `lsn`         | Optional\[str]                                                                      |
| `consistency` | Optional\[[`ConsistencyLevel`](#consistencylevel) \| Literal\['indexed', 'strong']] |

**Returns**

list\[dict\[str, Any]]

***

#### upsert()

```python theme={null}
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()

```python theme={null}
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()

```python theme={null}
delete(self, expr: Sequence[str] | query.LogicalExpr) -> str
```

Delete documents by their IDs or using a filter expression.

**Example:**

Delete documents by their IDs:

```python theme={null}
client.collection("books").delete(["id_1", "id_2"])
```

Delete documents by a filter expression:

```python theme={null}
from topk_sdk.query import field

client.collection("books").delete(field("published_year").gt(1997))
```

**Parameters**

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `expr`    | Sequence\[str] \| [`query.LogicalExpr`](/sdk/topk-py/query#logicalexpr) |

**Returns**

str

***

#### list\_partitions()

```python theme={null}
list_partitions(self, prefix: Optional[str] = None) -> PartitionListIterator
```

List partitions in the collection as an iterator.

**Parameters**

| Parameter | Type           |
| --------- | -------------- |
| `prefix`  | Optional\[str] |

**Returns**

[`PartitionListIterator`](#partitionlistiterator)

***

#### delete\_partition()

```python theme={null}
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()

```python theme={null}
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`](#consistencylevel) \| Literal\['indexed', 'strong']] |

**Returns**

Awaitable\[dict\[str, dict\[str, Any]]]

***

#### count()

```python theme={null}
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`](#consistencylevel) \| Literal\['indexed', 'strong']] |

**Returns**

Awaitable\[int]

***

#### query()

```python theme={null}
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`](/sdk/topk-py/query#query)                                           |
| `lsn`         | Optional\[str]                                                                      |
| `consistency` | Optional\[[`ConsistencyLevel`](#consistencylevel) \| Literal\['indexed', 'strong']] |

**Returns**

Awaitable\[list\[dict\[str, Any]]]

***

#### upsert()

```python theme={null}
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()

```python theme={null}
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()

```python theme={null}
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:

```python theme={null}
await client.collection("books").delete(["id_1", "id_2"])
```

Delete documents by a filter expression:

```python theme={null}
from topk_sdk.query import field

await client.collection("books").delete(field("published_year").gt(1997))
```

**Parameters**

| Parameter | Type                                                                    |
| --------- | ----------------------------------------------------------------------- |
| `expr`    | Sequence\[str] \| [`query.LogicalExpr`](/sdk/topk-py/query#logicalexpr) |

**Returns**

Awaitable\[str]

***

#### list\_partitions()

```python theme={null}
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`](#asyncpartitionlistiterator)

***

#### delete\_partition()

```python theme={null}
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`](/sdk/topk-py/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()

```python theme={null}
get(self, collection_name: str) -> Collection
```

Get information about a specific collection.

**Parameters**

| Parameter         | Type |
| ----------------- | ---- |
| `collection_name` | str  |

**Returns**

[`Collection`](#collection)

***

#### list()

```python theme={null}
list(self) -> list[Collection]
```

List all collections.

**Returns**

list\[[`Collection`](#collection)]

***

#### create()

```python theme={null}
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`](/sdk/topk-py/schema#schemafieldspec)] |

**Returns**

[`Collection`](#collection)

***

#### delete()

```python theme={null}
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()

```python theme={null}
get(self, collection_name: str) -> Awaitable[Collection]
```

Get information about a specific collection asynchronously.

**Parameters**

| Parameter         | Type |
| ----------------- | ---- |
| `collection_name` | str  |

**Returns**

Awaitable\[[`Collection`](#collection)]

***

#### list()

```python theme={null}
list(self) -> Awaitable[list[Collection]]
```

List all collections asynchronously.

**Returns**

Awaitable\[list\[[`Collection`](#collection)]]

***

#### create()

```python theme={null}
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`](/sdk/topk-py/schema#schemafieldspec)] |

**Returns**

Awaitable\[[`Collection`](#collection)]

***

#### delete()

```python theme={null}
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`](#consistencylevel) |   |
| `Strong`  | [`ConsistencyLevel`](#consistencylevel) |   |

### 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](/sdk/topk-py/error#slowdownerror).
2. 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`](#backoffconfig)] | The backoff configuration for the client.                                                           |

**Methods**

**Constructor**

```python theme={null}
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)] |

### 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**

```python theme={null}
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] |