> ## 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) -> CollectionClient
```

Get a client for managing data operations on a specific collection such as querying, upserting, and deleting documents.

**Parameters**

| Parameter    | Type |
| ------------ | ---- |
| `collection` | str  |

**Returns**

[`CollectionClient`](#collectionclient)

***

#### collections()

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

Get a client for managing collections.

**Returns**

[`CollectionsClient`](#collectionsclient)

***

#### dataset()

```python theme={null}
dataset(self, dataset: str) -> DatasetClient
```

Get a client for managing data operations on a specific dataset such as upserting files, managing metadata, and deleting files.

**Parameters**

| Parameter | Type |
| --------- | ---- |
| `dataset` | str  |

**Returns**

[`DatasetClient`](#datasetclient)

***

#### datasets()

```python theme={null}
datasets(self) -> DatasetsClient
```

Get a client for managing datasets.

**Returns**

[`DatasetsClient`](#datasetsclient)

***

#### ask()

```python theme={null}
ask(
   self,
   query: str,
   datasets: Sequence[Source] | Sequence[str] | Sequence[dict[str, Any]],
   filter: Optional[query.LogicalExpr] = None,
   mode: Optional[Literal['auto', 'summarize', 'research']] = None,
   select_fields: Optional[Sequence[str]] = None
)
```

Ask a question and get streaming responses as an iterator.

**Parameters**

| Parameter       | Type                                                                           |
| --------------- | ------------------------------------------------------------------------------ |
| `query`         | str                                                                            |
| `datasets`      | Sequence\[[`Source`](#source)] \| Sequence\[str] \| Sequence\[dict\[str, Any]] |
| `filter`        | Optional\[[`query.LogicalExpr`](/sdk/topk-py/query#logicalexpr)]               |
| `mode`          | Optional\[Literal\['auto', 'summarize', 'research']]                           |
| `select_fields` | Optional\[Sequence\[str]]                                                      |

**Returns**

[`AskIterator`](#askiterator)

***

#### search()

```python theme={null}
search(
   self,
   query: str,
   datasets: Sequence[Source] | Sequence[str] | Sequence[dict[str, Any]],
   top_k: int,
   filter: Optional[query.LogicalExpr] = None,
   select_fields: Optional[Sequence[str]] = None
)
```

Search for documents and get streaming responses as an iterator.

**Parameters**

| Parameter       | Type                                                                           |
| --------------- | ------------------------------------------------------------------------------ |
| `query`         | str                                                                            |
| `datasets`      | Sequence\[[`Source`](#source)] \| Sequence\[str] \| Sequence\[dict\[str, Any]] |
| `top_k`         | int                                                                            |
| `filter`        | Optional\[[`query.LogicalExpr`](/sdk/topk-py/query#logicalexpr)]               |
| `select_fields` | Optional\[Sequence\[str]]                                                      |

**Returns**

[`SearchIterator`](#searchiterator)

***

### 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) -> AsyncCollectionClient
```

Get an async client for a specific collection.

**Parameters**

| Parameter    | Type |
| ------------ | ---- |
| `collection` | str  |

**Returns**

[`AsyncCollectionClient`](#asynccollectionclient)

***

#### collections()

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

Get an async client for managing collections.

**Returns**

[`AsyncCollectionsClient`](#asynccollectionsclient)

***

#### dataset()

```python theme={null}
dataset(self, dataset: str) -> AsyncDatasetClient
```

Get an async client for managing data operations on a specific dataset.

**Parameters**

| Parameter | Type |
| --------- | ---- |
| `dataset` | str  |

**Returns**

[`AsyncDatasetClient`](#asyncdatasetclient)

***

#### datasets()

```python theme={null}
datasets(self) -> AsyncDatasetsClient
```

Get an async client for managing datasets.

**Returns**

[`AsyncDatasetsClient`](#asyncdatasetsclient)

***

#### ask()

```python theme={null}
ask(
   self,
   query: str,
   datasets: Sequence[Source] | Sequence[str] | Sequence[dict[str, Any]],
   filter: Optional[query.LogicalExpr] = None,
   mode: Optional[Literal['auto', 'summarize', 'research']] = None,
   select_fields: Optional[Sequence[str]] = None
)
```

Ask a question and get streaming responses asynchronously as an async iterator.

**Parameters**

| Parameter       | Type                                                                           |
| --------------- | ------------------------------------------------------------------------------ |
| `query`         | str                                                                            |
| `datasets`      | Sequence\[[`Source`](#source)] \| Sequence\[str] \| Sequence\[dict\[str, Any]] |
| `filter`        | Optional\[[`query.LogicalExpr`](/sdk/topk-py/query#logicalexpr)]               |
| `mode`          | Optional\[Literal\['auto', 'summarize', 'research']]                           |
| `select_fields` | Optional\[Sequence\[str]]                                                      |

**Returns**

[`AsyncAskIterator`](#asyncaskiterator)

***

#### search()

```python theme={null}
search(
   self,
   query: str,
   datasets: Sequence[Source] | Sequence[str] | Sequence[dict[str, Any]],
   top_k: int,
   filter: Optional[query.LogicalExpr] = None,
   select_fields: Optional[Sequence[str]] = None
)
```

Search for documents and get streaming responses asynchronously as an async iterator.

**Parameters**

| Parameter       | Type                                                                           |
| --------------- | ------------------------------------------------------------------------------ |
| `query`         | str                                                                            |
| `datasets`      | Sequence\[[`Source`](#source)] \| Sequence\[str] \| Sequence\[dict\[str, Any]] |
| `top_k`         | int                                                                            |
| `filter`        | Optional\[[`query.LogicalExpr`](/sdk/topk-py/query#logicalexpr)]               |
| `select_fields` | Optional\[Sequence\[str]]                                                      |

**Returns**

[`AsyncSearchIterator`](#asyncsearchiterator)

***

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

***

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

***

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

### Dataset

Represents a dataset in the TopK system.

**Properties**

| Property      | Type           |   |
| ------------- | -------------- | - |
| `name`        | str            |   |
| `description` | Optional\[str] |   |
| `org_id`      | str            |   |
| `project_id`  | str            |   |
| `region`      | str            |   |
| `created_at`  | str            |   |

### ListEntry

Entry in a dataset.

**Properties**

| Property        | Type            |   |
| --------------- | --------------- | - |
| `id`            | str             |   |
| `name`          | str             |   |
| `size`          | int             |   |
| `mime_type`     | str             |   |
| `status`        | str             |   |
| `status_reason` | Optional\[str]  |   |
| `metadata`      | dict\[str, Any] |   |

### 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.FieldSpec]) -> Collection
```

Create a new collection with the specified schema.

**Parameters**

| Parameter         | Type                                                               |
| ----------------- | ------------------------------------------------------------------ |
| `collection_name` | str                                                                |
| `schema`          | Mapping\[str, [`schema.FieldSpec`](/sdk/topk-py/schema#fieldspec)] |

**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.FieldSpec]) -> Awaitable[Collection]
```

Create a new collection with the specified schema asynchronously.

**Parameters**

| Parameter         | Type                                                               |
| ----------------- | ------------------------------------------------------------------ |
| `collection_name` | str                                                                |
| `schema`          | Mapping\[str, [`schema.FieldSpec`](/sdk/topk-py/schema#fieldspec)] |

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

***

### DatasetsClient

Synchronous client for managing datasets.

**Methods**

#### get()

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

Get information about a specific dataset.

**Parameters**

| Parameter      | Type |
| -------------- | ---- |
| `dataset_name` | str  |

**Returns**

[`Dataset`](#dataset)

***

#### list()

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

List all datasets.

**Returns**

list\[[`Dataset`](#dataset)]

***

#### create()

```python theme={null}
create(self, dataset_name: str, description: Optional[str] = None) -> Dataset
```

Create a new dataset.

**Parameters**

| Parameter      | Type           |
| -------------- | -------------- |
| `dataset_name` | str            |
| `description`  | Optional\[str] |

**Returns**

[`Dataset`](#dataset)

***

#### update()

```python theme={null}
update(self, dataset_name: str, description: Optional[str] = None) -> Dataset
```

Update dataset properties.

**Parameters**

| Parameter      | Type           |
| -------------- | -------------- |
| `dataset_name` | str            |
| `description`  | Optional\[str] |

**Returns**

[`Dataset`](#dataset)

***

#### delete()

```python theme={null}
delete(self, dataset_name: str) -> None
```

Delete a dataset.

**Parameters**

| Parameter      | Type |
| -------------- | ---- |
| `dataset_name` | str  |

**Returns**

None

***

### DatasetClient

Synchronous client for dataset operations.

**Methods**

#### upsert\_file()

```python theme={null}
upsert_file(
   self,
   doc_id: str,
   input: os.PathLike[Any] | Tuple[str, bytes, str],
   metadata: Mapping[str, Any]
)
```

Upsert a file to the dataset. Returns the processing handle.

**Parameters**

| Parameter  | Type                                         |
| ---------- | -------------------------------------------- |
| `doc_id`   | str                                          |
| `input`    | os.PathLike\[Any] \| Tuple\[str, bytes, str] |
| `metadata` | Mapping\[str, Any]                           |

**Returns**

str

***

#### get\_metadata()

```python theme={null}
get_metadata(
   self,
   ids: Sequence[str],
   fields: Optional[Sequence[str]] = None
)
```

Get metadata for one or more documents.

**Parameters**

| Parameter | Type                      |
| --------- | ------------------------- |
| `ids`     | Sequence\[str]            |
| `fields`  | Optional\[Sequence\[str]] |

**Returns**

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

***

#### update\_metadata()

```python theme={null}
update_metadata(self, doc_id: str, metadata: Mapping[str, Any]) -> str
```

Update metadata for a file. Returns the processing handle.

**Parameters**

| Parameter  | Type               |
| ---------- | ------------------ |
| `doc_id`   | str                |
| `metadata` | Mapping\[str, Any] |

**Returns**

str

***

#### delete()

```python theme={null}
delete(self, doc_id: str) -> str
```

Delete a file from the dataset. Returns the processing handle.

**Parameters**

| Parameter | Type |
| --------- | ---- |
| `doc_id`  | str  |

**Returns**

str

***

#### check\_handle()

```python theme={null}
check_handle(self, handle: str) -> bool
```

Return whether the handle has been processed.

**Parameters**

| Parameter | Type |
| --------- | ---- |
| `handle`  | str  |

**Returns**

bool

***

#### wait\_for\_handle()

```python theme={null}
wait_for_handle(self, handle: str, config: Optional[WaitConfig | dict[str, Any]] = None) -> None
```

Poll until a handle has been processed or the timeout is reached.

Raises an error if the handle is not processed within the configured timeout.

**Parameters**

| Parameter | Type                                                      |
| --------- | --------------------------------------------------------- |
| `handle`  | str                                                       |
| `config`  | Optional\[[`WaitConfig`](#waitconfig) \| dict\[str, Any]] |

**Returns**

None

***

#### list()

```python theme={null}
list(
   self,
   fields: Optional[Sequence[str]] = None,
   filter: Optional[query.LogicalExpr] = None
)
```

List files in the dataset as a streaming iterator.

**Parameters**

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

**Returns**

[`DatasetListIterator`](#datasetlistiterator)

***

### AsyncDatasetsClient

Asynchronous client for managing datasets.

**Methods**

#### get()

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

Get information about a specific dataset asynchronously.

**Parameters**

| Parameter      | Type |
| -------------- | ---- |
| `dataset_name` | str  |

**Returns**

Awaitable\[[`Dataset`](#dataset)]

***

#### list()

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

List all datasets asynchronously.

**Returns**

Awaitable\[list\[[`Dataset`](#dataset)]]

***

#### create()

```python theme={null}
create(self, dataset_name: str, description: Optional[str] = None) -> Awaitable[Dataset]
```

Create a new dataset asynchronously.

**Parameters**

| Parameter      | Type           |
| -------------- | -------------- |
| `dataset_name` | str            |
| `description`  | Optional\[str] |

**Returns**

Awaitable\[[`Dataset`](#dataset)]

***

#### update()

```python theme={null}
update(self, dataset_name: str, description: Optional[str] = None) -> Awaitable[Dataset]
```

Update dataset properties.

**Parameters**

| Parameter      | Type           |
| -------------- | -------------- |
| `dataset_name` | str            |
| `description`  | Optional\[str] |

**Returns**

Awaitable\[[`Dataset`](#dataset)]

***

#### delete()

```python theme={null}
delete(self, dataset_name: str) -> Awaitable[None]
```

Delete a dataset asynchronously.

**Parameters**

| Parameter      | Type |
| -------------- | ---- |
| `dataset_name` | str  |

**Returns**

Awaitable\[None]

***

### AsyncDatasetClient

Asynchronous client for dataset operations.

**Methods**

#### upsert\_file()

```python theme={null}
upsert_file(
   self,
   doc_id: str,
   input: os.PathLike[Any] | Tuple[str, bytes, str],
   metadata: Mapping[str, Any]
)
```

Upsert a file to the dataset asynchronously. Returns the processing handle.

**Parameters**

| Parameter  | Type                                         |
| ---------- | -------------------------------------------- |
| `doc_id`   | str                                          |
| `input`    | os.PathLike\[Any] \| Tuple\[str, bytes, str] |
| `metadata` | Mapping\[str, Any]                           |

**Returns**

Awaitable\[str]

***

#### get\_metadata()

```python theme={null}
get_metadata(
   self,
   ids: Sequence[str],
   fields: Optional[Sequence[str]] = None
)
```

Get metadata for one or more documents asynchronously.

**Parameters**

| Parameter | Type                      |
| --------- | ------------------------- |
| `ids`     | Sequence\[str]            |
| `fields`  | Optional\[Sequence\[str]] |

**Returns**

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

***

#### update\_metadata()

```python theme={null}
update_metadata(self, doc_id: str, metadata: Mapping[str, Any]) -> Awaitable[str]
```

Update metadata for a file asynchronously. Returns the processing handle.

**Parameters**

| Parameter  | Type               |
| ---------- | ------------------ |
| `doc_id`   | str                |
| `metadata` | Mapping\[str, Any] |

**Returns**

Awaitable\[str]

***

#### delete()

```python theme={null}
delete(self, doc_id: str) -> Awaitable[str]
```

Delete a file from the dataset asynchronously. Returns the processing handle.

**Parameters**

| Parameter | Type |
| --------- | ---- |
| `doc_id`  | str  |

**Returns**

Awaitable\[str]

***

#### check\_handle()

```python theme={null}
check_handle(self, handle: str) -> Awaitable[bool]
```

Return whether the handle has been processed asynchronously.

**Parameters**

| Parameter | Type |
| --------- | ---- |
| `handle`  | str  |

**Returns**

Awaitable\[bool]

***

#### wait\_for\_handle()

```python theme={null}
wait_for_handle(
   self,
   handle: str,
   config: Optional[WaitConfig | dict[str, Any]] = None
)
```

Poll until a handle has been processed or the timeout is reached asynchronously.

Raises an error if the handle is not processed within the configured timeout.

**Parameters**

| Parameter | Type                                                      |
| --------- | --------------------------------------------------------- |
| `handle`  | str                                                       |
| `config`  | Optional\[[`WaitConfig`](#waitconfig) \| dict\[str, Any]] |

**Returns**

Awaitable\[None]

***

#### list()

```python theme={null}
list(
   self,
   fields: Optional[Sequence[str]] = None,
   filter: Optional[query.LogicalExpr] = None
)
```

List files in the dataset as a streaming async iterator.

**Parameters**

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

**Returns**

[`AsyncDatasetListIterator`](#asyncdatasetlistiterator)

***

### Source

Represents a dataset with an optional filter.

**Properties**

| Property  | Type                                                             |   |
| --------- | ---------------------------------------------------------------- | - |
| `dataset` | str                                                              |   |
| `filter`  | Optional\[[`query.LogicalExpr`](/sdk/topk-py/query#logicalexpr)] |   |

### Fact

Represents a fact in an ask response.

**Properties**

| Property  | Type       |   |
| --------- | ---------- | - |
| `fact`    | str        |   |
| `ref_ids` | list\[str] |   |

### Chunk

Text chunk content.

**Properties**

| Property    | Type       |   |
| ----------- | ---------- | - |
| `text`      | str        |   |
| `doc_pages` | list\[int] |   |

### Image

Image content.

**Properties**

| Property    | Type  |   |
| ----------- | ----- | - |
| `data`      | bytes |   |
| `mime_type` | str   |   |

### Page

Page content with optional image.

**Properties**

| Property      | Type                         |   |
| ------------- | ---------------------------- | - |
| `page_number` | int                          |   |
| `image`       | Optional\[[`Image`](#image)] |   |

### Content

Content in a search result. One of chunk, page, or image.

**Properties**

| Property | Type                                                      |   |
| -------- | --------------------------------------------------------- | - |
| `type`   | Literal\['chunk', 'page', 'image']                        |   |
| `data`   | [`Chunk`](#chunk) \| [`Page`](#page) \| [`Image`](#image) |   |

### SearchResult

Represents a search result in an ask response.

**Properties**

| Property     | Type                             |   |
| ------------ | -------------------------------- | - |
| `doc_id`     | str                              |   |
| `doc_type`   | str                              |   |
| `dataset`    | str                              |   |
| `content_id` | str                              |   |
| `doc_name`   | str                              |   |
| `content`    | Optional\[[`Content`](#content)] |   |
| `metadata`   | dict\[str, Any]                  |   |

### Answer

Represents a final answer in an ask response.

**Properties**

| Property     | Type                                        |   |
| ------------ | ------------------------------------------- | - |
| `facts`      | list\[[`Fact`](#fact)]                      |   |
| `refs`       | dict\[str, [`SearchResult`](#searchresult)] |   |
| `confidence` | float                                       |   |

### Progress

Represents a progress update in an ask response.

**Properties**

| Property | Type |   |
| -------- | ---- | - |
| `update` | str  |   |

### AskIterator

Iterator for synchronous ask responses.

### AsyncAskIterator

Iterator for asynchronous ask responses.

### SearchIterator

Iterator for synchronous search responses.

### AsyncSearchIterator

Iterator for asynchronous search responses.

### DatasetListIterator

Iterator for synchronous dataset list responses.

### AsyncDatasetListIterator

Iterator for asynchronous dataset list responses.

### ConsistencyLevel

Consistency level for read operations.

**Properties**

| Property  | Type                                    |   |
| --------- | --------------------------------------- | - |
| `Indexed` | [`ConsistencyLevel`](#consistencylevel) |   |
| `Strong`  | [`ConsistencyLevel`](#consistencylevel) |   |

### WaitConfig

Configuration for polling when waiting for a handle to be processed.

**Properties**

| Property         | Type           |                                                                                   |
| ---------------- | -------------- | --------------------------------------------------------------------------------- |
| `frequency_secs` | Optional\[int] | How often to poll for the handle status in seconds. Default is 5.                 |
| `timeout_secs`   | Optional\[int] | Maximum time to wait before returning a timeout error in seconds. Default is 300. |

**Methods**

**Constructor**

```python theme={null}
WaitConfig(frequency_secs: Optional[int] = None, timeout_secs: Optional[int] = None) -> None
```

**Parameters**

| Parameter        | Type           |
| ---------------- | -------------- |
| `frequency_secs` | Optional\[int] |
| `timeout_secs`   | Optional\[int] |

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