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

# Base vectorielle Couchbase

La classe `CouchbaseVector` fournit une recherche vectorielle à l’aide de [Couchbase Vector Search](https://docs.couchbase.com/server/current/vector-search/vector-search.html). Elle permet d’effectuer efficacement des recherches de similarité et un filtrage des métadonnées dans vos collections Couchbase.

## Prérequis

- **Couchbase Server 7.6.4 ou version ultérieure**, ou un cluster Capella compatible
- **Service Search activé** sur votre déploiement Couchbase

## Installation

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## Exemple d’utilisation

```typescript
import { CouchbaseVector } from '@mastra/couchbase'

const store = new CouchbaseVector({
  id: 'couchbase-vector',
  connectionString: process.env.COUCHBASE_CONNECTION_STRING,
  username: process.env.COUCHBASE_USERNAME,
  password: process.env.COUCHBASE_PASSWORD,
  bucketName: process.env.COUCHBASE_BUCKET,
  scopeName: process.env.COUCHBASE_SCOPE,
  collectionName: process.env.COUCHBASE_COLLECTION,
})
```

## Options du constructeur

**id** (`string`): Identifiant unique de cette instance de base vectorielle

**connectionString** (`string`): Chaîne de connexion Couchbase

**username** (`string`): Nom d’utilisateur Couchbase

**password** (`string`): Mot de passe Couchbase

**bucketName** (`string`): Nom du bucket Couchbase à utiliser

**scopeName** (`string`): Nom du scope Couchbase à utiliser

**collectionName** (`string`): Nom de la collection Couchbase à utiliser

**options** (`CouchbaseClientOptions`): Options facultatives du client Couchbase

## Méthodes

### `createIndex()`

Crée un nouvel index vectoriel dans Couchbase.

> **Remarque:** La création d’un index est asynchrone. Après avoir appelé `createIndex`, attendez un certain temps (généralement 1 à 5 secondes pour les petits jeux de données, davantage pour les plus volumineux) avant d’effectuer une requête. En production, mettez en place une interrogation périodique de l’état de l’index au lieu d’utiliser des délais fixes.

**indexName** (`string`): Nom de l’index à créer

**dimension** (`number`): Dimension du vecteur (doit correspondre à votre modèle d’embedding)

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Métrique de distance pour la recherche de similarité (Default: `cosine`)

### `upsert()`

Ajoute ou met à jour des vecteurs et leurs métadonnées dans la collection.

> **Remarque:** Vous pouvez upserter des données avant ou après la création de l’index. La méthode `upsert` ne nécessite pas que l’index existe. Couchbase autorise plusieurs index Search sur une même collection.

**indexName** (`string`): Nom de l’index dans lequel effectuer l’insertion

**vectors** (`number[][]`): Tableau de vecteurs d’embedding

**metadata** (`Record<string, any>[]`): Métadonnées de chaque vecteur

**ids** (`string[]`): ID de vecteurs facultatifs (générés automatiquement s’ils ne sont pas fournis)

### `query()`

Recherche des vecteurs similaires.

> **Attention:** Les paramètres `filter` et `includeVector` ne sont actuellement pas pris en charge. Le filtrage doit être effectué côté client après la récupération des résultats, ou directement à l’aide des fonctionnalités Search du SDK Couchbase. Pour récupérer le vecteur d’embedding, récupérez le document complet à partir de son ID avec le SDK Couchbase.

**indexName** (`string`): Nom de l’index dans lequel effectuer la recherche

**queryVector** (`number[]`): Vecteur de requête pour lequel rechercher des vecteurs similaires

**topK** (`number`): Nombre de résultats à renvoyer (Default: `10`)

**filter** (`Record<string, any>`): Filtres de métadonnées

**includeVector** (`boolean`): Indique s’il faut inclure les données vectorielles dans les résultats (Default: `false`)

**minScore** (`number`): Seuil minimal du score de similarité (Default: `0`)

### `describeIndex()`

Renvoie des informations sur l’index.

**indexName** (`string`): Nom de l’index à décrire

Renvoie :

```typescript
interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}
```

### `deleteIndex()`

Supprime un index et toutes ses données.

**indexName** (`string`): Nom de l’index à supprimer

### `listIndexes()`

Répertorie tous les index vectoriels du bucket Couchbase.

Renvoie : `Promise<string[]>`

### `updateVector()`

Met à jour une entrée vectorielle donnée à partir de son ID avec de nouvelles données vectorielles et/ou métadonnées. Les mises à jour fondées sur des filtres ne sont pas encore implémentées pour Couchbase.

**indexName** (`string`): Nom de l’index contenant le vecteur

**id** (`string`): ID de l’entrée vectorielle à mettre à jour

**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Objet contenant le vecteur et/ou les métadonnées à mettre à jour

### `deleteVector()`

Supprime de l’index un seul vecteur à partir de son ID.

**indexName** (`string`): Nom de l’index contenant le vecteur

**id** (`string`): ID du vecteur à supprimer

### `deleteVectors()`

Supprime plusieurs vecteurs à partir de leurs ID. La suppression fondée sur des filtres n’est pas encore implémentée pour Couchbase.

**indexName** (`string`): Nom de l’index contenant les vecteurs à supprimer

**ids** (`string[]`): Tableau des ID de vecteurs à supprimer

### `disconnect()`

Ferme la connexion du client Couchbase. Doit être appelée lorsque vous avez fini d’utiliser la base vectorielle.

## Types de réponse

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

```typescript
interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}
```

## Gestion des erreurs

La base vectorielle déclenche des erreurs typées qui peuvent être interceptées :

```typescript
try {
  await store.query({
    indexName: 'my_index',
    queryVector: queryVector,
  })
} catch (error) {
  // Handle specific error cases
  if (error.message.includes('Invalid index name')) {
    console.error(
      'Index name must start with a letter or underscore and contain only valid characters.',
    )
  } else if (error.message.includes('Index not found')) {
    console.error('The specified index does not exist')
  } else {
    console.error('Vector store error:', error.message)
  }
}
```

## Remarques

- **Précaution concernant la suppression des index :** la suppression d’un index Search ne supprime pas les vecteurs ou documents de la collection Couchbase associée. Les données subsistent tant qu’elles ne sont pas explicitement supprimées.
- **Autorisations requises :** l’utilisateur Couchbase doit être autorisé à se connecter, à lire et écrire des documents dans la collection cible (rôle `kv`) ainsi qu’à gérer les index Search (rôle `search_admin` sur le bucket/scope concerné).
- **Détails de la définition de l’index et structure des documents :** la méthode `createIndex` construit une définition d’index Search qui indexe le champ `embedding` (en tant que type `vector`) et le champ `content` (en tant que type `text`), en ciblant les documents de la valeur `scopeName.collectionName` indiquée. Chaque document stocke le vecteur dans le champ `embedding` et les métadonnées dans le champ `metadata`. Si `metadata` contient une propriété `text`, sa valeur est également copiée dans un champ `content` de niveau supérieur, indexé pour la recherche textuelle.
- **Réplication et durabilité :** envisagez d’utiliser les fonctionnalités intégrées de réplication et de persistance de Couchbase pour assurer la durabilité des données. Surveillez régulièrement les statistiques des index afin de garantir l’efficacité des recherches.

## Limitations

- Les délais de création des index peuvent empêcher d’effectuer immédiatement des requêtes après leur création.
- La dimension des vecteurs n’est pas strictement imposée lors de l’ingestion (une incompatibilité de dimension provoquera une erreur lors de la requête).
- L’insertion de vecteurs et les mises à jour des index sont cohérentes à terme. Une cohérence forte n’est pas garantie immédiatement après les écritures.

## Ressources associées

- [Filtres de métadonnées](https://mastra.zisheng.pro/fr/reference/rag/metadata-filters)