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、ウォレットオプション、externalAuth）を直接渡すか、poolManager を渡して OracleStore が使用するプールを共有します。ベクトル固有のオプションは次のとおりです。
id:
poolManager?:
OracleStore と 1 つの Oracle プールを共有するための共有 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 },
},
}),
})