Skip to navigation
Getting Started

Quickstart

Connect to turbopuffer, write documents, and run your first search in minutes.

Install the SDK

npm install @turbopuffer/sdk

Initialize the client

import Turbopuffer from "@turbopuffer/sdk";
const client = new Turbopuffer({
  apiKey: process.env.TURBOPUFFER_API_KEY,
  baseUrl: "https://gcp-us-central1.turbopuffer.com",
});

Write documents

Write documents with vector embeddings and typed attributes. turbopuffer will create or update the namespace automatically on first write.

await client.namespaces.write("my-namespace", {
  upsertRows: [
    { id: "1", vector: [0.1, 0.2, 0.3], attributes: { text: "turbopuffer is fast", category: "product" } },
    { id: "2", vector: [0.4, 0.5, 0.6], attributes: { text: "vector search at scale", category: "search" } },
  ],
  schema: {
    text: { type: "string", fullTextSearch: true },
    category: { type: "string", filterable: true },
  },
});

Find the nearest neighbors to a query vector, with an optional filter:

const results = await client.namespaces.query("my-namespace", {
  rankBy: ["vector", "ANN", [0.1, 0.2, 0.3]],
  topK: 10,
  filters: ["category", "Eq", "product"],
  includeAttributes: ["text", "category"],
});
for (const row of results.rows ?? []) {
  console.log(row.id, row.attributes);
}

Run a full-text search

Search across text attributes using BM25:

const results = await client.namespaces.query("my-namespace", {
  rankBy: ["text", "BM25", "vector search"],
  topK: 10,
});

List namespaces

for await (const ns of await client.namespaces.list()) {
  console.log(ns.id);
}

Next steps

Vector Search Guide

Deep dive into ANN, kNN, and embedding models.

Full-Text Search Guide

BM25 configuration, tokenizers, and language support.

API Reference

Complete reference for all endpoints and types.