> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# OracleDB 벡터 저장소

`OracleVector`Oracle 데이터베이스에 임베딩을 저장합니다.`VECTOR`열을 생성하고 Mastra의 벡터 인터페이스를 통해 노출합니다. 각 논리적 Mastra 벡터 인덱스는 레지스트리 테이블을 통해 Oracle 벡터 테이블에 매핑되는 반면, 메타데이터는 구조적 필터링을 위해 Oracle JSON으로 저장됩니다.

## 설치

**npm**:

```bash
npm install @mastra/oracledb@latest
```

**pnpm**:

```bash
pnpm add @mastra/oracledb@latest
```

**Yarn**:

```bash
yarn add @mastra/oracledb@latest
```

**Bun**:

```bash
bun add @mastra/oracledb@latest
```

## 용법

```ts
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** (`string`): 이 벡터 저장소 인스턴스의 고유 식별자입니다.

**poolManager** (`OraclePoolManager`): 공유 Oracle 풀 관리자입니다. OracleStore와 하나의 Oracle 풀을 공유할 때 사용하세요.

**schemaName** (`string`): 벡터 레지스트리와 벡터 테이블을 한정하는 데 사용할 Oracle 스키마 이름입니다.

**tablePrefix** (`string`): 물리적 Oracle 벡터 테이블에 사용할 접두사입니다. (Default: `'MASTRA_VEC'`)

**registryTableName** (`string`): Mastra 논리 인덱스 이름을 물리적 벡터 테이블에 매핑하는 데 사용할 Oracle 테이블입니다. (Default: `'MASTRA_VECTOR_INDEXES'`)

**defaultIndexConfig** (`OracleVectorIndexConfig`): 기본 Oracle 벡터 인덱스 구성입니다. (Default: `{ type: 'none', accuracy: 95 }`)

**defaultMetadataIndexes** (`string[]`): 벡터 테이블을 생성할 때 자동으로 인덱싱할 메타데이터 필드입니다. (Default: `['thread_id', 'resource_id', 'message_id', 'source_id']`)

**defaultVectorFormat** (`'vector' | 'bit' | 'int8'`): 밀집, 이진 및 int8 임베딩에 사용할 기본 Oracle 벡터 형식입니다. (Default: `'vector'`)

**upsertBatchSize** (`number`): Oracle executeMany 호출당 전송할 벡터 수입니다. 전체 업서트는 모든 배치가 성공한 후 한 번만 커밋됩니다. (Default: `200`)

## 생성자 예

### OracleStore와 공유 풀

```ts
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`): 벡터 차원입니다. 임베딩 Model의 출력 크기와 일치해야 합니다.

**metric** (`'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'`): 유사도 검색에 사용할 거리 메트릭입니다. 이진 벡터는 hamming 및 jaccard를 지원합니다. (Default: `cosine`)

**vectorFormat** (`'vector' | 'bit' | 'int8'`): Oracle 벡터 저장 형식입니다. (Default: `vector`)

**indexConfig** (`OracleVectorIndexConfig`): Oracle 벡터 인덱스 구성입니다. none은 근사 벡터 인덱스 없이 정확 검색을 사용한다는 의미입니다. (Default: `{ type: 'none', accuracy: 95 }`)

**buildIndex** (`boolean`): indexConfig.type이 ivf 또는 hnsw일 때 Oracle 벡터 인덱스를 빌드할지 여부입니다. (Default: `true`)

**metadataIndexes** (`string[]`): JSON 메타데이터 필터링 속도를 높이기 위해 인덱싱할 메타데이터 필드 이름입니다.

#### `OracleVectorIndexConfig`

**type** (`'none' | 'ivf' | 'hnsw'`): Oracle 벡터 인덱스 유형입니다. (Default: `'none'`)

**accuracy** (`number`): 근사 벡터 검색의 목표 정확도입니다. (Default: `95`)

**ivf.neighborPartitions** (`number`): Oracle IVF 인접 파티션 설정입니다.

**hnsw\.neighbors** (`number`): Oracle HNSW 인접 항목 설정입니다.

**hnsw\.efConstruction** (`number`): Oracle HNSW 빌드 시 구성 설정입니다.

#### 인덱스 구성

```ts
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()`

**indexName** (`string`): 벡터를 업서트할 인덱스의 이름입니다.

**vectors** (`number[][]`): 임베딩 벡터 배열입니다.

**metadata** (`Record<string, any>[]`): Oracle JSON으로 저장되는 메타데이터입니다. vectors와 위치별로 일치해야 합니다.

**ids** (`string[]`): 선택적 벡터 ID입니다. 생략하면 ID가 생성됩니다.

### `query()`

**indexName** (`string`): 쿼리할 인덱스의 이름입니다.

**queryVector** (`number[]`): 쿼리 벡터입니다.

**topK** (`number`): 반환할 결과 수입니다. (Default: `10`)

**filter** (`Record<string, any>`): Oracle JSON 조건자로 변환되는 Mastra 메타데이터 필터입니다.

**includeVector** (`boolean`): 각 결과에 벡터를 포함할지 여부입니다. (Default: `false`)

**minScore** (`number`): 최소 유사도 점수 임계값입니다. (Default: `-1`)

**queryMode** (`'exact' | 'approx'`): Oracle 쿼리 모드입니다. 근사 벡터 인덱스가 구성되지 않은 경우 기본적으로 정확 검색을 사용합니다.

**targetAccuracy** (`number`): Oracle 근사 벡터 쿼리의 목표 정확도입니다.

### `listIndexes()`

Oracle 벡터 레지스트리 테이블에 기록된 논리적 Mastra 인덱스 이름을 반환합니다.

### `describeIndex()`

물리적 테이블 이름, 차원, 벡터 수, 지표, 인덱스 유형, 벡터 형식 및 구성된 정확도를 포함한 Oracle 인덱스 메타데이터를 반환합니다.

### `deleteIndex()`

Oracle 벡터 테이블을 삭제하고 논리 인덱스에 대한 레지스트리 항목을 제거합니다.

### `updateVector()`

ID 또는 메타데이터 필터를 기준으로 벡터를 업데이트합니다. `id` 또는 `filter` 중 하나만 제공해야 합니다. `update` 객체에는 `vector`, `metadata` 또는 둘 다 포함할 수 있습니다.

```ts
await vector.updateVector({
  indexName: 'support_articles',
  id: 'doc-1',
  update: { metadata: { status: 'reviewed' } },
})
```

### `deleteVector()`

ID별로 단일 벡터를 삭제합니다.

### `deleteVectors()`

ID 또는 메타데이터 필터를 기준으로 여러 벡터를 삭제합니다. `ids` 또는 `filter` 중 하나만 제공해야 합니다.

### `buildIndex()`

기존 논리 인덱스의 Oracle 벡터 인덱스를 빌드합니다. 확인된 인덱스 유형이 `none`이면 이 메서드는 아무 작업도 하지 않습니다.

### `rebuildIndex()`

일반적으로 대략적인 인덱스 조정을 변경한 후 기존 논리 인덱스에 대한 Oracle 벡터 인덱스를 삭제하고 다시 생성합니다.

### 인덱스 진단

Oracle 카탈로그 상태를 확인하려면 `getIndexStatus({ indexName })`를 사용하고, 근사 인덱스에서 `DBMS_VECTOR.INDEX_ACCURACY_QUERY`를 실행하려면 `indexAccuracyQuery({ indexName, queryVector, topK, targetAccuracy })`를 사용하세요.

### `configureVectorMemory()`

HNSW 인덱스에 필요한 Oracle Vector Pool Memory를 할당합니다. 이 호출은 `ALTER SYSTEM SET VECTOR_MEMORY_SIZE`를 실행하므로 `SYSDBA` 또는 `SYSTEM` 같은 권한 있는 연결이 필요합니다.

**size** (`string`): Vector Pool 크기입니다. 정수 뒤에 선택적으로 K, M 또는 G를 붙입니다(예: "512M").

**scope** (`'MEMORY' | 'SPFILE' | 'BOTH'`): Oracle ALTER SYSTEM 범위입니다. 데이터베이스를 재시작한 후에도 설정을 유지하려면 'SPFILE' 또는 'BOTH'를 사용하세요. (Default: `'MEMORY'`)

### `disconnect()`

`OracleVector`가 풀 관리자를 생성한 경우 Oracle 풀을 닫습니다. `pool` 또는 `poolManager`를 제공한 경우 해당 수명 주기는 사용자가 관리해야 합니다.

## 메타데이터 필터

`OracleVector`Mastra의 표준 메타데이터 필터 구문을 허용합니다. 필터는 바인딩된 값을 사용하여 Oracle JSON 조건자로 변환됩니다.

- 스칼라 비교 사용`JSON_VALUE`
- 배열, 존재 및 요소 일치 검사 사용`JSON_EXISTS`
- 정규식 필터 사용`REGEXP_LIKE`
- 문자열에는 대소문자를 구분하지 않는 필터가 포함되어 있습니다.`LIKE`

```ts
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`를 사용하세요.

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

## 응답 유형

쿼리 결과는 다음 형식으로 반환됩니다.

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

## 사용예

```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 스토리지](https://mastra.zisheng.pro/ko/reference/storage/oracledb)
- [메타데이터 필터](https://mastra.zisheng.pro/ko/reference/rag/metadata-filters)
- [벡터 데이터베이스](https://mastra.zisheng.pro/ko/guides/rag/vector-databases)