Initialiser le schéma du warehouse

Générer un fichier de référence de schéma complet et éditable par l'utilisateur pour le warehouse de données.

Scripts : ../analyzing-data/scripts/ — Toutes les commandes CLI ci-dessous sont relatives au répertoire de la skill analyzing-data. Avant d'exécuter toute commande scripts/cli.py, exécutez cd ../analyzing-data/ par rapport à ce fichier.

Ce que cela fait

1. Découvre toutes les bases de données, schémas, tables et colonnes du warehouse
2. Enrichit avec le contexte du codebase (modèles dbt, SQL gusty, documentation de schéma)
3. Enregistre les comptages de lignes et identifie les grandes tables
4. Génère .astro/warehouse.md - une référence contrôlable en version et partageable avec l'équipe
5. Active les recherches instantanées concept→table sans requêtes au warehouse

Processus

Étape 1 : Lire la configuration du warehouse

cat ~/.astro/agents/warehouse.yml

Récupérez la liste des bases de données à découvrir (par ex., databases: [HQ, ANALYTICS, RAW]).

Étape 2 : Rechercher le contexte dans le codebase (Parallèle)

Lancez un sous-agent pour trouver le contexte métier dans le code :

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}
    """
)

Étape 3 : Découverte parallèle du warehouse

Lancez un sous-agent par base de données en utilisant l'outil Task :

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"
        """
    )

Exécutez tous les sous-agents en parallèle (un seul message avec plusieurs appels Task).

Étape 4 : Découvrir les familles de valeurs catégoriques

Pour les colonnes catégoriques clés (comme OPERATOR, STATUS, TYPE, FEATURE), découvrez les familles de valeurs :

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)"

Groupez les valeurs associées en familles par préfixe/suffixe commun (par ex., Export* pour ExportCSV, ExportJSON, ExportParquet).

Étape 5 : Fusionner les résultats

Combinez les métadonnées du warehouse + contexte du codebase :

1. Table de référence rapide - mappages concept → table (pré-remplies à partir du code si trouvés)
2. Colonnes catégoriques - familles de valeurs pour les colonnes de filtre clés
3. Sections de base de données - une par base de données
4. Sous-sections de schéma - tables groupées par schéma
5. Détails de table - colonnes, comptages de lignes, descriptions du code, avertissements

Étape 6 : Générer warehouse.md

Écrivez le fichier à :

• .astro/warehouse.md (par défaut - spécifique au projet, contrôlable en version)
• ~/.astro/agents/warehouse.md (si flag --global)

Format de sortie

# 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 |
<!-- Add your concept mappings here -->

## Categorical Columns

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

| Table | Column | Value Families |
|-------|--------|----------------|
| {TABLE} | {COLUMN} | `{PREFIX}*` ({VALUE1}, {VALUE2}, ...) |
<!-- Populated by /astronomer-data:warehouse-init from actual warehouse data -->

## 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

{Inferred relationships based on column names like *_ID}

Options de commande

Étape 7 : Pré-remplir le cache

Après la génération de warehouse.md, remplissez le cache de concepts :

# 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

Étape 8 : Proposer l'intégration CLAUDE.md (Demander à l'utilisateur)

Posez la question à l'utilisateur :

Would you like to add the Quick Reference table to your CLAUDE.md file?

This ensures the schema mappings are always in context for data queries, improving accuracy from ~25% to ~100% for complex queries.

Options:

1. Yes, add to CLAUDE.md (Recommended) - Append Quick Reference section
2. No, skip - Use warehouse.md and cache only

Si l'utilisateur choisit Oui :

1. Vérifiez si .claude/CLAUDE.md ou CLAUDE.md existe
2. S'il existe, ajoutez la section Quick Reference (évitez les doublons)
3. S'il n'existe pas, créez .claude/CLAUDE.md avec uniquement la Quick Reference

Section Quick Reference à ajouter :

## 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.

Si oui : Ajoutez la section Quick Reference à .claude/CLAUDE.md ou CLAUDE.md.

Après la génération

Informez l'utilisateur :

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

Comportement du refresh

Quand --refresh est spécifié :

1. Lisez le warehouse.md existant
2. Préservez tous les commentaires HTML (<!-- ... -->)
3. Préservez les entrées de la table Quick Reference (ajoutées par l'utilisateur)
4. Préservez les descriptions ajoutées par l'utilisateur
5. Mettez à jour les comptages de lignes et ajoutez les nouvelles tables
6. Marquez les tables supprimées avec un commentaire <!-- REMOVED -->

Cache stale & schema drift

Le cache runtime a un TTL de 7 jours par défaut. Après 7 jours, les entrées en cache expirent et seront redécouvertes à la prochaine utilisation.

Quand effectuer un refresh

Exécutez /astronomer-data:warehouse-init --refresh quand :

• Changements de schéma : Tables ajoutées, renommées ou supprimées
• Changements de colonnes : Nouvelles colonnes ajoutées ou types modifiés
• Après les déploiements : Si votre pipeline de données déploie des migrations de schéma
• Hebdomadairement : En bonne pratique, même sans changements connus

Signes d'un cache stale

Observez ces indicateurs :

• Les requêtes échouent avec des erreurs « table not found »
• Les résultats semblent faux ou obsolètes
• Les nouvelles tables ne sont pas découvertes

Réinitialisation manuelle du cache

Si vous soupçonnez des problèmes de cache :

# 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

Motifs du codebase reconnus

Exemple de session

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