Amplitudeチャートを作成
自然言語からチャートを作成し、イベントの発見、チャート定義の構築、結果の検証を行います。
最初に計画を立てる（重要）
ツールを呼び出す前に、リクエストを分解します：
1. チャートの構成要素を特定：
- チャートの種類と指標（何を測定するか）
- 時間範囲（指定がない場合のデフォルト：過去30日間）
- プライマリイベント（カウント対象のアクション）
- セグメント条件（ユーザーフィルター/グループ）
- フィルター、グループ化、内訳
- ファネルステップ（コンバージョン分析の場合）
2. イベント検索の計画：
- 異なるイベント概念ごとに1回の検索
- 複数の概念を1回の検索にまとめない
- 例：「purchase」と「signup」は別々に検索
3. 並行ツール呼び出しの計画：
- コンテキスト取得、イベント検索、コホート検索は並行して実行可能
- 定義を構築する前に結果を待つ
イベント発見（重要：発見が優先）
重要：絞り込む前に広く検索すること
ユーザーのリクエストがあいまい、または複数のイベントにマッピングされる可能性がある場合：
- 最初に広く検索して、関連するオプションを発見する
- 関連する結果を確認し、関連イベント、カスタムイベント、メタイベントを探す
- オプションをユーザーに提示するか、選択した理由を説明する
- 探索せずに単一のイベントだけが答えだと決めつけない
イベントの検索：
Amplitude:search with entity_types=['EVENT', 'CUSTOM_EVENT']
- 一度に1つの概念を検索
- まず広い検索語を使用（例：「AIチャット」ではなく「AI」）
- ✓ 良い例：「user completes purchase」
- ✗ 悪い例：「signup or purchase events」
情報に基づいた判断を下し、説明する：
- 広く検索してすべてのオプションを発見
- 結果を確認し、最も包括的/正確なアプローチを特定
- 最善の判断を下す（単一イベントよりも集約されたカスタムイベントを優先）
- 常に説明する：「X、Y、Zのオプションが見つかりました。[理由]により[X]を選択しました。これには[範囲]が含まれ/除外されます。」
- ユーザーは前提が間違っていた場合に修正可能
判断基準：
- 関連アクティビティを集約するカスタムイベントを優先（例：「[2026] Activation Metric [AI events only]」）
- 集約イベントが存在しない場合は、主要なインタラクションイベントを選択
- そのプロダクトエリアでの「アクティブユーザー」の一般的な意味を考慮
- ユーザーが狭い焦点を指定しない限り、デフォルトでより広い範囲を選択
例：
- ❌ 悪い例：ユーザーが「週間AIユーザー」と依頼 → 即座に「ai-chat: send message」を選択、探索なし、説明なし
- ✅ 良い例：ユーザーが「週間AIユーザー」と依頼 → 「AI」を検索し、Ask AI、Agents、Visibility、カスタム集約イベントを見つける。応答：「AIアクティビティはAsk AI、Agents、Visibilityにわたって見つかりました。すべてのAIプロダクトインタラクションを含むカスタムイベント「[2026] Activation Metric [AI events only]」を使用しています。これにより、全機能にわたる総AIユーザー数が得られます。特定のAIプロダクトに焦点を当てたい場合はお知らせください。」
使用前に検証：
- そのイベントを使用している既存のチャートを検索で取得
- イベントに実際のボリュームがあることを確認（ゼロまたは古いデータではない）
- 関連アクティビティを集約するカスタムイベントを探す
- 結果がゼロの場合は、代替案を検索
プロパティの取得：
Amplitude:get_event_properties で正確なプロパティ名/値を取得
コホートの検索：
Amplitude:search with entity_types=['COHORT']
Amplitude:get_cohorts で完全な定義を取得
チャートタイプの選択
| チャートタイプ | 使用するタイミング |
|---|---|
eventsSegmentation | イベント/ユーザーを経時的にカウント、トレンド、比較、KPI、分布、プロパティ分析 |
funnels | 既知のシーケンスによるマルチステップコンバージョン分析、ドロップオフ分析、特定イベント間の時間、コンバージョンまでの時間指標 |
retention | ユーザーのリターン行動、コホートリテンション曲線、チャーン分析 |
dataTableV2 | 表形式の比較、ランキング、多次元の内訳 |
customerJourney | パス探索、ユーザーが取る未知のパスの発見、コンバージョンしたパスとドロップオフしたパスの比較 |
sessions | セッション期間、セッション頻度、ユーザーあたりの滞在時間、セッション長分布 |
クイックリファレンス
eventsSegmentation - 最も汎用性が高い。以下に使用：
- ユーザー数（DAU、WAU、MAU）を
uniques指標で - イベント合計、平均、プロパティの合計
- パーセンタイル、分布、数式
- ローリングウィンドウによる時系列
集約スコープ（eventsSegmentation）：
PROPSUM(A)/metric: "sums"= 全イベントにわたるグローバル合計metric: "frequency"= ユーザーあたりのイベントカウントの分布（何人のユーザーが1回、2回、3回実行したか）- 「ユーザーあたりのプロパティ合計の分布」：Amplitudeはこれを直接サポートしていません。イベントカウント分布には
metric: "frequency"を使用するか、user_idでグループ化したdataTableV2とPROPSUMを使用し、外部分析のためにエクスポートしてください。
funnels - 事前定義されたステップによるコンバージョン分析。以下に使用：
- 期待されるシーケンスがわかっている場合のステップごとのコンバージョン率
- 順序ありまたは順序なしのシーケンス
- コンバージョンまでの時間（イベント間の中央時間）
- 除外イベント、コンバージョンウィンドウ
- 重複イベント：複数のイベントを（任意の順序で）実行したユーザーを見つけるには、「任意の順序」でファネルを使用し、コンバージョンウィンドウをチャートの日付範囲に設定します
- 注：ユーザーが取るパスを発見したい場合は、代わりに
customerJourneyを使用してください
retention - リターン行動。以下に使用：
- N日またはローリングリテンション曲線
- コホート分析（新規 vs リピーターユーザー）
- 開始イベント → リターンイベントのパターン
dataTableV2 - 表形式データ。以下に使用：
- ディメンションによる内訳（国、プラットフォームなど）
- 表形式での複数指標比較
customerJourney - パス探索と発見。以下に使用：
- ユーザーが取る実際のパスを理解する（ファネルの期待パスとの比較）
- 特定のイベントで始まる、終わる、または2つのイベント間のパスを分析
- コンバージョンしたパスとドロップオフしたパスを並べて比較
- 予期しないナビゲーションパターンや摩擦点を発見
- パスの頻度、類似性、または完了までの平均時間を探索
- 理想的なカスタマージャーニーと実際のユーザー行動のギャップを埋める
sessions - セッションベースのエンゲージメント指標。以下に使用：
- セッション期間分析（平均長、滞在時間、分布）
- セッション頻度（ユーザーあたりの平均セッション数、総セッション数）
- 経時的なユーザーあたりの滞在時間
- セッション内で実行されたイベント（セッションあたりの平均イベント数）
- ユーザーセグメント間のセッション行動の比較
特別な指標：
- ユーザー数：
metric: "uniques" - イベント数：
metric: "totals" - プロパティの合計：
metric: "sums"（group_byにプロパティを指定） - 率/パーセンテージ：異なるサイズのグループを比較する場合に使用
メタイベント：
_active：任意のアクティブイベント（DAU、MAU）_new：新規ユーザー（初回イベント）_any_revenue_event：収益イベント
チャート定義の構造
コアパラメータ（全チャートタイプ共通）：
{
"name": "説明的なチャートタイトル",
"projectId": "12345",
"definition": {
"app": "12345",
"type": "eventsSegmentation",
"params": {
"range": "Last 30 Days",
"events": [{
"event_type": "Purchase Completed",
"filters": [],
"group_by": []
}],
"metric": "uniques",
"countGroup": "User",
"interval": 1,
"segments": [{"conditions": []}]
}
}
}
主要パラメータ：
countGroup：「User」（ユニークユーザー）または「Event」（イベント発生回数）interval：1（日次）、7（週次）、30（月次）segments：ユーザーフィルター/グループ（空配列 = 全ユーザー）
イベントフィルター（インラインOR論理）：
"filters": [{
"group_type": "User",
"subprop_key": "country",
"subprop_op": "is",
"subprop_type": "event",
"subprop_value": ["United States", "Canada"]
}]
ユーザーセグメント（条件AND論理）：
"segments": [{
"name": "Active Users",
"conditions": [{
"type": "property",
"group_type": "User",
"prop_type": "user",
"prop": "plan",
"op": "is",
"values": ["Pro", "Enterprise"]
}]
}]
コホートセグメント： コホートを検索し、IDを取得後：
"segments": [{
"name": "My Cohort",
"conditions": [{
"type": "cohort",
"group_type": "User",
"cohort_id": "abc123",
"op": "is_in"
}]
}]
ワークフロー：チャートを作成
- コンテキストを取得：
Amplitude:get_context (projectId を取得)
- イベントを発見（最初に広く検索）：
Amplitude:search で各異なる概念ごとに
- 最初は広い検索語を使用
- すべての関連イベント、カスタムイベント、コホートを確認
- 選択前にすべての結果を確認
- 評価して決定：
- 発見されたすべてのイベントとカスタムイベントを確認
- 情報に基づいた決定を行う（集約イベントを優先）
- 見つけた内容と選択理由の明確な説明を準備
- 類似チャートを見つける（例を参考に）：
Amplitude:search entity_types=['CHART'] query="類似概念"
Amplitude:get_charts で定義構造を確認
- 必要に応じてプロパティを取得：
Amplitude:get_event_properties
- 発見した名前を使用して定義を構築
- 応答でイベント選択の根拠を説明
- チャートを作成：
Amplitude:query_dataset で完全な定義を送信
-
結果を検証 - データが妥当か確認
-
チャートを保存：
Amplitude:save_chart_edits with editId from query_dataset
エラーハンドリング
query_dataset が失敗した場合：
- エラーメッセージを注意深く読む
- 一般的な問題：誤ったイベント名、無効なフィルター、誤ったパラメータタイプ
- 定義を修正して再試行
- 検索でイベントが存在することを最初に確認
結果がゼロの場合：
- フィルターが制限しすぎていないか確認
- イベントにデータがあることを確認（それを使用したチャートを検索）
- より広い時間範囲を試す
- セグメント条件を確認
ベストプラクティス
命名：
- 指標 + 時間コンテキストを含める：「過去90日間の週間アクティブユーザー」
- 避けるべき例：「WAU」や「Users」
時間範囲：
- デフォルトは「過去30日間」
- 特定の期間には包括的な範囲を使用
- 解釈した範囲を明示的に記載
検証：
- 使用前にイベントが存在することを常に確認
- 類似チャートを確認してイベントの使用法を理解
- get_event_properties でプロパティを確認
比較：
- 同じチャート上でユーザーグループを比較するにはセグメントを使用
- 異なるサイズのグループには率/パーセンテージを使用
常に含めること：
- 応答内のチャートURL
- チャートが示す内容
- 初期データからの主要なインサイト
- 使用した方法論