Magasin vectoriel OracleDB

OracleVector stocke les embeddings dans des colonnes VECTOR d’Oracle Database et les expose par l’interface vectorielle de Mastra. Chaque index vectoriel logique Mastra est associé à une table vectorielle Oracle par l’intermédiaire d’une table de registre, tandis que les métadonnées sont stockées au format Oracle JSON pour permettre un filtrage structuré.

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

Utilisation

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

Par défaut, OracleVector utilise la recherche exacte sans index vectoriel approximatif. Configurez IVF ou HNSW lorsque votre jeu de données et vos exigences de latence nécessitent une recherche approximative.

Options du constructeur

Transmettez directement les options de connexion Oracle (user, password, connectString, pool, options de portefeuille ou externalAuth), ou transmettez poolManager pour partager le pool utilisé par OracleStore. Les options spécifiques aux vecteurs sont :

id:

string

Identifiant unique de cette instance de magasin vectoriel.

poolManager?:

OraclePoolManager

Gestionnaire de pool Oracle partagé. Utilisez-le pour partager un pool Oracle avec OracleStore.

schemaName?:

string

Nom du schéma Oracle utilisé pour qualifier le registre vectoriel et les tables vectorielles.

tablePrefix?:

string

= 'MASTRA_VEC'

Préfixe utilisé pour les tables vectorielles Oracle physiques.

registryTableName?:

string

= 'MASTRA_VECTOR_INDEXES'

Table Oracle utilisée pour associer les noms d’index logiques Mastra aux tables vectorielles physiques.

defaultIndexConfig?:

OracleVectorIndexConfig

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

Configuration d’index vectoriel Oracle par défaut.

defaultMetadataIndexes?:

string[]

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

Champs de métadonnées à indexer automatiquement lors de la création des tables vectorielles.

defaultVectorFormat?:

'vector' | 'bit' | 'int8'

= 'vector'

Format vectoriel Oracle par défaut pour les embeddings denses, binaires et int8.

upsertBatchSize?:

number

= 200

Nombre de vecteurs envoyés par appel Oracle executeMany. L’upsert complet effectue un commit unique après la réussite de tous les lots.

Exemples de constructeur

Pool partagé avec 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(),
})

Pour Autonomous Database et les connexions mTLS, transmettez walletLocation, walletPassword et configDir au même constructeur.

Méthodes

createIndex()

Crée la ligne de registre, la table vectorielle Oracle physique, les index de métadonnées et, éventuellement, un index vectoriel Oracle.

indexName:

string

Nom d’index logique Mastra. Le fournisseur l’associe en interne à un nom de table Oracle valide.

dimension:

number

Dimension du vecteur. Elle doit correspondre à la taille de sortie du modèle d’embedding.

metric?:

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

= cosine

Métrique de distance pour la recherche de similarité. Les vecteurs binaires prennent en charge hamming et jaccard.

vectorFormat?:

'vector' | 'bit' | 'int8'

= vector

Format de stockage vectoriel Oracle.

indexConfig?:

OracleVectorIndexConfig

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

Configuration d’index vectoriel Oracle. none signifie une recherche exacte sans index vectoriel approximatif.

buildIndex?:

boolean

= true

Indique s’il faut construire l’index vectoriel Oracle lorsque indexConfig.type vaut ivf ou hnsw.

metadataIndexes?:

string[]

Noms des champs de métadonnées à indexer pour accélérer le filtrage des métadonnées JSON.

OracleVectorIndexConfig

type?:

'none' | 'ivf' | 'hnsw'

= 'none'

Type d’index vectoriel Oracle.

accuracy?:

number

= 95

Précision cible pour la recherche vectorielle approximative.

ivf.neighborPartitions?:

number

Paramètre de partitions voisines Oracle IVF.

hnsw.neighbors?:

number

Paramètre de voisins Oracle HNSW.

hnsw.efConstruction?:

number

Paramètre de construction Oracle HNSW au moment de la création.

Configuration de l’index

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

La valeur par défaut est indexConfig: { type: 'none' }, qui utilise la recherche exacte et ne nécessite aucun réglage d’index approximatif. Utilisez IVF ou HNSW uniquement lorsque votre volume de données et vos exigences de latence justifient une recherche approximative. HNSW est configuré avec indexConfig: { type: 'hnsw', hnsw: { neighbors, efConstruction } } et nécessite de la mémoire Oracle Vector Pool, que configureVectorMemory() peut allouer pour les bases de données locales ou autogérées.

upsert()

indexName:

string

Nom de l’index dans lequel effectuer l’upsert des vecteurs.

vectors:

number[][]

Tableau de vecteurs d’embedding.

metadata?:

Record<string, any>[]

Métadonnées stockées au format Oracle JSON. Elles doivent être alignées par position avec vectors.

ids?:

string[]

ID de vecteurs facultatifs. Les ID sont générés lorsqu’ils sont omis.

query()

indexName:

string

Nom de l’index à interroger.

queryVector:

number[]

Vecteur de requête.

topK?:

number

= 10

Nombre de résultats à renvoyer.

filter?:

Record<string, any>

Filtre de métadonnées Mastra traduit en prédicats Oracle JSON.

includeVector?:

boolean

= false

Indique s’il faut inclure le vecteur dans chaque résultat.

minScore?:

number

= -1

Seuil minimal du score de similarité.

queryMode?:

'exact' | 'approx'

Mode de requête Oracle. La recherche exacte est utilisée par défaut lorsqu’aucun index vectoriel approximatif n’est configuré.

targetAccuracy?:

number

Précision cible pour les requêtes vectorielles Oracle approximatives.

listIndexes()

Renvoie les noms d’index logiques Mastra enregistrés dans la table de registre vectoriel Oracle.

describeIndex()

Renvoie les métadonnées de l’index Oracle, notamment le nom de la table physique, la dimension, le nombre de vecteurs, la métrique, le type d’index, le format vectoriel et la précision configurée.

deleteIndex()

Supprime la table vectorielle Oracle et retire l’entrée de registre de l’index logique.

updateVector()

Met à jour des vecteurs par ID ou filtre de métadonnées. Vous devez fournir id ou filter, mais pas les deux. L’objet update peut inclure vector, metadata ou les deux.

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

deleteVector()

Supprime un seul vecteur par ID.

deleteVectors()

Supprime plusieurs vecteurs par ID ou filtre de métadonnées. Vous devez fournir ids ou filter, mais pas les deux.

buildIndex()

Construit un index vectoriel Oracle pour un index logique existant. Si le type d’index résolu est none, cette méthode ne fait rien.

rebuildIndex()

Supprime et recrée l’index vectoriel Oracle d’un index logique existant, généralement après la modification du réglage de l’index approximatif.

Diagnostic de l’index

Utilisez getIndexStatus({ indexName }) pour examiner l’état du catalogue Oracle, et indexAccuracyQuery({ indexName, queryVector, topK, targetAccuracy }) pour exécuter DBMS_VECTOR.INDEX_ACCURACY_QUERY sur des index approximatifs.

configureVectorMemory()

Alloue la mémoire Oracle Vector Pool requise par les index HNSW. Cette méthode appelle ALTER SYSTEM SET VECTOR_MEMORY_SIZE ; elle nécessite donc une connexion privilégiée telle que SYSDBA ou SYSTEM.

size:

string

Taille du pool vectoriel, sous forme d’entier éventuellement suivi de K, M ou G (par exemple, "512M").

scope?:

'MEMORY' | 'SPFILE' | 'BOTH'

= 'MEMORY'

Portée Oracle ALTER SYSTEM. Utilisez 'SPFILE' ou 'BOTH' pour que le réglage persiste après le redémarrage de la base de données.

disconnect()

Ferme le pool Oracle lorsque OracleVector a créé le gestionnaire de pool. Si vous fournissez pool ou poolManager, vous gérez ce cycle de vie.

Filtres de métadonnées

OracleVector accepte la syntaxe standard de filtre de métadonnées de Mastra. Les filtres sont traduits en prédicats Oracle JSON avec valeurs liées :

• les comparaisons scalaires utilisent JSON_VALUE
• les vérifications de tableaux, d’existence et de correspondance d’éléments utilisent JSON_EXISTS
• les filtres regex utilisent REGEXP_LIKE
• les filtres « contient » sur les chaînes utilisent LIKE sans distinction de casse

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

Les métadonnées sont stockées au format Oracle JSON natif ; les lignes sont donc également lisibles directement avec les outils JDBC Oracle standard, tels que DBeaver et SQL Developer.

Utilisez ORACLEDB_PROMPT lorsqu’un agent doit générer des filtres de métadonnées compatibles avec Oracle pour 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 },
})

Types de réponse

Les résultats de requête sont renvoyés dans ce format :

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

Exemple d’utilisation

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

Articles associés

• Stockage OracleDB
• Filtres de métadonnées
• Bases de données vectorielles