> 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.

# Vector Search

## Overview

turbopuffer supports both approximate nearest neighbor (ANN) search for speed at scale, and exact kNN search for recall-critical workloads. Both operate over dense float vector embeddings stored in your namespace.

## ANN search

ANN search uses an index to find the nearest neighbors quickly, trading a small amount of recall for significant speed gains at scale.

```typescript
const results = await client.namespaces.query("my-namespace", {
  rankBy: ["vector", "ANN", queryVector],
  topK: 20,
  distanceMetric: "cosine_distance",
});
```

## Exact kNN search

kNN performs an exhaustive search — guaranteed recall, slower on large datasets.

```typescript
const results = await client.namespaces.query("my-namespace", {
  rankBy: ["vector", "kNN", queryVector],
  topK: 20,
});
```

## Distance metrics

| Metric              | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `cosine_distance`   | `1 - cosine_similarity`. Ranges 0–2. Lower is better. |
| `euclidean_squared` | `sum((x - y)^2)`. Lower is better.                    |

## Auto-embedding

turbopuffer can generate embeddings automatically from a text attribute using a hosted model:

```typescript
await client.namespaces.write("my-namespace", {
  schema: {
    text: {
      type: "string",
      embed: { model: "text-embedding-3-small" },
    },
  },
});
```

Then query using an `Embed` expression instead of a raw vector:

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