OracleDB 向量儲存
OracleVector 將嵌入向量儲存在 Oracle Database 的 VECTOR 欄位中，並透過 Mastra 的向量介面公開這些向量。每個 Mastra 邏輯向量索引都會透過登錄表映射至 Oracle 向量資料表，而中繼資料則以 Oracle JSON 儲存，以供結構化篩選使用。
安裝安裝 的直接連結
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/oracledb@latest
pnpm add @mastra/oracledb@latest
yarn add @mastra/oracledb@latest
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:
poolManager?:
OracleStore 共用同一個 Oracle 連線池。schemaName?:
tablePrefix?:
registryTableName?:
defaultIndexConfig?:
defaultMetadataIndexes?:
defaultVectorFormat?:
upsertBatchSize?:
executeMany 呼叫傳送的向量數目。所有批次均成功後，整個 upsert 才會提交一次。建構函式範例建構函式範例 的直接連結
與 OracleStore 共用連線池與 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()createindex 的直接連結
建立登錄列、實體 Oracle 向量資料表、中繼資料索引，並可選擇建立 Oracle 向量索引。
indexName:
dimension:
metric?:
hamming 和 jaccard。vectorFormat?:
indexConfig?:
none 表示使用精確搜尋，不設近似向量索引。buildIndex?:
indexConfig.type 為 ivf 或 hnsw 時，是否建立 Oracle 向量索引。metadataIndexes?:
OracleVectorIndexConfigoraclevectorindexconfig 的直接連結
type?:
accuracy?:
ivf.neighborPartitions?:
hnsw.neighbors?:
hnsw.efConstruction?:
索引設定索引設定 的直接連結
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()upsert 的直接連結
indexName:
vectors:
metadata?:
vectors 對應。ids?:
query()query 的直接連結
indexName:
queryVector:
topK?:
filter?:
includeVector?:
minScore?:
queryMode?:
targetAccuracy?:
listIndexes()listindexes 的直接連結
傳回記錄在 Oracle 向量登錄表中的 Mastra 邏輯索引名稱。
describeIndex()describeindex 的直接連結
傳回 Oracle 索引中繼資料，包括實體資料表名稱、維度、向量數目、度量、索引類型、向量格式及已設定的準確度。
deleteIndex()deleteindex 的直接連結
刪除 Oracle 向量資料表，並移除邏輯索引的登錄項目。
updateVector()updatevector 的直接連結
按 ID 或中繼資料篩選器更新向量。必須提供 id 或 filter 其中之一，但不可同時提供。update 物件可以包括 vector、metadata，或同時包括兩者。
await vector.updateVector({
indexName: 'support_articles',
id: 'doc-1',
update: { metadata: { status: 'reviewed' } },
})
deleteVector()deletevector 的直接連結
按 ID 刪除單一向量。
deleteVectors()deletevectors 的直接連結
按 ID 或中繼資料篩選器刪除多個向量。必須提供 ids 或 filter 其中之一，但不可同時提供。
buildIndex()buildindex 的直接連結
為現有的邏輯索引建立 Oracle 向量索引。如解析出的索引類型為 none，此方法不會執行任何操作。
rebuildIndex()rebuildindex 的直接連結
刪除並重新建立現有邏輯索引的 Oracle 向量索引，通常在變更近似索引調整設定後使用。
索引診斷索引診斷 的直接連結
使用 getIndexStatus({ indexName }) 檢查 Oracle 目錄狀態，並使用 indexAccuracyQuery({ indexName, queryVector, topK, targetAccuracy }) 對近似索引執行 DBMS_VECTOR.INDEX_ACCURACY_QUERY。
configureVectorMemory()configurevectormemory 的直接連結
分配 HNSW 索引所需的 Oracle Vector Pool 記憶體。此方法會呼叫 ALTER SYSTEM SET VECTOR_MEMORY_SIZE，因此需要具權限的連線，例如 SYSDBA 或 SYSTEM。
size:
K、M 或 G（例如 "512M"）。scope?:
disconnect()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[]
}
使用範例使用範例 的直接連結
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 },
},
}),
})