04 — 資料模型

標準事件與 BigQuery schema

一個 envelope 把所有來源正規化。共通欄位是強型別欄位，方便快速篩選；來源專屬的 payload 放在單一 JSON 欄位。

欄位

欄位	說明	型別	必填
event_id	事件唯一識別碼（UUID）	STRING	●
occurred_at	事件在來源端發生的時間	TIMESTAMP	●
received_at	API 收到 log 的時間 · partition key · 由 API 補齊	TIMESTAMP	●
source_system	來源系統名稱（jenkins、vault…）	STRING	●
source_instance	來源的特定 instance / 環境	STRING	○
action	執行的動作 / 事件名稱	STRING	●
outcome	動作結果（SUCCESS、FAILURE、DENIED）	STRING	○
severity	嚴重程度（INFO、WARN、ERROR）	STRING	○
actor_id	發起動作的主體 / 帳號	STRING	○
target_id	動作影響的目標資源	STRING	○
correlation_id	串連跨服務操作的 trace ID	STRING	○
ingest_client_id	由 API 驗證通過的 Zitadel client · 來自 JWT subject	STRING	○
metadata	來源專屬欄位，可擴充的 JSON	JSON	○

BigQuery DDL

CREATE TABLE audit.audit_logs (
  event_id          STRING    NOT NULL,
  occurred_at       TIMESTAMP NOT NULL,
  received_at       TIMESTAMP NOT NULL,
  source_system     STRING    NOT NULL,
  source_instance   STRING,
  action            STRING    NOT NULL,
  outcome           STRING,
  severity          STRING,
  actor_id          STRING,
  target_id         STRING,
  correlation_id    STRING,
  ingest_client_id  STRING,
  metadata          JSON
)
PARTITION BY DATE(received_at)
CLUSTER BY source_system, action;

PARTITION	以 received_at 每日分區——減少掃描量，並可設定保留期到期。
CLUSTER	以 source 與 action 叢集——多數篩選都命中這兩欄，降低讀取位元組數。