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

# 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**:

```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
```

## Utilisation

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

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`): Préfixe utilisé pour les tables vectorielles Oracle physiques. (Default: `'MASTRA_VEC'`)

**registryTableName** (`string`): Table Oracle utilisée pour associer les noms d’index logiques Mastra aux tables vectorielles physiques. (Default: `'MASTRA_VECTOR_INDEXES'`)

**defaultIndexConfig** (`OracleVectorIndexConfig`): Configuration d’index vectoriel Oracle par défaut. (Default: `{ type: 'none', accuracy: 95 }`)

**defaultMetadataIndexes** (`string[]`): Champs de métadonnées à indexer automatiquement lors de la création des tables vectorielles. (Default: `['thread_id', 'resource_id', 'message_id', 'source_id']`)

**defaultVectorFormat** (`'vector' | 'bit' | 'int8'`): Format vectoriel Oracle par défaut pour les embeddings denses, binaires et int8. (Default: `'vector'`)

**upsertBatchSize** (`number`): 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. (Default: `200`)

## Exemples de constructeur

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

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'`): Métrique de distance pour la recherche de similarité. Les vecteurs binaires prennent en charge hamming et jaccard. (Default: `cosine`)

**vectorFormat** (`'vector' | 'bit' | 'int8'`): Format de stockage vectoriel Oracle. (Default: `vector`)

**indexConfig** (`OracleVectorIndexConfig`): Configuration d’index vectoriel Oracle. none signifie une recherche exacte sans index vectoriel approximatif. (Default: `{ type: 'none', accuracy: 95 }`)

**buildIndex** (`boolean`): Indique s’il faut construire l’index vectoriel Oracle lorsque indexConfig.type vaut ivf ou hnsw. (Default: `true`)

**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'`): Type d’index vectoriel Oracle. (Default: `'none'`)

**accuracy** (`number`): Précision cible pour la recherche vectorielle approximative. (Default: `95`)

**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

```ts
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`): Nombre de résultats à renvoyer. (Default: `10`)

**filter** (`Record<string, any>`): Filtre de métadonnées Mastra traduit en prédicats Oracle JSON.

**includeVector** (`boolean`): Indique s’il faut inclure le vecteur dans chaque résultat. (Default: `false`)

**minScore** (`number`): Seuil minimal du score de similarité. (Default: `-1`)

**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.

```ts
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'`): 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. (Default: `'MEMORY'`)

### `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

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

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

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

## Types de réponse

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

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

## Exemple d’utilisation

```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](https://mastra.zisheng.pro/fr/reference/storage/oracledb)
- [Filtres de métadonnées](https://mastra.zisheng.pro/fr/reference/rag/metadata-filters)
- [Bases de données vectorielles](https://mastra.zisheng.pro/fr/guides/rag/vector-databases)