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

# Stockage vectoriel libSQL

L'implémentation de stockage libSQL fournit une recherche vectorielle compatible avec SQLite au moyen de [libSQL](https://github.com/tursodatabase/libsql), un fork de SQLite doté d'extensions vectorielles, et de [Turso](https://turso.tech/) avec des extensions vectorielles, offrant ainsi une solution de base de données vectorielle légère et efficace. Elle fait partie du package `@mastra/libsql` et offre une recherche efficace par similarité vectorielle avec filtrage des métadonnées.

## Installation

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## Utilisation

```typescript
import { LibSQLVector } from "@mastra/libsql";

// Create a new vector store instance
const store = new LibSQLVector({
  id: 'libsql-vector',
  url: process.env.DATABASE_URL,
  // Optional: for Turso cloud databases
  authToken: process.env.DATABASE_AUTH_TOKEN,
});

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

// 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, // top K results
  filter: { category: "A" } // optional metadata filter
});
```

## Options du constructeur

**url** (`string`): URL de la base de données libSQL. Utilisez ':memory:' pour une base en mémoire, 'file:dbname.db' pour un fichier local ou une chaîne de connexion compatible avec libSQL telle que 'libsql://your-database.turso.io'.

**authToken** (`string`): Token d'authentification pour les bases de données cloud Turso

**syncUrl** (`string`): URL de réplication de la base de données (propre à Turso)

**syncInterval** (`number`): Intervalle de synchronisation de la base de données en millisecondes (propre à Turso)

## Méthodes

### `createIndex()`

Crée une nouvelle collection vectorielle. Le nom de l'index doit commencer par une lettre ou un trait de soulignement et ne peut contenir que des lettres, des chiffres et des traits de soulignement. La dimension doit être un entier positif.

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

**dimension** (`number`): Taille des dimensions du vecteur (doit correspondre à votre modèle d'embedding)

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Métrique de distance pour la recherche par similarité. Remarque : libSQL ne prend actuellement en charge que la similarité cosinus. (Default: `cosine`)

### `upsert()`

Ajoute ou met à jour les vecteurs et leurs métadonnées dans l'index. Utilise une transaction pour garantir l'insertion atomique de tous les vecteurs : si une insertion échoue, l'ensemble de l'opération est annulé.

**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[]`): Identifiants facultatifs des vecteurs (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

**includeVector** (`boolean`): Indique si les résultats doivent inclure les données vectorielles (Default: `false`)

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

### `describeIndex()`

Récupère 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[]>`

### `truncateIndex()`

Supprime tous les vecteurs d'un index tout en conservant sa structure.

**indexName** (`string`): Nom de l'index à tronquer

### `updateVector()`

Met à jour un seul vecteur à partir de son identifiant ou d'un filtre de métadonnées. Vous devez fournir soit `id`, soit `filter`, mais pas les deux.

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

**id** (`string`): Identifiant de l'entrée vectorielle à mettre à jour (mutuellement exclusif avec filter)

**filter** (`Record<string, any>`): Filtre de métadonnées permettant de repérer 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 précise à partir de son identifiant.

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

**id** (`string`): Identifiant de l'entrée vectorielle à supprimer

### `deleteVectors()`

Supprime plusieurs vecteurs à partir de leurs identifiants ou d'un filtre de métadonnées. Vous devez fournir soit `ids`, soit `filter`, mais pas les deux.

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

**ids** (`string[]`): Tableau d'identifiants de vecteurs à supprimer (mutuellement exclusif avec filter)

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

## Types de réponse

Les résultats de la requête sont renvoyés au format suivant :

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

## Gestion des erreurs

Le stockage lève des erreurs propres aux différents cas d'échec :

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

Les cas d'erreur courants comprennent :

- Format de nom d'index non valide
- Dimensions vectorielles non valides
- Table ou index introuvable
- Problèmes de connexion à la base de données
- Échecs de transaction pendant l'upsert

## Exemple d'utilisation

### Embeddings locaux avec fastembed

Les embeddings sont des vecteurs numériques utilisés par `semanticRecall` de la mémoire pour récupérer les messages associés en fonction de leur sens, et non de mots-clés. Cette configuration utilise `@mastra/fastembed` pour générer des embeddings vectoriels.

Pour commencer, installez `fastembed` :

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

Ajoutez ce qui suit à votre Agent :

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
import { fastembed } from '@mastra/fastembed'

export const libsqlAgent = new Agent({
  id: 'libsql-agent',
  name: 'libSQL Agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'libsql-agent-storage',
      url: 'file:libsql-agent.db',
    }),
    vector: new LibSQLVector({
      id: 'libsql-agent-vector',
      url: 'file:libsql-agent.db',
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
      generateTitle: true, // Explicitly enable automatic title generation
    },
  }),
})
```

## Voir aussi

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