OracleDB 向量儲存

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

安裝

npm

npm install @mastra/oracledb@latest

pnpm

pnpm add @mastra/oracledb@latest

Yarn

yarn add @mastra/oracledb@latest

Bun

bun add @mastra/oracledb@latest

使用方式

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

= 'MASTRA_VEC'

Oracle 實體向量資料表使用的前綴。

registryTableName?:

string

= 'MASTRA_VECTOR_INDEXES'

用於將 Mastra 邏輯索引名稱對應至實體向量資料表的 Oracle 資料表。

defaultIndexConfig?:

OracleVectorIndexConfig

= { type: 'none', accuracy: 95 }

預設 Oracle 向量索引設定。

defaultMetadataIndexes?:

string[]

= ['thread_id', 'resource_id', 'message_id', 'source_id']

建立向量資料表時自動建立索引的中繼資料欄位。

defaultVectorFormat?:

'vector' | 'bit' | 'int8'

= 'vector'

密集、二進位與 int8 嵌入的預設 Oracle 向量格式。

upsertBatchSize?:

number

= 200

每次 Oracle executeMany 呼叫傳送的向量數量。所有批次成功後，完整 upsert 只會提交一次。

建構函式範例

與 OracleStore 共用連線池

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'

= cosine

相似度搜尋使用的距離度量。二進位向量支援 hamming 和 jaccard。

vectorFormat?:

'vector' | 'bit' | 'int8'

= vector

Oracle 向量儲存格式。

indexConfig?:

OracleVectorIndexConfig

= { type: 'none', accuracy: 95 }

Oracle 向量索引設定。none 代表使用精確搜尋，不建立近似向量索引。

buildIndex?:

boolean

= true

當 indexConfig.type 為 ivf 或 hnsw 時，是否建置 Oracle 向量索引。

metadataIndexes?:

string[]

要建立索引的中繼資料欄位名稱，以加快 JSON 中繼資料篩選。

OracleVectorIndexConfig

type?:

'none' | 'ivf' | 'hnsw'

= 'none'

Oracle 向量索引型別。

accuracy?:

number

= 95

近似向量搜尋的目標準確度。

ivf.neighborPartitions?:

number

Oracle IVF 鄰近分割區設定。

hnsw.neighbors?:

number

Oracle HNSW 鄰近節點設定。

hnsw.efConstruction?:

number

Oracle HNSW 建置時的建構設定。

索引設定

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

= 10

要傳回的結果數量。

filter?:

Record<string, any>

轉譯為 Oracle JSON 述詞的 Mastra 中繼資料篩選條件。

includeVector?:

boolean

= false

每筆結果是否包含向量。

minScore?:

number

= -1

最低相似度分數門檻。

queryMode?:

'exact' | 'approx'

Oracle 查詢模式。未設定近似向量索引時，預設使用精確搜尋。

targetAccuracy?:

number

Oracle 近似向量查詢的目標準確度。

listIndexes()

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

describeIndex()

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

deleteIndex()

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

updateVector()

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

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'

= 'MEMORY'

Oracle ALTER SYSTEM 範圍。使用 'SPFILE' 或 'BOTH'，讓設定在資料庫重新啟動後仍然有效。

disconnect()

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

中繼資料篩選條件

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

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

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：

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 },
})

回應型別

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

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

使用範例

src/mastra/agents/oracle-agent.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 儲存
• 中繼資料篩選條件
• 向量資料庫