Aller au contenu
Saiku Cloud

Branchement dbt / MetricFlow

Si vous exécutez déjà dbt avec des modèles sémantiques MetricFlow, vous pouvez les amener dans Saiku sans aucun remodelage. dbt Core 1.12 émet un document Open Semantic Interchange aux côtés de ses artefacts de build habituels, et Saiku charge ce fichier tel quel via son flux normal d’enregistrement de datasource.

Une fois branché, tout ce que Saiku expose au-dessus d’un modèle Ossie fonctionne contre votre couche sémantique dbt : le workbench, l’API AI Query typée, les outils MCP, la couche /ask en langage naturel, les endpoints d’anomalie et de prévision.

Prérequis

  • Un projet dbt avec des modèles sémantiques MetricFlow
  • dbt Core 1.12 ou plus récent — les versions antérieures n’émettent pas le document OSI
  • Le même entrepôt que celui ciblé par votre projet dbt
  • Une instance Saiku en cours d’exécution (Saiku Cloud ou auto-hébergée) — vous avez besoin d’un accès en écriture au répertoire des datasources sur l’hôte, ou d’un accès admin à l’API

Le parcours

  1. Compilez votre projet dbt. Le document OSI est émis dans le cadre de toute commande qui déclenche un parse complet — dbt compile, dbt run, dbt build.

    Fenêtre de terminal
    cd path/to/your-dbt-project
    dbt compile

    Le résultat atterrit à target/osi_document.json. C’est un unique fichier JSON contenant chaque modèle sémantique que votre projet déclare, au format OSI v0.1.1.

  2. Pointez Saiku dessus. Enregistrez une datasource pointant vers le fichier JSON et l’entrepôt que dbt cible. Sur un launcher auto-hébergé c’est un fichier .sds ; sur Saiku Cloud vous pouvez l’enregistrer via l’API admin.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <dataSource>
        <id>orders-ossie-01</id>
        <name>Orders</name>
        <type>OSSIE</type>
        <ossieYaml>/path/to/dbt-project/target/osi_document.json</ossieYaml>
        <location>jdbc:postgresql://your-warehouse:5432/analytics</location>
        <schema>semantic_model</schema>
        <username>saiku_reader</username>
        <password>...</password>
        <advanced>false</advanced>
        <enabled>true</enabled>
    </dataSource>

    Deux choses à noter :

    • L’élément <ossieYaml> prend tout fichier que l’analyseur YAML de Jackson accepte — YAML et JSON. Pointez-le vers le fichier exact que dbt a écrit ; pas d’étape de conversion.
    • La valeur <schema> est le champ name du modèle sémantique que dbt émet. Pour un projet neuf c’est typiquement "semantic_model" (le défaut de dbt quand aucun nom explicite n’est donné).

  3. Vérifiez. Le modèle apparaît dans /ai/ossie/models immédiatement après le prochain rafraîchissement de connexion de Saiku.

    Fenêtre de terminal
    curl -s -b cookies.txt https://your-saiku/rest/saiku/api/ai/ossie/models | jq
    [
      {
        "connectionName": "unknown_Orders",
        "modelName": "semantic_model",
        "factDataset": "orders",
        "datasetCount": 2,
        "metricCount": 2
      }
    ]

  4. Requêtez. Chaque endpoint REST, outil MCP et fonctionnalité du workbench fonctionne désormais contre votre couche sémantique dbt. Posez une question :

    Fenêtre de terminal
    curl -s -b cookies.txt -H "X-XSRF-TOKEN: $XSRF" \
      -H 'Content-Type: application/json' \
      -X POST https://your-saiku/rest/saiku/api/ai/ossie/query \
      -d '{
        "connection": "unknown_Orders",
        "model": "semantic_model",
        "rows": [{"dataset": "customers", "field": "customer_country"}],
        "values": [{"metric": "total_revenue"}, {"metric": "order_count"}],
        "sorts": [{"metric": "total_revenue", "direction": "DESC"}]
      }'

C’est toute l’intégration. Pas de modélisation fantôme, pas de re-déclaration, pas de pipeline de conversion.

Rester synchronisé

Parce que dbt écrit osi_document.json à chaque compilation, l’intégration reste fraîche automatiquement :

  • Boucle de développement. dbt compile à la sauvegarde (ou via dbt-watch) garde le fichier à jour pendant que vous développez des métriques. Saiku récupère les changements via le même chemin de rafraîchissement admin qu’il utilise pour les cubes OLAP.
  • CI/CD. Branchez votre job CI dbt pour copier target/osi_document.json vers l’emplacement que votre instance Saiku lit. Sur Saiku Cloud, l’API admin accepte les uploads directs.
  • Jobs dbt de production. Chaque dbt run en production écrit un document frais. Livrez-le aux côtés de vos artefacts dbt.

Ce que dbt met dans le fichier

Chaque modèle sémantique de votre projet dbt est transféré :

  • Datasets. Un par entrée semantic_models[*] dans votre YAML MetricFlow. Inclut le nom de table pleinement qualifié, la clé primaire, la description, et chaque dimension comme champ.
  • Métriques. Les métriques simples et de ratio passent avec leur expression SQL. Les métriques cumulatives émettent un avertissement et sont abandonnées (la spec OSI 0.1.x ne modélise pas encore la sémantique de fenêtre).
  • Relations. L’inférence de join de MetricFlow (basée sur la correspondance des noms d’entités entre modèles sémantiques) devient des relations Ossie explicites. La règle d’auto-join Calcite de Saiku les récupère au moment de la requête.
  • Labels. Les attributs label: de MetricFlow sur les dimensions et métriques sont reportés comme labels de champ OSI. NETREVENUE dans la colonne brute s’affiche comme « Net Revenue » partout dans Saiku.
  • Contexte AI. Tout bloc ai_context: que vous avez ajouté à votre YAML MetricFlow (descriptions, valeurs d’échantillon, synonymes) est exposé via le schéma AI de Saiku pour les consommateurs LLM.

Ce qui n’est pas dans v0.1.1

La spec OSI en v0.1.1 (ce que dbt 1.12 émet) ne couvre pas encore :

  • Les métriques cumulatives / glissantes / de période sur période
  • Les métriques imbriquées / dérivées qui référencent d’autres métriques
  • Les fonctions d’agrégation personnalisées au-delà de sum / count / avg / min / max

Ce sont des lacunes connues dans la spec, pas dans Saiku. À mesure qu’OSI avance vers la v0.2 avec une participation plus large des éditeurs, celles-ci arriveront. L’intégration les récupérera automatiquement car Saiku lit le même fichier que dbt écrit.

FAQ

Dois-je installer quoi que ce soit côté dbt ? Non. dbt compile dans dbt-core 1.12+ écrit le document OSI sans configuration.

Et pour les versions plus anciennes de dbt ? Pour dbt 1.10 et 1.11, vous pouvez convertir votre YAML MetricFlow en YAML Ossie avec le petit convertisseur Python dans le dépôt Saiku. Une fois que votre version de dbt atteint 1.12, laissez tomber le convertisseur et utilisez target/osi_document.json directement.

Puis-je mélanger des modèles Ossie issus de dbt et écrits à la main ? Oui. Chaque datasource .sds enregistre un modèle. Pointez-en certains vers target/osi_document.json, d’autres vers du YAML écrit à la main.

Et si dbt émet un semantic_model avec un nom que je n’aime pas ? Définissez name sur le modèle sémantique externe dans votre YAML MetricFlow — dbt le passe tel quel. Si vous n’en définissez pas, dbt utilise par défaut "semantic_model".

Voir aussi