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.

Constructor

config

ClientConfig

required

Configuration object for the TopK client

import { Client } from "topk-js";

const client = new Client({
  apiKey: "YOUR_TOPK_API_KEY",
  region: "aws-us-east-1-elastica"
});

ClientConfig

Configuration for the TopK client. This struct contains all the necessary configuration options to connect to the TopK API.

apiKey

string

required

Your TopK API key for authentication

region

string

required

The region where your data is stored. For available regions see: https://docs.topk.io/regions

host

string

Custom host URL (optional, defaults to the standard TopK endpoint)

https

boolean

Whether to use HTTPS (optional, defaults to true)

retryConfig

RetryConfig

Retry configuration for failed requests (optional)

Methods

collections()

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

const collectionsClient = client.collections();

// List all collections
const collections = await collectionsClient.list();

// Create a new collection
await collectionsClient.create("books", schema);

return

CollectionsClient

A client for managing collections

collection(name)

Returns a client for interacting with a specific collection.

name

string

required

The name of the collection

const booksCollection = client.collection("books");

// Query the collection
const results = await booksCollection.query(query);

// Upsert documents
await booksCollection.upsert([{ _id: "1", title: "Book Title" }]);

return

CollectionClient

A client for interacting with the specified collection

CollectionClient

Client for interacting with a specific collection. This client provides methods to perform operations on a specific collection, including querying, upserting, and deleting documents.

get(ids, fields?, options?)

Retrieves documents by their IDs.

ids

Array<string>

required

Array of document IDs to retrieve

fields

Array<string>

Optional array of field names to retrieve. If not specified, all fields are returned

options

QueryOptions

Optional query options for consistency control

// Get documents by IDs
const docs = await client.collection("books").get(["id_1", "id_2"]);

// Get specific fields only
const titleOnly = await client.collection("books").get(
  ["id_1", "id_2"],
  ["title", "author"]
);

return

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

A promise that resolves to a map of document IDs to documents

count(options?)

Counts the number of documents in the collection.

options

QueryOptions

Optional query options for consistency control

const totalDocs = await client.collection("books").count();
console.log(`Total documents: ${totalDocs}`);

return

Promise<number>

A promise that resolves to the number of documents in the collection

query(query, options?)

Executes a query against the collection.

query

query.Query

required

The query to execute

options

QueryOptions

Optional query options for consistency control

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

const results = await client.collection("books").query(
  select({
    title: field("title"),
    similarity: fn.semanticSimilarity("title", "classic novel")
  })
  .topk(field("similarity"), 10)
);

return

Promise<Array<Record<string, any>>>

A promise that resolves to an array of matching documents

upsert(docs)

Inserts or updates documents in the collection.

docs

Array<Record<string, any>>

required

Array of documents to upsert. Each document must have an _id field

await client.collection("books").upsert([
  { _id: "gatsby", title: "The Great Gatsby", author: "F. Scott Fitzgerald" },
  { _id: "1984", title: "1984", author: "George Orwell" }
]);

return

Promise<string>

A promise that resolves to the LSN (Log Sequence Number) at which the upsert was applied

update(docs, failOnMissing?)

Updates documents in the collection. Existing documents will be merged with the provided fields. Missing documents will be ignored.

docs

Array<Record<string, any>>

required

Array of documents with fields to update. Each document must have an _id field

failOnMissing

boolean

If true, the operation will fail if any document is missing. Defaults to false

await client.collection("books").update([
  { _id: "gatsby", year: 1925 },
  { _id: "1984", year: 1949 }
]);

return

Promise<string>

The LSN at which the update was applied. If no updates were applied, this will be empty

delete(expr)

Deletes documents from the collection by their IDs or using a filter expression.

expr

Array<string> | query.LogicalExpression

required

Either an array of document IDs or a logical filter expression

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

return

Promise<string>

A promise that resolves to the LSN at which the delete was applied

Supporting Types

RetryConfig

Configuration for retry behavior when requests fail.

maxRetries

number

Maximum number of retries to attempt before giving up

timeout

number

Total timeout for the entire retry chain in milliseconds

backoff

BackoffConfig

Backoff configuration for spacing out retry attempts

BackoffConfig

Configuration for exponential backoff between retry attempts.

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

QueryOptions

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

lsn

string

Last sequence number to query at (for consistency)

consistency

ConsistencyLevel

Consistency level for the query. Can be:

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

ConsistencyLevel

Consistency levels for query operations.

'indexed' - Indexed consistency: faster, eventual consistency
'strong' - Strong consistency: slower, waits for all replicas

API Reference

Client

Client

Constructor

ClientConfig

Methods

collections()

collection(name)

CollectionClient

get(ids, fields?, options?)

count(options?)

query(query, options?)

upsert(docs)

update(docs, failOnMissing?)

delete(expr)

Supporting Types

RetryConfig

BackoffConfig

QueryOptions

ConsistencyLevel

Build docs developers (and LLMs) love

API Reference

​Client

​Constructor

​ClientConfig

​Methods

​collections()

​collection(name)

​CollectionClient

​get(ids, fields?, options?)

​count(options?)

​query(query, options?)

​upsert(docs)

​update(docs, failOnMissing?)

​delete(expr)

​Supporting Types

​RetryConfig

​BackoffConfig

​QueryOptions

​ConsistencyLevel

Build docs developers (and LLMs) love

Client

Constructor

ClientConfig

Methods

collections()

collection(name)

CollectionClient

get(ids, fields?, options?)

count(options?)

query(query, options?)

upsert(docs)

update(docs, failOnMissing?)

delete(expr)

Supporting Types

RetryConfig

BackoffConfig

QueryOptions

ConsistencyLevel