Zum Inhalt springen
Saiku Cloud

dbt- / MetricFlow-Anbindung

Wenn Sie dbt bereits mit MetricFlow-Semantikmodellen betreiben, können Sie diese ohne jegliche Neumodellierung in Saiku bringen. dbt Core 1.12 gibt neben seinen üblichen Build-Artefakten ein Open Semantic Interchange-Dokument aus, und Saiku lädt diese Datei unverändert über seinen normalen Datasource-Registrierungs-Flow.

Einmal verdrahtet, funktioniert alles, was Saiku über ein Ossie-Modell bereitstellt, gegen Ihre dbt-Semantikebene: der Workbench, die typisierte AI Query API, die MCP-Tools, die natürlichsprachliche /ask-Ebene, die Anomalie- und Forecast-Endpunkte.

Voraussetzungen

  • Ein dbt-Projekt mit MetricFlow-Semantikmodellen
  • dbt Core 1.12 oder neuer — frühere Versionen geben das OSI-Dokument nicht aus
  • Das gleiche Warehouse, auf das Ihr dbt-Projekt zielt
  • Eine laufende Saiku-Instanz (Saiku Cloud oder selbst gehostet) — Sie benötigen Schreibzugriff auf das Datasources-Verzeichnis auf dem Host oder Admin-API-Zugriff

Die Durchführung

  1. Kompilieren Sie Ihr dbt-Projekt. Das OSI-Dokument wird als Teil jedes Befehls ausgegeben, der einen vollständigen Parse auslöst — dbt compile, dbt run, dbt build.

    Terminal-Fenster
    cd path/to/your-dbt-project
    dbt compile

    Das Ergebnis landet bei target/osi_document.json. Es ist eine einzelne JSON-Datei, die jedes Semantikmodell enthält, das Ihr Projekt deklariert, im OSI-v0.1.1-Format.

  2. Zeigen Sie Saiku darauf. Registrieren Sie eine Datasource, die auf die JSON-Datei und das Warehouse zeigt, auf das dbt zielt. Auf einem selbst gehosteten Launcher ist das eine .sds-Datei; auf Saiku Cloud können Sie über die Admin-API registrieren.

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

    Zwei Dinge sind zu beachten:

    • Das <ossieYaml>-Element nimmt jede Datei, die Jacksons YAML-Parser akzeptiert — YAML und JSON. Zeigen Sie es auf genau die Datei, die dbt geschrieben hat; kein Konvertierungsschritt.
    • Der <schema>-Wert ist das name-Feld auf dem Semantikmodell, das dbt ausgibt. Für ein frisches Projekt ist das typischerweise "semantic_model" (dbts Standard, wenn kein expliziter Name angegeben ist).

  3. Verifizieren. Das Modell erscheint in /ai/ossie/models sofort nach Saikus nächstem Connection-Refresh.

    Terminal-Fenster
    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. Abfragen. Jeder REST-Endpunkt, jedes MCP-Tool und jedes Workbench-Feature funktioniert jetzt gegen Ihre dbt-Semantikebene. Stellen Sie eine Frage:

    Terminal-Fenster
    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"}]
      }'

Das ist die gesamte Integration. Keine Schattenmodellierung, keine Neudeklaration, keine Konvertierungspipeline.

In Sync bleiben

Da dbt bei jedem Compile osi_document.json schreibt, bleibt die Integration automatisch aktuell:

  • Entwicklungs-Loop. dbt compile beim Speichern (oder via dbt-watch) hält die Datei aktuell, während Sie Metriken entwickeln. Saiku nimmt Änderungen über denselben Admin-Refresh-Pfad auf, den es für OLAP-Cubes verwendet.
  • CI/CD. Verdrahten Sie Ihren dbt-CI-Job so, dass er target/osi_document.json an den Ort kopiert, den Ihre Saiku-Instanz liest. Auf Saiku Cloud akzeptiert die Admin-API direkte Uploads.
  • Produktions-dbt-Jobs. Jedes dbt run in der Produktion schreibt ein frisches Dokument. Liefern Sie es neben Ihren dbt-Artefakten aus.

Was dbt in die Datei schreibt

Jedes Semantikmodell in Ihrem dbt-Projekt kommt herüber:

  • Datasets. Eines pro semantic_models[*]-Eintrag in Ihrem MetricFlow-YAML. Enthält den vollqualifizierten Tabellennamen, den Primärschlüssel, die Beschreibung und jede Dimension als Feld.
  • Metriken. Simple- und Ratio-Metriken kommen mit ihrem SQL-Ausdruck herüber. Kumulative Metriken geben eine Warnung aus und werden verworfen (die OSI-0.1.x-Spezifikation modelliert Window-Semantik noch nicht).
  • Beziehungen. MetricFlows Join-Inferenz (basierend auf übereinstimmenden Entity-Namen über Semantikmodelle hinweg) wird zu expliziten Ossie-Beziehungen. Saikus Calcite-Auto-Join-Regel nimmt sie zur Abfragezeit auf.
  • Labels. MetricFlows label:-Attribute auf Dimensionen und Metriken kommen als OSI-Feld-Labels herüber. NETREVENUE in der Rohspalte wird überall in Saiku als „Net Revenue” gerendert.
  • AI-Kontext. Alle ai_context:-Blöcke, die Sie Ihrem MetricFlow-YAML hinzugefügt haben (Beschreibungen, Sample-Werte, Synonyme), werden über das Saiku-AI-Schema für LLM-Konsumenten sichtbar gemacht.

Was in v0.1.1 nicht enthalten ist

Die OSI-Spezifikation bei v0.1.1 (was dbt 1.12 ausgibt) deckt noch nicht ab:

  • Kumulative / rollierende / Period-over-Period-Metriken
  • Verschachtelte / abgeleitete Metriken, die andere Metriken referenzieren
  • Benutzerdefinierte Aggregationsfunktionen über sum / count / avg / min / max hinaus

Das sind bekannte Lücken in der Spezifikation, nicht in Saiku. Während sich OSI in Richtung v0.2 mit breiterer Anbieterbeteiligung bewegt, werden diese landen. Die Integration wird sie automatisch aufnehmen, weil Saiku dieselbe Datei liest, die dbt schreibt.

FAQ

Muss ich etwas auf der dbt-Seite installieren? Nein. dbt compile in dbt-core 1.12+ schreibt das OSI-Dokument ohne Konfiguration.

Was ist mit älteren dbt-Versionen? Für dbt 1.10 und 1.11 können Sie Ihr MetricFlow-YAML mit dem kleinen Python-Konverter im Saiku-Repository zu Ossie-YAML konvertieren. Sobald Ihre dbt-Version 1.12 erreicht, lassen Sie den Konverter fallen und verwenden Sie target/osi_document.json direkt.

Kann ich dbt-gestützte und handverfasste Ossie-Modelle mischen? Ja. Jede .sds-Datasource registriert ein Modell. Zeigen Sie einige auf target/osi_document.json, andere auf handgeschriebenes YAML.

Was, wenn dbt ein semantic_model mit einem Namen ausgibt, der mir nicht gefällt? Setzen Sie name auf dem äußeren Semantikmodell in Ihrem MetricFlow-YAML — dbt reicht es durch. Wenn Sie keinen setzen, verwendet dbt standardmäßig "semantic_model".

Siehe auch