Skip to main content

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
ParameterType
configClientConfig
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
ParameterType
querystring
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
ParameterType
namestring
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
ParameterType
namestring
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
ParameterType
querystring
datasets( | string | { dataset: string; filter?: LogicalExpression; })[]
topKnumber
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
ParameterType
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
ParameterType
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
ParameterType
idsstring[]
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
ParameterType
queryQuery
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
ParameterType
docsRecord<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
ParameterType
docsRecord<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
ParameterType
namestring
schemaRecord<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
ParameterType
namestring
Returns Promise<void>
get()
get(name: string): Promise<Collection>;
Retrieves information about a specific collection. Parameters
ParameterType
namestring
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
ParameterType
handlestring
Returns Promise<boolean>
delete()
delete(docId: string): Promise<string>;
Delete a file from the dataset. Parameters
ParameterType
docIdstring
Returns Promise<string>
getMetadata()
getMetadata(ids: string[], fields?: string[]): Promise<Record<string, Record<string, any>>>;
Get metadata for one or more documents. Parameters
ParameterType
idsstring[]
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
ParameterType
fields?string[]
filter?LogicalExpression
Returns DatasetListStream
updateMetadata()
updateMetadata(docId: string, metadata: Record<string, any>): Promise<string>;
Update metadata for a file. Parameters
ParameterType
docIdstring
metadataRecord<string, any>
Returns Promise<string>
upsertFile()
upsertFile(
   docId: string, 
   input: InputFile, 
metadata: Record<string, any>): Promise<string>;
Upsert a file to the dataset. Parameters
ParameterType
docIdstring
inputInputFile
metadataRecord<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
ParameterType
handlestring
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
ParameterType
namestring
Returns Promise<Dataset>
delete()
delete(name: string): Promise<void>;
Delete a dataset. Parameters
ParameterType
namestring
Returns Promise<void>
get()
get(name: string): Promise<Dataset>;
Get information about a specific dataset. Parameters
ParameterType
namestring
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
ParameterType
namestring
paramsUpdateDatasetParams
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
PropertyType
confidencenumber
factsFact[]
refsRecord<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
PropertyTypeDescription
base?numberBase multiplier for exponential backoff (default: 2.0)
initBackoff?numberInitial delay before the first retry in milliseconds
maxBackoff?numberMaximum delay between retries in milliseconds

Chunk

Text chunk content. Properties
PropertyType
docPagesnumber[]
textstring

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
PropertyTypeDescription
apiKeystringYour TopK API key for authentication
host?stringCustom host URL (optional, defaults to the standard TopK endpoint)
https?booleanWhether to use HTTPS (optional, defaults to true)
regionstringThe region where your data is stored. For available regions see: https://docs.topk.io/regions.
retryConfig?RetryConfigRetry 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
PropertyTypeDescription
createdAtstringTimestamp when the collection was created (ISO 8601)
namestringName of the collection
orgIdstringOrganization ID that owns the collection
projectIdstringProject ID that contains the collection
regionstringRegion where the collection is stored
schemaRecord<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
PropertyTypeDescription
dataTypeDataTypeData type of the field
index?FieldIndexUnionIndex configuration for the field (optional)
requiredbooleanWhether the field is required (must be present in all documents)

Content

Content in a search result. One of chunk, page, or image. Properties
PropertyType
data| Chunk | Page | Image
type"page" | "image" | "chunk"

Dataset

Represents a dataset in the TopK service. Properties
PropertyTypeDescription
createdAtstringRFC 3339 timestamp when the dataset was created
description?stringDataset description
namestringName of the dataset
orgIdstringOrganization ID that owns the dataset
projectIdstringProject ID that contains the dataset
regionstringRegion where the dataset is stored

Fact

Represents a fact in an ask response. Properties
PropertyType
factstring
refIdsstring[]

Image

Image content. Properties
PropertyType
datanumber[]
mimeTypestring

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
PropertyTypeDescription
data?BufferInline file data as a Buffer.
fileName?stringFile name (required when using inline data).
mimeType?stringMIME type (required when using inline data).
path?stringPath to a file on disk. If provided, fileName and mimeType are inferred.

ListEntry

Entry in a dataset. Properties
PropertyType
idstring
metadataRecord<string, any>
mimeTypestring
namestring
sizenumber
statusstring
statusReason?string

Page

Page content with optional image. Properties
PropertyType
image?Image
pageNumbernumber

Progress

Represents a progress update in an ask response. Properties
PropertyType
updatestring

QueryOptions

Options for query operations. These options control the behavior of query operations, including consistency guarantees and sequence number constraints. Properties
PropertyTypeDescription
consistency?ConsistencyLevelConsistency level for the query
lsn?stringLast 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
PropertyTypeDescription
backoff?BackoffConfigBackoff configuration for spacing out retry attempts
maxRetries?numberMaximum number of retries to attempt before giving up
timeout?numberTotal timeout for the entire retry chain in milliseconds

SearchResult

Represents a search result in an ask response. Properties
PropertyType
content?Content
contentIdstring
datasetstring
docIdstring
docNamestring
docTypestring
metadataRecord<string, any>

UpdateDatasetParams

Properties
PropertyTypeDescription
description?stringDataset description

WaitConfig

Configuration for polling when waiting for a handle to be processed. Properties
PropertyTypeDescription
frequencySecs?numberHow often to poll for the handle status, in seconds. Default is 5.
timeoutSecs?numberMaximum 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.