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

## Classes

### Client

Client for interacting with the TopK API. For available regions see [https://docs.topk.io/regions](https://docs.topk.io/regions)

**Constructors**

**Constructor**

```ts theme={null}
new Client(config: ClientConfig): Client;
```

Creates a new TopK client with the provided configuration.

**Parameters**

| Parameter | Type                                              |
| --------- | ------------------------------------------------- |
| `config`  | [`ClientConfig`](/sdk/topk-js/index#clientconfig) |

**Returns**

[`Client`](/sdk/topk-js/index#client)

**Methods**

##### collection()

```ts theme={null}
collection(name: string, partition?: string): CollectionClient;
```

Returns a client for interacting with a specific collection.

Optionally, pass partition name to scope data operations to that partition.

**Parameters**

| Parameter    | Type     |
| ------------ | -------- |
| `name`       | `string` |
| `partition?` | `string` |

**Returns**

[`CollectionClient`](/sdk/topk-js/index#collectionclient)

##### collections()

```ts theme={null}
collections(): CollectionsClient;
```

Returns a client for managing collections.

This method provides access to collection management operations like creating,
listing, and deleting collections.

**Returns**

[`CollectionsClient`](/sdk/topk-js/index#collectionsclient)

***

### CollectionClient

**`Internal`**

Client for interacting with a specific collection.

This client provides methods to perform operations on a specific collection,
including querying, upserting, and deleting documents.

**Methods**

##### count()

```ts theme={null}
count(options?: QueryOptions): Promise<number>;
```

Counts the number of documents in the collection.

**Parameters**

| Parameter  | Type                                              |
| ---------- | ------------------------------------------------- |
| `options?` | [`QueryOptions`](/sdk/topk-js/index#queryoptions) |

**Returns**

`Promise`\<`number`>

##### delete()

```ts theme={null}
delete(expr: 
  | string[]
| LogicalExpression): Promise<string>;
```

Deletes documents from the collection by their IDs or using a filter expression.

Example:
Delete documents by their IDs:

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

Delete documents by a filter expression:

```javascript theme={null}
import { field } from "topk-js/query";

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

**Parameters**

| Parameter | Type                                                                                    |
| --------- | --------------------------------------------------------------------------------------- |
| `expr`    | \| `string`\[] \| [`LogicalExpression`](/sdk/topk-js/Namespace.query#logicalexpression) |

**Returns**

`Promise`\<`string`>

##### deletePartition()

```ts theme={null}
deletePartition(name: string): Promise<void>;
```

Delete a partition and all documents within it.

**Parameters**

| Parameter | Type     |
| --------- | -------- |
| `name`    | `string` |

**Returns**

`Promise`\<`void`>

##### get()

```ts theme={null}
get(
   ids: string[], 
   fields?: string[], 
options?: QueryOptions): Promise<Record<string, Record<string, any>>>;
```

Retrieves documents by their IDs.

**Parameters**

| Parameter  | Type                                              |
| ---------- | ------------------------------------------------- |
| `ids`      | `string`\[]                                       |
| `fields?`  | `string`\[]                                       |
| `options?` | [`QueryOptions`](/sdk/topk-js/index#queryoptions) |

**Returns**

`Promise`\<`Record`\<`string`, `Record`\<`string`, `any`>>>

##### listPartitions()

```ts theme={null}
listPartitions(prefix?: string): PartitionListStream;
```

List partitions in the collection as an async iterator.

**Parameters**

| Parameter | Type     |
| --------- | -------- |
| `prefix?` | `string` |

**Returns**

[`PartitionListStream`](/sdk/topk-js/index#partitionliststream)

##### query()

```ts theme={null}
query(query: Query, options?: QueryOptions): Promise<Record<string, any>[]>;
```

Executes a query against the collection.

**Parameters**

| Parameter  | Type                                              |
| ---------- | ------------------------------------------------- |
| `query`    | [`Query`](/sdk/topk-js/Namespace.query#query)     |
| `options?` | [`QueryOptions`](/sdk/topk-js/index#queryoptions) |

**Returns**

`Promise`\<`Record`\<`string`, `any`>\[]>

##### update()

```ts theme={null}
update(docs: Record<string, any>[], failOnMissing?: boolean): Promise<string>;
```

Updates documents in the collection.

Existing documents will be merged with the provided fields.
Missing documents will be ignored.

**Parameters**

| Parameter        | Type                          |
| ---------------- | ----------------------------- |
| `docs`           | `Record`\<`string`, `any`>\[] |
| `failOnMissing?` | `boolean`                     |

**Returns**

`Promise`\<`string`>

The `LSN` at which the update was applied.
If no updates were applied, this will be empty.

##### upsert()

```ts theme={null}
upsert(docs: Record<string, any>[]): Promise<string>;
```

Inserts or updates documents in the collection.

**Parameters**

| Parameter | Type                          |
| --------- | ----------------------------- |
| `docs`    | `Record`\<`string`, `any`>\[] |

**Returns**

`Promise`\<`string`>

***

### CollectionsClient

**`Internal`**

Client for managing collections.

This client provides methods to create, list, get, and delete collections.

**Methods**

##### create()

```ts theme={null}
create(name: string, schema: Record<string, SchemaFieldSpec>): Promise<Collection>;
```

Creates a new collection with the specified schema.

**Parameters**

| Parameter | Type                                                                         |
| --------- | ---------------------------------------------------------------------------- |
| `name`    | `string`                                                                     |
| `schema`  | `Record`\<`string`, [`SchemaFieldSpec`](/sdk/topk-js/index#schemafieldspec)> |

**Returns**

`Promise`\<[`Collection`](/sdk/topk-js/index#collection-1)>

##### delete()

```ts theme={null}
delete(name: string): Promise<void>;
```

Deletes a collection and all its data.

<Warning>
  This operation is irreversible and will permanently delete all data in the collection.
</Warning>

**Parameters**

| Parameter | Type     |
| --------- | -------- |
| `name`    | `string` |

**Returns**

`Promise`\<`void`>

##### get()

```ts theme={null}
get(name: string): Promise<Collection>;
```

Retrieves information about a specific collection.

**Parameters**

| Parameter | Type     |
| --------- | -------- |
| `name`    | `string` |

**Returns**

`Promise`\<[`Collection`](/sdk/topk-js/index#collection-1)>

##### list()

```ts theme={null}
list(): Promise<Collection[]>;
```

Lists all collections in the current project.

**Returns**

`Promise`\<[`Collection`](/sdk/topk-js/index#collection-1)\[]>

***

### PartitionListStream

Iterator for partition list responses.

This type implements JavaScript's async iterable protocol.
It can be used with `for await...of` loops.

**See**

[https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration\_protocols#the\_async\_iterator\_and\_async\_iterable\_protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols)

**Constructors**

**Constructor**

```ts theme={null}
new PartitionListStream(): PartitionListStream;
```

**Returns**

[`PartitionListStream`](/sdk/topk-js/index#partitionliststream)

**Methods**

##### \[asyncIterator]\()

```ts theme={null}
asyncIterator: AsyncGenerator<Partition, void, undefined>;
```

**Returns**

`AsyncGenerator`\<[`Partition`](/sdk/topk-js/index#partition), `void`, `undefined`>

##### next()

```ts theme={null}
next(): Promise<Partition>;
```

Returns the next partition in the stream.

**Returns**

`Promise`\<[`Partition`](/sdk/topk-js/index#partition)>

## Interfaces

### BackoffConfig

Configuration for exponential backoff between retry attempts.

This struct controls how the delay between retry attempts increases over time.
All fields are optional and will use sensible defaults if not provided.

**Properties**

| Property                                       | Type     | Description                                            |
| ---------------------------------------------- | -------- | ------------------------------------------------------ |
| <a id="property-base" /> `base?`               | `number` | Base multiplier for exponential backoff (default: 2.0) |
| <a id="property-initbackoff" /> `initBackoff?` | `number` | Initial delay before the first retry in milliseconds   |
| <a id="property-maxbackoff" /> `maxBackoff?`   | `number` | Maximum delay between retries in milliseconds          |

***

### ClientConfig

Configuration for the TopK client.

This struct contains all the necessary configuration options to connect to the TopK API.
The `api_key` and `region` are required, while other options have sensible defaults.

**Properties**

| Property                                       | Type                                            | Description                                                                                                                    |
| ---------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| <a id="property-apikey" /> `apiKey`            | `string`                                        | Your TopK API key for authentication                                                                                           |
| <a id="property-host" /> `host?`               | `string`                                        | Custom host URL (optional, defaults to the standard TopK endpoint)                                                             |
| <a id="property-https" /> `https?`             | `boolean`                                       | Whether to use HTTPS (optional, defaults to true)                                                                              |
| <a id="property-region" /> `region`            | `string`                                        | The region where your data is stored. For available regions see: [https://docs.topk.io/regions](https://docs.topk.io/regions). |
| <a id="property-retryconfig" /> `retryConfig?` | [`RetryConfig`](/sdk/topk-js/index#retryconfig) | Retry configuration for failed requests (optional)                                                                             |

***

### Collection

Represents a collection in the TopK service.

A collection is a container for documents with a defined schema.
This struct contains metadata about the collection including its name,
organization, project, schema, and region.

**Properties**

| Property                                  | Type                                                                                 | Description                                          |
| ----------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| <a id="property-createdat" /> `createdAt` | `string`                                                                             | Timestamp when the collection was created (ISO 8601) |
| <a id="property-name" /> `name`           | `string`                                                                             | Name of the collection                               |
| <a id="property-orgid" /> `orgId`         | `string`                                                                             | Organization ID that owns the collection             |
| <a id="property-projectid" /> `projectId` | `string`                                                                             | Project ID that contains the collection              |
| <a id="property-region-1" /> `region`     | `string`                                                                             | Region where the collection is stored                |
| <a id="property-schema" /> `schema`       | `Record`\<`string`, [`CollectionFieldSpec`](/sdk/topk-js/index#collectionfieldspec)> | Schema definition for the collection fields          |

***

### CollectionFieldSpec

Represents a field specification within a collection schema.

This struct defines the properties of a field in a collection,
including its data type, whether it's required, and any index configuration.

**Properties**

| Property                                | Type              | Description                                                      |
| --------------------------------------- | ----------------- | ---------------------------------------------------------------- |
| <a id="property-datatype" /> `dataType` | `DataType`        | Data type of the field                                           |
| <a id="property-index" /> `index?`      | `FieldIndexUnion` | Index configuration for the field (optional)                     |
| <a id="property-required" /> `required` | `boolean`         | Whether the field is required (must be present in all documents) |

***

### Partition

A partition within a collection.

**Properties**

| Property                                    | Type     | Description                   |
| ------------------------------------------- | -------- | ----------------------------- |
| <a id="property-createdat-1" /> `createdAt` | `string` | RFC3339 created\_at timestamp |
| <a id="property-name-1" /> `name`           | `string` | Partition name                |

***

### QueryOptions

Options for query operations.

These options control the behavior of query operations, including consistency
guarantees and sequence number constraints.

**Properties**

| Property                                       | Type                                                      | Description                                        |
| ---------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------- |
| <a id="property-consistency" /> `consistency?` | [`ConsistencyLevel`](/sdk/topk-js/index#consistencylevel) | Consistency level for the query                    |
| <a id="property-lsn" /> `lsn?`                 | `string`                                                  | Last sequence number to query at (for consistency) |

***

### RetryConfig

Configuration for retry behavior when requests fail.

This struct allows you to customize how the client handles retries for failed requests.
All fields are optional and will use sensible defaults if not provided.

**Properties**

| Property                                     | Type                                                | Description                                              |
| -------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------- |
| <a id="property-backoff" /> `backoff?`       | [`BackoffConfig`](/sdk/topk-js/index#backoffconfig) | Backoff configuration for spacing out retry attempts     |
| <a id="property-maxretries" /> `maxRetries?` | `number`                                            | Maximum number of retries to attempt before giving up    |
| <a id="property-timeout" /> `timeout?`       | `number`                                            | Total timeout for the entire retry chain in milliseconds |

## Namespaces

* [data](/sdk/topk-js/Namespace.data)
* [query](/sdk/topk-js/Namespace.query)
* [query\_agg](/sdk/topk-js/Namespace.query_agg)
* [query\_fn](/sdk/topk-js/Namespace.query_fn)
* [schema](/sdk/topk-js/Namespace.schema)

## Type Aliases

### ConsistencyLevel

```ts theme={null}
type ConsistencyLevel = "indexed" | "strong";
```

Consistency levels for query operations.

* `Indexed`: Query returns results as soon as they are indexed (faster, eventual consistency)
* `Strong`: Query waits for all replicas to be consistent (slower, strong consistency)

***

### SchemaFieldSpec

```ts theme={null}
type SchemaFieldSpec = 
  | FieldSpec
  | {
[field: string]: SchemaFieldSpec;
};
```