> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://turbopuffer.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://turbopuffer.ferndocs.com/_mcp/server.

# Quickstart

## Install the SDK

#### TypeScript

```bash
npm install @turbopuffer/sdk
```

#### Python

```bash
pip install turbopuffer
```

## Initialize the client

#### TypeScript

```typescript
import Turbopuffer from "@turbopuffer/sdk";

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

#### Python

```python
import turbopuffer as tpuf

tpuf.api_key = os.environ["TURBOPUFFER_API_KEY"]
ns = tpuf.Namespace("my-namespace", region="gcp-us-central1")
```

## Write documents

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

#### TypeScript

```typescript
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 },
  },
});
```

#### Python

```python
ns.upsert(
    rows=[
        {"id": "1", "vector": [0.1, 0.2, 0.3], "text": "turbopuffer is fast", "category": "product"},
        {"id": "2", "vector": [0.4, 0.5, 0.6], "text": "vector search at scale", "category": "search"},
    ],
    schema={
        "text": {"type": "string", "full_text_search": True},
        "category": {"type": "string", "filterable": True},
    },
)
```

## Run a vector search

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

#### TypeScript

```typescript
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);
}
```

#### Python

```python
results = ns.query(
    rank_by=["vector", "ANN", [0.1, 0.2, 0.3]],
    top_k=10,
    filters=["category", "Eq", "product"],
    include_attributes=["text", "category"],
)

for row in results:
    print(row.id, row.attributes)
```

## Run a full-text search

Search across text attributes using BM25:

#### TypeScript

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

#### Python

```python
results = ns.query(
    rank_by=["text", "BM25", "vector search"],
    top_k=10,
)
```

## List namespaces

#### TypeScript

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

#### Python

```python
for ns in tpuf.namespaces():
    print(ns.id)
```

## Next steps

#### [Vector Search Guide](/docs/guides/vector-search)

Deep dive into ANN, kNN, and embedding models.

#### [Full-Text Search Guide](/docs/guides/full-text-search)

BM25 configuration, tokenizers, and language support.

#### [API Reference](/docs/api)

Complete reference for all endpoints and types.