> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Turbopuffer Vector 存储

TurbopufferVector 类使用 [Turbopuffer](https://turbopuffer.com/) 提供 Vector 搜索。Turbopuffer 是一个针对 RAG 应用优化的高性能 Vector 数据库，提供快速的 Vector 相似度搜索、高级过滤功能和高效的存储管理。

## 构造函数选项

**apiKey** (`string`): 用于向 Turbopuffer 进行身份验证的 API key

**baseUrl** (`string`): Turbopuffer API 的基础 URL (Default: `https://api.turbopuffer.com`)

**connectTimeout** (`number`): 建立连接的超时时间（毫秒）。仅适用于 Node 和 Deno。 (Default: `10000`)

**connectionIdleTimeout** (`number`): socket 空闲超时时间（毫秒）。仅适用于 Node 和 Deno。 (Default: `60000`)

**warmConnections** (`number`): 创建新客户端时最初打开的连接数。 (Default: `0`)

**compression** (`boolean`): 是否压缩请求并接受压缩响应。 (Default: `true`)

**consistency** (`'strong' | 'eventual'`): 查询的默认一致性级别。可为每次查询单独覆盖。"strong" 会以更高延迟为代价，保证查询能看到查询开始前写入的所有数据。"eventual" 延迟更低，但最近写入的数据可能尚不可见。 (Default: `strong`)

**schemaConfigForIndex** (`function`): 一个回调函数，接收索引名称并返回该索引的配置对象。你可以为每个索引定义显式 schema。

## 方法

### `createIndex()`

**indexName** (`string`): 要创建的索引名称

**dimension** (`number`): Vector 维度（必须与你的嵌入模型匹配）

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 用于相似度搜索的距离度量 (Default: `cosine`)

### `upsert()`

**vectors** (`number[][]`): 嵌入 Vector 数组

**metadata** (`Record<string, any>[]`): 每个 Vector 的元数据

**ids** (`string[]`): 可选的 Vector ID（未提供时自动生成）

### `query()`

**indexName** (`string`): 要查询的索引名称

**queryVector** (`number[]`): 用于查找相似 Vector 的查询 Vector

**topK** (`number`): 要返回的结果数量 (Default: `10`)

**filter** (`Record<string, any>`): 查询所用的元数据过滤条件

**includeVector** (`boolean`): 是否在结果中包含 Vector (Default: `false`)

**consistency** (`'strong' | 'eventual'`): 本次查询的一致性级别。会覆盖构造函数中设置的一致性级别。默认为 "strong"。

### `listIndexes()`

以字符串数组形式返回索引名称。

### `describeIndex()`

**indexName** (`string`): 要描述的索引名称

返回：

```typescript
interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}
```

### `deleteIndex()`

**indexName** (`string`): 要删除的索引名称

### `updateVector()`

按 ID 或元数据过滤条件更新单个 Vector。必须提供 `id` 或 `filter`，但不能同时提供两者。

**indexName** (`string`): 包含该 Vector 的索引名称

**id** (`string`): 要更新的 Vector ID（与 filter 互斥）

**filter** (`Record<string, any>`): 用于标识待更新 Vector 的元数据过滤条件（与 id 互斥）

**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): 包含待更新 Vector 和/或元数据的对象

### `deleteVector()`

**indexName** (`string`): 包含该 Vector 的索引名称

**id** (`string`): 要删除的 Vector ID

### `deleteVectors()`

按 ID 或元数据过滤条件删除多个 Vector。必须提供 `ids` 或 `filter`，但不能同时提供两者。

**indexName** (`string`): 包含待删除 Vector 的索引名称

**ids** (`string[]`): 要删除的 Vector ID 数组（与 filter 互斥）

**filter** (`Record<string, any>`): 用于标识待删除 Vector 的元数据过滤条件（与 ids 互斥）

## 响应类型

查询结果以以下格式返回：

```typescript
interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}
```

## Schema 配置

`schemaConfigForIndex` 选项允许你为不同索引定义显式 schema：

```typescript
schemaConfigForIndex: (indexName: string) => {
  // Mastra's default embedding model and index for memory messages:
  if (indexName === 'memory_messages_384') {
    return {
      dimensions: 384,
      schema: {
        thread_id: {
          type: 'string',
          filterable: true,
        },
      },
    }
  } else {
    throw new Error(`TODO: add schema for index: ${indexName}`)
  }
}
```

## 错误处理

该存储会抛出可捕获的类型化错误：

```typescript
try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}
```

## 相关内容

- [元数据过滤器](https://mastra.zisheng.pro/reference/rag/metadata-filters)