Backend Documentation

BigQuery欠損データ同期

コマンドシグネチャ

php artisan gcp:sync-products --missed [--items-per-page=]
php artisan gcp:sync-reviews --missed [--items-per-page=]
php artisan gcp:sync-review-sentences --missed [--items-per-page=]

目的

これらのコマンドは、定期同期中に欠損したデータが最終的にBigQueryからローカルデータベースに同期されることを保証します。作成時間に関係なく、BigQueryテーブルでnull状態値を持つレコードを特に対象とします。これは、データ整合性と完全性を維持するためのセーフティネットとして機能します。

シーケンス図

商品欠損データ同期

sequenceDiagram
    participant System
    participant MissedProducts as gcp:sync-products --missed
    participant BigQuery
    participant ProductsTable as products table
    participant ProductDetailsTable as product_details table
    participant Redis
    
    Note over System,Redis: 商品欠損データ同期フロー
    
    rect rgb(255, 200, 200)
    Note right of System: 日次
    System->>MissedProducts: 実行
    MissedProducts->>BigQuery: 商品クエリ WHERE status IS NULL
    BigQuery-->>MissedProducts: 欠損商品データを返す
    MissedProducts->>ProductsTable: 商品レコードの挿入/更新
    MissedProducts->>ProductDetailsTable: 商品詳細レコードの挿入/更新
    MissedProducts->>Redis: 状態更新用の商品IDを保存
    end

レビュー欠損データ同期

sequenceDiagram
    participant System
    participant MissedReviews as gcp:sync-reviews --missed
    participant BigQuery
    participant ReviewsTable as reviews table
    participant Redis
    
    Note over System,Redis: レビュー欠損データ同期フロー
    
    rect rgb(255, 200, 200)
    Note right of System: 日次
    System->>MissedReviews: 実行
    MissedReviews->>BigQuery: レビュークエリ WHERE status IS NULL
    BigQuery-->>MissedReviews: 欠損レビューデータを返す
    MissedReviews->>ReviewsTable: レビューレコードの挿入/更新
    MissedReviews->>Redis: 状態更新用のレビューIDを保存
    end

レビュー文欠損データ同期

sequenceDiagram
    participant System
    participant MissedSentences as gcp:sync-review-sentences --missed
    participant BigQuery
    participant ReviewSentencesTable as review_sentences table
    participant Redis
    
    Note over System,Redis: レビュー文欠損データ同期フロー
    
    rect rgb(255, 200, 200)
    Note right of System: 日次
    System->>MissedSentences: 実行
    MissedSentences->>BigQuery: レビュー文クエリ WHERE status IS NULL
    BigQuery-->>MissedSentences: 欠損文データを返す
    MissedSentences->>ReviewSentencesTable: レビュー文レコードの挿入/更新
    MissedSentences->>Redis: 状態更新用の文IDを保存
    end

実装詳細

パラメータ

  • --missed: 作成時間に関係なくnull状態のすべてのレコードを選択するようにクエリを変更するフラグ
  • --items-per-page=N: バッチサイズを制御するオプションパラメータ（デフォルト: 500）

頻度

日次 - 低トラフィック期間中に実行されるようにスケジュール

依存関係

  • Google Cloud Platformアクセス認証情報
  • BigQueryプロジェクトとデータセット設定
  • 処理済みID追跡のためのRedis
  • ジョブ処理のためのキューワーカー
  • レコードを処理済みとしてマークするための状態更新コマンド

処理フロー

  1. コマンドがnull状態のレコードをBigQueryにクエリ（定期同期の時間制約なし）
  2. データはバッチにチャンク化され、キュージョブで処理される
  3. 定期同期と同じ変換と保存ロジックが適用される
  4. 処理済みIDがRedisに保存される
  5. 状態更新コマンドが後でこれらのレコードを処理済みとしてマーク

エラーハンドリング

ジョブ構造

  • 定期同期と同じエラーハンドリングを使用
  • Laravelキュー設定に基づいて失敗したジョブを再試行
  • トラブルシューティング用の詳細なエラーを記録

ログ記録

  • ジョブ数とレコード数を含む詳細ログ
  • デバッグ用のエラースタックトレース
  • BigQueryテーブルと条件への相互参照

通知

  • 重要な障害のSlackアラート
  • 処理統計付きの成功通知

トラブルシューティング

一般的な問題

  1. 大量データボリューム: 定期同期が失敗している場合、欠損データ同期は大量のボリュームを処理する可能性
  2. キューオーバーロード: 欠損データ同期中のキューサイズとワーカー容量を監視
  3. リソース競合: パフォーマンスへの影響を避けるため、オフピーク時間中に欠損同期をスケジュール

パフォーマンス最適化

  1. --items-per-pageパラメータでバッチサイズを調整
  2. 欠損データ同期実行前にキューワーカー数を増加
  3. 実行中のシステムリソース使用量を監視
  4. 同時実行ではなく欠損同期コマンドの段階的実行を検討

検証手順

  1. 同期前後でnull状態のBigQueryレコード数を比較
  2. 正常に処理されたレコードIDのRedisを確認
  3. ローカルデータベースのレコード数とコンテンツを確認
  4. 正常なバッチ処理の状態更新コマンドログをレビュー