Classes
Client
The main TopK client for interacting with the TopK service.
This client provides access to collections and allows you to perform various operations
like creating collections, querying data, and managing documents.
Constructors
Constructor
new Client(config: ClientConfig): Client;
| Parameter | Type |
|---|
config | ClientConfig |
Client
Methods
collection()
collection(name: string): CollectionClient;
CollectionClient
collections()
collections(): CollectionsClient;
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>;
| Parameter | Type |
|---|
options? | QueryOptions |
Promise<number>
delete()
delete(expr:
| string[]
| LogicalExpression): Promise<string>;
await client.collection("books").delete(["id_1", "id_2"])
import { field } from "topk-js/query";
await client.collection("books").delete(field("published_year").gt(1997))
| Parameter | Type |
|---|
expr | | string[] | LogicalExpression |
Promise<string>
get()
get(
ids: string[],
fields?: string[],
options?: QueryOptions): Promise<Record<string, Record<string, any>>>;
| Parameter | Type |
|---|
ids | string[] |
fields? | string[] |
options? | QueryOptions |
Promise<Record<string, Record<string, any>>>
query()
query(query: Query, options?: QueryOptions): Promise<Record<string, any>[]>;
| Parameter | Type |
|---|
query | Query |
options? | QueryOptions |
Promise<Record<string, any>[]>
update()
update(docs: Record<string, any>[], failOnMissing?: boolean): Promise<string>;
| Parameter | Type |
|---|
docs | Record<string, any>[] |
failOnMissing? | boolean |
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>;
| Parameter | Type |
|---|
docs | Record<string, any>[] |
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>;
| Parameter | Type |
|---|
name | string |
schema | Record<string, FieldSpec> |
Promise<Collection>
delete()
delete(name: string): Promise<void>;
This operation is irreversible and will permanently delete all data in the collection.
Promise<void>
get()
get(name: string): Promise<Collection>;
Promise<Collection>
list()
list(): Promise<Collection[]>;
Promise<Collection[]>
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 |
|---|
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) |
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) |
RerankOptions
Options for rerank stages.
This struct contains configuration options for reranking results,
including the model, query, and fields to use.
Properties
| Property | Type | Description |
|---|
fields? | string[] | Fields to include in reranking |
model? | string | The reranking model to use |
query? | string | The query text for reranking |
topkMultiple? | number | Multiple of top-k to consider for reranking |
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
Type Aliases
ConsistencyLevel
type ConsistencyLevel = "indexed" | "strong";
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)
