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

# DatabaseConfig

使用向量查詢 Tool 時，`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）
- 環境隔離（開發／預備／正式環境各自使用不同的 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`）
- 必須看見最新資料的「讀到自己的寫入」工作流程（`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. **文件**：記錄具體設定選擇，供團隊成員參考

## 移轉指南

現有的向量查詢 Tool 無須變更即可繼續運作。若要新增資料庫設定：

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

## 相關內容

- [createVectorQueryTool()](https://mastra.zisheng.pro/zh-TW/reference/tools/vector-query-tool)
- [混合向量搜尋](https://mastra.zisheng.pro/zh-TW/guides/rag/retrieval)
- [中繼資料篩選器](https://mastra.zisheng.pro/zh-TW/reference/rag/metadata-filters)