explore-lakehouse

Lakehouse の探索

bq CLI を使って、このプロジェクトの BigQuery lakehouse を探索します。

環境

コマンドを実行する前に、環境変数から接続情報を解決してください。

echo "Project: $GOOGLE_CLOUD_PROJECT"
echo "Dataset: $REVOS_BQ_DATASET"

• $GOOGLE_CLOUD_PROJECT — BQ プロジェクト ID
• $REVOS_BQ_DATASET — デフォルトのデータセット（ユーザーによる上書きが可能です）
• INFORMATION_SCHEMA クエリ：--location フラグは省略し、bq query --nouse_legacy_sql をそのまま使用してください

コマンド

組織のデータセット内のテーブルを一覧表示します。

bq ls $REVOS_BQ_DATASET

プロジェクト内のすべてのデータセットを一覧表示します（ユーザーから明示的に依頼された場合のみ）。

bq ls --project_id=$GOOGLE_CLOUD_PROJECT

テーブルスキーマを確認します（内部列を除外します）。

bq show --schema --format=prettyjson $REVOS_BQ_DATASET.<table> | python3 -c "
import json, sys
cols = json.load(sys.stdin)
names = [c['name'] for c in cols if not c['name'].startswith('_airbyte')]
print('\n'.join(names))
"

サンプル行をプレビューします。

bq head -n 5 $REVOS_BQ_DATASET.<table>

テーブルのリストの行数を取得します。

for table in table1 table2 table3; do
  echo -n "$table: "
  bq query --nouse_legacy_sql --format=csv \
    "SELECT COUNT(*) FROM \`$GOOGLE_CLOUD_PROJECT.$REVOS_BQ_DATASET.$table\`" 2>/dev/null | tail -1
done

指定した列の NULL 率を確認します。

bq query --nouse_legacy_sql "
SELECT
  COUNTIF(col1 IS NULL) AS col1_null,
  COUNTIF(col2 IS NULL) AS col2_null,
  COUNT(*) AS total
FROM \`$GOOGLE_CLOUD_PROJECT.$REVOS_BQ_DATASET.<table>\`
"

ワークフロー

「データベースには何がある？」／全般的な概要

1. 組織のデータセット内のテーブルを一覧表示します：bq ls $REVOS_BQ_DATASET
2. データセットが空（テーブルがない）の場合は、ユーザーに次のように伝えます：
   • revos sources create を実行して RevOS UI を開き、データソースを追加できます
   • revos sources list で既存のソースを確認できます
   • ここで終了します — データがないため、これ以上の探索はできません
3. テーブル名のプレフィックス（例：salesforce_*、stripe_*、hubspot_*）からデータソースとドメインを推測します
4. テーブルをソース／ドメインごとにグループ化します
5. 見つかったソース、ソースごとのテーブル数、テーブルの種類（TABLE／VIEW）、グループごとの1行の説明を返します

「このデータはどのレイヤー？」／bronze–silver–gold の評価

1. dbt モデルのフォルダーを確認します：find dbt/models -type f | sort
2. フォルダー内が .gitkeep のみの場合、そのレイヤーはまだ構築されていません
3. テーブル自体を評価します：
   • Bronze の指標： ソース名がプレフィックスになった生の名前、ソースシステムの命名規則（例：properties_*、fields_*）に従ったフラットな列が多数ある、集計がない、スキーマ上で結合が確認できない
   • Silver の指標： 整理された列名、重複排除済み、型が統一されている、_id 外部キー
   • Gold の指標： 集計済みのメトリクス、横幅の広いファクトテーブル、ビジネス用の列名（arr、churn_rate、ltv）
4. 存在するレイヤーと不足しているレイヤーを報告します

「データは完全？」／データ品質の確認

1. すべてのテーブルを取得します：bq ls <dataset>
2. 各テーブルのスキーマを取得し、実際の列名を確認します
3. スキーマからビジネス上重要な列を特定します。以下を探してください：
   • 識別子／キー列： id、*_id、email、name などの名前を持つ列
   • 日付列： created_at、*_date、*_at
   • 関係列： 他のオブジェクトに関連付ける外部キー
   • 主要なメトリクス列： 金額、ステータス、段階、担当者の割り当て
4. それらの列を対象に、テーブルごとに COUNTIF(col IS NULL) クエリを1回実行します
5. ソースで archived／is_deleted フラグを使用している場合は、除外します：WHERE archived = false OR archived IS NULL
6. 結果をテーブルごとに提示します：

フィールド	NULL 数	欠損率	ステータス
...	...	...%	✅ / ⚠️ / ❌

ステータスのしきい値：✅ 5% 未満 · ⚠️ 5〜50% · ❌ 50% 超

7. 調査結果を要約します：データが十分に入っているテーブル、重大な不足があるテーブル、それが下流での利用にどう影響するか

「特定のテーブルには何がある？」

1. bq show --schema — すべての列の一覧を取得します（_airbyte_* 列は省略します）
2. SELECT COUNT(*) — 行数
3. bq head -n 5 — サンプル行
4. スキーマから、ビジネス上最も重要な列を特定して強調します

出力ルール

• Airbyte については決して言及しないでください — ユーザーには見えない内部 ETL の仕組みです
• _airbyte_* 列の名前を挙げたり、その由来を説明したりしないでください。スキーマの要約から除外します
• データの鮮度は中立的に説明してください：「毎日更新」など。「_airbyte_extracted_at でパーティション分割」のようには説明しません
• 「Airbyte 経由」、「Airbyte のフラット列パターン」、「Airbyte の生成物」のような表現は使わないでください
• スキーマからテーブル構造を常に動的に確認してください。以前のセッションで見た列名を前提にしないでください
• 多数のテーブルを一覧表示する際は、統合ソースごとに出力をグループ化します
• 行数が少ない（100 行未満）場合は、サンドボックスデータまたはテストデータである可能性を示します