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

# DatabaseConfig

使用向量查询工具时，`DatabaseConfig` 类型允许你指定数据库专属配置。这些配置让你能够使用不同向量存储提供的功能和优化。

## 类型定义

```typescript
export type DatabaseConfig = {
  pinecone?: PineconeConfig
  pgvector?: PgVectorConfig
  chroma?: ChromaConfig
  turbopuffer?: TurbopufferConfig
  [key: string]: any // Extensible for future databases
}
```

## 数据库专属类型

### `PineconeConfig`

Pinecone 向量存储专属的配置选项。

**namespace** (`string`): Pinecone namespace，用于在同一索引中组织和隔离向量。适用于多租户或环境隔离。

**sparseVector** (`{ indices: number[]; values: number[]; }`): 用于混合搜索的稀疏向量，可结合稠密嵌入和稀疏嵌入。可提升基于关键词的查询质量。indices 和 values 数组必须具有相同长度。

**sparseVector.indices** (`number[]`): 稀疏向量组件的索引数组

**sparseVector.values** (`number[]`): 与索引对应的值数组

**使用场景：**

- 多租户应用（每个租户使用独立 namespace）
- 环境隔离（dev/staging/prod namespace）
- 结合语义匹配和关键词匹配的混合搜索

### `PgVectorConfig`

带有 pgvector 扩展的 PostgreSQL 专属配置选项。

**minScore** (`number`): 结果的最低相似度分数阈值。仅返回相似度分数高于此值的向量。

**ef** (`number`): HNSW 搜索参数，用于控制搜索期间动态候选列表的大小。值越高，准确度越高，但速度越慢。通常设置在 topK 到 200 之间。

**probes** (`number`): IVFFlat probe 参数，用于指定搜索期间要访问的索引单元数量。值越高，召回率越高，但速度越慢。

**性能指南：**

- **ef**：从 topK 值的 2–4 倍开始，需要更高准确度时再增加
- **probes**：从 1–10 开始，需要更高召回率时再增加
- **minScore**：根据质量要求使用介于 0.5–0.9 的值

**使用场景：**

- 高负载场景的性能优化
- 通过质量过滤移除无关结果
- 微调搜索准确度与速度之间的权衡

### `ChromaConfig`

Chroma 向量存储专属的配置选项。

**where** (`Record<string, any>`): 使用 MongoDB 风格查询语法的元数据过滤条件。根据元数据字段过滤结果。

**whereDocument** (`Record<string, any>`): 文档内容过滤条件。允许基于实际文档文本内容进行过滤。

**过滤语法示例：**

```typescript
// Simple equality
where: { "category": "technical" }

// Operators
where: { "price": { "$gt": 100 } }

// Multiple conditions
where: {
  "category": "electronics",
  "inStock": true
}

// Document content filtering
whereDocument: { "$contains": "API documentation" }
```

**使用场景：**

- 高级元数据过滤
- 基于内容的文档过滤
- 复杂查询组合

### `TurbopufferConfig`

Turbopuffer 向量存储专属的配置选项。

**consistency** (`'strong' | 'eventual'`): 查询的一致性级别。"strong"（默认值）保证查询可看到查询开始前写入的所有数据，但延迟更高。"eventual" 延迟较低，但最近写入的数据可能暂时不可见。

**使用场景：**

- 可接受轻微陈旧数据的延迟敏感型查询（`eventual`）
- 必须看到最新数据的 read-your-writes 工作流（`strong`）

## 使用示例

**基本用法**:

### 基本数据库配置

```typescript
import { createVectorQueryTool } from '@mastra/rag'

const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'production',
    },
  },
})
```

**运行时覆盖**:

### 运行时配置覆盖

```typescript
import { RequestContext } from '@mastra/core/request-context'

// Initial configuration
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'development',
    },
  },
})

// Override at runtime
const requestContext = new RequestContext()
requestContext.set('databaseConfig', {
  pinecone: {
    namespace: 'production',
  },
})

await vectorTool.execute({ queryText: 'search query' }, { mastra, requestContext })
```

**多数据库**:

### 多数据库配置

```typescript
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'dynamic', // Will be determined at runtime
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'default',
    },
    pgvector: {
      minScore: 0.8,
      ef: 150,
    },
    chroma: {
      where: { type: 'documentation' },
    },
  },
})
```

> **备注:** **多数据库支持**：配置多个数据库时，只会应用与实际使用的向量存储相匹配的配置。

**性能调优**:

### 性能调优

```typescript
// High accuracy configuration
const highAccuracyTool = createVectorQueryTool({
  vectorStoreName: 'postgres',
  indexName: 'embeddings',
  model: embedModel,
  databaseConfig: {
    pgvector: {
      ef: 400, // High accuracy
      probes: 20, // High recall
      minScore: 0.85, // High quality threshold
    },
  },
})

// High speed configuration
const highSpeedTool = createVectorQueryTool({
  vectorStoreName: 'postgres',
  indexName: 'embeddings',
  model: embedModel,
  databaseConfig: {
    pgvector: {
      ef: 50, // Lower accuracy, faster
      probes: 3, // Lower recall, faster
      minScore: 0.6, // Lower quality threshold
    },
  },
})
```

## 可扩展性

`DatabaseConfig` 类型设计为可扩展。要添加对新向量数据库的支持：

```typescript
// 1. Define the configuration interface
export interface NewDatabaseConfig {
  customParam1?: string
  customParam2?: number
}

// 2. Extend DatabaseConfig type
export type DatabaseConfig = {
  pinecone?: PineconeConfig
  pgvector?: PgVectorConfig
  chroma?: ChromaConfig
  newdatabase?: NewDatabaseConfig
  [key: string]: any
}

// 3. Use in vector query tool
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'newdatabase',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    newdatabase: {
      customParam1: 'value',
      customParam2: 42,
    },
  },
})
```

## 最佳实践

1. **环境配置**：为不同环境使用不同的 namespace 或配置
2. **性能调优**：从默认值开始，并根据具体需求调整
3. **质量过滤**：使用 minScore 过滤低质量结果
4. **运行时灵活性**：针对运行时定义的场景在运行时覆盖配置
5. **文档**：为团队成员记录具体的配置选择

## 迁移指南

现有向量查询工具无需更改即可继续工作。要添加数据库配置：

```diff
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
+ databaseConfig: {
+   pinecone: {
+     namespace: 'production'
+   }
+ }
});
```

## 相关内容

- [createVectorQueryTool()](https://mastra.zisheng.pro/reference/tools/vector-query-tool)
- [混合向量搜索](https://mastra.zisheng.pro/guides/rag/retrieval)
- [元数据过滤器](https://mastra.zisheng.pro/reference/rag/metadata-filters)