建立 Amplitude 圖表
透過自然語言探索事件、建立圖表定義並驗證結果，從而建立圖表。
事前規劃 (關鍵)
在進行任何工具呼叫前，請先拆解請求：
1. 辨識圖表元件：
- 圖表類型和指標（要量測的項目）
- 時間範圍（未指定時預設為「最近 30 天」）
- 主要事件（要計數的行為）
- 區隔條件（使用者篩選/分組）
- 篩選器、分組、細分維度
- 漏斗步驟（如果是轉換分析）
2. 規劃事件搜尋：
- 每個不同的事件概念進行「一次」搜尋
- 絕對不要在一次搜尋中合併多個概念
- 範例：「購買」和「註冊」需要分開搜尋
3. 規劃平行工具呼叫：
- 取得情境、搜尋事件、尋找同類群組可以同時執行
- 等待結果後再建立定義
事件探索 (關鍵：先探索)
重要：在縮小範圍前先廣泛搜尋
當使用者請求含糊不清或可能對應到多個事件時：
- 先「廣泛」搜尋以探索相關選項
- 檢閱相關結果 – 尋找相關事件、自訂事件、元事件
- 向使用者呈現選項「或」說明你的選擇理由
- 盡量不要未經探索就假設某個事件是唯一答案
搜尋事件：
Amplitude:search with entity_types=['EVENT', 'CUSTOM_EVENT']
- 一次搜尋一個概念
- 先使用廣泛的搜尋詞（例如「AI」而不只是「AI 聊天」）
- ✓ 好的做法：「使用者完成購買」
- ✗ 不好的做法：「註冊或購買事件」
做出明智決定，然後說明：
- 廣泛搜尋以探索所有選項
- 檢閱結果並找出最全面/準確的方法
- 做出你的最佳判斷（較偏好匯總的自訂事件而非單一事件）
- 務必說明：「我找到了 X、Y、Z 選項。我選擇了 [X] 因為 [理由]。這包含/排除了 [範圍]。」
- 使用者可以糾正如果你的假設錯誤
決策標準：
- 較偏好匯總相關活動的自訂事件（例如「[2026] 啟用指標 [僅 AI 事件]」）
- 如果沒有匯總事件，則選擇主要的互動事件
- 思考該產品領域中「活躍使用者」通常的定義
- 除非使用者指定狹義範圍，否則預設使用較廣的範圍
範例：
- ❌ 不好的做法：使用者問「每週 AI 使用者」→ 立即選擇「ai-chat: send message」而沒有探索，也沒有解釋
- ✅ 好的做法：使用者問「每週 AI 使用者」→ 搜尋「AI」，找到 Ask AI、Agents、Visibility、自訂匯總事件。回應：「我發現 AI 活動橫跨 Ask AI、Agents 和 Visibility。我使用匯總事件『[2026] 啟用指標 [僅 AI 事件]』，它包含所有 AI 產品互動。這會給您所有功能的 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"取得事件計數分佈，或使用 dataTableV2 以 user_id 分組並搭配 PROPSUM，然後匯出進行外部分析。
funnels - 具有「預定義步驟」的轉換分析。用於：
- 當您知道預期順序時，逐步轉換率
- 有序或無序序列
- 轉換時間（事件之間的中位數時間）
- 排除事件、轉換窗口
- 重疊事件：要尋找執行多個事件（任何順序）的使用者，請使用「任何順序」的漏斗，並將轉換窗口設定為與圖表日期範圍相符
- 注意：如果您想「探索」使用者採取的實際路徑，請改用
customerJourney
retention - 回訪行為。用於：
- N 天或滾動留存曲線
- 同類群組分析（新使用者 vs 回訪使用者）
- 起始事件 → 回訪事件模式
dataTableV2 - 表格資料。用於：
- 按維度細分（國家、平台等）
- 在表格格式中進行多指標比較
customerJourney - 路徑探索與發現。用於：
- 了解使用者實際採取的實際路徑（相對於漏斗中的預期路徑）
- 分析以特定事件開始、結束或介於兩個事件之間的路徑
- 並排比較已轉換和流失的使用者路徑
- 發現意外的導航模式或摩擦點
- 探索路徑頻率、相似性或平均完成時間
- 橋接理想客戶旅程與實際使用者行為之間的差距
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 (for projectId)
- 探索事件（先廣泛搜尋）：
Amplitude:search for each distinct concept
- Use broad search terms initially
- Look for all related events, custom events, cohorts
- Review ALL results before selecting
- 評估並決定：
- 檢閱所有探索到的事件和自訂事件
- 做出明智決定（較偏好匯總事件）
- 準備清晰說明你的發現和選擇
- 尋找類似圖表（參考範例）：
Amplitude:search entity_types=['CHART'] query="similar concept"
Amplitude:get_charts to see definition structure
- 必要時取得屬性：
Amplitude:get_event_properties
- 建立定義 使用探索到的名稱
- 在回應中說明事件選擇理由
- 建立圖表：
Amplitude:query_dataset with full definition
-
驗證結果 – 檢查資料是否合理
-
儲存圖表：
Amplitude:save_chart_edits with editId from query_dataset
錯誤處理
如果 query_dataset 失敗：
- 仔細閱讀錯誤訊息
- 常見問題：事件名稱錯誤、無效篩選器、參數類型錯誤
- 修正定義並重試
- 先透過搜尋驗證事件是否存在
如果結果為零：
- 檢查篩選器是否過於嚴格
- 驗證事件有資料（搜尋使用該事件的圖表）
- 嘗試更廣的時間範圍
- 檢查區隔條件
最佳實務
命名：
- 包含指標 + 時間情境：「最近 90 天的每週活躍使用者」
- 不要只寫「WAU」或「使用者」
時間範圍：
- 預設為「最近 30 天」
- 對於特定時間區間，使用包含性範圍
- 明確說明已解讀的範圍
驗證：
- 使用前務必驗證事件是否存在
- 檢查類似圖表以了解事件使用方式
- 使用 get_event_properties 確認屬性
比較：
- 使用區隔在同一圖表上比較不同使用者群組
- 對於不同規模的群組，使用比率/百分比
務必包含：
- 回應中的圖表 URL
- 圖表顯示的內容
- 初始資料的關鍵見解
- 使用的方法論