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

# Magasin vectoriel Chroma

La classe ChromaVector fournit une recherche vectorielle à l’aide de [Chroma](https://docs.trychroma.com/docs/overview/getting-started), une base de données open source d’embeddings. Elle offre une recherche vectorielle efficace avec filtrage des métadonnées et capacités de recherche hybride.

> **Info:**
>
> **Chroma Cloud**
>
> Chroma Cloud alimente la recherche vectorielle et la recherche en texte intégral sans serveur. Le service est extrêmement rapide, économique, à grande capacité et simple à utiliser. Créez une base de données et essayez-le en moins de 30 secondes grâce à 5 $ de crédits offerts.
>
> [Démarrer avec Chroma Cloud](https://trychroma.com/signup)

## Options du constructeur

**host** (`string`): Adresse hôte du serveur Chroma. Utilise 'localhost' par défaut.

**port** (`number`): Numéro de port du serveur Chroma. Utilise 8000 par défaut.

**ssl** (`boolean`): Indique s’il faut utiliser SSL/HTTPS pour les connexions. Utilise false par défaut.

**apiKey** (`string`): Clé API Chroma Cloud.

**tenant** (`string`): Nom du locataire du serveur Chroma auquel se connecter. Utilise 'default\_tenant' par défaut pour Chroma à nœud unique. Résolu automatiquement pour les utilisateurs de Chroma Cloud à partir de la clé API fournie.

**database** (`string`): Nom de la base de données à laquelle se connecter. Utilise 'default\_database' par défaut pour Chroma à nœud unique. Résolu automatiquement pour les utilisateurs de Chroma Cloud à partir de la clé API fournie.

**headers** (`Record<string, any>`): En-têtes HTTP supplémentaires à envoyer avec les requêtes.

**fetchOptions** (`RequestInit`): Options fetch supplémentaires pour les requêtes HTTP.

## Exécuter un serveur Chroma

Si vous utilisez Chroma Cloud, fournissez au constructeur `ChromaVector` votre clé API, votre locataire et le nom de votre base de données.

Lorsque vous installez le package `@mastra/chroma`, vous accédez à la [CLI Chroma](https://docs.trychroma.com/docs/cli/db), qui peut les définir comme variables d’environnement : `chroma db connect [DB-NAME] --env-file`.

Sinon, vous disposez de plusieurs options pour configurer votre serveur Chroma à nœud unique :

- Exécutez-en un localement avec la CLI Chroma : `chroma run`. Vous trouverez davantage d’options de configuration dans la [documentation Chroma](https://docs.trychroma.com/docs/cli/run).
- Exécutez-le sur [Docker](https://docs.trychroma.com/guides/deploy/docker) avec l’image Chroma officielle.
- Déployez votre propre serveur Chroma chez le fournisseur de votre choix. Chroma propose des modèles d’exemple pour [AWS](https://docs.trychroma.com/guides/deploy/aws), [Azure](https://docs.trychroma.com/guides/deploy/azure) et [GCP](https://docs.trychroma.com/guides/deploy/gcp).

## Méthodes

### `createIndex()`

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

### `forkIndex()`

Remarque : la duplication n’est prise en charge que dans Chroma Cloud, ou si vous déployez votre propre Chroma OSS **distribué**.

`forkIndex` vous permet de dupliquer instantanément un index Chroma existant. Les opérations sur l’index dupliqué n’affectent pas l’original. Pour en savoir plus, consultez la [documentation Chroma](https://docs.trychroma.com/cloud/collection-forking).

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

**newIndexName** (`string`): Nom de l’index dupliqué.

### `upsert()`

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

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

**documents** (`string[]`): Spécifique à Chroma : documents texte d’origine associés aux vecteurs.

### `query()`

Interroge un index à l’aide d’un `queryVector`. Renvoie un tableau d’enregistrements sémantiquement similaires, classés par distance par rapport au `queryVector`. Chaque enregistrement a la forme suivante :

```typescript
{
  id: string;
  score: number;
  document?: string;
  metadata?: Record<string, string | number | boolean>;
  embedding?: number[]
}
```

Vous pouvez également fournir la forme de vos métadonnées à un appel `query` pour l’inférence de type : `query<T>()`.

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

**queryVector** (`number[]`): Vecteur de requête servant à trouver des vecteurs similaires.

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

**filter** (`Record<string, any>`): Filtres de métadonnées pour la requête.

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

**documentFilter** (`Record<string, any>`): Spécifique à Chroma : filtre à appliquer au contenu du document.

### `get()`

Obtient des enregistrements de votre index Chroma par ID, métadonnées et filtres de documents. Renvoie un tableau d’enregistrements de la forme suivante :

```typescript
{
  id: string;
  document?: string;
  metadata?: Record<string, string | number | boolean>;
  embedding?: number[]
}
```

Vous pouvez également fournir la forme de vos métadonnées à un appel `get` pour l’inférence de type : `get<T>()`.

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

**ids** (`string[]`): Liste des ID d’enregistrements à renvoyer. Si elle n’est pas fournie, tous les enregistrements sont renvoyés.

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

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

**documentFilter** (`Record<string, any>`): Spécifique à Chroma : filtre à appliquer au contenu du document.

**limit** (`number`): Nombre maximal d’enregistrements à renvoyer. (Default: `100`)

**offset** (`number`): Décalage des enregistrements à renvoyer. À utiliser avec limit pour paginer les résultats.

### `listIndexes()`

Renvoie un tableau de noms d’index sous forme de chaînes.

### `describeIndex()`

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

Renvoie :

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

### `deleteIndex()`

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

### `updateVector()`

Met à jour un seul vecteur par ID ou filtre de métadonnées. Vous devez fournir `id` ou `filter`, mais pas les deux.

**indexName** (`string`): Nom de l’index qui contient le vecteur à mettre à jour.

**id** (`string`): ID du vecteur à mettre à jour (mutuellement exclusif avec filter).

**filter** (`Record<string, any>`): Filtre de métadonnées permettant d’identifier le ou les vecteurs à mettre à jour (mutuellement exclusif avec id).

**update** (`object`): Paramètres de mise à jour.

L’objet `update` peut contenir :

**vector** (`number[]`): Nouveau vecteur qui remplace le vecteur existant.

**metadata** (`Record<string, any>`): Nouvelles métadonnées qui remplacent les métadonnées existantes.

Exemple :

```typescript
// Update by ID
await vectorStore.updateVector({
  indexName: 'docs',
  id: 'vec_123',
  update: { metadata: { status: 'reviewed' } },
})

// Update by filter
await vectorStore.updateVector({
  indexName: 'docs',
  filter: { source_id: 'manual.pdf' },
  update: { metadata: { version: 2 } },
})
```

### `deleteVector()`

**indexName** (`string`): Nom de l’index qui contient le vecteur à supprimer.

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

### `deleteVectors()`

Supprime plusieurs vecteurs par ID ou filtre de métadonnées. La méthode prend en charge la suppression en masse et la gestion des vecteurs par source. Vous devez fournir `ids` ou `filter`, mais pas les deux.

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

**ids** (`string[]`): Tableau des ID de vecteurs à supprimer (mutuellement exclusif avec filter).

**filter** (`Record<string, any>`): Filtre de métadonnées permettant d’identifier les vecteurs à supprimer (mutuellement exclusif avec ids).

Exemple :

```typescript
// Delete all chunks from a document
await vectorStore.deleteVectors({
  indexName: 'docs',
  filter: { source_id: 'manual.pdf' },
})

// Delete multiple vectors by ID
await vectorStore.deleteVectors({
  indexName: 'docs',
  ids: ['vec_1', 'vec_2', 'vec_3'],
})

// Delete old temporary documents
await vectorStore.deleteVectors({
  indexName: 'docs',
  filter: {
    $and: [{ bucket: 'temp' }, { indexed_at: { $lt: '2025-01-01' } }],
  },
})
```

## Types de réponse

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

```typescript
interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  document?: string // Chroma-specific: Original document if it was stored
  vector?: number[] // Only included if includeVector is true
}
```

## Gestion des erreurs

Le magasin lève des erreurs typées qui peuvent être interceptées :

```typescript
try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}
```

## Articles associés

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