Przejdź do głównej zawartości
Saiku Cloud

Podpięcie dbt / MetricFlow

Jeśli już uruchamiasz dbt z modelami semantycznymi MetricFlow, możesz wprowadzić je do Saiku bez żadnego przemodelowania. dbt Core 1.12 emituje dokument Open Semantic Interchange obok swoich zwykłych artefaktów budowy, a Saiku ładuje ten plik as-is poprzez swój normalny przepływ rejestracji datasource.

Po podłączeniu wszystko, co Saiku udostępnia poprzez model Ossie, działa względem twojej warstwy semantycznej dbt: workbench, typowane AI Query API, narzędzia MCP, warstwa /ask w języku naturalnym, endpointy anomalii i prognozy.

Wymagania wstępne

  • Projekt dbt z modelami semantycznymi MetricFlow
  • dbt Core 1.12 lub nowszy — wcześniejsze wersje nie emitują dokumentu OSI
  • Ta sama hurtownia, na którą celuje twój projekt dbt
  • Działająca instancja Saiku (Saiku Cloud lub self-hosted) — potrzebujesz dostępu do zapisu w katalogu datasources na hoście lub dostępu do admin API

Krok po kroku

  1. Skompiluj swój projekt dbt. Dokument OSI jest emitowany jako część każdego polecenia, które wyzwala pełne parsowanie — dbt compile, dbt run, dbt build.

    Okno terminala
    cd path/to/your-dbt-project
    dbt compile

    Wynik ląduje w target/osi_document.json. To pojedynczy plik JSON zawierający każdy model semantyczny, który twój projekt deklaruje, w formacie OSI v0.1.1.

  2. Wskaż na niego Saiku. Zarejestruj datasource wskazujący na plik JSON i hurtownię, na którą celuje dbt. Na self-hosted launcherze jest to plik .sds; na Saiku Cloud możesz zarejestrować przez admin API.

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

    Dwie rzeczy do zapamiętania:

    • Element <ossieYaml> przyjmuje każdy plik, który akceptuje parser YAML Jacksona — YAML i JSON. Wskaż na dokładnie ten plik, który dbt zapisał; żadnego kroku konwersji.
    • Wartość <schema> to pole name na modelu semantycznym, który dbt emituje. Dla świeżego projektu to zwykle "semantic_model" (domyślne dbt, gdy nie podano jawnej nazwy).

  3. Zweryfikuj. Model pojawia się w /ai/ossie/models natychmiast po następnym odświeżeniu połączenia Saiku.

    Okno terminala
    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. Odpytuj. Każdy endpoint REST, narzędzie MCP i funkcja workbench działa teraz względem twojej warstwy semantycznej dbt. Zadaj pytanie:

    Okno terminala
    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"}]
      }'

To cała integracja. Żadnego modelowania w cieniu, żadnej ponownej deklaracji, żadnego potoku konwersji.

Utrzymywanie synchronizacji

Ponieważ dbt zapisuje osi_document.json przy każdej kompilacji, integracja automatycznie pozostaje świeża:

  • Pętla deweloperska. dbt compile przy zapisie (lub przez dbt-watch) utrzymuje plik aktualnym, gdy rozwijasz metryki. Saiku podchwytuje zmiany tą samą ścieżką odświeżania admina, której używa dla kostek OLAP.
  • CI/CD. Podłącz swoje zadanie CI dbt tak, by kopiowało target/osi_document.json do lokalizacji, którą czyta twoja instancja Saiku. Na Saiku Cloud admin API akceptuje bezpośrednie uploady.
  • Produkcyjne zadania dbt. Każdy dbt run na produkcji zapisuje świeży dokument. Wysyłaj go obok swoich artefaktów dbt.

Co dbt umieszcza w pliku

Każdy model semantyczny w twoim projekcie dbt przechodzi:

  • Zbiory danych. Jeden na wpis semantic_models[*] w twoim MetricFlow YAML. Zawiera w pełni kwalifikowaną nazwę tabeli, klucz główny, opis i każdy wymiar jako pole.
  • Metryki. Metryki proste i wskaźnikowe (ratio) przechodzą ze swoim wyrażeniem SQL. Metryki kumulatywne emitują ostrzeżenie i są pomijane (specyfikacja OSI 0.1.x jeszcze nie modeluje semantyki okien).
  • Relacje. Wnioskowanie złączeń MetricFlow (oparte na dopasowaniu nazw encji między modelami semantycznymi) staje się jawnymi relacjami Ossie. Reguła auto-złączenia Calcite w Saiku podchwytuje je w czasie zapytania.
  • Etykiety. Atrybuty label: MetricFlow na wymiarach i metrykach przechodzą jako etykiety pól OSI. NETREVENUE w surowej kolumnie renderuje się jako „Net Revenue” wszędzie w Saiku.
  • Kontekst AI. Wszelkie bloki ai_context:, które dodałeś do swojego MetricFlow YAML (opisy, przykładowe wartości, synonimy), są ujawniane poprzez schemę AI Saiku dla konsumentów LLM.

Czego nie ma w v0.1.1

Specyfikacja OSI w v0.1.1 (co emituje dbt 1.12) jeszcze nie pokrywa:

  • Metryk kumulatywnych / kroczących / okres-do-okresu
  • Zagnieżdżonych / pochodnych metryk odwołujących się do innych metryk
  • Niestandardowych funkcji agregacji poza sum / count / avg / min / max

To znane luki w specyfikacji, nie w Saiku. Gdy OSI zmierza ku v0.2 z szerszym udziałem dostawców, te wylądują. Integracja podchwyci je automatycznie, ponieważ Saiku czyta ten sam plik, który dbt zapisuje.

FAQ

Czy muszę cokolwiek instalować po stronie dbt? Nie. dbt compile w dbt-core 1.12+ zapisuje dokument OSI bez żadnej konfiguracji.

A co ze starszymi wersjami dbt? Dla dbt 1.10 i 1.11 możesz przekonwertować swój MetricFlow YAML na Ossie YAML za pomocą małego konwertera w Pythonie w repozytorium Saiku. Gdy twoja wersja dbt osiągnie 1.12, porzuć konwerter i używaj target/osi_document.json bezpośrednio.

Czy mogę mieszać modele Ossie ze źródła dbt i pisane ręcznie? Tak. Każdy datasource .sds rejestruje jeden model. Wskaż niektóre na target/osi_document.json, inne na ręcznie pisany YAML.

Co, jeśli dbt emituje semantic_model o nazwie, której nie lubię? Ustaw name na zewnętrznym modelu semantycznym w swoim MetricFlow YAML — dbt go przekazuje. Jeśli żadnej nie ustawisz, dbt domyślnie przyjmuje "semantic_model".

Zobacz też