TypeScript SDK

TypeScript SDK

Zero runtime dependencies. Uses native fetch (available in browsers, Node.js 18+, Deno).

Installation

npm install zeppelin-typescript

# From source
cd clients/typescript && npm install && npm run build

Quick Start

import { ZeppelinClient, Filters, RankBy } from "zeppelin-typescript";

const client = new ZeppelinClient({ baseUrl: "http://localhost:8080" });

// Create namespace
const ns = await client.createNamespace("my_vectors", 384, {
  distanceMetric: "cosine",
});

// Upsert vectors
const count = await client.upsertVectors("my_vectors", [
  { id: "vec-1", values: [0.1, 0.2, ...], attributes: { color: "red" } },
  { id: "vec-2", values: [0.3, 0.4, ...], attributes: { color: "blue" } },
]);

// Query
const response = await client.query("my_vectors", {
  vector: [0.1, 0.2, ...],
  topK: 10,
});

for (const result of response.results) {
  console.log(`${result.id}: ${result.score}`);
}

Client Options

const client = new ZeppelinClient({
  baseUrl: "http://localhost:8080",       // Server URL (default)
  timeout: 30000,                         // Timeout in ms (default: 30000)
  headers: { Authorization: "Bearer t" }, // Custom headers
  fetch: customFetch,                     // Custom fetch (Node.js < 18)
});

Namespace Operations

// Create
const ns = await client.createNamespace("my_ns", 384, {
  distanceMetric: "cosine",
});

// Create with FTS
const ns = await client.createNamespace("articles", 384, {
  distanceMetric: "cosine",
  fullTextSearch: {
    title: { language: "english", stemming: true, k1: 1.5 },
    content: { language: "english" },
  },
});

// List
const namespaces = await client.listNamespaces();

// Get
const ns = await client.getNamespace("my_ns");

// Delete
await client.deleteNamespace("my_ns");

Vector Operations

// Upsert
const count = await client.upsertVectors("my_ns", [
  {
    id: "vec-1",
    values: [0.1, 0.2, 0.3],
    attributes: {
      category: "product",
      price: 29.99,
      tags: ["electronics", "gadgets"],
    },
  },
]);

// Delete
const count = await client.deleteVectors("my_ns", ["vec-1", "vec-2"]);

Querying

Vector search

const response = await client.query("my_ns", {
  vector: [0.1, 0.2, 0.3],
  topK: 10,
  nprobe: 20,
  consistency: "strong",
});

for (const result of response.results) {
  console.log(`${result.id}: score=${result.score}`, result.attributes);
}

BM25 search

const response = await client.query("articles", {
  rankBy: RankBy.bm25("content", "vector search engine"),
  topK: 10,
});

Weighted multi-field BM25

const response = await client.query("articles", {
  rankBy: RankBy.sum(
    RankBy.product(2.0, RankBy.bm25("title", "vector search")),
    RankBy.bm25("content", "vector search"),
  ),
  topK: 10,
});

Prefix search

const response = await client.query("articles", {
  rankBy: RankBy.bm25("title", "vec"),
  lastAsPrefix: true,
  topK: 5,
});

Filter Builder

import { Filters } from "zeppelin-typescript";

// Equality
Filters.eq("color", "red");

// Inequality
Filters.notEq("status", "deleted");

// Range
Filters.range("price", { gte: 10.0, lte: 100.0 });

// Set membership
Filters.in("category", ["electronics", "books"]);
Filters.notIn("category", ["spam"]);

// List contains
Filters.contains("tags", "rust");

// FTS token filters
Filters.containsAllTokens("content", ["rust", "programming"]);
Filters.containsTokenSequence("content", ["vector", "search"]);

// Logical operators
Filters.and(
  Filters.eq("color", "red"),
  Filters.range("price", { lte: 50.0 }),
);

Filters.or(
  Filters.eq("color", "red"),
  Filters.eq("color", "blue"),
);

Filters.not(Filters.eq("archived", true));

Query with filters

const response = await client.query("my_ns", {
  vector: [0.1, 0.2, 0.3],
  topK: 10,
  filter: Filters.and(
    Filters.eq("category", "product"),
    Filters.range("price", { gte: 10, lte: 100 }),
  ),
});

RankBy Builder

import { RankBy } from "zeppelin-typescript";

// Single-field BM25
RankBy.bm25("content", "search query");

// Sum of multiple fields
RankBy.sum(
  RankBy.bm25("title", "query"),
  RankBy.bm25("content", "query"),
);

// Max across fields
RankBy.max(
  RankBy.bm25("title", "query"),
  RankBy.bm25("content", "query"),
);

// Weighted
RankBy.product(2.0, RankBy.bm25("title", "query"));

Error Handling

import {
  ZeppelinError,
  NotFoundError,
  ValidationError,
  ConflictError,
  ServerError,
} from "zeppelin-typescript";

try {
  await client.getNamespace("nonexistent");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(`Not found: ${error.message} (${error.statusCode})`);
  } else if (error instanceof ValidationError) {
    console.log(`Bad request: ${error.message}`);
  } else if (error instanceof ConflictError) {
    console.log(`Conflict: ${error.message}`);
  } else if (error instanceof ServerError) {
    console.log(`Server error: ${error.message}`);
  } else if (error instanceof ZeppelinError) {
    console.log(`Error: ${error.message} (${error.statusCode})`);
  }
}

Type Exports

The SDK exports all types for use in your application:

import type {
  DistanceMetric,
  ConsistencyLevel,
  AttributeValue,
  Attributes,
  VectorEntry,
  SearchResult,
  Namespace,
  Filter,
  FtsFieldConfig,
  QueryResponse,
  ZeppelinClientOptions,
} from "zeppelin-typescript";

Health Checks

const health = await client.health();    // { status: "ok" }
const ready = await client.ready();      // { status: "ready", s3_connected: true }