> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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`): 向量池大小，以整數表示，其後可選擇加上 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-HK/reference/storage/oracledb)
- [中繼資料篩選器](https://mastra.zisheng.pro/zh-HK/reference/rag/metadata-filters)
- [向量資料庫](https://mastra.zisheng.pro/zh-HK/guides/rag/vector-databases)