OracleDB vector store

OracleVector stores embeddings in Oracle Database VECTOR columns and exposes them through Mastra's vector interface. Each logical Mastra vector index is mapped to an Oracle vector table through a registry table, while metadata is stored as Oracle JSON for structured filtering.

Installation

npm

npm install @mastra/oracledb@latest

pnpm

pnpm add @mastra/oracledb@latest

Yarn

yarn add @mastra/oracledb@latest

Bun

bun add @mastra/oracledb@latest

Usage

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' },
})

By default, OracleVector uses exact search with no approximate vector index. Configure IVF or HNSW when your dataset and latency requirements need approximate search.

Constructor options

Pass Oracle connection options (user, password, connectString, pool, wallet options, or externalAuth) directly, or pass poolManager to share the pool used by OracleStore. The vector-specific options are:

id:

string

Unique identifier for this vector store instance.

poolManager?:

OraclePoolManager

Shared Oracle pool manager. Use this to share one Oracle pool with OracleStore.

schemaName?:

string

Oracle schema name used to qualify the vector registry and vector tables.

tablePrefix?:

string

= 'MASTRA_VEC'

Prefix used for physical Oracle vector tables.

registryTableName?:

string

= 'MASTRA_VECTOR_INDEXES'

Oracle table used to map Mastra logical index names to physical vector tables.

defaultIndexConfig?:

OracleVectorIndexConfig

= { type: 'none', accuracy: 95 }

Default Oracle vector index configuration.

defaultMetadataIndexes?:

string[]

= ['thread_id', 'resource_id', 'message_id', 'source_id']

Metadata fields to index automatically when vector tables are created.

defaultVectorFormat?:

'vector' | 'bit' | 'int8'

= 'vector'

Default Oracle vector format for dense, binary, and int8 embeddings.

upsertBatchSize?:

number

= 200

Number of vectors sent per Oracle executeMany call. The full upsert commits once after all batches succeed.

Constructor examples

Shared pool with 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(),
})

For Autonomous Database and mTLS connections, pass walletLocation, walletPassword, and configDir in the same constructor.

Methods

createIndex()

Creates the registry row, physical Oracle vector table, metadata indexes, and optionally an Oracle vector index.

indexName:

string

Logical Mastra index name. The provider maps this to a valid Oracle table name internally.

dimension:

number

Vector dimension. This must match the embedding model output size.

metric?:

'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'

= cosine

Distance metric for similarity search. Binary vectors support hamming and jaccard.

vectorFormat?:

'vector' | 'bit' | 'int8'

= vector

Oracle vector storage format.

indexConfig?:

OracleVectorIndexConfig

= { type: 'none', accuracy: 95 }

Oracle vector index configuration. none means exact search with no approximate vector index.

buildIndex?:

boolean

= true

Whether to build the Oracle vector index when indexConfig.type is ivf or hnsw.

metadataIndexes?:

string[]

Metadata field names to index for faster JSON metadata filtering.

OracleVectorIndexConfig

type?:

'none' | 'ivf' | 'hnsw'

= 'none'

Oracle vector index type.

accuracy?:

number

= 95

Target accuracy for approximate vector search.

ivf.neighborPartitions?:

number

Oracle IVF neighbor partitions setting.

hnsw.neighbors?:

number

Oracle HNSW neighbor setting.

hnsw.efConstruction?:

number

Oracle HNSW build-time construction setting.

Index configuration

await vector.createIndex({
  indexName: 'support_articles',
  dimension: 1536,
  metric: 'cosine',
  indexConfig: {
    type: 'ivf',
    accuracy: 95,
    ivf: {
      neighborPartitions: 32,
    },
  },
})

The default is indexConfig: { type: 'none' }, which uses exact search and requires no approximate index tuning. Use IVF or HNSW only when your data volume and latency requirements justify approximate search. HNSW is configured with indexConfig: { type: 'hnsw', hnsw: { neighbors, efConstruction } } and requires Oracle Vector Pool memory, which configureVectorMemory() can allocate for local or self-managed databases.

upsert()

indexName:

string

Name of the index to upsert vectors into.

vectors:

number[][]

Array of embedding vectors.

metadata?:

Record<string, any>[]

Metadata stored as Oracle JSON. Must align by position with vectors.

ids?:

string[]

Optional vector IDs. IDs are generated when omitted.

query()

indexName:

string

Name of the index to query.

queryVector:

number[]

Query vector.

topK?:

number

= 10

Number of results to return.

filter?:

Record<string, any>

Mastra metadata filter translated to Oracle JSON predicates.

includeVector?:

boolean

= false

Whether to include the vector in each result.

minScore?:

number

= -1

Minimum similarity score threshold.

queryMode?:

'exact' | 'approx'

Oracle query mode. Exact search is used by default when no approximate vector index is configured.

targetAccuracy?:

number

Target accuracy for approximate Oracle vector queries.

listIndexes()

Returns the logical Mastra index names recorded in the Oracle vector registry table.

describeIndex()

Returns Oracle index metadata, including the physical table name, dimension, vector count, metric, index type, vector format, and configured accuracy.

deleteIndex()

Deletes the Oracle vector table and removes the registry entry for the logical index.

updateVector()

Update vectors by ID or metadata filter. Either id or filter must be provided, but not both. The update object may include vector, metadata, or both.

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

deleteVector()

Deletes a single vector by ID.

deleteVectors()

Deletes multiple vectors by IDs or by metadata filter. Either ids or filter must be provided, but not both.

buildIndex()

Builds an Oracle vector index for an existing logical index. If the resolved index type is none, this method is a no-op.

rebuildIndex()

Drops and recreates the Oracle vector index for an existing logical index, typically after changing approximate-index tuning.

Index diagnostics

Use getIndexStatus({ indexName }) to inspect Oracle catalog status, and indexAccuracyQuery({ indexName, queryVector, topK, targetAccuracy }) to run DBMS_VECTOR.INDEX_ACCURACY_QUERY for approximate indexes.

configureVectorMemory()

Allocates Oracle Vector Pool memory, which HNSW indexes require. This calls ALTER SYSTEM SET VECTOR_MEMORY_SIZE, so it requires a privileged connection such as SYSDBA or SYSTEM.

size:

string

Vector pool size, as an integer optionally followed by K, M, or G (for example "512M").

scope?:

'MEMORY' | 'SPFILE' | 'BOTH'

= 'MEMORY'

Oracle ALTER SYSTEM scope. Use 'SPFILE' or 'BOTH' so the setting survives a database restart.

disconnect()

Closes the Oracle pool when OracleVector created the pool manager. If you provide pool or poolManager, you own that lifecycle.

Metadata filters

OracleVector accepts Mastra's standard metadata filter syntax. Filters are translated into Oracle JSON predicates with bound values:

• scalar comparisons use JSON_VALUE
• array, existence, and element-match checks use JSON_EXISTS
• regex filters use REGEXP_LIKE
• string contains filters use case-insensitive 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' }],
  },
})

Metadata is stored as native Oracle JSON, so the rows are also readable directly with standard Oracle JDBC tools such as DBeaver and SQL Developer.

Use ORACLEDB_PROMPT when an agent should generate Oracle-compatible metadata filters for 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 },
})

Response types

Query results are returned in this format:

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

Usage example

src/mastra/agents/oracle-agent.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 },
    },
  }),
})

Related

• OracleDB storage
• Metadata Filters
• Vector databases