arize-dataset

Arize Dataset Skill

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

概念

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

サンプルのシステム管理フィールド（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 に案内してください
• スペースが不明 → Space を参照してください
• プロジェクトが不明確 → ユーザーに尋ねるか、ax projects list -o json --limit 100 を実行し、選択肢として提示してください
• セキュリティ： .env ファイルを読んだり、ファイルシステムを検索して認証情報を探したりしてはいけません。例外は、機密情報ではない ARIZE_SPACE_ID の行です（Space を参照）。Arize の認証情報には ax profiles、LLM プロバイダーのキーには ax ai-integrations を使用してください。チャットに秘密情報を貼り付けるようユーザーに求めてはいけません。認証情報がない場合は、references/ax-profiles.md を参照してください。

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

スペース内のデータセットを確認します。一覧表示は人が閲覧するためのものです。データセット名または ID がわかっている場合は、ax datasets get NAME_OR_ID --space SPACE -o json を直接実行してください。

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

すべてのフラグについては、ax datasets list --help を実行してください。

データセットの取得：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

すべてのフラグについては、ax datasets get --help を実行してください。

レスポンスフィールド

フィールド	型	説明
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

サンプルをファイルにダウンロードします。デフォルトでは、エクスポートされるサンプルは1ページ分です（--limit はページサイズを設定し、--cursor は後続ページを選択します）。データセット全体をエクスポートするには --all を指定してください。サンプル列、id、annotation.<name>.* に対する SQL のような式でサーバー側の絞り込みを行うには、--filter を使用します。--filter は --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 --filter "annotation.Correctness.label = 'Correct'"
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

すべてのフラグについては、ax datasets export --help を実行してください。

エージェント向けルール： すべてのサンプルが必要なタスクでは、必ず --all を指定してください。--all を指定しないエクスポートは、1ページ分で停止します。

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

# 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

データファイル（--file）またはインライン JSON（--json）から新しいデータセットを作成します。

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
ax datasets create --name "My Dataset" --space SPACE --json '[{"question": "What is 2+2?", "answer": "4"}]'

すべてのフラグについては、ax datasets create --help を実行してください。

stdin 経由でのデータ渡し

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

サポートされているファイル形式

形式	拡張子	備考
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

すべてのフラグを確認するには、ax datasets append --help を実行してください。

--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 update-examples

ax datasets update-examples は例の id を使って行にパッチを適用します。ax datasets delete-examples は 1 つのバージョンから行を削除します。削除するには、--version-id と、例 ID の JSON 配列を指定する --example-ids が必要です。あまり一般的ではありません。フラグと入力形式を確認するには、ax datasets update-examples --help または ax datasets delete-examples --help を実行してください。

データセットを削除する：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

すべてのフラグを確認するには、ax datasets delete --help を実行してください。

データセットを更新する：ax datasets update

既存のデータセットの名前を変更します。

ax datasets update NAME_OR_ID --name "new-dataset-name"
ax datasets update NAME_OR_ID --name "new-dataset-name" --space SPACE

すべてのフラグを確認するには、ax datasets update --help を実行してください。

例にアノテーションを付ける：ax datasets annotate-examples

ファイルを使って、データセットの例にアノテーションを一括で書き込みます。アップサート方式です。同じキーの既存のアノテーションは更新され、新しいものは作成されます。1 リクエストあたり最大 1000 件の例を処理できます。各レコードには record_id（データセットの例の ID）と values が必要です。一致しないレコード ID は通知されないまま無視されるため、事前にエクスポート結果と照合して ID を確認してください。

ax datasets annotate-examples NAME_OR_ID --file annotations.json
ax datasets annotate-examples NAME_OR_ID --file annotations.csv --space SPACE

すべてのフラグを確認するには、ax datasets annotate-examples --help を実行してください。

ワークフロー

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

すべてのデータセットコマンドは、名前または ID を直接受け付けます（名前を指定する場合は --space SPACE を追加してください）。名前を ID に解決するには、get の出力から ID を取得します。

ax datasets get "eval-set-v1" --space SPACE -o json | jq -r '.id'

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

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

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

# 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 export DATASET_NAME --space SPACE --all -- すべての例をファイルにダウンロードします
2. 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 --all
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 --all --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	サーバー	UUID が自動生成されます。更新時は必須で、作成／追加時は禁止されています
created_at	datetime	サーバー	変更できない作成日時
updated_at	datetime	サーバー	変更時に自動更新されます
(任意のユーザーフィールド)	任意の JSON 型	ユーザー	文字列、数値、ブール値、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 get NAME_OR_ID --space SPACE で名前または ID を確認してください。正しい名前を探す場合に限り、ax datasets list --space SPACE を使用してください
File format error	対応形式：CSV、JSON、JSONL、Parquet。標準入力から読み込むには --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 の「今後のために認証情報を保存する」を参照してください。