OracleDB Vector 存储
OracleVector 将嵌入存储在 Oracle Database 的 VECTOR 列中，并通过 Mastra 的 Vector 接口公开。每个逻辑 Mastra Vector 索引都通过注册表映射到一个 Oracle Vector 表，而元数据则以 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 使用精确搜索，不创建近似 Vector 索引。当数据集和延迟要求需要近似搜索时，可配置 IVF 或 HNSW。
构造函数选项构造函数选项的直接链接
直接传入 Oracle 连接选项（user、password、connectString、pool、wallet 选项或 externalAuth），或者传入 poolManager，以共享 OracleStore 使用的连接池。Vector 专用选项如下：
id:
poolManager?:
OracleStore 共享同一个 Oracle 连接池。schemaName?:
tablePrefix?:
registryTableName?:
defaultIndexConfig?:
defaultMetadataIndexes?:
defaultVectorFormat?:
upsertBatchSize?:
executeMany 调用发送的 Vector 数量。所有批次均成功后，整个 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 Vector 表、元数据索引，并可选择创建 Oracle Vector 索引。
indexName:
dimension:
metric?:
hamming 和 jaccard。vectorFormat?:
indexConfig?:
none 表示使用精确搜索，不创建近似 Vector 索引。buildIndex?:
indexConfig.type 为 ivf 或 hnsw 时，是否构建 Oracle Vector 索引。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 Vector 注册表中记录的逻辑 Mastra 索引名称。
describeIndex()describeindex的直接链接
返回 Oracle 索引元数据，包括物理表名、维度、Vector 数量、度量、索引类型、Vector 格式和配置的准确率。
deleteIndex()deleteindex的直接链接
删除 Oracle Vector 表，并移除逻辑索引的注册表条目。
updateVector()updatevector的直接链接
按 ID 或元数据筛选条件更新 Vector。必须提供 id 或 filter，但不能同时提供两者。update 对象可以包含 vector、metadata 或两者。
await vector.updateVector({
indexName: 'support_articles',
id: 'doc-1',
update: { metadata: { status: 'reviewed' } },
})
deleteVector()deletevector的直接链接
按 ID 删除单个 Vector。
deleteVectors()deletevectors的直接链接
按 ID 或元数据筛选条件删除多个 Vector。必须提供 ids 或 filter，但不能同时提供两者。
buildIndex()buildindex的直接链接
为现有逻辑索引构建 Oracle Vector 索引。如果解析后的索引类型为 none，此方法不会执行任何操作。
rebuildIndex()rebuildindex的直接链接
删除并重新创建现有逻辑索引的 Oracle Vector 索引，通常用于更改近似索引的调优设置后。
索引诊断索引诊断的直接链接
使用 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 应生成与 Oracle 兼容的元数据筛选条件时，请使用 ORACLEDB_PROMPT 配合 createVectorQueryTool()：
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 },
},
}),
})