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

# OracleDB 向量儲存

`OracleVector` 會將嵌入儲存在 Oracle Database 的 `VECTOR` 欄位中，並透過 Mastra 向量介面公開。每個 Mastra 邏輯向量索引都會透過登錄資料表對應至 Oracle 向量資料表，而中繼資料則以 Oracle JSON 儲存，供結構化篩選使用。

## 安裝

**npm**:

```bash
npm install @mastra/oracledb@latest
```

**pnpm**:

```bash
pnpm add @mastra/oracledb@latest
```

**Yarn**:

```bash
yarn add @mastra/oracledb@latest
```

**Bun**:

```bash
bun add @mastra/oracledb@latest
```

## 使用方式

```ts
import { OracleVector } from '@mastra/oracledb'

const vector = new OracleVector({
  id: 'oracle-vector',
  user: process.env.ORACLE_DATABASE_USER,
  password: process.env.ORACLE_DATABASE_PASSWORD,
  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
})

await vector.createIndex({
  indexName: 'memory_messages',
  dimension: 1536,
  metric: 'cosine',
})

await vector.upsert({
  indexName: 'memory_messages',
  vectors: [embedding],
  metadata: [{ resource_id: 'user-1', thread_id: 'thread-1' }],
})

const results = await vector.query({
  indexName: 'memory_messages',
  queryVector,
  topK: 5,
  filter: { resource_id: 'user-1' },
})
```

`OracleVector` 預設使用精確搜尋，不建立近似向量索引。當資料集與延遲需求需要近似搜尋時，請設定 IVF 或 HNSW。

## 建構函式選項

直接傳入 Oracle 連線選項（`user`、`password`、`connectString`、`pool`、wallet 選項或 `externalAuth`），或傳入 `poolManager` 以共用 `OracleStore` 使用的連線池。向量專用選項如下：

**id** (`string`): 此向量儲存執行個體的不重複識別碼。

**poolManager** (`OraclePoolManager`): 共用的 Oracle 連線池管理器。使用此選項與 OracleStore 共用一個 Oracle 連線池。

**schemaName** (`string`): 用於限定向量登錄與向量資料表的 Oracle schema 名稱。

**tablePrefix** (`string`): Oracle 實體向量資料表使用的前綴。 (Default: `'MASTRA_VEC'`)

**registryTableName** (`string`): 用於將 Mastra 邏輯索引名稱對應至實體向量資料表的 Oracle 資料表。 (Default: `'MASTRA_VECTOR_INDEXES'`)

**defaultIndexConfig** (`OracleVectorIndexConfig`): 預設 Oracle 向量索引設定。 (Default: `{ type: 'none', accuracy: 95 }`)

**defaultMetadataIndexes** (`string[]`): 建立向量資料表時自動建立索引的中繼資料欄位。 (Default: `['thread_id', 'resource_id', 'message_id', 'source_id']`)

**defaultVectorFormat** (`'vector' | 'bit' | 'int8'`): 密集、二進位與 int8 嵌入的預設 Oracle 向量格式。 (Default: `'vector'`)

**upsertBatchSize** (`number`): 每次 Oracle executeMany 呼叫傳送的向量數量。所有批次成功後，完整 upsert 只會提交一次。 (Default: `200`)

## 建構函式範例

### 與 OracleStore 共用連線池

```ts
import { OracleStore, OracleVector } from '@mastra/oracledb'

const storage = new OracleStore({ id: 'oracle-storage', user, password, connectString })

const vector = new OracleVector({
  id: 'oracle-vector',
  poolManager: storage.getPoolManager(),
})
```

對於 Autonomous Database 與 mTLS 連線，請在同一個建構函式中傳入 `walletLocation`、`walletPassword` 和 `configDir`。

## 方法

### `createIndex()`

建立登錄資料列、Oracle 實體向量資料表、中繼資料索引，並可選擇建立 Oracle 向量索引。

**indexName** (`string`): Mastra 邏輯索引名稱。Provider 會在內部將其對應至有效的 Oracle 資料表名稱。

**dimension** (`number`): 向量維度。這必須與嵌入模型的輸出大小相符。

**metric** (`'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'`): 相似度搜尋使用的距離度量。二進位向量支援 hamming 和 jaccard。 (Default: `cosine`)

**vectorFormat** (`'vector' | 'bit' | 'int8'`): Oracle 向量儲存格式。 (Default: `vector`)

**indexConfig** (`OracleVectorIndexConfig`): Oracle 向量索引設定。none 代表使用精確搜尋，不建立近似向量索引。 (Default: `{ type: 'none', accuracy: 95 }`)

**buildIndex** (`boolean`): 當 indexConfig.type 為 ivf 或 hnsw 時，是否建置 Oracle 向量索引。 (Default: `true`)

**metadataIndexes** (`string[]`): 要建立索引的中繼資料欄位名稱，以加快 JSON 中繼資料篩選。

#### `OracleVectorIndexConfig`

**type** (`'none' | 'ivf' | 'hnsw'`): Oracle 向量索引型別。 (Default: `'none'`)

**accuracy** (`number`): 近似向量搜尋的目標準確度。 (Default: `95`)

**ivf.neighborPartitions** (`number`): Oracle IVF 鄰近分割區設定。

**hnsw\.neighbors** (`number`): Oracle HNSW 鄰近節點設定。

**hnsw\.efConstruction** (`number`): Oracle HNSW 建置時的建構設定。

#### 索引設定

```ts
await vector.createIndex({
  indexName: 'support_articles',
  dimension: 1536,
  metric: 'cosine',
  indexConfig: {
    type: 'ivf',
    accuracy: 95,
    ivf: {
      neighborPartitions: 32,
    },
  },
})
```

預設為 `indexConfig: { type: 'none' }`，使用精確搜尋且不需調校近似索引。只有當資料量與延遲需求足以支援使用近似搜尋時，才使用 IVF 或 HNSW。HNSW 透過 `indexConfig: { type: 'hnsw', hnsw: { neighbors, efConstruction } }` 設定，且需要 Oracle Vector Pool 記憶體；本機或自行管理的資料庫可使用 `configureVectorMemory()` 設定該記憶體。

### `upsert()`

**indexName** (`string`): 要 upsert 向量的索引名稱。

**vectors** (`number[][]`): 嵌入向量陣列。

**metadata** (`Record<string, any>[]`): 以 Oracle JSON 儲存的中繼資料。位置必須與 vectors 對齊。

**ids** (`string[]`): 選用的向量 ID。省略時會產生 ID。

### `query()`

**indexName** (`string`): 要查詢的索引名稱。

**queryVector** (`number[]`): 查詢向量。

**topK** (`number`): 要傳回的結果數量。 (Default: `10`)

**filter** (`Record<string, any>`): 轉譯為 Oracle JSON 述詞的 Mastra 中繼資料篩選條件。

**includeVector** (`boolean`): 每筆結果是否包含向量。 (Default: `false`)

**minScore** (`number`): 最低相似度分數門檻。 (Default: `-1`)

**queryMode** (`'exact' | 'approx'`): Oracle 查詢模式。未設定近似向量索引時，預設使用精確搜尋。

**targetAccuracy** (`number`): Oracle 近似向量查詢的目標準確度。

### `listIndexes()`

傳回 Oracle 向量登錄資料表中記錄的 Mastra 邏輯索引名稱。

### `describeIndex()`

傳回 Oracle 索引中繼資料，包括實體資料表名稱、維度、向量數量、度量、索引型別、向量格式與設定的準確度。

### `deleteIndex()`

刪除 Oracle 向量資料表，並移除邏輯索引的登錄項目。

### `updateVector()`

依 ID 或中繼資料篩選條件更新向量。必須提供 `id` 或 `filter` 其中一項，但不能同時提供兩者。`update` 物件可包含 `vector`、`metadata` 或兩者。

```ts
await vector.updateVector({
  indexName: 'support_articles',
  id: 'doc-1',
  update: { metadata: { status: 'reviewed' } },
})
```

### `deleteVector()`

依 ID 刪除單一向量。

### `deleteVectors()`

依 ID 或中繼資料篩選條件刪除多個向量。必須提供 `ids` 或 `filter` 其中一項，但不能同時提供兩者。

### `buildIndex()`

為現有邏輯索引建置 Oracle 向量索引。如果解析出的索引型別為 `none`，此方法不會執行任何操作。

### `rebuildIndex()`

移除並重新建立現有邏輯索引的 Oracle 向量索引，通常用於變更近似索引調校後。

### 索引診斷

使用 `getIndexStatus({ indexName })` 檢查 Oracle 目錄狀態，並使用 `indexAccuracyQuery({ indexName, queryVector, topK, targetAccuracy })` 為近似索引執行 `DBMS_VECTOR.INDEX_ACCURACY_QUERY`。

### `configureVectorMemory()`

設定 HNSW 索引所需的 Oracle Vector Pool 記憶體。此方法會呼叫 `ALTER SYSTEM SET VECTOR_MEMORY_SIZE`，因此需要 `SYSDBA` 或 `SYSTEM` 等具權限的連線。

**size** (`string`): Vector Pool 大小，以整數表示，後面可接 K、M 或 G（例如 "512M"）。

**scope** (`'MEMORY' | 'SPFILE' | 'BOTH'`): Oracle ALTER SYSTEM 範圍。使用 'SPFILE' 或 'BOTH'，讓設定在資料庫重新啟動後仍然有效。 (Default: `'MEMORY'`)

### `disconnect()`

如果連線池管理器由 `OracleVector` 建立，此方法會關閉 Oracle 連線池。如果由你提供 `pool` 或 `poolManager`，則由你管理其生命週期。

## 中繼資料篩選條件

`OracleVector` 接受 Mastra 的標準中繼資料篩選語法。篩選條件會轉譯為具繫結值的 Oracle JSON 述詞：

- 純量比較使用 `JSON_VALUE`
- 陣列、存在性與元素比對檢查使用 `JSON_EXISTS`
- 規則運算式篩選使用 `REGEXP_LIKE`
- 字串包含篩選使用不區分大小寫的 `LIKE`

```ts
const results = await vector.query({
  indexName: 'memory_messages',
  queryVector,
  topK: 5,
  filter: {
    resource_id: 'user-1',
    tags: { $contains: 'support' },
    score: { $gte: 0.8 },
    $or: [{ source: 'docs' }, { source: 'tickets' }],
  },
})
```

中繼資料會儲存為原生 Oracle JSON，因此也可使用 DBeaver 與 SQL Developer 等標準 Oracle JDBC 工具直接讀取資料列。

當 Agent 應為 `createVectorQueryTool()` 產生與 Oracle 相容的中繼資料篩選條件時，請使用 `ORACLEDB_PROMPT`：

```ts
import { Agent } from '@mastra/core/agent'
import { createVectorQueryTool } from '@mastra/rag'
import { fastembed } from '@mastra/fastembed'
import { ORACLEDB_PROMPT } from '@mastra/oracledb'

const vectorQueryTool = createVectorQueryTool({
  vectorStoreName: 'oracle',
  indexName: 'support_articles',
  model: fastembed,
  enableFilter: true,
})

export const ragAgent = new Agent({
  id: 'oracle-rag-agent',
  name: 'Oracle RAG Agent',
  model: 'openai/gpt-5.6-sol',
  instructions: `
Use the retrieval tool when you need source context.
Available metadata fields: resource_id, thread_id, source, category, tags.
${ORACLEDB_PROMPT}
`,
  tools: { vectorQueryTool },
})
```

## 回應型別

查詢結果會以下列格式傳回：

```ts
interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[]
}
```

## 使用範例

```ts
import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { fastembed } from '@mastra/fastembed'
import { OracleStore, OracleVector } from '@mastra/oracledb'

const storage = new OracleStore({
  id: 'oracle-storage',
  user: process.env.ORACLE_DATABASE_USER,
  password: process.env.ORACLE_DATABASE_PASSWORD,
  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
})

const vector = new OracleVector({
  id: 'oracle-vector',
  poolManager: storage.getPoolManager(),
})

export const oracleAgent = new Agent({
  id: 'oracle-agent',
  name: 'Oracle Agent',
  instructions: 'You are an assistant with OracleDB-backed memory and semantic recall.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage,
    vector,
    embedder: fastembed,
    options: {
      semanticRecall: { topK: 3, messageRange: 2 },
    },
  }),
})
```

## 相關內容

- [OracleDB 儲存](https://mastra.zisheng.pro/zh-TW/reference/storage/oracledb)
- [中繼資料篩選條件](https://mastra.zisheng.pro/zh-TW/reference/rag/metadata-filters)
- [向量資料庫](https://mastra.zisheng.pro/zh-TW/guides/rag/vector-databases)