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

# Dataset の概要

**追加バージョン:** `@mastra/core@1.4.0`

Dataset は、Agent や Workflow の性能を測る Experiment で使用するテストケースのコレクションです。変更するたびに新しいバージョンが作成されるため、過去の Experiment を正確に再現できます。Dataset と [Scorer](https://mastra.zisheng.pro/ja/docs/evals/overview) を組み合わせると、プロンプト、モデル、コードの変更に伴う品質を追跡できます。

**AI Agent 向け:** Studio を開いたり一時スクリプトを書いたりせず、`npx mastra api dataset create '{"name":"translation-pairs"}'` を実行して Dataset を直接作成できます。このコマンドには、Dataset をサポートするストレージアダプターを備えた稼働中の Mastra サーバーが必要です。`npx mastra dev` でローカルサーバーを起動するか、`--url` で接続可能なサーバーのベース URL を指定してください。異なる Dataset フィールドを追加する前に、`npx mastra api dataset create --schema` を実行します。API CLI の検出、ターゲット指定、スキーマ、認証、エラー処理に関する詳しいガイダンスを利用するには、`npx skills add mastra-ai/skills --skill mastra` で Mastra の Skill をインストールしてください。

## 使用方法

### ストレージを設定する

Mastra インスタンスにストレージを設定します。Dataset には、`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',
  }),
})
```

### Datasets API にアクセスする

Dataset のすべての操作は `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()
```

すべてのメソッドについては、[`DatasetsManager` リファレンス](https://mastra.zisheng.pro/ja/reference/datasets/datasets-manager)を参照してください。

## Studio

[Studio](https://mastra.zisheng.pro/ja/docs/studio/overview) でも Dataset を管理できます。Studio を開き、サイドバーから **Datasets** を選択すると、利用可能なすべての Dataset を確認したり、新規作成したりできます。

まず **Create Dataset** を選択し、名前、説明、任意のスキーマを設定します。確定すると Dataset の詳細ページが開き、**Items** と [**Experiments**](https://mastra.zisheng.pro/ja/docs/datasets/running-experiments) の2つのタブが表示されます。

**Items** ビューでは、項目の追加、更新、削除、バージョン履歴の確認ができます。**Add Item** を選択すると、input と ground truth を JSON エディターで入力して新しい項目を追加できます。このビューでは、CSV または JSON ファイルから項目を一括インポートすることもできます。インポート時に、各列を対応する Dataset フィールドへ割り当てます。

**Versions** を選択すると、Dataset の変更履歴全体を確認できます。**Compare Versions** を選択して任意の2つのバージョンを指定し、**Compare** を選択すると、バージョン間で追加、変更、削除されたすべての項目が並べて表示されます。

## Dataset を作成する

名前と任意の説明を指定して [`create()`](https://mastra.zisheng.pro/ja/reference/datasets/create) を呼び出します。

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

### スキーマを定義する

Dataset の作成時に [Standard JSON Schema](https://standardschema.dev/json-schema)（[Zod](https://zod.dev/)、[Valibot](https://valibot.dev/)、[ArkType](https://arktype.io/) など）を渡すと、`input` と `groundTruth` の構造を強制できます。

```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(),
  }),
})
```

スキーマに一致しない項目は、追加時に拒否されます。

## 項目を追加する

単一の項目には [`addItem()`](https://mastra.zisheng.pro/ja/reference/datasets/addItem)、一括追加には [`addItems()`](https://mastra.zisheng.pro/ja/reference/datasets/addItems) を使用します。

```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' },
    },
  ],
})
```

## 項目を更新、削除する

[`updateItem()`](https://mastra.zisheng.pro/ja/reference/datasets/updateItem)、[`deleteItem()`](https://mastra.zisheng.pro/ja/reference/datasets/deleteItem)、[`deleteItems()`](https://mastra.zisheng.pro/ja/reference/datasets/deleteItems) を使うと、`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'] })
```

## 項目を一覧表示、検索する

[`listItems()`](https://mastra.zisheng.pro/ja/reference/datasets/listItems) はページネーションと全文検索に対応しています。

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

## バージョン管理

Dataset の項目を変更（追加、更新、削除）するたびに Dataset のバージョンが上がります。これにより、Experiment を特定のデータスナップショットに固定できます。

### バージョンを一覧表示する

[`listVersions()`](https://mastra.zisheng.pro/ja/reference/datasets/listVersions) を使用すると、バージョン履歴をページ分割して確認できます。

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

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

### 項目の履歴を確認する

`itemId` を指定して [`getItemHistory()`](https://mastra.zisheng.pro/ja/reference/datasets/getItemHistory) を呼び出すと、特定の項目がバージョン間でどう変化したかを確認できます。

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

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

### バージョンに固定する

過去のバージョンに存在した項目をそのまま取得します。

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

Experiment も特定のバージョンに固定できます。詳しくは [Experiment の実行](https://mastra.zisheng.pro/ja/docs/datasets/running-experiments)を参照してください。すべてのメソッドとパラメーターについては、[`Dataset` リファレンス](https://mastra.zisheng.pro/ja/reference/datasets/dataset)を参照してください。

## 関連情報

- [Experiment の実行](https://mastra.zisheng.pro/ja/docs/datasets/running-experiments)
- [Scorer の概要](https://mastra.zisheng.pro/ja/docs/evals/overview)
- [DatasetsManager リファレンス](https://mastra.zisheng.pro/ja/reference/datasets/datasets-manager)
- [Dataset リファレンス](https://mastra.zisheng.pro/ja/reference/datasets/dataset)
- 📹 [Mastra の Evals、Dataset、Experiment ワークショップ](https://www.youtube.com/watch?v=Vla5LfmOOrM)