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

# Base vectorielle DuckDB

L’implémentation de stockage DuckDB fournit une solution de recherche vectorielle embarquée hautes performances à l’aide de [DuckDB](https://duckdb.org/), une base de données analytique intégrée au processus. Elle utilise l’extension VSS pour la recherche de similarité vectorielle avec indexation HNSW, offrant ainsi une base vectorielle légère et efficace qui ne nécessite aucun serveur externe.

Elle fait partie du package `@mastra/duckdb` et fournit une recherche efficace de similarité vectorielle avec filtrage des métadonnées.

## Installation

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## Utilisation

```typescript
import { DuckDBVector } from "@mastra/duckdb";

// Create a new vector store instance
const store = new DuckDBVector({
  id: "duckdb-vector",
  path: ":memory:", // or './vectors.duckdb' for file persistence
});

// Create an index
await store.createIndex({
  indexName: "myCollection",
  dimension: 1536,
  metric: "cosine",
});

// Add vectors with metadata
const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
const metadata = [
  { text: "first document", category: "A" },
  { text: "second document", category: "B" },
];
await store.upsert({
  indexName: "myCollection",
  vectors,
  metadata,
});

// Query similar vectors
const queryVector = [0.1, 0.2, ...];
const results = await store.query({
  indexName: "myCollection",
  queryVector,
  topK: 10,
  filter: { category: "A" },
});

// Clean up
await store.close();
```

## Options du constructeur

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

**path** (`string`): Chemin du fichier de base de données. Utilisez ':memory:' pour une base en mémoire, ou un chemin tel que './vectors.duckdb' pour assurer la persistance. (Default: `':memory:'`)

**dimensions** (`number`): Dimension par défaut des embeddings vectoriels (Default: `1536`)

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

## Méthodes

### `createIndex()`

Crée une nouvelle collection vectorielle avec un index HNSW facultatif pour une recherche rapide et approximative des plus proches voisins.

**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 les vecteurs et leurs métadonnées dans l’index.

**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 (UUID générés automatiquement s’ils ne sont pas fournis)

### `query()`

Recherche des vecteurs similaires avec un filtrage facultatif des métadonnées.

**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** (`Filter`): Filtres de métadonnées utilisant une syntaxe de requête similaire à MongoDB

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

### `describeIndex()`

Obtient des informations sur un 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 de la base de données.

Renvoie : `Promise<string[]>`

### `updateVector()`

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

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

**id** (`string`): ID de l’entrée vectorielle à 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`): Données de mise à jour contenant le vecteur et/ou les métadonnées

**update.vector** (`number[]`): Nouvelles données vectorielles à appliquer

**update.metadata** (`Record<string, any>`): Nouvelles métadonnées à appliquer

### `deleteVector()`

Supprime d’un index une entrée vectorielle donnée à partir de son ID.

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

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

### `deleteVectors()`

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

**indexName** (`string`): Nom de l’index contenant 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)

### `close()`

Ferme la connexion à la base de données et libère les ressources.

```typescript
await store.close()
```

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

## Opérateurs de filtre

La base vectorielle DuckDB prend en charge des opérateurs de filtre similaires à ceux de MongoDB :

| Catégorie   | Opérateurs                                 |
| ----------- | ------------------------------------------ |
| Comparaison | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` |
| Logique     | `$and`, `$or`, `$not`, `$nor`              |
| Tableau     | `$in`, `$nin`                              |
| Élément     | `$exists`                                  |
| Texte       | `$contains`                                |

### Exemples de filtres

```typescript
// Allegato operators
const results = await store.query({
  indexName: "docs",
  queryVector: [...],
  filter: {
    $and: [
      { category: "electronics" },
      { price: { $gte: 100, $lte: 500 } },
    ],
  },
});

// Nested field access
const results = await store.query({
  indexName: "docs",
  queryVector: [...],
  filter: { "user.profile.tier": "premium" },
});
```

## Métriques de distance

| Métrique     | Description        | Interprétation du score     | Cas d’utilisation recommandé               |
| ------------ | ------------------ | --------------------------- | ------------------------------------------ |
| `cosine`     | Similarité cosinus | 0-1 (1 = le plus similaire) | Embeddings de texte, vecteurs normalisés   |
| `euclidean`  | Distance L2        | 0-∞ (0 = le plus similaire) | Embeddings d’image, données spatiales      |
| `dotproduct` | Produit scalaire   | Plus élevé = plus similaire | Lorsque la norme du vecteur est importante |

## Gestion des erreurs

La base vectorielle déclenche des erreurs propres aux différents cas d’échec :

```typescript
try {
  await store.query({
    indexName: 'my-collection',
    queryVector: queryVector,
  })
} catch (error) {
  if (error.message.includes('not found')) {
    console.error('The specified index does not exist')
  } else if (error.message.includes('Invalid identifier')) {
    console.error('Index name contains invalid characters')
  } else {
    console.error('Vector store error:', error.message)
  }
}
```

Les cas d’erreur courants comprennent :

- Format de nom d’index non valide
- Index/table introuvable
- Incompatibilité de dimension entre le vecteur de requête et l’index
- Filtre ou tableau d’ID vide lors des opérations de suppression/mise à jour
- Violation de l’exclusion mutuelle (fourniture simultanée de `id` et `filter`)

## Cas d’utilisation

### Recherche sémantique embarquée

Créez des applications d’IA capables de fonctionner hors ligne avec une recherche sémantique entièrement exécutée dans le processus :

```typescript
const store = new DuckDBVector({
  id: 'offline-search',
  path: './search.duckdb',
})
```

### Pipelines RAG locaux

Traitez localement des documents sensibles sans envoyer les données vers des bases vectorielles cloud :

```typescript
const store = new DuckDBVector({
  id: 'private-rag',
  path: './confidential.duckdb',
  dimensions: 1536,
})
```

### Développement et tests

Prototypez rapidement des fonctionnalités de recherche vectorielle sans aucune infrastructure :

```typescript
const store = new DuckDBVector({
  id: 'dev-store',
  path: ':memory:', // Fast in-memory for tests
})
```

## Ressources associées

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