arize-dataset

Arize データセットスキル

SPACE — すべての --space フラグと ARIZE_SPACE 環境変数には、スペースの名前（例：my-workspace）または base64 形式のスペース ID（例：U3BhY2U6...）を指定できます。ax spaces list で確認できます。

概念

• データセット = 評価や実験に使用する、バージョン管理されたサンプルのコレクションです
• データセットバージョン = ある時点におけるデータセットのスナップショットです。更新はその場で行うことも、新しいバージョンを作成することもできます
• サンプル = データセット内の単一のレコードです。任意のユーザー定義フィールド（例：question、answer、context）を含みます
• スペース = 組織用のコンテナです。データセットはスペースに属します

サンプルのシステム管理フィールド（id、created_at、updated_at）はサーバーによって自動生成されます。作成または追加のペイロードには絶対に含めないでください。

前提条件

タスクに直接取り掛かり、必要な ax コマンドを実行してください。事前にバージョン、環境変数、プロファイルを確認しないでください。

ax コマンドが失敗した場合は、エラーに応じてトラブルシューティングしてください。

• command not found またはバージョンエラー → references/ax-setup.md を参照してください
• 401 Unauthorized ／API キーがない → ax profiles show を実行して現在のプロファイルを確認してください。プロファイルがない、または API キーが間違っている場合は、references/ax-profiles.md に従って作成または更新してください。ユーザーがキーを持っていない場合は、https://app.arize.com/admin > API Keys に案内してください
• スペースが不明 → ax spaces list を実行して名前で選ぶか、ユーザーに確認してください
• プロジェクトが不明 → ユーザーに確認するか、ax projects list -o json --limit 100 を実行して選択肢として提示してください
• セキュリティ： .env ファイルを読んだり、ファイルシステム内を検索して認証情報を探したりしないでください。Arize の認証情報には ax profiles を、LLM プロバイダーのキーには ax ai-integrations を使用してください。これらの方法で認証情報を取得できない場合は、ユーザーに確認してください。

データセットの一覧表示：ax datasets list

スペース内のデータセットを確認します。出力は標準出力に送られます。

ax datasets list
ax datasets list --space SPACE --limit 20
ax datasets list --cursor CURSOR_TOKEN
ax datasets list -o json

フラグ

フラグ	型	デフォルト	説明
--space	string	プロファイルから取得	スペースで絞り込み
--limit, -l	int	15	最大結果数（1-100）
--cursor	string	なし	前回のレスポンスから取得したページネーションカーソル
-o, --output	string	table	出力形式：table、json、csv、parquet、またはファイルパス
-p, --profile	string	default	設定プロファイル

データセットの取得：ax datasets get

簡易メタデータ検索です。データセット名、スペース、タイムスタンプ、バージョン一覧を返します。

ax datasets get NAME_OR_ID
ax datasets get NAME_OR_ID -o json
ax datasets get NAME_OR_ID --space SPACE   # required when using dataset name instead of ID

フラグ

フラグ	型	デフォルト	説明
NAME_OR_ID	string	必須	データセット名または ID（位置引数）
--space	string	なし	スペース名または ID（データセット名を使用する場合は必須）
-o, --output	string	table	出力形式
-p, --profile	string	default	設定プロファイル

レスポンスフィールド

フィールド	型	説明
id	string	データセット ID
name	string	データセット名
space_id	string	このデータセットが属するスペース
created_at	datetime	データセットが作成された日時
updated_at	datetime	最終更新日時
versions	array	データセットバージョンの一覧（id、name、dataset_id、created_at、updated_at）

データセットのエクスポート：ax datasets export

すべてのサンプルをファイルにダウンロードします。500 件を超えるデータセットの場合は、--all を指定して一括エクスポート（件数制限なし）を行ってください。

ax datasets export NAME_OR_ID
# -> dataset_abc123_20260305_141500/examples.json

ax datasets export NAME_OR_ID --all
ax datasets export NAME_OR_ID --version-id VERSION_ID
ax datasets export NAME_OR_ID --output-dir ./data
ax datasets export NAME_OR_ID --stdout
ax datasets export NAME_OR_ID --stdout | jq '.[0]'
ax datasets export NAME_OR_ID --space SPACE   # required when using dataset name instead of ID

フラグ

フラグ	型	デフォルト	説明
NAME_OR_ID	string	required	データセット名または ID（位置引数）
--space	string	none	スペース名または ID（ID ではなくデータセット名を使う場合に必須）
--version-id	string	latest	特定のデータセットバージョンをエクスポートします
--all	bool	false	件数無制限の一括エクスポート（500 件を超えるデータセットで使用）
--output-dir	string	.	出力ディレクトリ
--stdout	bool	false	ファイルではなく、JSON を標準出力に表示します
-p, --profile	string	default	設定プロファイル

エージェントの自動エスカレーションルール： エクスポート結果がちょうど 500 件の場合、結果が切り詰められている可能性が高いため、--all を付けて再実行し、データセット全体を取得してください。

エクスポートの完全性の確認： エクスポート後、行数がサーバーの報告する件数と一致することを確認してください。

# Get the server-reported count from dataset metadata
ax datasets get DATASET_NAME --space SPACE -o json | jq '.versions[-1] | {version: .id, examples: .example_count}'

# Compare to what was exported
jq 'length' dataset_*/examples.json

# If counts differ, re-export with --all

出力は、サンプルオブジェクトの JSON 配列です。各サンプルには、システムフィールド（id、created_at、updated_at）と、ユーザー定義フィールドがすべて含まれます。

[
  {
    "id": "ex_001",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z",
    "question": "What is 2+2?",
    "answer": "4",
    "topic": "math"
  }
]

データセットの作成：ax datasets create

データファイルから新しいデータセットを作成します。

ax datasets create --name "My Dataset" --space SPACE --file data.csv
ax datasets create --name "My Dataset" --space SPACE --file data.json
ax datasets create --name "My Dataset" --space SPACE --file data.jsonl
ax datasets create --name "My Dataset" --space SPACE --file data.parquet

フラグ

フラグ	型	必須	説明
--name, -n	string	yes	データセット名
--space	string	yes	データセットを作成するスペース
--file, -f	path	yes	データファイル：CSV、JSON、JSONL、または Parquet
-o, --output	string	no	返されるデータセットメタデータの出力形式
-p, --profile	string	no	設定プロファイル

標準入力からデータを渡す

--file - を使うと、データを直接パイプで渡せます。一時ファイルは不要です。

echo '[{"question": "What is 2+2?", "answer": "4"}]' | ax datasets create --name "my-dataset" --space SPACE --file -

# Or with a heredoc
ax datasets create --name "my-dataset" --space SPACE --file - << 'EOF'
[{"question": "What is 2+2?", "answer": "4"}]
EOF

既存のデータセットに行を追加するには、ファイルを使わずに ax datasets append --json '[...]' を使用してください。

対応ファイル形式

形式	拡張子	備考
CSV	.csv	列ヘッダーがフィールド名になります
JSON	.json	オブジェクトの配列
JSON Lines	.jsonl	1 行に 1 つのオブジェクト（JSON 配列ではありません）
Parquet	.parquet	列名がフィールド名になります。型が保持されます

形式ごとの注意点：

• CSV：型情報が失われます。日付は文字列になり、null は空文字列になります。型を保持するには JSON または Parquet を使用してください。
• JSONL：各行が個別の JSON オブジェクトです。.jsonl ファイル内の JSON 配列（[{...}, {...}]）はエラーになります。代わりに .json 拡張子を使用してください。
• Parquet：列の型が保持されます。ローカルで読み込むには pandas／pyarrow が必要です：pd.read_parquet("examples.parquet")。

サンプルの追加：ax datasets append

既存のデータセットにサンプルを追加します。入力方法は 2 種類あります。用途に合った方法を使用してください。

インライン JSON（エージェント向け）

ペイロードを直接生成します。一時ファイルは不要です。

ax datasets append DATASET_NAME --space SPACE --json '[{"question": "What is 2+2?", "answer": "4"}]'

ax datasets append DATASET_NAME --space SPACE --json '[
  {"question": "What is gravity?", "answer": "A fundamental force..."},
  {"question": "What is light?", "answer": "Electromagnetic radiation..."}
]'

ファイルから

ax datasets append DATASET_NAME --space SPACE --file new_examples.csv
ax datasets append DATASET_NAME --space SPACE --file additions.json

特定のバージョンに追加

ax datasets append DATASET_NAME --space SPACE --json '[{"q": "..."}]' --version-id VERSION_ID

フラグ

フラグ	型	必須	説明
NAME_OR_ID	string	yes	データセット名または ID（位置引数）。名前を使う場合は --space を追加します
--space	string	no	スペース名または ID（ID ではなくデータセット名を使う場合に必須）
--json	string	mutex	サンプルオブジェクトの JSON 配列
--file, -f	path	mutex	データファイル（CSV、JSON、JSONL、Parquet）
--version-id	string	no	特定のバージョンに追加します（デフォルト：latest）
-o, --output	string	no	返されるデータセットメタデータの出力形式
-p, --profile	string	no	設定プロファイル

--json と --file のいずれか一方が必須です。

検証

• 各サンプルは、ユーザー定義フィールドを 1 つ以上含む JSON オブジェクトである必要があります
• 1 リクエストあたりのサンプル数は最大 100,000 件です

追加前のスキーマ検証： データセットにすでにサンプルがある場合は、フィールドの不一致が気づかないまま発生するのを防ぐため、追加前にスキーマを確認してください。

# Check existing field names in the dataset
ax datasets export DATASET_NAME --space SPACE --stdout | jq '.[0] | keys'

# Verify your new data has matching field names
echo '[{"question": "..."}]' | jq '.[0] | keys'

# Both outputs should show the same user-defined fields

フィールドは自由形式です。新しいサンプルに余分なフィールドがある場合は追加され、不足しているフィールドは null になります。ただし、フィールド名の誤字（例：queston と question）があると、新しい列が気づかないまま作成されます。追加前に綴りを確認してください。

データセットの削除：ax datasets delete

ax datasets delete NAME_OR_ID
ax datasets delete NAME_OR_ID --space SPACE   # required when using dataset name instead of ID
ax datasets delete NAME_OR_ID --force   # skip confirmation prompt

フラグ

フラグ	型	デフォルト	説明
NAME_OR_ID	string	必須	データセット名または ID（位置引数）
--space	string	なし	スペース名または ID（ID の代わりにデータセット名を使用する場合は必須）
--force, -f	bool	false	確認プロンプトをスキップします
-p, --profile	string	default	設定プロファイル

ワークフロー

名前でデータセットを検索する

すべてのデータセットコマンドでは、名前または ID を直接指定できます。位置引数にデータセット名を指定できます（ID を使用しない場合は --space SPACE を追加してください）。

# Use name directly
ax datasets get "eval-set-v1" --space SPACE
ax datasets export "eval-set-v1" --space SPACE

# Or resolve name to ID via list if you need the base64 ID
ax datasets list -o json | jq '.[] | select(.name == "eval-set-v1") | .id'

評価用にファイルからデータセットを作成する

1. 評価用の列（例：input、expected_output）を含む CSV/JSON/Parquet ファイルを用意します
   • データをインラインで生成する場合は、--file - を使用して stdin 経由でパイプします（「データセットの作成」セクションを参照）
2. ax datasets create --name "eval-set-v1" --space SPACE --file eval_data.csv
3. 確認します：ax datasets get DATASET_NAME --space SPACE
4. データセット名を使って実験を実行します

既存のデータセットに例を追加する

# Find the dataset
ax datasets list --space SPACE

# Append inline or from a file using the dataset name (see Append Examples section for full syntax)
ax datasets append DATASET_NAME --space SPACE --json '[{"question": "...", "answer": "..."}]'
ax datasets append DATASET_NAME --space SPACE --file additional_examples.csv

オフライン分析用にデータセットをダウンロードする

1. ax datasets list --space SPACE -- データセット名を検索します
2. ax datasets export DATASET_NAME --space SPACE -- ファイルにダウンロードします
3. JSON を解析します：jq '.[] | .question' dataset_*/examples.json

特定のバージョンをエクスポートする

# List versions
ax datasets get DATASET_NAME --space SPACE -o json | jq '.versions'

# Export that version
ax datasets export DATASET_NAME --space SPACE --version-id VERSION_ID

データセットを反復して改善する

1. 現在のバージョンをエクスポートします：ax datasets export DATASET_NAME --space SPACE
2. 例をローカルで編集します
3. 新しい行を追加します：ax datasets append DATASET_NAME --space SPACE --file new_rows.csv
4. または新しいバージョンを作成します：ax datasets create --name "eval-set-v2" --space SPACE --file updated_data.json

エクスポートを他のツールにパイプする

# Count examples
ax datasets export DATASET_NAME --space SPACE --stdout | jq 'length'

# Extract a single field
ax datasets export DATASET_NAME --space SPACE --stdout | jq '.[].question'

# Convert to CSV with jq
ax datasets export DATASET_NAME --space SPACE --stdout | jq -r '.[] | [.question, .answer] | @csv'

データセットの例のスキーマ

例は自由形式の JSON オブジェクトです。固定スキーマはなく、列は指定したフィールドによって決まります。サーバーによって管理されるフィールドが追加されます。

フィールド	型	管理者	備考
id	string	server	自動生成される UUID です。更新時は必須で、作成／追加時は禁止されています
created_at	datetime	server	変更できない作成日時です
updated_at	datetime	server	変更時に自動更新されます
(任意のユーザーフィールド)	any JSON type	user	文字列、数値、ブール値、null、ネストされたオブジェクト、配列

関連スキル

• arize-trace：本番環境のスパンをエクスポートして、データセットに含めるデータを把握します → arize-trace を使用します
• arize-experiment：このデータセットに対して評価を実行します → 次のステップは arize-experiment です
• arize-prompt-optimization：データセットと実験結果を使ってプロンプトを改善します → arize-prompt-optimization を使用します

トラブルシューティング

問題	解決策
ax: command not found	references/ax-setup.md を参照してください
401 Unauthorized	API キーが間違っているか、有効期限切れか、このスペースへのアクセス権がありません。references/ax-profiles.md を使ってプロファイルを修正してください。
No profile found	プロファイルが設定されていません。references/ax-profiles.md を参照して作成してください。
Dataset not found	ax datasets list でデータセット ID を確認してください
File format error	対応形式：CSV、JSON、JSONL、Parquet。stdin から読み込むには --file - を使用してください。
platform-managed column	作成／追加のペイロードから id、created_at、updated_at を削除してください
reserved column	time、count、または source_record_* フィールドを削除してください
Provide either --json or --file	追加時には入力ソースをちょうど 1 つ指定する必要があります
Examples array is empty	JSON 配列またはファイルに少なくとも 1 つの例が含まれていることを確認してください
not a JSON object	--json 配列の各要素は {...} オブジェクトである必要があります。文字列や数値は指定できません

今後の使用に備えて認証情報を保存する

references/ax-profiles.md §「今後の使用に備えて認証情報を保存する」を参照してください。