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.
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): CollectionClient;
Returns a client for interacting with a specific collection.
Parameters
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
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>
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>>>
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, FieldSpec>): Promise<Collection>;
Creates a new collection with the specified schema.
Parameters
| Parameter | Type |
|---|
name | string |
schema | Record<string, FieldSpec> |
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
Returns
Promise<void>
get()
get(name: string): Promise<Collection>;
Retrieves information about a specific collection.
Parameters
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
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): Promise<Dataset>;
Create a new dataset.
Parameters
Returns
Promise<Dataset>
delete()
delete(name: string): Promise<void>;
Delete a dataset.
Parameters
Returns
Promise<void>
get()
get(name: string): Promise<Dataset>;
Get information about a specific dataset.
Parameters
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>
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 |
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 |
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.