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

# OracleDB Vector 存储

`OracleVector` 将嵌入存储在 Oracle Database 的 `VECTOR` 列中，并通过 Mastra 的 Vector 接口公开。每个逻辑 Mastra Vector 索引都通过注册表映射到一个 Oracle Vector 表，而元数据则以 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` 使用精确搜索，不创建近似 Vector 索引。当数据集和延迟要求需要近似搜索时，可配置 IVF 或 HNSW。

## 构造函数选项

直接传入 Oracle 连接选项（`user`、`password`、`connectString`、`pool`、wallet 选项或 `externalAuth`），或者传入 `poolManager`，以共享 `OracleStore` 使用的连接池。Vector 专用选项如下：

**id** (`string`): 此 Vector 存储实例的唯一标识符。

**poolManager** (`OraclePoolManager`): 共享的 Oracle 连接池管理器。使用此选项可与 OracleStore 共享同一个 Oracle 连接池。

**schemaName** (`string`): 用于限定 Vector 注册表和 Vector 表的 Oracle schema 名称。

**tablePrefix** (`string`): 物理 Oracle Vector 表使用的前缀。 (Default: `'MASTRA_VEC'`)

**registryTableName** (`string`): 用于将 Mastra 逻辑索引名称映射到物理 Vector 表的 Oracle 表。 (Default: `'MASTRA_VECTOR_INDEXES'`)

**defaultIndexConfig** (`OracleVectorIndexConfig`): 默认 Oracle Vector 索引配置。 (Default: `{ type: 'none', accuracy: 95 }`)

**defaultMetadataIndexes** (`string[]`): 创建 Vector 表时自动建立索引的元数据字段。 (Default: `['thread_id', 'resource_id', 'message_id', 'source_id']`)

**defaultVectorFormat** (`'vector' | 'bit' | 'int8'`): 密集、二进制和 int8 嵌入使用的默认 Oracle Vector 格式。 (Default: `'vector'`)

**upsertBatchSize** (`number`): 每次 Oracle executeMany 调用发送的 Vector 数量。所有批次均成功后，整个 upsert 仅提交一次。 (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 Vector 表、元数据索引，并可选择创建 Oracle Vector 索引。

**indexName** (`string`): 逻辑 Mastra 索引名称。Provider 会在内部将其映射到有效的 Oracle 表名。

**dimension** (`number`): Vector 维度。该值必须与嵌入模型的输出大小一致。

**metric** (`'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'`): 相似度搜索使用的距离度量。二进制 Vector 支持 hamming 和 jaccard。 (Default: `cosine`)

**vectorFormat** (`'vector' | 'bit' | 'int8'`): Oracle Vector 存储格式。 (Default: `vector`)

**indexConfig** (`OracleVectorIndexConfig`): Oracle Vector 索引配置。none 表示使用精确搜索，不创建近似 Vector 索引。 (Default: `{ type: 'none', accuracy: 95 }`)

**buildIndex** (`boolean`): 当 indexConfig.type 为 ivf 或 hnsw 时，是否构建 Oracle Vector 索引。 (Default: `true`)

**metadataIndexes** (`string[]`): 要建立索引的元数据字段名称，以加快 JSON 元数据筛选。

#### `OracleVectorIndexConfig`

**type** (`'none' | 'ivf' | 'hnsw'`): Oracle Vector 索引类型。 (Default: `'none'`)

**accuracy** (`number`): 近似 Vector 搜索的目标准确率。 (Default: `95`)

**ivf.neighborPartitions** (`number`): Oracle IVF 相邻分区设置。

**hnsw\.neighbors** (`number`): Oracle HNSW 邻居设置。

**hnsw\.efConstruction** (`number`): Oracle HNSW 构建时的 construction 设置。

#### 索引配置

```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 内存；对于本地或自行管理的数据库，可使用 `configureVectorMemory()` 分配该内存。

### `upsert()`

**indexName** (`string`): 要 upsert Vector 的索引名称。

**vectors** (`number[][]`): 嵌入 Vector 数组。

**metadata** (`Record<string, any>[]`): 以 Oracle JSON 格式存储的元数据。必须按位置与 vectors 对齐。

**ids** (`string[]`): 可选的 Vector ID。省略时会生成 ID。

### `query()`

**indexName** (`string`): 要查询的索引名称。

**queryVector** (`number[]`): 查询 Vector。

**topK** (`number`): 要返回的结果数量。 (Default: `10`)

**filter** (`Record<string, any>`): 转换为 Oracle JSON 谓词的 Mastra 元数据筛选条件。

**includeVector** (`boolean`): 每个结果中是否包含 Vector。 (Default: `false`)

**minScore** (`number`): 最低相似度分数阈值。 (Default: `-1`)

**queryMode** (`'exact' | 'approx'`): Oracle 查询模式。未配置近似 Vector 索引时，默认使用精确搜索。

**targetAccuracy** (`number`): Oracle 近似 Vector 查询的目标准确率。

### `listIndexes()`

返回 Oracle Vector 注册表中记录的逻辑 Mastra 索引名称。

### `describeIndex()`

返回 Oracle 索引元数据，包括物理表名、维度、Vector 数量、度量、索引类型、Vector 格式和配置的准确率。

### `deleteIndex()`

删除 Oracle Vector 表，并移除逻辑索引的注册表条目。

### `updateVector()`

按 ID 或元数据筛选条件更新 Vector。必须提供 `id` 或 `filter`，但不能同时提供两者。`update` 对象可以包含 `vector`、`metadata` 或两者。

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

### `deleteVector()`

按 ID 删除单个 Vector。

### `deleteVectors()`

按 ID 或元数据筛选条件删除多个 Vector。必须提供 `ids` 或 `filter`，但不能同时提供两者。

### `buildIndex()`

为现有逻辑索引构建 Oracle Vector 索引。如果解析后的索引类型为 `none`，此方法不会执行任何操作。

### `rebuildIndex()`

删除并重新创建现有逻辑索引的 Oracle Vector 索引，通常用于更改近似索引的调优设置后。

### 索引诊断

使用 `getIndexStatus({ indexName })` 检查 Oracle 目录状态；使用 `indexAccuracyQuery({ indexName, queryVector, topK, targetAccuracy })` 针对近似索引运行 `DBMS_VECTOR.INDEX_ACCURACY_QUERY`。

### `configureVectorMemory()`

分配 HNSW 索引所需的 Oracle Vector Pool 内存。此方法会调用 `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 工具直接读取这些行。

当 Agent 应生成与 Oracle 兼容的元数据筛选条件时，请使用 `ORACLEDB_PROMPT` 配合 `createVectorQueryTool()`：

```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/reference/storage/oracledb)
- [元数据筛选器](https://mastra.zisheng.pro/reference/rag/metadata-filters)
- [Vector 数据库](https://mastra.zisheng.pro/guides/rag/vector-databases)