Exécution des commandes dbt

Préférences

1. Utiliser les outils MCP si disponibles (dbt_build, dbt_run, dbt_show, etc.) — ils gèrent les chemins, les timeouts et le formatage automatiquement
2. Toujours utiliser build — même si l'utilisateur dit "run" - Quand un utilisateur demande "exécuter" un modèle, recommandez dbt build à la place. build = run + test en une seule étape, donc il détecte les problèmes de qualité des données immédiatement. dbt run seul n'est presque jamais la bonne réponse en développement.
3. Toujours utiliser --quiet avec --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}' pour réduire la sortie tout en détectant les erreurs de sélecteur
4. Toujours utiliser --select - ne jamais exécuter tout le projet sans approbation explicite de l'utilisateur

Référence rapide

# Motif de commande standard
dbt build --select my_model --quiet --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'

# Aperçu de la sortie du modèle
dbt show --select my_model --limit 10

# Exécuter une requête SQL inline
dbt show --inline "select * from {{ ref('orders') }}" --limit 5

# Avec des variables (format JSON pour plusieurs)
dbt build --select my_model --vars '{"key": "value"}'

# Actualisation complète pour les modèles incrémentiels
dbt build --select my_model --full-refresh

# Lister les ressources avant d'exécuter
dbt list --select my_model+ --resource-type model

Variantes de CLI dbt

Trois CLIs existent. Demandez à l'utilisateur lequel si vous n'êtes pas sûr.

Configuration courante : Core dans venv + Fusion à ~/.local/bin. Exécuter dbt utilise Core. Utilisez dbtf ou ~/.local/bin/dbt pour Fusion.

Sélecteurs

Toujours fournir un sélecteur. Opérateurs de graphe :

--select my_model              # Modèle unique
--select staging.*             # Motif de chemin
--select fqn:*stg_*            # Motif FQN
--select model_a model_b       # Union (espace)
--select tag:x,config.mat:y    # Intersection (virgule)
--exclude my_model             # Exclure de la sélection

Filtre de type de ressource :

--resource-type model
--resource-type test --resource-type unit_test

Types valides : model, test, unit_test, snapshot, seed, source, exposure, metric, semantic_model, saved_query, analysis

List

Utilisez dbt list pour aperçu la sélection avant d'exécuter. Utile pour valider les sélecteurs complexes.

dbt list --select my_model+              # Aperçu de la sélection
dbt list --select my_model+ --resource-type model  # Modèles seulement
dbt list --output json                   # Sortie JSON
dbt list --select my_model --output json --output-keys unique_id name resource_type config

Clés de sortie disponibles pour --output json : unique_id, name, resource_type, package_name, original_file_path, path, alias, description, columns, meta, tags, config, depends_on, patch_path, schema, database, relation_name, raw_code, compiled_code, language, docs, group, access, version, fqn, refs, sources, metrics

Show

Aperçu des données avec dbt show. Utilisez --inline pour des requêtes SQL arbitraires.

dbt show --select my_model --limit 10
dbt show --inline "select * from {{ ref('orders') }} where status = 'pending'" --limit 5

Important : Utilisez le flag --limit, pas la clause SQL LIMIT.

Variables

Passez comme STRING, pas dict. Pas de caractères spéciaux (\, \n).

--vars 'my_var: value'                              # Unique
--vars '{"k1": "v1", "k2": 42, "k3": true}'         # Multiple (JSON)

Analyse des résultats d'exécution

Après une commande dbt, consultez target/run_results.json pour les informations d'exécution détaillées :

# Vérification rapide du statut
cat target/run_results.json | jq '.results[] | {node: .unique_id, status: .status, time: .execution_time}'

# Trouver les échecs
cat target/run_results.json | jq '.results[] | select(.status != "success")'

Champs clés :

• status: success, error, fail, skipped, warn
• execution_time: secondes passées en exécution
• compiled_code: SQL rendu
• adapter_response: métadonnées de la base (lignes affectées, octets traités)

Defer (Ignorer les builds en amont)

Référencez les données de production au lieu de construire des modèles en amont :

dbt build --select my_model --defer --state prod-artifacts

Flags :

• --defer - activer le report vers le manifest de state
• --state <path> - chemin vers le manifest d'une exécution précédente (ex. artefacts de production)
• --favor-state - préférer les définitions de nœud de state même si elles existent localement

dbt build --select my_model --defer --state prod-artifacts --favor-state

Analyse statique (Fusion uniquement)

Remplacez l'analyse SQL pour les modèles avec SQL dynamique ou UDFs non reconnus :

dbt run --static-analysis=off
dbt run --static-analysis=unsafe

Erreurs courantes