SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场warehouse-init

warehouse-init

数据与分析

查看项目

更新于 10-14 09:11

技能介绍

用途

warehouse-init 用于初始化数据仓库的模式发现，生成一份全面的、用户可编辑的数据仓库模式参考文件。它通过从仓库中发现数据库、模式、表和列，并结合代码库上下文，为团队提供可直接查表的参考文档，使得概念到表的查找无需再查询仓库即可完成。

主要能力

  1. 仓库发现：读取仓库配置（cat ~/.astro/agents/warehouse.yml），获取要发现的数据库列表（如 databases: [HQ, ANALYTICS, RAW]），并并行发现每个数据库的模式、表、行数和列。

  2. 代码库上下文搜索：启动子代理查找代码中的业务上下文，包括：

    • dbt 模型（/models//*.yml、**/schema.yml）：提取表描述、列描述、主键和测试
    • Gusty/声明式 SQL（/dags//*.sql with YAML frontmatter）：解析 frontmatter 中的 description、primary_key、tests，以及模式映射
    • AGENTS.md 或 CLAUDE.md 中的数据层文档 返回 table_name -> {description, primary_key, important_columns, layer} 的映射。

  3. 并行仓库发现：为每个数据库启动一个子代理，查询 schemas、tables（含行数和注释）、重要模式的列信息（如 MODEL_、METRICS_、MART_*），并标记超过 1 亿行的大表为 "large"。使用的命令示例：

    • uv run scripts/cli.py exec "df = run_sql('...')"
    • uv run scripts/cli.py exec "print(df)"

  4. 分类值族发现：对关键分类列（如 OPERATOR、STATUS、TYPE、FEATURE）发现值族，按公共前缀/后缀分组。

  5. 合并结果：将仓库元数据与代码库上下文合并，生成包含快速参考表、分类列、数据库章节、模式子章节、表详情等内容的 warehouse.md。

  6. 生成 warehouse.md：写入 .astro/warehouse.md（默认，项目特定、可版本控制）或 ~/.astro/agents/warehouse.md（如果使用 --global 标志）。

  7. 预填充缓存：生成 warehouse.md 后，通过 uv run cli.py concept import -p .astro/warehouse.md 和 uv run cli.py concept learn customers HQ.MART_CUST.CURRENT_ASTRO_CUSTS -k ACCT_ID 填充概念缓存。

  8. 提供 CLAUDE.md 集成：询问用户是否将快速参考表添加到 CLAUDE.md 文件，以提升复杂查询的准确性。

使用方式

  • /astronomer-data:warehouse-init — 生成 .astro/warehouse.md
  • /astronomer-data:warehouse-init --refresh — 重新生成，保留用户编辑（保留 HTML 注释、快速参考表用户条目、用户添加的描述；更新行数、添加新表、标记已删除表）
  • /astronomer-data:warehouse-init --database HQ — 仅发现指定数据库
  • /astronomer-data:warehouse-init --global — 写入到 ~/.astro/agents/ 而不是项目目录

生成后建议：编辑 .astro/warehouse.md 添加业务上下文、提交到版本控制、模式变更时运行 --refresh。

适用场景

  • 需要快速查找概念对应的数据表，避免每次查询仓库
  • 团队共享数据仓库模式参考
  • 结合代码库（dbt、gusty、文档）丰富表描述
  • 需要标记大表并提醒添加日期过滤
  • 数据管道部署模式迁移后需要刷新模式信息
  • 定期（如每周）维护模式参考

限制

  • 运行时缓存默认 TTL 为 7 天，过期后缓存条目将失效并重新发现
  • 当出现 "table not found" 错误、结果错误或过时、新表未被发现时，可能表示缓存陈旧，可手动重置：
    • uv run scripts/cli.py cache status
    • uv run scripts/cli.py cache clear --stale-only
    • uv run scripts/cli.py cache clear
  • 所有 CLI 命令相对于 analyzing-data 技能的目录（../analyzing-data/），运行前需 cd 到该目录。
  • 脚本路径为 ../analyzing-data/scripts/。
  • 关于收费、价格、平台支持和具体效果，资料中暂未提供。

识别到的代码库模式

模式 来源 提取内容
/models//*.yml dbt 表/列描述、测试
/dags//*.sql gusty YAML frontmatter（description、primary_key）
AGENTS.md、CLAUDE.md docs 数据层层次、约定
/docs//*.md docs 业务上下文

数据层层次（查询时优先下游）

reporting > mart_* > metric_* > model_* > IN_*

层 前缀 用途
Reporting reporting.* 仪表盘优化
Mart mart_* 组合分析
Metric metric_* 各种粒度的 KPI
Model model_* 清洗后的真实来源
Raw IN_* 源数据 - 避免使用