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

# Stockage Convex

L'implémentation du stockage Convex fournit une solution de stockage serverless fondée sur [Convex](https://convex.dev), une plateforme de développement TypeScript full-stack avec synchronisation en temps réel et mise en cache automatique.

> **Observabilité non prise en charge:** Le stockage Convex **ne prend pas en charge le domaine de l'observabilité**. Les traces de `MastraStorageExporter` ne peuvent pas être conservées dans Convex, et les fonctionnalités d'observabilité de [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview) ne fonctionneront pas si Convex est votre seul Provider de stockage. Pour activer l'observabilité, utilisez le [stockage composite](https://mastra.zisheng.pro/fr/reference/storage/composite) afin d'acheminer les données d'observabilité vers un Provider pris en charge tel que ClickHouse.

> **Limite de taille des enregistrements:** Convex impose une **taille maximale d'enregistrement de 1 Mio**. Cette limite peut être dépassée lors du stockage de messages contenant des pièces jointes encodées en base64, telles que des images. Consultez [Gérer les pièces jointes volumineuses](https://mastra.zisheng.pro/fr/docs/memory/memory-processors) pour découvrir des solutions de contournement, notamment le téléversement des pièces jointes vers un stockage externe tel que S3, Cloudflare R2 ou le [stockage de fichiers Convex](https://docs.convex.dev/file-storage).

## Installation

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## Configuration de Convex

Avant d'utiliser `ConvexStore`, configurez le schéma Convex et le gestionnaire de stockage dans votre projet Convex. L'exemple de schéma ci-dessous comprend la configuration complète de `ConvexStore` et `ConvexServerCache`. Si vous utilisez uniquement `ConvexStore`, omettez `mastraCacheTable` et `mastraCacheListItemsTable` ; si vous utilisez `ConvexServerCache`, incluez ces tables et créez le gestionnaire de cache.

### 1. Configurer le schéma Convex

Dans `convex/schema.ts` :

```typescript
import { defineSchema } from 'convex/server'
import {
  mastraThreadsTable,
  mastraMessagesTable,
  mastraResourcesTable,
  mastraWorkflowSnapshotsTable,
  mastraScoresTable,
  mastraObservationalMemoryTable,
  mastraVectorIndexesTable,
  mastraVectorsTable,
  mastraCacheTable,
  mastraCacheListItemsTable,
  mastraDocumentsTable,
} from '@mastra/convex/schema'

export default defineSchema({
  mastra_threads: mastraThreadsTable,
  mastra_messages: mastraMessagesTable,
  mastra_resources: mastraResourcesTable,
  mastra_workflow_snapshots: mastraWorkflowSnapshotsTable,
  mastra_scorers: mastraScoresTable,
  mastra_observational_memory: mastraObservationalMemoryTable,
  mastra_vector_indexes: mastraVectorIndexesTable,
  mastra_vectors: mastraVectorsTable,
  mastra_cache: mastraCacheTable,
  mastra_cache_list_items: mastraCacheListItemsTable,
  mastra_documents: mastraDocumentsTable,
})
```

### 2. Créer le gestionnaire de stockage

Dans `convex/mastra/storage.ts` :

```typescript
import { mastraStorage } from '@mastra/convex/server'

export const handle = mastraStorage
```

Si vous utilisez `ConvexServerCache`, créez `convex/mastra/cache.ts` :

```typescript
import { mastraCache } from '@mastra/convex/server'

export const handle = mastraCache
```

### 3. Déployer sur Convex

```bash
npx convex dev
# or for production
npx convex deploy
```

## Utilisation

```typescript
import { ConvexServerCache, ConvexStore } from '@mastra/convex'

const storage = new ConvexStore({
  id: 'convex-storage',
  deploymentUrl: process.env.CONVEX_URL!,
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
})

const cache = new ConvexServerCache({
  deploymentUrl: process.env.CONVEX_URL!,
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
})
```

## Paramètres de ConvexStore

**deploymentUrl** (`string`): URL du déploiement Convex (par exemple, https\://your-project.convex.cloud)

**adminAuthToken** (`string`): Jeton d'authentification d'administration Convex pour accéder au backend

**storageFunction** (`string`): Chemin de la fonction de mutation du stockage (valeur par défaut : 'mastra/storage:handle') (Default: `mastra/storage:handle`)

## Paramètres de ConvexServerCache

**deploymentUrl** (`string`): URL du déploiement Convex (par exemple, https\://your-project.convex.cloud)

**adminAuthToken** (`string`): Jeton d'authentification d'administration Convex pour accéder au backend

**cacheFunction** (`string`): Chemin de la fonction de mutation du cache pour ConvexServerCache (valeur par défaut : 'mastra/cache:handle') (Default: `mastra/cache:handle`)

**requestTimeoutMs** (`number`): Délai d'expiration des requêtes de mutation du cache Convex, en millisecondes. Définissez-le sur 0 pour désactiver le délai d'expiration côté client. (Default: `30000`)

**keyPrefix** (`string`): Préfixe appliqué aux clés de ConvexServerCache. clear() supprime les lignes dont le préfixe enregistré correspond exactement à cette valeur. (Default: `mastra:cache:`)

**ttlMs** (`number`): TTL par défaut de ConvexServerCache en millisecondes. Définissez-le sur 0 pour désactiver l'expiration. (Default: `300000`)

## Exemples de constructeur

```ts
import { ConvexServerCache, ConvexStore } from '@mastra/convex'

// Basic configuration
const store = new ConvexStore({
  id: 'convex-storage',
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
})

// With custom storage function path
const storeCustom = new ConvexStore({
  id: 'convex-storage',
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
  storageFunction: 'custom/path:handler',
})

// Server cache for durable stream replay and response caching
const cache = new ConvexServerCache({
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
  cacheFunction: 'mastra/cache:handle',
})
```

## Cache serveur

`ConvexServerCache` implémente avec Convex le contrat de cache serveur de Mastra. Utilisez-le lorsque vous souhaitez un état de cache durable pour des fonctionnalités telles que les flux d'agents durables pouvant être repris, la relecture des flux de workflows ou la mise en cache des réponses.

`ConvexServerCache` stocke les entrées de liste sous forme de documents Convex distincts. Cela évite d'agrandir une liste de relecture de flux dans un seul document et aide à respecter la limite de taille des enregistrements de Convex.

Chaque valeur scalaire du cache et chaque élément de liste sont stockés dans une ligne Convex et doivent respecter les limites de taille des lignes de Convex. Les listes très volumineuses restent soumises aux limites des requêtes Convex lors de la relecture d'une plage.

Le nettoyage du cache et `clear()` s'exécutent par lots limités. Un seul appel client peut parcourir jusqu'à 1 000 mutations Convex, chacune traitant jusqu'à 25 éléments de liste. Pendant que `clear()` nettoie une clé, les lectures de cette clé peuvent renvoyer des résultats vides jusqu'à la fin du nettoyage.

Pour les espaces de noms de cache très volumineux, effectuez le nettoyage progressivement ou utilisez des préfixes plus précis afin d'éviter les opérations de nettoyage trop longues.

Pendant le nettoyage par lots, les métadonnées du cache peuvent temporairement utiliser un état interne `deleted`. Le passage de nettoyage suivant supprime ces lignes. Évitez d'écrire de nouvelles valeurs avec le même préfixe avant la fin de `clear()`.

`clear()` supprime uniquement les lignes dont le `keyPrefix` enregistré correspond exactement au `keyPrefix` configuré. Elle ne nettoie pas les préfixes imbriqués par correspondance de préfixe de chaîne. Chaque appel à `listPush()` actualise le TTL de la liste en utilisant le `ttlMs` configuré du cache.

Utilisez un `keyPrefix` non vide, sauf si vous souhaitez volontairement que `clear()` supprime toutes les clés de cache du déploiement. Les lignes de liste expirées sont récupérées progressivement lors des lectures et des écritures. `clear()` supprime toutes les lignes correspondant au préfixe.

`ConvexServerCache` convient particulièrement à la relecture durable d'événements de fréquence modérée. Pour les flux de tokens à haute fréquence, privilégiez le regroupement des événements en lots ou un backend de cache à plus faible latence.

`ConvexServerCache` ne remplace pas un transport pub/sub distribué. Si votre application nécessite une diffusion en direct d'événements entre processus, configurez séparément un backend pub/sub de production.

## Remarques supplémentaires

### Gestion du schéma

L'implémentation du stockage utilise des tables Convex typées pour chaque domaine Mastra :

| Domaine                  | Table Convex                  | Rôle                                                 |
| ------------------------ | ----------------------------- | ---------------------------------------------------- |
| Fils                     | `mastra_threads`              | Fils de conversation                                 |
| Messages                 | `mastra_messages`             | Messages de conversation                             |
| Ressources               | `mastra_resources`            | Mémoire de travail de l'utilisateur                  |
| Mémoire observationnelle | `mastra_observational_memory` | Générations de mémoire observationnelle              |
| Workflows                | `mastra_workflow_snapshots`   | État du workflow                                     |
| Scorers                  | `mastra_scorers`              | Données d'évaluation                                 |
| Cache                    | `mastra_cache`                | Valeurs, compteurs et métadonnées de listes du cache |
| Éléments du cache        | `mastra_cache_list_items`     | Entrées de liste du cache                            |
| Repli                    | `mastra_documents`            | Tables inconnues                                     |

### Mémoire observationnelle

`ConvexStore` prend en charge la [mémoire observationnelle](https://mastra.zisheng.pro/fr/docs/memory/observational-memory). Ajoutez `mastraObservationalMemoryTable` à votre schéma Convex et redéployez avec `npx convex deploy` pour l'activer. Les déploiements existants créés avant l'ajout de cette table nécessitent la même mise à jour du schéma.

### Architecture

Toutes les tables typées comprennent :

- un champ `id` pour l'identifiant d'enregistrement de Mastra (distinct de l'identifiant `_id` généré automatiquement par Convex) ;
- un index `by_record_id` permettant des recherches efficaces par identifiant Mastra.

Cette conception assure la compatibilité avec le contrat de stockage de Mastra tout en exploitant l'indexation automatique et les capacités en temps réel de Convex.

### Variables d'environnement

Définissez ces variables d'environnement pour votre déploiement :

- `CONVEX_URL` : URL de votre déploiement Convex
- `CONVEX_ADMIN_KEY` : jeton d'authentification administrateur (à obtenir depuis le tableau de bord Convex)

## Ressources associées

- [Stockage vectoriel Convex](https://mastra.zisheng.pro/fr/reference/vectors/convex)
- [Documentation Convex](https://docs.convex.dev/)