topk-js - TopK

Classes

AskStream

Iterator for ask 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 Constructors Constructor

new AskStream(): AskStream;

Returns AskStream Methods

[asyncIterator]()

asyncIterator: AsyncGenerator<
  | Answer
| Progress, void, undefined>;

Returns AsyncGenerator< | Answer | Progress, void, undefined>

Client

Client for interacting with the TopK API. For available regions see https://docs.topk.io/regions Constructors Constructor

new Client(config: ClientConfig): Client;

Creates a new TopK client with the provided configuration. Parameters

Parameter	Type
`config`	`ClientConfig`

Returns Client Methods

ask()

ask(
   query: string, 
   datasets: (
  | string
  | {
  dataset: string;
  filter?: LogicalExpression;
})[], 
   filter?: LogicalExpression, 
   mode?: Mode, 
   selectFields?: string[], 
   includeContent?: boolean): AskStream;

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

Parameter	Type
`query`	`string`
`datasets`	( \| `string` \| { `dataset`: `string`; `filter?`: `LogicalExpression`; })[]
`filter?`	`LogicalExpression`
`mode?`	`Mode`
`selectFields?`	`string`[]
`includeContent?`	`boolean`

Returns AskStream

collection()

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

collections()

collections(): CollectionsClient;

Returns a client for managing collections. This method provides access to collection management operations like creating, listing, and deleting collections. Returns CollectionsClient

dataset()

dataset(name: string): DatasetClient;

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

Parameter	Type
`name`	`string`

Returns DatasetClient

datasets()

datasets(): DatasetsClient;

Get a client for managing datasets. Returns DatasetsClient

search()

search(
   query: string, 
   datasets: (
  | string
  | {
  dataset: string;
  filter?: LogicalExpression;
})[], 
   topK: number, 
   filter?: LogicalExpression, 
   selectFields?: string[]): SearchStream;

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

Parameter	Type
`query`	`string`
`datasets`	( \| `string` \| { `dataset`: `string`; `filter?`: `LogicalExpression`; })[]
`topK`	`number`
`filter?`	`LogicalExpression`
`selectFields?`	`string`[]

Returns SearchStream

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()

count(options?: QueryOptions): Promise<number>;

Counts the number of documents in the collection. Parameters

Parameter	Type
`options?`	`QueryOptions`

Returns Promise<number>

delete()

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:

await client.collection("books").delete(["id_1", "id_2"])

Delete documents by a filter expression:

import { field } from "topk-js/query";

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

Parameters

Parameter	Type
`expr`	\| `string`[] \| `LogicalExpression`

Returns Promise<string>

deletePartition()

deletePartition(name: string): Promise<void>;

Delete a partition and all documents within it. Parameters

Parameter	Type
`name`	`string`

Returns Promise<void>

get()

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`

Returns Promise<Record<string, Record<string, any>>>

listPartitions()

listPartitions(prefix?: string): PartitionListStream;

List partitions in the collection as an async iterator. Parameters

Parameter	Type
`prefix?`	`string`

Returns PartitionListStream

query()

query(query: Query, options?: QueryOptions): Promise<Record<string, any>[]>;

Executes a query against the collection. Parameters

Parameter	Type
`query`	`Query`
`options?`	`QueryOptions`

Returns Promise<Record<string, any>[]>

update()

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()

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()

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

Returns Promise<Collection>

delete()

delete(name: string): Promise<void>;

Deletes a collection and all its data.

This operation is irreversible and will permanently delete all data in the collection.

Parameters

Parameter	Type
`name`	`string`

Returns Promise<void>

get()

get(name: string): Promise<Collection>;

Retrieves information about a specific collection. Parameters

Parameter	Type
`name`	`string`

Returns Promise<Collection>

list()

list(): Promise<Collection[]>;

Lists all collections in the current project. Returns Promise<Collection[]>

DatasetClient

Internal Client for dataset operations. Methods

checkHandle()

checkHandle(handle: string): Promise<boolean>;

Return whether the handle has been processed. Parameters

Parameter	Type
`handle`	`string`

Returns Promise<boolean>

delete()

delete(docId: string): Promise<string>;

Delete a file from the dataset. Parameters

Parameter	Type
`docId`	`string`

Returns Promise<string>

getMetadata()

getMetadata(ids: string[], fields?: string[]): Promise<Record<string, Record<string, any>>>;

Get metadata for one or more documents. Parameters

Parameter	Type
`ids`	`string`[]
`fields?`	`string`[]

Returns Promise<Record<string, Record<string, any>>>

list()

list(fields?: string[], filter?: LogicalExpression): DatasetListStream;

List files in the dataset as an async iterator. Parameters

Parameter	Type
`fields?`	`string`[]
`filter?`	`LogicalExpression`

Returns DatasetListStream

updateMetadata()

updateMetadata(docId: string, metadata: Record<string, any>): Promise<string>;

Update metadata for a file. Parameters

Parameter	Type
`docId`	`string`
`metadata`	`Record`<`string`, `any`>

Returns Promise<string>

upsertFile()

upsertFile(
   docId: string, 
   input: InputFile, 
metadata: Record<string, any>): Promise<string>;

Upsert a file to the dataset. Parameters

Parameter	Type
`docId`	`string`
`input`	`InputFile`
`metadata`	`Record`<`string`, `any`>

Returns Promise<string>

waitForHandle()

waitForHandle(handle: string, config?: WaitConfig): Promise<void>;

Poll until a handle has been processed or the timeout is reached. Throws if the handle is not processed within the configured timeout. Parameters

Parameter	Type
`handle`	`string`
`config?`	`WaitConfig`

Returns Promise<void>

DatasetListStream

Iterator for dataset 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 Constructors Constructor

new DatasetListStream(): DatasetListStream;

Returns DatasetListStream Methods

[asyncIterator]()

asyncIterator: AsyncGenerator<ListEntry, void, undefined>;

Returns AsyncGenerator<ListEntry, void, undefined>

next()

next(): Promise<ListEntry>;

Returns the next entry in the stream. Returns Promise<ListEntry>

DatasetsClient

Internal Client for managing datasets. Methods

create()

create(name: string, description?: string): Promise<Dataset>;

Create a new dataset. Parameters

Parameter	Type
`name`	`string`
`description?`	`string`

Returns Promise<Dataset>

delete()

delete(name: string): Promise<void>;

Delete a dataset. Parameters

Parameter	Type
`name`	`string`

Returns Promise<void>

get()

get(name: string): Promise<Dataset>;

Get information about a specific dataset. Parameters

Parameter	Type
`name`	`string`

Returns Promise<Dataset>

list()

list(): Promise<Dataset[]>;

List all datasets. Returns Promise<Dataset[]>

update()

update(name: string, params: UpdateDatasetParams): Promise<Dataset>;

Update dataset properties Parameters

Parameter	Type
`name`	`string`
`params`	`UpdateDatasetParams`

Returns Promise<Dataset>

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 Constructors Constructor

new PartitionListStream(): PartitionListStream;

Returns PartitionListStream Methods

[asyncIterator]()

asyncIterator: AsyncGenerator<Partition, void, undefined>;

Returns AsyncGenerator<Partition, void, undefined>

next()

next(): Promise<Partition>;

Returns the next partition in the stream. Returns Promise<Partition>

SearchStream

Iterator for search 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 Constructors Constructor

new SearchStream(): SearchStream;

Returns SearchStream Methods

[asyncIterator]()

asyncIterator: AsyncGenerator<SearchResult, void, undefined>;

Returns AsyncGenerator<SearchResult, void, undefined>

Interfaces

Answer

Represents a final answer in an ask response. Properties

Property	Type
`confidence`	`number`
`facts`	`Fact`[]
`refs`	`Record`<`string`, `SearchResult`>

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
`base?`	`number`	Base multiplier for exponential backoff (default: 2.0)
`initBackoff?`	`number`	Initial delay before the first retry in milliseconds
`maxBackoff?`	`number`	Maximum delay between retries in milliseconds

Chunk

Text chunk content. Properties

Property	Type
`docPages`	`number`[]
`text`	`string`

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
`apiKey`	`string`	Your TopK API key for authentication
`host?`	`string`	Custom host URL (optional, defaults to the standard TopK endpoint)
`https?`	`boolean`	Whether to use HTTPS (optional, defaults to true)
`region`	`string`	The region where your data is stored. For available regions see: https://docs.topk.io/regions.
`retryConfig?`	`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
`createdAt`	`string`	Timestamp when the collection was created (ISO 8601)
`name`	`string`	Name of the collection
`orgId`	`string`	Organization ID that owns the collection
`projectId`	`string`	Project ID that contains the collection
`region`	`string`	Region where the collection is stored
`schema`	`Record`<`string`, `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
`dataType`	`DataType`	Data type of the field
`index?`	`FieldIndexUnion`	Index configuration for the field (optional)
`required`	`boolean`	Whether the field is required (must be present in all documents)

Content

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

Property	Type
`data`	\| `Chunk` \| `Page` \| `Image`
`type`	`"page"` \| `"image"` \| `"chunk"`

Dataset

Represents a dataset in the TopK service. Properties

Property	Type	Description
`createdAt`	`string`	RFC 3339 timestamp when the dataset was created
`description?`	`string`	Dataset description
`name`	`string`	Name of the dataset
`orgId`	`string`	Organization ID that owns the dataset
`projectId`	`string`	Project ID that contains the dataset
`region`	`string`	Region where the dataset is stored

Fact

Represents a fact in an ask response. Properties

Property	Type
`fact`	`string`
`refIds`	`string`[]

Image

Image content. Properties

Property	Type
`data`	`number`[]
`mimeType`	`string`

InputFile

Input for upserting a file to a dataset. Provide either a path to a file on disk, or inline data via data + fileName + mimeType. Properties

Property	Type	Description
`data?`	`Buffer`	Inline file data as a Buffer.
`fileName?`	`string`	File name (required when using inline `data`).
`mimeType?`	`string`	MIME type (required when using inline `data`).
`path?`	`string`	Path to a file on disk. If provided, fileName and mimeType are inferred.

ListEntry

Entry in a dataset. Properties

Property	Type
`id`	`string`
`metadata`	`Record`<`string`, `any`>
`mimeType`	`string`
`name`	`string`
`size`	`number`
`status`	`string`
`statusReason?`	`string`

Page

Page content with optional image. Properties

Property	Type
`image?`	`Image`
`pageNumber`	`number`

Partition

A partition within a collection. Properties

Property	Type	Description
`createdAt`	`string`	RFC3339 created_at timestamp
`name`	`string`	Partition name

Progress

Represents a progress update in an ask response. Properties

Property	Type
`update`	`string`

QueryOptions

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

Property	Type	Description
`consistency?`	`ConsistencyLevel`	Consistency level for the query
`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
`backoff?`	`BackoffConfig`	Backoff configuration for spacing out retry attempts
`maxRetries?`	`number`	Maximum number of retries to attempt before giving up
`timeout?`	`number`	Total timeout for the entire retry chain in milliseconds

SearchResult

Represents a search result in an ask response. Properties

Property	Type
`content?`	`Content`
`contentId`	`string`
`dataset`	`string`
`docId`	`string`
`docName`	`string`
`docType`	`string`
`metadata`	`Record`<`string`, `any`>

UpdateDatasetParams

Properties

Property	Type	Description
`description?`	`string`	Dataset description

WaitConfig

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

Property	Type	Description
`frequencySecs?`	`number`	How often to poll for the handle status, in seconds. Default is 5.
`timeoutSecs?`	`number`	Maximum time to wait before timing out, in seconds. Default is 300.

Namespaces

Type Aliases

ConsistencyLevel

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)

Mode

type Mode = "auto" | "summarize" | "research";

Mode for ask operations.

SchemaFieldSpec

type SchemaFieldSpec = 
  | FieldSpec
  | {
[field: string]: SchemaFieldSpec;
};

​Classes

​AskStream

[asyncIterator]()

​Client

ask()

collection()

collections()

dataset()

datasets()

search()

​CollectionClient

count()

delete()

deletePartition()

get()

listPartitions()

query()

update()

upsert()

​CollectionsClient

create()

delete()

get()

list()

​DatasetClient

checkHandle()

delete()

getMetadata()

list()

updateMetadata()

upsertFile()

waitForHandle()

​DatasetListStream

[asyncIterator]()

next()

​DatasetsClient

create()

delete()

get()

list()

update()

​PartitionListStream

[asyncIterator]()

next()

​SearchStream

[asyncIterator]()

​Interfaces

​Answer

​BackoffConfig

​Chunk

​ClientConfig

​Collection

​CollectionFieldSpec

​Content

​Dataset

​Fact

​Image

​InputFile

​ListEntry

​Page

​Partition

​Progress

​QueryOptions

​RetryConfig

​SearchResult

​UpdateDatasetParams

​WaitConfig

​Namespaces

​Type Aliases

​ConsistencyLevel

​Mode

​SchemaFieldSpec

Classes

AskStream

Client

CollectionClient

CollectionsClient

DatasetClient

DatasetListStream

DatasetsClient

PartitionListStream

SearchStream

Interfaces

Answer

BackoffConfig

Chunk

ClientConfig

Collection

CollectionFieldSpec

Content

Dataset

Fact

Image

InputFile

ListEntry

Page

Partition

Progress

QueryOptions

RetryConfig

SearchResult

UpdateDatasetParams

WaitConfig

Namespaces

Type Aliases

ConsistencyLevel

Mode

SchemaFieldSpec