【要約】Garminの日次データを1行にまとめると何が消える？——v1.3で複数観測を残した理由 [Zenn_Python] | Summary by TechDistill
> Source: Zenn_Python
Execute Primary Source
// Problem
開発者がGarminのデータを正規化する際、データの扱いやすさを求めて「1日1行」への単純化を試みる。しかし、この単純化はデータの整合性を損なうリスクを孕んでいる。具体的には、以下の技術的課題に直面する。
- ・同一日付内に複数の観測が存在する場合、置換関係が不明なまま集約するとデータが消失する。
- ・「最新値優先（latest-wins）」という根拠のないルールは、重要な観測を誤って上書きする。
- ・日付の一致を「事実の同一性」と誤認し、Activityとの不適切なデータ結合を招く。
// Approach
開発チームは、データの正確性を担保するため「観測粒度」と「関係性」を明確に分離する設計を採用した。具体的には、以下の手法を用いて実装の不確実性を排除した。
- ・「Source-backed Observation Grain」を採用し、ソース上の独立した観測を個別に保持する。
- ・日次サマリーは正本ではなく、元の観測を保持した「派生ビュー」として定義する。
- ・「Contract-before-Code」を導入し、実装前に粒度や関係性の境界を文書化する。
- ・最新時刻やファイル順を、データの正しさや置換関係の根拠として使用しない。
// Result
v1.3.0のリリースにより、17のデータセットと212のフィールドが文書化された。この設計変更は、データ分析の信頼性を高める以下の成果をもたらした。
- ・睡眠やVO2Maxなど、新たに10種類のデータセットが追加された。
- ・pytest 199件、unittest 170件のテストにより、決定的再現性44/44件を確認した。
- ・非公開検証において、安定粒度キーの不一致が0件であることを確認し、設計の妥当性を証明した。
Senior Engineer Insight
> 時系列データの正規化において「最新値優先」は、情報の欠落を招く致命的な設計ミスだ。本記事の「粒度と関係性の分離」は、整合性とスケーラビリティを両立する極めて実践的な解法である。実装前に「何を保証し、何を保証しないか」という契約を定義するプロセスは、大規模システムの運用コストを劇的に下げる。