> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # Storage DynamoDB L'implémentation du Storage DynamoDB fournit à Mastra une solution de base de données NoSQL haute capacité et performante, fondée sur un modèle à table unique avec [ElectroDB](https://electrodb.dev/). > **Observability non prise en charge:** Le Storage DynamoDB **ne prend pas en charge le domaine Observability**. Les Traces de `MastraStorageExporter` ne peuvent pas être rendues persistantes dans DynamoDB, et les fonctionnalités Observability de [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview) ne fonctionnent pas si DynamoDB est votre seul Provider de Storage. Pour activer Observability, utilisez le [Storage composite](https://mastra.zisheng.pro/fr/reference/storage/composite) afin d'acheminer ses données vers un Provider pris en charge tel que ClickHouse. > **Limite de taille des éléments:** DynamoDB impose une **taille maximale de 400 Ko par élément**. 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 [Gestion des pièces jointes volumineuses](https://mastra.zisheng.pro/fr/docs/memory/memory-processors) pour découvrir des solutions, notamment l'envoi des pièces jointes vers un Storage externe. ## Fonctionnalités - Architecture à table unique efficace pour tous les besoins de Storage de Mastra - Repose sur ElectroDB pour un accès à DynamoDB avec typage sûr - Prend en charge les identifiants, les régions et les endpoints AWS - Compatible avec AWS DynamoDB Local pour le développement - Stocke les données Thread, Message, Eval et Workflow - Optimisée pour les environnements serverless - TTL (Time To Live) configurable pour l'expiration automatique des données par type d'entité ## Installation **npm**: ```bash npm install @mastra/dynamodb@latest ``` **pnpm**: ```bash pnpm add @mastra/dynamodb@latest ``` **Yarn**: ```bash yarn add @mastra/dynamodb@latest ``` **Bun**: ```bash bun add @mastra/dynamodb@latest ``` ## Prérequis Avant d'utiliser ce package, vous **devez** créer une table DynamoDB possédant une structure précise, notamment des clés primaires et des Global Secondary Indexes (GSI). Cet adaptateur exige que la table DynamoDB et ses GSI soient provisionnés en externe. Des instructions détaillées pour configurer la table au moyen d'AWS CloudFormation ou d'AWS CDK sont disponibles dans [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md). Assurez-vous que votre table est configurée conformément à ces instructions avant de continuer. ## Utilisation ### Utilisation de base ```typescript import { Memory } from '@mastra/memory' import { DynamoDBStore } from '@mastra/dynamodb' // Initialize the DynamoDB storage const storage = new DynamoDBStore({ id: 'dynamodb', // Unique identifier for this storage instance config: { tableName: 'mastra-single-table', // Name of your DynamoDB table region: 'us-east-1', // Optional: AWS region, defaults to 'us-east-1' // endpoint: "http://localhost:8000", // Optional: For local DynamoDB // credentials: { accessKeyId: "YOUR_ACCESS_KEY", secretAccessKey: "YOUR_SECRET_KEY" } // Optional }, }) // Example: Initialize Memory with DynamoDB storage const memory = new Memory({ storage, options: { lastMessages: 10, }, }) ``` ### Développement local avec DynamoDB Local Pour le développement local, vous pouvez utiliser [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html). 1. **Exécutez DynamoDB Local (par exemple, au moyen de Docker) :** ```bash docker run -p 8000:8000 amazon/dynamodb-local ``` 2. **Configurez `DynamoDBStore` afin d'utiliser l'endpoint local :** ```typescript import { DynamoDBStore } from '@mastra/dynamodb' const storage = new DynamoDBStore({ id: 'dynamodb-local', config: { tableName: 'mastra-single-table', // Ensure this table is created in your local DynamoDB region: 'localhost', // Can be any string for local, 'localhost' is common endpoint: 'http://localhost:8000', // For DynamoDB Local, credentials are not typically required unless configured. // If you've configured local credentials: // credentials: { accessKeyId: "fakeMyKeyId", secretAccessKey: "fakeSecretAccessKey" } }, }) ``` Vous devez tout de même créer la table et les GSI dans votre instance DynamoDB locale, par exemple au moyen de la CLI AWS configurée pour votre endpoint local. ## Paramètres **id** (`string`): Identifiant unique de cette instance de Storage. **config.tableName** (`string`): Nom de votre table DynamoDB. **config.region** (`string`): Région AWS. Utilise par défaut 'us-east-1'. Pour le développement local, peut être définie sur 'localhost' ou une valeur similaire. **config.endpoint** (`string`): Endpoint personnalisé de DynamoDB (par exemple, 'http\://localhost:8000' pour le développement local). **config.credentials** (`object`): Objet d'identifiants AWS contenant accessKeyId et secretAccessKey. S'il n'est pas fourni, le SDK AWS tente de récupérer les identifiants depuis les variables d'environnement, les rôles IAM (par exemple, pour EC2/Lambda) ou le fichier partagé d'identifiants AWS. **config.ttl** (`object`): Configuration TTL (Time To Live) pour l'expiration automatique des données. À configurer par type d'entité : thread, message, trace, eval, workflow\_snapshot, resource, score. Chaque configuration d'entité comprend : enabled (boolean), attributeName (string, valeur par défaut : 'ttl') et defaultTtlSeconds (number). ## Configuration TTL (Time To Live) Le TTL de DynamoDB permet de supprimer automatiquement des éléments après une durée déterminée dans les cas suivants : - **Optimisation des coûts** : supprimer automatiquement les anciennes données afin de réduire les coûts de stockage - **Gestion du cycle de vie des données** : implémenter des politiques de rétention à des fins de conformité - **Performances** : empêcher la croissance indéfinie des tables - **Respect de la confidentialité** : purger automatiquement les données personnelles après des périodes déterminées ### Activation de TTL Pour utiliser TTL, vous devez : 1. **Configurer TTL dans DynamoDBStore** (voir ci-dessous) 2. **Activer TTL sur votre table DynamoDB** au moyen de la console ou de la CLI AWS, en indiquant le nom de l'attribut (par défaut : `ttl`) ```typescript import { DynamoDBStore } from '@mastra/dynamodb' const storage = new DynamoDBStore({ name: 'dynamodb', config: { tableName: 'mastra-single-table', region: 'us-east-1', ttl: { // Messages expire after 30 days message: { enabled: true, defaultTtlSeconds: 30 * 24 * 60 * 60, // 30 days }, // Threads expire after 90 days thread: { enabled: true, defaultTtlSeconds: 90 * 24 * 60 * 60, // 90 days }, // Traces expire after 7 days with custom attribute name trace: { enabled: true, attributeName: 'expiresAt', // Custom TTL attribute defaultTtlSeconds: 7 * 24 * 60 * 60, // 7 days }, // Workflow snapshots don't expire workflow_snapshot: { enabled: false, }, }, }, }) ``` ### Types d'entités pris en charge TTL peut être configuré pour les types d'entités suivants : | Entité | Description | | ------------------- | --------------------------------- | | `thread` | Fils de discussion | | `message` | Messages des fils de discussion | | `trace` | Traces Observability | | `eval` | Résultats d'évaluation | | `workflow_snapshot` | Snapshots de l'état des Workflows | | `resource` | Données utilisateur/ressource | | `score` | Résultats de scoring | ### Configuration TTL des entités Chaque type d'entité accepte la configuration suivante : **enabled** (`boolean`): Indique si TTL est activé pour ce type d'entité. **attributeName** (`string`): Nom de l'attribut DynamoDB à utiliser pour TTL. Doit correspondre à l'attribut TTL configuré sur votre table DynamoDB. Utilise par défaut 'ttl'. **defaultTtlSeconds** (`number`): TTL par défaut, en secondes, à compter de la création de l’élément. DynamoDB supprime automatiquement les éléments après cette durée. ### Activation de TTL sur votre table DynamoDB Après avoir configuré TTL dans votre code, vous devez l'activer sur la table DynamoDB elle-même : **Avec la CLI AWS :** ```bash aws dynamodb update-time-to-live \ --table-name mastra-single-table \ --time-to-live-specification "Enabled=true, AttributeName=ttl" ``` **Avec la console AWS :** 1. Accédez à la console DynamoDB 2. Sélectionnez votre table 3. Ouvrez l'onglet « Additional settings » 4. Sous « Time to Live (TTL) », sélectionnez « Manage TTL » 5. Activez TTL et indiquez le nom de l'attribut (par défaut : `ttl`) > **Remarque:** DynamoDB supprime les éléments expirés dans les 48 heures suivant leur expiration. Ils restent interrogeables jusqu'à leur suppression effective. ## Autorisations AWS IAM Le rôle ou l'utilisateur IAM qui exécute le code doit disposer des autorisations nécessaires pour interagir avec la table DynamoDB indiquée et ses index. Vous trouverez ci-dessous un exemple de politique. Remplacez `${YOUR_TABLE_NAME}` par le nom réel de votre table, et `${YOUR_AWS_REGION}` et `${YOUR_AWS_ACCOUNT_ID}` par les valeurs appropriées. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "dynamodb:DescribeTable", "dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:Query", "dynamodb:Scan", "dynamodb:BatchGetItem", "dynamodb:BatchWriteItem" ], "Resource": [ "arn:aws:dynamodb:${YOUR_AWS_REGION}:${YOUR_AWS_ACCOUNT_ID}:table/${YOUR_TABLE_NAME}", "arn:aws:dynamodb:${YOUR_AWS_REGION}:${YOUR_AWS_ACCOUNT_ID}:table/${YOUR_TABLE_NAME}/index/*" ] } ] } ``` ## Points essentiels Avant d'aborder les détails de l'architecture, gardez les points suivants à l'esprit lorsque vous utilisez l'adaptateur de Storage DynamoDB : - **Provisionnement externe de la table :** cet adaptateur _exige_ que vous créiez et configuriez vous-même la table DynamoDB et ses Global Secondary Indexes (GSI) avant de l'utiliser. Suivez le guide de [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md). - **Architecture à table unique :** toutes les données Mastra (fils de discussion, messages, etc.) sont stockées dans une seule table DynamoDB. Ce choix délibéré est optimisé pour DynamoDB et diffère des approches des bases de données relationnelles. - **Compréhension des GSI :** connaître la structure des GSI (décrite dans `TABLE_SETUP.md`) est important pour comprendre la récupération des données et les modèles de requêtes possibles. - **ElectroDB :** l'adaptateur utilise ElectroDB pour gérer les interactions avec DynamoDB et fournir une couche d'abstraction et de typage sûr au-dessus des opérations DynamoDB brutes. ## Approche architecturale Cet adaptateur de Storage utilise un **modèle à table unique** avec [ElectroDB](https://electrodb.dev/), une approche courante et recommandée pour DynamoDB. Son architecture diffère de celle des adaptateurs de bases de données relationnelles (tels que `@mastra/pg` ou `@mastra/libsql`), qui utilisent généralement plusieurs tables, chacune dédiée à une entité précise (fils de discussion, messages, etc.). Principaux aspects de cette approche : - **Natif DynamoDB :** l'architecture à table unique est optimisée pour les fonctionnalités clé-valeur et de requête de DynamoDB, ce qui offre souvent de meilleures performances et une meilleure capacité que l'imitation de modèles relationnels. - **Gestion externe des tables :** contrairement à certains adaptateurs susceptibles de proposer des fonctions utilitaires pour créer des tables au moyen de code, cet adaptateur **exige que la table DynamoDB et ses Global Secondary Indexes (GSI) associés soient provisionnés en externe** avant son utilisation. Consultez [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md) pour obtenir des instructions détaillées utilisant des Tools tels qu'AWS CloudFormation ou CDK. L'adaptateur se concentre uniquement sur les interactions avec la structure de table préexistante. - **Cohérence grâce à l'interface :** bien que le modèle de Storage sous-jacent diffère, cet adaptateur respecte la même interface `MastraStorage` que les autres adaptateurs, ce qui garantit son interchangeabilité dans le composant `Memory` de Mastra. ### Données Mastra dans la table unique Dans la table DynamoDB unique, les différentes entités de données Mastra (telles que Threads, Messages, Traces, Evals et Workflows) sont gérées et distinguées au moyen d'ElectroDB. ElectroDB définit des modèles propres à chaque type d'entité, qui comprennent des structures de clés et des attributs uniques. L'adaptateur peut ainsi stocker et récupérer efficacement divers types de données dans une même table. Par exemple, un élément `Thread` peut posséder une clé primaire telle que `THREAD#`, tandis qu'un élément `Message` appartenant à ce fil peut utiliser `THREAD#` comme clé de partition et `MESSAGE#` comme clé de tri. Les Global Secondary Indexes (GSI), détaillés dans `TABLE_SETUP.md`, sont conçus de manière stratégique pour prendre en charge les modèles d'accès courants entre ces différentes entités, tels que la récupération de tous les messages d'un fil ou l'interrogation des Traces associées à un Workflow. ### Avantages de l'architecture à table unique Cette implémentation utilise un modèle à table unique avec ElectroDB, qui offre plusieurs avantages dans le contexte de DynamoDB : 1. **Coûts potentiellement inférieurs :** un nombre réduit de tables peut simplifier le provisionnement et la gestion des Read/Write Capacity Units (RCU/WCU), en particulier avec la capacité à la demande. 2. **Meilleures performances :** les données associées peuvent être colocalisées ou consultées efficacement au moyen des GSI, ce qui permet des recherches rapides pour les modèles d'accès courants. 3. **Administration simplifiée :** moins de tables distinctes à surveiller et à sauvegarder, donc moins d'éléments à gérer. 4. **Complexité réduite des modèles d'accès :** ElectroDB aide à gérer la complexité des types d'éléments et des modèles d'accès dans une table unique. 5. **Prise en charge des transactions :** les transactions DynamoDB peuvent, si nécessaire, être utilisées entre différents types d'« entités » stockés dans la même table.