資料更新與 lineage

資料更新機制#

不同資料主題具有不同的更新頻率與特性。平台會依據資料來源與資料類型，設計對應的 ingestion 與更新流程。

常見更新模式包括：

在設計系統時，不應假設所有資料都是即時的。應依據資料類型與更新頻率，決定是否可以直接用於策略或需要做額外處理。

• 即時或近即時更新：用於行情資料與部分市場指標，資料在發布後短時間內即可取得
• 定期更新：用於月營收、財報等資料，依據官方發布週期更新
• 事件驅動更新：用於公告與公司事件，資料在事件發布後即被擷取與處理

freshness（資料時效）#

每個 API 回應都包含 freshness 欄位，用於描述資料的時間狀態。

這個欄位可以用來：

實務上，應將 freshness 納入流程，而不是在應用邏輯中忽略。尤其在事件驅動或自動交易系統中，資料延遲可能直接影響結果。

• 判斷資料是否已更新
• 避免使用過期資料進行決策
• 在 pipeline 中設計條件（例如：資料未更新則暫停流程）

lineage（來源追蹤）#

lineage 描述資料從來源到 API 回應的完整路徑。每筆資料都會附帶 lineage 資訊，讓你可以追蹤：

這些資訊讓資料具備可審計性（auditability）。當你需要驗證某個結果時，可以回到原始來源，而不是依賴不可追蹤的中間資料。

• 資料來自哪個來源（例如 TWSE、TPEx、MOPS）
• 何時被擷取（ingested_at）
• 經過哪些處理流程
• 對應的 trace identifier（trace_id）

source_role（來源角色）#

平台會對資料來源進行分層標記：

這樣的設計可以避免不同來源混用造成的不一致問題。在實務上，你可以根據 source_role 決定資料是否適合用於關鍵決策。

• canonical：官方來源或最具權威性的資料
• fallback：當 canonical 資料缺失時使用的替代來源
• helper：用於補充或輔助計算的資料

為什麼這很重要#

在簡單的應用中，資料來源與更新時間可能不是主要問題。但在研究、策略開發與 production 系統中，這些資訊是必要條件。

幾個典型場景：

如果資料不可追溯，就無法驗證結果。這會讓系統在規模擴大時產生風險。

• 回測結果與實際交易不一致：需要確認當時使用的資料版本與來源
• 模型輸出異常：需要追蹤資料是否延遲或來自 fallback
• 多資料來源整合：需要確保欄位一致與時間對齊
• 團隊協作：需要明確資料責任與來源