JavaScript SDK

Get started with TopK using JavaScript SDK.

The TopK JavaScript library provides convenient access to the TopK API from Node.js environments with full TypeScript support.

Installation

npm install topk-js
# or
yarn add topk-js
# or
pnpm install topk-js

Building with a coding agent

Using Claude Code, Cursor, Codex, or another coding agent? Install the TopK skill so the agent writes correct TopK code. It covers schema design, chunking, hybrid queries, multi-tenancy, and the common mistakes.

npx skills add topk-io/topk --skill topk

Prerequisites

• API key — sign in to console.topk.io and generate an API key.
• Region — available regions are listed at docs.topk.io/regions.

Usage

Hybrid Search

import { Client } from "topk-js";
import { text, keywordIndex, semanticIndex } from "topk-js/schema";
import { select, field, fn } from "topk-js/query";

const client = new Client({
  apiKey: process.env.TOPK_API_KEY!,
  region: "aws-us-east-1-elastica",
});

// Create a collection
await client.collections().create("books", {
  title: text().required().index(keywordIndex()),
  content: text().index(semanticIndex()),
});

// Upsert documents
await client.collection("books").upsert([
  {
    _id: "1",
    title: "Catcher in the Rye",
    content: "IF YOU REALLY WANT TO HEAR about it, the first thing you'll probably want to know is ...",
    author: "J.D. Salinger",
    rating: 3.8,
  },
  {
    _id: "2",
    title: "1984",
    content: "It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith, ...",
    author: "George Orwell",
    rating: 4.7,
  },
]);

// Query with hybrid search
const results = await client.collection("books").query(
  select({
    title: field("title"),
    author: field("author"),
    // Compute semantic similarity of content field with the query
    similarity_score: fn.semanticSimilarity(
      "content",
      "What is the meaning of life?",
    ),
  })
  // Filter documents by metadata
  .filter(field("rating").gte(3.0))
  // Rank using the computed similarity score and rating
  .sort(field("rating").mul(field("similarity_score")), false)
  // Get top 10 highest ranked documents
  .limit(10)
);

Vector Search

import { Client } from "topk-js";
import { text, f32Vector, vectorIndex } from "topk-js/schema";
import { select, field, fn } from "topk-js/query";

const client = new Client({
  apiKey: process.env.TOPK_API_KEY!,
  region: "aws-us-east-1-elastica",
});

// Create a collection with a vector field (dimension must match your embedding model's output size)
await client.collections().create("books", {
  title: text().required(),
  embedding: f32Vector({ dimension: 1536 }).required().index(vectorIndex({ metric: "dot_product" })),
});

// Upsert documents with embeddings
await client.collection("books").upsert([
  { _id: "1", title: "Catcher in the Rye", embedding: [0.1, 0.2, ...] },
  { _id: "2", title: "1984",               embedding: [0.9, 0.8, ...] },
]);

// Query the nearest neighbors to a query vector
const results = await client.collection("books").query(
  select({
    title: field("title"),
    distance: fn.vectorDistance("embedding", [0.8, 0.9, ...]),
  })
  // Return the 10 closest documents (ascending = closest first)
  .sort(field("distance"), true)
  .limit(10)
);

Handling errors

The SDK throws plain Error objects. Check err.message to identify the error:

try {
  await client.collections().get("books");
} catch (err) {
  if (err instanceof Error) {
    if (err.message === "collection not found") console.error("Collection does not exist");
    else if (err.message === "permission denied") console.error("Check your API key");
    else console.error("Unexpected error:", err.message);
  }
}

err.message	Description
"collection not found"	Collection does not exist
"collection already exists"	Collection with this name already exists
"permission denied"	Invalid or missing API key
starts with "request too large:"	Request payload too large

Retries

The client automatically retries transient errors (server unavailable, network failures) and LSN consistency timeouts. Retry behaviour can be configured via retryConfig:

import { Client } from "topk-js";

const client = new Client({
  apiKey: process.env.TOPK_API_KEY,
  region: "aws-us-east-1-elastica",
  retryConfig: {
    maxRetries: 5,       // default: 3
    timeout: 60_000,     // total retry chain timeout in ms, default: 30,000
    backoff: {
      initBackoff: 200,  // default: 100 ms
      maxBackoff: 5_000, // default: 10,000 ms
    },
  },
});

Requirements

Node.js 18 or higher.