Utiliser dbt State

dbt State est un mécanisme de réutilisation piloté par serveur. Il ne faut pas le confondre avec le sélecteur state:modified ou le report --state de dbt.

Avant de construire chaque nœud sélectionné, dbt demande au serveur dbt State si l'objet peut être ignoré (réutilisé depuis le schéma cible), cloné (réutilisé depuis un autre schéma) ou doit être construit. C'est le successeur de State-Aware Orchestration, mais il fonctionne dans dbt Core, en développement et en CI — pas seulement dans Fusion en production.

dbt State est un produit payant, mais il ne nécessite pas d'abonnement à la plateforme dbt (anciennement dbt Cloud).

Idées fausses courantes

Comment fonctionne la décision de réutilisation

Pour chaque nœud sélectionné, dbt State choisit l'option la moins coûteuse valide :

1. Ignorer — l'objet existe dans le schéma cible, son hash sémantique est inchangé, et aucun parent n'a des données plus fraîches au-delà de lag_tolerance. Ne fait rien.
2. Cloner — un objet correspondant (même hash, données fraîches) existe dans un autre schéma (par exemple production ou le schéma dev d'un collègue). Le clone est marqué Réutilisé. Utilise un clone sans copie s'il est supporté par l'entrepôt, ou exécute une instruction CTAS pour copier les données transformées d'ailleurs sinon. Les résultats des tests sont aussi réutilisés — un test échoué apparaît toujours même s'il n'a pas été réexécuté.
3. Construire — pas de réutilisation valide. Construit normalement, en différant automatiquement les nœuds en amont non sélectionnés.

Si un nœud est sélectionné pour exécution mais ses entrées n'existent pas dans le schéma cible, dbt State utilise le report comme d'habitude. Si un manifest.json est présent, il l'utilisera, sinon il fera une meilleure supposition possible du FQN correct basée sur les macros generate_*_name. Le report ne consomme pas de DATTs. La config defer_to_target dans profiles.yml peut être utilisée pour spécifier le schéma vers lequel différer pour les utilisateurs auto-gérés. Ce n'est pas nécessaire pour les utilisateurs de plateforme dbt.

Pour obtenir la fraîcheur, dbt récupère les métadonnées de l'entrepôt (ou loaded_at_field/loaded_at_query) pour chaque relation en entrée. Pour les vues sans config loaded_at, il parcourt en amont jusqu'à trouver une vraie table.

Normalisation des requêtes et raison pour laquelle les modèles se reconstruisent

dbt State hache une arborescence syntaxique analysée, il ignore donc les changements cosmétiques — espaces, commentaires, alias de tables, reformatage par dbt lint --fix. Un modèle se reconstruit seulement quand sa logique ou ses données changent.

SQL volatil (current_timestamp(), getdate(), random()): traité par défaut comme de la logique — le hash utilise le nom de la fonction, pas sa valeur d'exécution, donc il n'invalide pas le modèle à chaque exécution (sinon rien en aval de getdate() ne pourrait jamais être réutilisé). Pour que un modèle se reconstruise quand la valeur change :

• Définir evaluate_volatile_sql: true (préféré — couvre toutes les fonctions du modèle, héritable comme n'importe quelle config). dbt State émule la valeur de la fonction dans le hash.
• Ou utiliser un équivalent Jinja (par exemple {{ run_started_at }}) — Jinja s'affiche avant l'analyse, donc il change le SQL compilé à chaque exécution.

Jinja non-déterministe (par exemple dbt_utils.get_relations_by_pattern retournant les relations dans un ordre variable) produit un hash compilé différent et déclenche des reconstructions même quand la logique est inchangée.

Changements de config : seules les configs pertinentes pour la construction affectent le hash (materialized, on_schema_change, severity, …). Les configs cosmétiques (meta, tags) sont ignorées. Si un hook post-exécution mute les tables basées sur des champs ignorés (par exemple appliquer meta comme tags d'entrepôt), définir execute_hooks_on_any_reuse: true pour que les hooks s'exécutent à la réutilisation.

Référence rapide des configs

À définir sous models: +state: dans dbt_project.yml, dans la config schema.yml config.state, ou dans {{ config(state={...}) }}.

Entrepôts supportés : Snowflake, Databricks, BigQuery, Redshift.

Facturation : tables cibles actives quotidiennement (DATT)

L'utilisation de dbt State est mesurée en DATTs (tables cibles actives quotidiennement), pas par « modèles construits ».

• Une table cible est un objet de base de données géré par votre projet (par base de données + schéma) : seeds, snapshots, modèles (incl. incrémentels), et chaque test distinct — même les tests non stockés en base de données (store_failures off). Exemple : dim_customers avec not_null et unique sur id = 3 tables cibles (le modèle + 2 tests).
• Une table cible devient un DATT quand dbt State effectue au moins une omission, clone ou réutilisation de test dessus un jour donné (UTC). Toutes les réutilisations de la même table cible en un jour comptent comme un seul DATT. Une construction complète n'est pas une réutilisation.
• Les vues ne sont jamais facturées comme DATTs, même si réutilisées ou clonées. Les tests attachés à une vue seront facturés normalement.

Si vous avez des questions sur les tarifs, consultez https://www.getdbt.com/product/dbt-state.

Optimisations pour de meilleurs résultats

• lag_tolerance par environnement — en dev, réglez-la élevée (par exemple une semaine) pour que dbt ne fasse rien quand les données sont légèrement obsolètes ; le clonage est pas cher mais ne rien faire est moins cher. Exemple :

  # dbt_project.yml
  models:
    +state:
      lag_tolerance: "{{ '4h' if target.name == 'prod' else '7d' }}"

• Continuez à utiliser les sélecteurs en développement. Toute table cible que dbt State réutilise compte comme un DATT pour ce jour (même une à l'intérieur de sa fenêtre lag-tolerance). Sélectionnez seulement les nœuds sur lesquels vous travaillez pour que le report simple gère le reste — les nœuds non modifiés et non sélectionnés n'entraînent aucune utilisation de dbt State.
• Réduisez l'utilisation de sélecteurs complexes en production. dbt State rend la plupart des jobs proches d'un simple dbt build ; laissez-le décider ce qu'il faut reconstruire au lieu de peaufiner manuellement la sélection par job. Spécifiez lag_tolerance pour éviter la reconstruction excessive.
• *Spécifiez les colonnes au lieu de `select pour augmenter la probabilité de réutilisation**. Si dbt State ne peut pas prouver qu'untable.*` ou similaire a le même ensemble de colonnes, il reconstruira pour être sûr. C'est particulièrement pertinent pour les vues. L'analyse statique de Fusion n'est actuellement pas utilisée pour cela.

Diagnostiquer les comportements déroutants

v1 (Python) vs v2 (Rust/Fusion)

• Les utilisateurs de dbt v1.7-1.11 doivent installer le package dbt-state séparé pour utiliser dbt State.
• Les utilisateurs de dbt v1.12+ ont le package dbt-state inclus automatiquement.
• Les utilisateurs de dbt v2.0+ (distributions Core ou Fusion) ont l'implémentation Rust de la logique client intégrée, donc aucune installation séparée n'est nécessaire.

Le comportement de réutilisation, les configs et la normalisation des requêtes sont côté serveur et se comportent de manière cohérente sur tous les moteurs. La principale différence v1 est l'installation sépaée dbt-state pour 1.7–1.11. Le diagnostic dbt-state explain n'est pas disponible dans dbt v2.

Docs associées

• Aperçu : /docs/deploy/dbt-state-about
• Configuration : /docs/deploy/dbt-state-setup · Exemples : /docs/deploy/dbt-state-examples
• Monitorer l'activité : /docs/deploy/dbt-state-interface · Report : /docs/deploy/dbt-state-deferral · CI/CD : /docs/deploy/dbt-state-cicd
• Configs : /reference/resource-configs/dbt-state-configs · lag_tolerance · defer_to_target