Importer depuis dbt

Qui peut le faire

Administrateurs disposant de la permission Modèles sémantiques.

Si votre équipe maintient un projet dbt, inutile de décrire vos données deux fois. Axiome importe les artefacts que dbt produit déjà et les transforme en modèles sémantiques — modèles, clés, dimensions, mesures et métriques — pour que votre projet dbt reste l'unique source de vérité.

Il y a trois façons de faire entrer les définitions, de la plus rapide à la plus automatisée :

1. Upload manuel — choisissez un fichier, prévisualisez, confirmez. Idéal pour un premier essai.
2. Jetons d'ingestion CI — une étape curl dans n'importe quelle CI pousse le manifeste après chaque build.
3. Synchronisation GitHub — installez l'app GitHub d'Axiome une fois et chaque merge importe automatiquement. Pas de jeton, pas d'étape d'upload.

Les trois passent par le même pipeline : mêmes règles de prévisualisation, même rapport d'import, même garde-fou.

Ce qui est importé

dbt écrit ses artefacts dans target/ à chaque commande de parsing (dbt parse, dbt run, dbt build). Axiome en lit deux :

Fichier	Ce qu'Axiome importe
target/semantic_manifest.json	Les définitions MetricFlow — modèles sémantiques, entités (comme clés), dimensions, mesures et métriques. L'import le plus riche ; utilisez-le si votre projet définit une sémantique MetricFlow.
target/manifest.json	Les métadonnées seulement — descriptions des modèles et tests relationships (comme clés et jointures). La solution de repli pour les projets sans définitions MetricFlow.

Un import porte sur un seul fichier — les deux sont des descriptions alternatives du même projet, pas des compléments.

Manifeste sémantique vide ?

Les projets utilisant encore l'ancienne syntaxe YAML semantic_models: au niveau racine produisent un semantic_manifest.json vide avec les versions récentes de dbt (avertissement dbt1157). Migrez avec dbt-autofix deprecations --semantic-layer, relancez dbt parse, puis importez le nouvel artefact.

Où vivent les définitions importées

Les définitions importées deviennent la couche gouvernée de la connexion : elles se posent au-dessus de la base qu'Axiome génère depuis votre schéma, et sous les modifications que les administrateurs font dans l'atelier. Deux conséquences à connaître :

• Vos modifications dans l'atelier gagnent. Renommer une dimension ou affiner une description dans Axiome n'est jamais écrasé par un ré-import.
• Chaque import remplace la couche gouvernée en entier. La couche reflète toujours exactement un manifeste — pas de fusion partielle, donc Axiome et dbt ne peuvent jamais diverger.

Tant qu'un import est actif, l'atelier affiche un bandeau — « 12 modèles sont gouvernés par un import dbt — dernier import le … » — et chaque élément gouverné porte un badge de provenance dbt.

Importer manuellement

1. Allez dans Paramètres → Administration → Modèles sémantiques et choisissez la connexion dans le sélecteur en haut.
2. Cliquez sur Importer depuis dbt.
3. Choisir un fichier (ou collez le JSON directement). Axiome vous indique quel type de manifeste il a détecté.
4. Cliquez sur Prévisualiser l'import et lisez le rapport — rien n'est encore enregistré.
5. Cliquez sur Confirmer l'import.

Lire le rapport de prévisualisation

Le rapport compte ce qui sera importé par catégorie (Modèles, Clés, Dimensions, Mesures, Métriques) et signale tout ce qui mérite votre attention :

• Importés avec une fidélité réduite — l'élément entre, moins une capacité. Exemple : « Les fenêtres de validité (SCD) ne sont pas modélisées — importée comme dimension simple. »
• Ignorés — l'élément est laissé de côté, avec la raison. Exemple : « La table derrière ce modèle est introuvable dans le schéma connecté. »
• Métriques qui ne compileraient pas — chaque métrique est compilée à blanc contre le schéma réel de votre base avant l'import : une définition qui référence une colonne inexistante est attrapée ici, pas sur un tableau de bord.
• Changements par rapport à l'import actuel — lors d'un ré-import : quels modèles sont Ajoutés, Supprimés ou Modifiés.

Si le manifeste est identique à ce qui est déjà importé, la prévisualisation le dit et il n'y a rien à confirmer.

Automatiser depuis la CI

Une fois l'import manuel validé, branchez-le sur la CI pour qu'Axiome suive votre projet dbt tout seul. Choisissez :

	Synchronisation GitHub	Jetons d'ingestion CI
Fonctionne avec	GitHub + GitHub Actions	Toute CI capable de lancer curl
Mise en place	Installer l'app, suivre le dépôt	Créer un jeton, ajouter une étape de push
Secrets à gérer	Aucun	Un jeton bearer
Retour d'information	Statut de livraison dans Axiome	Statut HTTP dans le job CI lui-même

Les deux passent par le même garde-fou : les manifestes sains s'appliquent seuls, les risqués sont mis en attente de revue.

Synchronisation GitHub

D'abord, faites uploader les artefacts par votre workflow, après dbt parse / dbt build :

- name: Upload dbt artifacts for Axiome
  uses: actions/upload-artifact@v4
  with:
    name: axiome-dbt-artifacts
    path: |
      target/semantic_manifest.json
      target/manifest.json

Puis, dans l'atelier :

1. Ouvrez le menu ⋯ à côté d'Importer depuis dbt et choisissez Synchronisation GitHub.
2. Cliquez sur Connecter GitHub et installez l'app Axiome sur l'organisation qui héberge votre dépôt dbt. (Si votre organisation exige l'approbation d'un propriétaire, revenez vous reconnecter une fois qu'elle est accordée.)
3. Choisissez le Dépôt, la Branche à suivre (par défaut, la branche par défaut du dépôt) et le Nom de l'artefact — il doit correspondre au name: de votre étape d'upload ; axiome-dbt-artifacts est la valeur par défaut des deux côtés.
4. Cliquez sur Suivre le dépôt.

À partir de là, chaque exécution réussie du workflow sur la branche suivie déclenche un import. Chaque livraison importe un fichier : semantic_manifest.json s'il contient des modèles sémantiques, sinon manifest.json — c'est pourquoi l'étape d'upload inclut les deux. Les re-livraisons du même manifeste sont reconnues et ne font rien.

Le dialogue affiche le résultat de la dernière livraison :

Statut	Signification
appliquée	Importée et en production
en attente de revue	Attend un administrateur — voir le garde-fou
déjà à jour	Même manifeste que l'import actuel
rien à importer	L'artefact ne contenait aucune définition utilisable
aucun artefact trouvé	Pas d'artefact au nom configuré sur cette exécution — vérifiez le name: de votre étape d'upload
échouée	La livraison a échoué — relancez le workflow pour réessayer

Ne plus suivre arrête les imports depuis un dépôt (les modèles déjà importés restent). Déconnecter retire l'intégration pour tout l'espace de travail — attention, cela ne désinstalle pas l'app côté GitHub ; retirez-la aussi dans les réglages de votre organisation GitHub.

Jetons d'ingestion CI

Pour GitLab, Bitbucket, Jenkins ou toute autre CI :

1. Ouvrez le menu ⋯ et choisissez Jetons d'ingestion CI.
2. Donnez un libellé au jeton (par ex. gitlab-ci-main) et cliquez sur Créer un jeton.
3. Copiez le jeton maintenant — il n'est affiché qu'une seule fois — et stockez-le comme secret dans votre CI.
4. Ajoutez à votre pipeline l'étape de push affichée dans le dialogue, après dbt parse :

curl --fail-with-body -X POST "https://app.axiome.cc/api/semantic-import/dbt" \
  -H "Authorization: Bearer $AXIOME_DBT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Axiome-Ref: $GITHUB_REF_NAME" -H "X-Axiome-Sha: $GITHUB_SHA" -H "X-Axiome-Run-Id: $GITHUB_RUN_ID" \
  --data-binary @target/semantic_manifest.json

Le corps est le manifeste brut — pas d'enveloppe, pas d'encodage de formulaire. Les trois en-têtes X-Axiome-* sont des coordonnées git optionnelles ; les envoyer rend les pushes en attente et l'historique traçables jusqu'au commit (adaptez les variables aux équivalents de votre CI).

La réponse indique à votre pipeline ce qui s'est passé :

Statut HTTP	Signification
200	Appliqué — ou déjà à jour
202	En attente de revue — un administrateur doit l'approuver dans Axiome
422	Rien à importer dans le manifeste
401	Le jeton est invalide ou révoqué

Avec --fail-with-body, l'étape fait échouer le job sur un 401/422 pour qu'une mauvaise configuration ne passe pas inaperçue ; un 202 reste un succès, un push en attente étant un résultat normal.

Chaque connexion peut avoir jusqu'à 10 jetons actifs. Révoquer coupe un jeton immédiatement ; la liste montre la dernière utilisation de chacun.

Les imports sains s'appliquent, les imports risqués sont mis en attente

Les imports CI tournent sans humain dans la boucle, Axiome applique donc un garde-fou. Un manifeste poussé est appliqué automatiquement sauf si :

• une métrique ne compilerait pas contre le schéma réel, ou
• une métrique actuellement gouvernée disparaîtrait — le signe le plus fort d'un mauvais artefact (branche périmée, fichier tronqué, mauvais projet).

Dans ces cas le push est mis en attente : rien ne change dans votre couche sémantique, et l'atelier affiche un bandeau — « Un manifeste dbt poussé le … est en attente de revue. » Cliquez sur Examiner pour voir précisément quelles métriques gouvernées disparaîtraient et lesquelles ne compilent pas, ainsi que le commit d'origine. Puis :

• Approuver et appliquer — Axiome rejoue l'import complet contre le schéma réel et l'applique, ou
• Rejeter — le push est abandonné ; le prochain push CI repart de zéro.

Il n'y a jamais qu'un seul push en attente par connexion — un push plus récent le remplace, donc une fois le correctif mergé dans le dépôt, il n'y a rien à nettoyer.

Les uploads manuels ne sont jamais mis en attente : le parcours prévisualiser → confirmer est la revue.

Historique des imports

Le dialogue ⋯ → Historique des imports liste chaque import de la connexion, du plus récent au plus ancien : date, source (Upload, Push CI ou GitHub — avec branche et commit quand ils sont envoyés), nombre de modèles et de métriques, et statut (Appliqué, En attente, Rejeté ou Remplacé), avec l'auteur de l'approbation pour les pushes mis en attente.

Supprimer l'import

⋯ → Supprimer l'import efface la couche gouvernée : les modèles concernés retombent sur la base générée, et les modifications faites dans l'atelier sont conservées. Vous pouvez ré-importer à tout moment — y compris approuver un push encore en attente sur la connexion vidée.