事件表結構

Framedash 將原始遙測儲存在 ClickHouse 的 events 表中。你可以從三個入口用 SQL 讀取它：

REST 的 POST /v1/query 端點。
framedash query CLI 指令。
MCP 的 query 工具。

本頁列出欄位與驗證器規則，讓你不需 Claude Code 外掛也能撰寫查詢。

存取與 scope

原始 SQL 需要具有 data:admin scope 的 API 金鑰（Full 預設）。Read-only 金鑰可以使用內建分析端點與 MCP 工具，但不能使用原始 query 路徑。Ingest（events:write）金鑰依設計既不能查詢，也不能列舉自己的專案。

查詢規則

查詢會被驗證、改寫以強制專案隔離，並在唯讀連線上執行。驗證器強制：

僅允許 SELECT。不允許 INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、TRUNCATE、SYSTEM、OPTIMIZE、KILL，以及 UNION / EXCEPT / INTERSECT。
FROM / JOIN 中只能出現兩個表：events（原始事件）和 daily_sessions_project_mv（預先彙總的每日工作階段）。直接寫 FROM events，隔離篩選會自動注入。
不要在 SQL 中參照 tenant_id 或 project_id。它們會被自動限定，直接參照會被拒絕。
字串常值只能用單引號。雙引號和反引號會被拒絕。
不允許 SETTINGS、FORMAT 或 GLOBAL 子句。允許 IN (SELECT ...) 和 IN ('a','b')；不允許 IN some_table。
若省略頂層 LIMIT，會自動附加一個。

結果為 { "rows": [ { "col": "value" } ], "rowCount": 123 } 的形狀。CLI 和 MCP 工具會直接回傳這個形狀。直接呼叫 REST 端點時,會包在標準 API 信封中:{ "success": true, "data": { "rows": [...], "rowCount": 123 } }。MCP 的 query 工具上限為 1000 列；REST 端點和 CLI 上限為 10000 列。若需更大擷取，請用 LIMIT ... OFFSET ... 分頁，或縮小 timestamp 範圍。

欄位

欄位	型別	說明
`event_name`	String	事件名，例如 `player_death`、`level_start`、`perf_heartbeat`
`timestamp`	DateTime64(6)	事件時間（UTC）
`session_id`	String	遊玩工作階段 id
`player_id`	String	穩定的玩家/裝置 id
`position_x`, `position_y`, `position_z`	Float32	世界座標
`map_id`	String	地圖/關卡識別碼
`fps`	Float32	影格率（perf 事件）
`frame_time_ms`	Float32	影格時間 ms（perf 事件）
`memory_used_bytes`	Int64	記憶體位元組數（perf 事件）
`gpu_time_ms`	Float32	GPU 時間 ms（perf 事件）
`game_thread_ms`	Float32	遊戲執行緒時間 ms
`render_thread_ms`	Float32	算繪執行緒時間 ms
`camera_yaw`, `camera_pitch`	Nullable(Float32)	攝影機朝向
`source`	String	SDK 自身的內部事件（session_start、perf_heartbeat）為 `automated`；您的 `Track(...)` 呼叫為 `player`。不代表 CI 執行(見下方慣例)
`build_id`	String	建置識別碼（perf-diff 候選）
`platform`	String	例如 `windows`、`android`
`engine_version`	String	引擎/建置版本字串
`attributes`	Map(String, String)	自訂字串屬性
`metrics`	Map(String, Float64)	自訂數值指標

Map 型別的欄位用方括號存取：attributes['ci.branch']、metrics['score']。

沒有 server_timestamp 欄位。事件時間請用 timestamp。選取未知欄位會回傳查詢錯誤，因此請先核對上面的欄位名。被拒絕的查詢會回傳 HTTP 400 及 ClickHouse 診斷訊息（未知的欄位、資料表或函式，語法錯誤，型別不符，禁止的操作）；僅基礎設施故障回傳 500。

慣例

自動的效能事件是 perf_heartbeat。perf 查詢請用 WHERE event_name = 'perf_heartbeat' 篩選；並非所有事件都帶有 fps / frame_time_ms。
source = 'automated' 標示 SDK 自身的內部事件(session_start、perf_heartbeat),用來與您的 Track(...) 呼叫區分,不論是否為 CI,每個工作階段都會設定它,因此無法單獨用它識別 CI 執行。
若要篩選 CI 效能分析資料,請使用 build_id 或 attributes['ci.*'] 標籤(由 BeginAutomatedSession / BeginAutomatedSessionFromEnvironment 設定),而非 source。
CI 中繼資料放在 attributes 中：attributes['ci.branch']、attributes['ci.commit']、attributes['ci.scenario']，以及一等欄位 build_id。
事件名是你在 Track(...) 中自選的自由字串。官方 SDK 範例使用 snake_case（player_death、level_start）；請在整個專案中維持一種慣例。
請一律限定 timestamp，讓查詢裁剪分區（該表依日分區）以維持快速。

範例

今日活躍玩家數：

SELECT uniqExact(player_id) AS dau
FROM events
WHERE timestamp >= today()

最近 7 天依事件名的事件量：

SELECT event_name, count() AS events, uniqExact(session_id) AS sessions
FROM events
WHERE timestamp >= today() - 7
GROUP BY event_name
ORDER BY events DESC

依建置的效能百分位：

SELECT build_id,
       count() AS samples,
       round(quantile(0.50)(fps), 1) AS fps_p50,
       round(quantile(0.95)(frame_time_ms), 2) AS frametime_p95_ms
FROM events
WHERE event_name = 'perf_heartbeat'
  AND timestamp >= today() - 14
GROUP BY build_id
ORDER BY samples DESC

後續步驟

API 概觀：認證與查詢端點
CLI 參考：framedash query
疑難排解：查詢前先確認事件已到達

針對 AI 代理: llms.txt