OracleDB 벡터 저장소
OracleVectorOracle 데이터베이스에 임베딩을 저장합니다.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)을 직접 전달하거나, OracleStore에서 사용하는 풀을 공유하려면 poolManager를 전달하세요. 벡터 관련 옵션은 다음과 같습니다.
id:
poolManager?:
OracleStore와 하나의 Oracle 풀을 공유할 때 사용하세요.schemaName?:
tablePrefix?:
registryTableName?:
defaultIndexConfig?:
defaultMetadataIndexes?:
defaultVectorFormat?:
upsertBatchSize?:
executeMany 호출당 전송할 벡터 수입니다. 전체 업서트는 모든 배치가 성공한 후 한 번만 커밋됩니다.생성자 예생성자 예에 대한 직접 링크
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 Memory가 필요합니다. 로컬 또는 자체 관리형 데이터베이스에서는 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 벡터 인덱스를 삭제하고 다시 생성합니다.
인덱스 진단인덱스 진단에 대한 직접 링크
Oracle 카탈로그 상태를 확인하려면 getIndexStatus({ indexName })를 사용하고, 근사 인덱스에서 DBMS_VECTOR.INDEX_ACCURACY_QUERY를 실행하려면 indexAccuracyQuery({ indexName, queryVector, topK, targetAccuracy })를 사용하세요.
configureVectorMemory()configurevectormemory에 대한 직접 링크
HNSW 인덱스에 필요한 Oracle Vector Pool Memory를 할당합니다. 이 호출은 ALTER SYSTEM SET VECTOR_MEMORY_SIZE를 실행하므로 SYSDBA 또는 SYSTEM 같은 권한 있는 연결이 필요합니다.
size:
K, M 또는 G를 붙입니다(예: "512M").scope?:
disconnect()disconnect에 대한 직접 링크
OracleVector가 풀 관리자를 생성한 경우 Oracle 풀을 닫습니다. pool 또는 poolManager를 제공한 경우 해당 수명 주기는 사용자가 관리해야 합니다.
메타데이터 필터메타데이터 필터에 대한 직접 링크
OracleVectorMastra의 표준 메타데이터 필터 구문을 허용합니다. 필터는 바인딩된 값을 사용하여 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 Tool을 사용하여 행을 직접 읽을 수도 있습니다.
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 },
},
}),
})