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

# Présentation des Datasets

**Ajouté dans :** `@mastra/core@1.4.0`

Les Datasets sont des collections de cas de test sur lesquels vous exécutez des Experiments afin de mesurer les performances de vos Agents et Workflows. Chaque mutation crée une nouvelle version, ce qui vous permet de reproduire exactement les Experiments passés. Associez les Datasets à des [Scorers](https://mastra.zisheng.pro/fr/docs/evals/overview) pour suivre la qualité en fonction des prompts, des modèles ou des modifications du code.

**Pour les Agents IA :** exécutez `npx mastra api dataset create '{"name":"translation-pairs"}'` afin de créer directement un Dataset, sans ouvrir Studio ni écrire de script temporaire. Cette commande nécessite un serveur Mastra en cours d’exécution avec un adaptateur de stockage compatible avec les Datasets ; démarrez le serveur local avec `npx mastra dev` ou transmettez l’URL de base du serveur accessible au moyen de `--url`. Exécutez `npx mastra api dataset create --schema` avant d’ajouter différents champs au Dataset. Installez le Skill de Mastra avec `npx skills add mastra-ai/skills --skill mastra` pour obtenir des instructions complètes sur la découverte des API avec la CLI, le ciblage, les schémas, l’authentification et la gestion des erreurs.

## Utilisation

### Configurer le stockage

Configurez le stockage dans votre instance Mastra. Les Datasets nécessitent un adaptateur de stockage qui fournit le domaine `datasets` :

```typescript
import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'my-store',
    url: 'file:./mastra.db',
  }),
})
```

### Accéder à l’API des Datasets

Toutes les opérations sur les Datasets sont accessibles au moyen de `mastra.datasets` :

```typescript
const datasets = mastra.datasets

// Create a dataset
const dataset = await datasets.create({ name: 'my-dataset' })

// Retrieve an existing dataset
const existing = await datasets.get({ id: 'dataset-id' })

// List all datasets
const { datasets: all } = await datasets.list()
```

Consultez la [référence de `DatasetsManager`](https://mastra.zisheng.pro/fr/reference/datasets/datasets-manager) pour obtenir la liste complète des méthodes.

## Studio

Vous pouvez également gérer les Datasets dans [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview). Après avoir ouvert Studio, sélectionnez **Datasets** dans la barre latérale pour afficher tous les Datasets disponibles ou en créer un nouveau.

Pour commencer, sélectionnez **Create Dataset**, puis définissez un nom, une description et, si nécessaire, des schémas. Après confirmation, la page de détails du Dataset affiche deux onglets : **Items** et [**Experiments**](https://mastra.zisheng.pro/fr/docs/datasets/running-experiments).

Dans la vue **Items**, vous pouvez ajouter, mettre à jour et supprimer des éléments, ainsi que consulter l’historique des versions. Sélectionnez **Add Item** pour insérer un nouvel élément à l’aide d’éditeurs JSON pour l’entrée et la vérité terrain. Cette vue permet également d’importer des éléments en masse depuis un fichier CSV ou JSON. Lors de l’importation, associez chaque colonne au champ correspondant du Dataset.

Sélectionnez **Versions** pour consulter l’historique complet des modifications du Dataset. Après avoir sélectionné **Compare Versions**, choisissez deux versions, puis sélectionnez **Compare** pour afficher côte à côte les différences entre tous les éléments ajoutés, modifiés ou supprimés d’une version à l’autre.

## Créer un Dataset

Appelez [`create()`](https://mastra.zisheng.pro/fr/reference/datasets/create) avec un nom et, éventuellement, une description :

```typescript
import { mastra } from '../index'

const dataset = await mastra.datasets.create({
  name: 'translation-pairs',
  description: 'English to Spanish translation test cases',
})

console.log(dataset.id) // auto-generated UUID
```

### Définir des schémas

Vous pouvez imposer la structure d’`input` et de `groundTruth` en transmettant un [schéma JSON standard](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.) lors de la création du Dataset :

```typescript
import { z } from 'zod'
import { mastra } from '../index'

const dataset = await mastra.datasets.create({
  name: 'translation-pairs',
  inputSchema: z.object({
    text: z.string(),
    sourceLang: z.string(),
    targetLang: z.string(),
  }),
  groundTruthSchema: z.object({
    translation: z.string(),
  }),
})
```

Les éléments qui ne correspondent pas au schéma sont refusés lors de l’insertion.

## Ajouter des éléments

Utilisez [`addItem()`](https://mastra.zisheng.pro/fr/reference/datasets/addItem) pour un seul élément ou [`addItems()`](https://mastra.zisheng.pro/fr/reference/datasets/addItems) pour effectuer une insertion en masse :

```typescript
// Single item
await dataset.addItem({
  input: { text: 'Hello', sourceLang: 'en', targetLang: 'es' },
  groundTruth: { translation: 'Hola' },
})

// Bulk insert
await dataset.addItems({
  items: [
    {
      input: { text: 'Goodbye', sourceLang: 'en', targetLang: 'es' },
      groundTruth: { translation: 'Adiós' },
    },
    {
      input: { text: 'Thank you', sourceLang: 'en', targetLang: 'es' },
      groundTruth: { translation: 'Gracias' },
    },
  ],
})
```

## Mettre à jour et supprimer des éléments

[`updateItem()`](https://mastra.zisheng.pro/fr/reference/datasets/updateItem), [`deleteItem()`](https://mastra.zisheng.pro/fr/reference/datasets/deleteItem) et [`deleteItems()`](https://mastra.zisheng.pro/fr/reference/datasets/deleteItems) permettent de modifier ou de supprimer des éléments existants à l’aide de leur `itemId` :

```typescript
await dataset.updateItem({
  itemId: 'item-abc-123',
  groundTruth: { translation: '¡Hola!' },
})

await dataset.deleteItem({ itemId: 'item-abc-123' })

await dataset.deleteItems({ itemIds: ['item-1', 'item-2'] })
```

## Répertorier et rechercher des éléments

[`listItems()`](https://mastra.zisheng.pro/fr/reference/datasets/listItems) prend en charge la pagination et la recherche en texte intégral :

```typescript
// Paginated list
const { items, pagination } = await dataset.listItems({
  page: 0,
  perPage: 50,
})

// Full-text search
const { items: matches } = await dataset.listItems({
  search: 'Hello',
})

// Search and pagination can be combined with a specific version
const { items: v2Matches } = await dataset.listItems({
  version: 2,
  search: 'Hello',
  page: 0,
  perPage: 50,
})

// Version-only snapshot returns a bare DatasetItem[]
const v2Items = await dataset.listItems({ version: 2 })
```

## Gestion des versions

Chaque mutation apportée aux éléments d’un Dataset (ajout, mise à jour ou suppression) incrémente sa version. Vous pouvez ainsi épingler des Experiments à un snapshot précis des données.

### Répertorier les versions

Utilisez [`listVersions()`](https://mastra.zisheng.pro/fr/reference/datasets/listVersions) pour consulter l’historique paginé des versions :

```typescript
const { versions, pagination } = await dataset.listVersions()

for (const v of versions) {
  console.log(`Version ${v.version} — created ${v.createdAt}`)
}
```

### Consulter l’historique d’un élément

Pour savoir comment un élément précis a évolué d’une version à l’autre, appelez [`getItemHistory()`](https://mastra.zisheng.pro/fr/reference/datasets/getItemHistory) avec son `itemId` :

```typescript
const history = await dataset.getItemHistory({ itemId: 'item-abc-123' })

for (const row of history) {
  console.log(`Version ${row.datasetVersion}`, row.input, row.groundTruth)
}
```

### Épingler une version

Récupérez les éléments exacts qui existaient dans une version antérieure :

```typescript
const items = await dataset.listItems({ version: 2 })
```

Vous pouvez également épingler des Experiments à une version ; consultez la page [Exécuter des Experiments](https://mastra.zisheng.pro/fr/docs/datasets/running-experiments). Consultez la [référence de `Dataset`](https://mastra.zisheng.pro/fr/reference/datasets/dataset) pour obtenir la liste complète des méthodes et paramètres.

## Voir aussi

- [Exécuter des Experiments](https://mastra.zisheng.pro/fr/docs/datasets/running-experiments)
- [Présentation des Scorers](https://mastra.zisheng.pro/fr/docs/evals/overview)
- [Référence de DatasetsManager](https://mastra.zisheng.pro/fr/reference/datasets/datasets-manager)
- [Référence de Dataset](https://mastra.zisheng.pro/fr/reference/datasets/dataset)
- 📹 [Atelier Mastra sur les Evals, Datasets et Experiments](https://www.youtube.com/watch?v=Vla5LfmOOrM)