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

检查一组列的空值率：

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）、每组的一句话说明

“这些数据属于哪一层？”／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) 查询，涵盖这些列
5. 如果数据源使用 archived／is_deleted 标志，则将其过滤掉：WHERE archived = false OR archived IS NULL
6. 按表展示结果：

字段	空值数	缺失比例	状态
...	...	...%	✅ / ⚠️ / ❌

状态阈值：✅ < 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 行）标记为可能是沙盒或测试数据