warehouse-init

ウェアハウススキーマを初期化する

データウェアハウスの包括的な、ユーザーが編集可能なスキーマリファレンスファイルを生成します。

スクリプト： ../analyzing-data/scripts/ — 以下のすべての CLI コマンドは、analyzing-data スキルのディレクトリからの相対パスです。scripts/cli.py コマンドを実行する前に、このファイルからの相対パスで ../analyzing-data/ に cd してください。

この処理で行うこと

1. ウェアハウスからすべてのデータベース、スキーマ、テーブル、カラムを検出します
2. コードベースのコンテキストを補足します（dbt モデル、gusty SQL、スキーマドキュメント）
3. 行数を記録し、大規模なテーブルを特定します
4. .astro/warehouse.md を生成します。バージョン管理でき、チームで共有できるリファレンスです
5. ウェアハウスにクエリを実行せずに、コンセプトからテーブルをすぐに検索できるようにします

手順

ステップ 1：ウェアハウスの設定を読む

cat ~/.astro/agents/warehouse.yml

検出対象となるデータベースの一覧を取得します（例：databases: [HQ, ANALYTICS, RAW]）。

ステップ 2：コードベースのコンテキストを検索する（並列）

サブエージェントを起動して、コード内のビジネスコンテキストを探します。

Task(
    subagent_type="Explore",
    prompt="""
    Search for data model documentation in the codebase:

    1. dbt models: **/models/**/*.yml, **/schema.yml
       - Extract table descriptions, column descriptions
       - Note primary keys and tests

    2. Gusty/declarative SQL: **/dags/**/*.sql with YAML frontmatter
       - Parse frontmatter for: description, primary_key, tests
       - Note schema mappings

    3. AGENTS.md or CLAUDE.md files with data layer documentation

    Return a mapping of:
      table_name -> {description, primary_key, important_columns, layer}
    """
)

ステップ 3：ウェアハウスを並列で検出する

Task ツールを使い、データベースごとにサブエージェントを1つ起動します。

For each database in configured_databases:
    Task(
        subagent_type="general-purpose",
        prompt="""
        Discover all metadata for database {DATABASE}.

        Use the CLI to run SQL queries:
        # Scripts are relative to ../analyzing-data/
        uv run scripts/cli.py exec "df = run_sql('...')"
        uv run scripts/cli.py exec "print(df)"

        1. Query schemas:
           SELECT SCHEMA_NAME FROM {DATABASE}.INFORMATION_SCHEMA.SCHEMATA

        2. Query tables with row counts:
           SELECT TABLE_SCHEMA, TABLE_NAME, ROW_COUNT, COMMENT
           FROM {DATABASE}.INFORMATION_SCHEMA.TABLES
           ORDER BY TABLE_SCHEMA, TABLE_NAME

        3. For important schemas (MODEL_*, METRICS_*, MART_*), query columns:
           SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE, COMMENT
           FROM {DATABASE}.INFORMATION_SCHEMA.COLUMNS
           WHERE TABLE_SCHEMA = 'X'

        Return a structured summary:
        - Database name
        - List of schemas with table counts
        - For each table: name, row_count, key columns
        - Flag any tables with >100M rows as "large"
        """
    )

すべてのサブエージェントを並列で実行します（複数の Task 呼び出しを1つのメッセージで送信）。

ステップ 4：カテゴリ値のファミリーを検出する

主要なカテゴリ列（OPERATOR、STATUS、TYPE、FEATURE など）について、値のファミリーを検出します。

uv run cli.py exec "df = run_sql('''
SELECT DISTINCT column_name, COUNT(*) as occurrences
FROM table
WHERE column_name IS NOT NULL
GROUP BY column_name
ORDER BY occurrences DESC
LIMIT 50
''')"
uv run cli.py exec "print(df)"

共通の接頭辞または接尾辞で、関連する値をファミリーにまとめます（例：ExportCSV、ExportJSON、ExportParquet を Export* にまとめます）。

ステップ 5：結果を統合する

ウェアハウスのメタデータとコードベースのコンテキストを統合します。

1. クイックリファレンステーブル - コンセプトからテーブルへの対応付け（コード内に見つかった場合は事前入力）
2. カテゴリ列 - 主要なフィルター列の値のファミリー
3. データベースセクション - データベースごとに1つ
4. スキーマのサブセクション - スキーマごとにテーブルをグループ化
5. テーブルの詳細 - カラム、行数、コードから取得した説明、警告

ステップ 6：warehouse.md を生成する

ファイルの書き込み先：

• .astro/warehouse.md（デフォルト。プロジェクト固有で、バージョン管理できます）
• ~/.astro/agents/warehouse.md（--global フラグを指定した場合）

出力形式

# Warehouse Schema

> Generated by `/astronomer-data:warehouse-init` on {DATE}. Edit freely to add business context.

## Quick Reference

| Concept | Table | Key Column | Date Column |
|---------|-------|------------|-------------|
| customers | HQ.MODEL_ASTRO.ORGANIZATIONS | ORG_ID | CREATED_AT |


## Categorical Columns

When filtering on these columns, explore value families first (values often have variants):

| Table | Column | Value Families |
|-------|--------|----------------|
| {TABLE} | {COLUMN} | `{PREFIX}*` ({VALUE1}, {VALUE2}, ...) |


## Data Layer Hierarchy

Query downstream first: `reporting` > `mart_*` > `metric_*` > `model_*` > `IN_*`

| Layer | Prefix | Purpose |
|-------|--------|---------|
| Reporting | `reporting.*` | Dashboard-optimized |
| Mart | `mart_*` | Combined analytics |
| Metric | `metric_*` | KPIs at various grains |
| Model | `model_*` | Cleansed sources of truth |
| Raw | `IN_*` | Source data - avoid |

## {DATABASE} Database

### {SCHEMA} Schema

#### {TABLE_NAME}
{DESCRIPTION from code if found}

| Column | Type | Description |
|--------|------|-------------|
| COL1 | VARCHAR | {from code or inferred} |

- **Rows:** {ROW_COUNT}
- **Key column:** {PRIMARY_KEY from code or inferred}
{IF ROW_COUNT > 100M: - **⚠️ WARNING:** Large table - always add date filters}

## Relationships

カラム名（*_ID など）に基づいて推定した関係

コマンドオプション

オプション	効果
/astronomer-data:warehouse-init	.astro/warehouse.md を生成します
/astronomer-data:warehouse-init --refresh	ユーザーによる編集内容を保持して再生成します
/astronomer-data:warehouse-init --database HQ	指定したデータベースのみを検出します
/astronomer-data:warehouse-init --global	~/.astro/agents/ に書き込みます

ステップ 7：キャッシュを事前に入力する

warehouse.md の生成後、コンセプトキャッシュにデータを入力します。

# Scripts are relative to ../analyzing-data/
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 ファイルに追加しますか？

これにより、データクエリでスキーマの対応付けが常にコンテキストに含まれ、複雑なクエリの精度が約25%から約100%に向上します。

選択肢：

1. はい、CLAUDE.md に追加する（推奨）— クイックリファレンスセクションを追記します
2. いいえ、スキップする — warehouse.md とキャッシュのみを使用します

ユーザーが「はい」を選んだ場合：

1. .claude/CLAUDE.md または CLAUDE.md が存在するか確認します
2. 存在する場合は、クイックリファレンスセクションを追記します（重複は避けます）
3. 存在しない場合は、クイックリファレンスのみを含む .claude/CLAUDE.md を作成します

追加するクイックリファレンスセクション：

## Data Warehouse Quick Reference

When querying the warehouse, use these table mappings:

| Concept | Table | Key Column | Date Column |
|---------|-------|------------|-------------|
{rows from warehouse.md Quick Reference}

**Large tables (always filter by date):** {list tables with >100M rows}

> Auto-generated by `/astronomer-data:warehouse-init`. Run `/astronomer-data:warehouse-init --refresh` to update.

はいの場合： クイックリファレンスセクションを .claude/CLAUDE.md または CLAUDE.md に追記します。

生成後

ユーザーに次の内容を伝えます。

Generated .astro/warehouse.md

Summary:
  - {N} databases, {N} schemas, {N} tables
  - {N} tables enriched with code descriptions
  - {N} concepts cached for instant lookup

Next steps:
  1. Edit .astro/warehouse.md to add business context
  2. Commit to version control
  3. Run /astronomer-data:warehouse-init --refresh when schema changes

更新時の動作

--refresh を指定した場合：

1. 既存の warehouse.md を読み込みます
2. すべての HTML コメント（``）を保持します
3. クイックリファレンステーブルの項目（ユーザーが追加したもの）を保持します
4. ユーザーが追加した説明を保持します
5. 行数を更新し、新しいテーブルを追加します
6. 削除されたテーブルに `` コメントを付けます

キャッシュの古さとスキーマドリフト

ランタイムキャッシュのデフォルトの TTL は7日間です。7日後にキャッシュされたエントリは期限切れとなり、次回使用時に再検出されます。

更新のタイミング

次の場合は、/astronomer-data:warehouse-init --refresh を実行してください。

• スキーマの変更：テーブルの追加、名前の変更、削除
• カラムの変更：カラムの追加、またはデータ型の変更
• デプロイ後：データパイプラインのデプロイでスキーマのマイグレーションが行われる場合
• 毎週：既知の変更がなくても、適切なプラクティスとして実行します

キャッシュが古い場合の兆候

次の兆候に注意してください。

• クエリが「table not found」エラーで失敗する
• 結果が誤っている、または古いように見える
• 新しいテーブルが検出されない

キャッシュの手動リセット

キャッシュに問題があると思われる場合は、次を実行してください。

# Scripts are relative to ../analyzing-data/
uv run scripts/cli.py cache status
uv run scripts/cli.py cache clear --stale-only
uv run scripts/cli.py cache clear

認識されるコードベースのパターン

パターン	ソース	抽出する内容
**/models/**/*.yml	dbt	テーブル／カラムの説明、テスト
**/dags/**/*.sql	gusty	YAML フロントマター（説明、primary_key）
AGENTS.md、CLAUDE.md	ドキュメント	データレイヤーの階層、規約
**/docs/**/*.md	ドキュメント	ビジネスコンテキスト

セッション例

User: /astronomer-data:warehouse-init

Agent:
→ Reading warehouse configuration...
→ Found 1 warehouse with databases: HQ, PRODUCT

→ Searching codebase for data documentation...
  Found: AGENTS.md with data layer hierarchy
  Found: 45 SQL files with YAML frontmatter in dags/declarative/

→ Launching parallel warehouse discovery...
  [Database: HQ] Discovering schemas...
  [Database: PRODUCT] Discovering schemas...

→ HQ: Found 29 schemas, 401 tables
→ PRODUCT: Found 1 schema, 0 tables

→ Merging warehouse metadata with code context...
  Enriched 45 tables with descriptions from code

→ Generated .astro/warehouse.md

Summary:
  - 2 databases
  - 30 schemas
  - 401 tables
  - 45 tables enriched with code descriptions
  - 8 large tables flagged (>100M rows)

Next steps:
  1. Review .astro/warehouse.md
  2. Add concept mappings to Quick Reference
  3. Commit to version control
  4. Run /astronomer-data:warehouse-init --refresh when schema changes