topk-js

Classes

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

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

---

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

---

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>

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

---

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)

---

Partition

A partition within a collection.

Properties

Property	Type	Description
createdAt	string	RFC3339 created_at timestamp
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
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

Namespaces

• data
• query
• query_agg
• query_fn
• schema

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)

---

SchemaFieldSpec

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