Pular para o conteúdo
Saiku Cloud

Hookup dbt / MetricFlow

Se você já roda dbt com modelos semânticos MetricFlow, pode trazê-los para o Saiku com zero remodelagem. O dbt Core 1.12 emite um documento Open Semantic Interchange ao lado de seus artefatos de build usuais, e o Saiku carrega esse arquivo como está através de seu fluxo normal de registro de datasource.

Uma vez conectado, tudo o que o Saiku expõe sobre um modelo Ossie funciona contra sua camada semântica dbt: o workbench, a AI Query API tipada, as ferramentas MCP, a camada de linguagem natural /ask, os endpoints de anomalia e forecast.

Pré-requisitos

  • Um projeto dbt com modelos semânticos MetricFlow
  • dbt Core 1.12 ou mais novo — versões anteriores não emitem o documento OSI
  • O mesmo warehouse que seu projeto dbt visa
  • Uma instância Saiku em execução (Saiku Cloud ou self-hosted) — você precisa de acesso de escrita ao diretório de datasources no host, ou acesso à API de admin

O passo a passo

  1. Compile seu projeto dbt. O documento OSI é emitido como parte de qualquer comando que dispara um parse completo — dbt compile, dbt run, dbt build.

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

    O resultado cai em target/osi_document.json. É um único arquivo JSON contendo cada modelo semântico que seu projeto declara, no formato OSI v0.1.1.

  2. Aponte o Saiku para ele. Registre um datasource apontando para o arquivo JSON e o warehouse que o dbt visa. Em um launcher self-hosted isso é um arquivo .sds; no Saiku Cloud você pode registrar via a API de 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>

    Duas coisas a notar:

    • O elemento <ossieYaml> aceita qualquer arquivo que o parser YAML do Jackson aceite — YAML e JSON. Aponte-o para o arquivo exato que o dbt escreveu; sem passo de conversão.
    • O valor de <schema> é o field name do modelo semântico que o dbt emite. Para um projeto novo isso é tipicamente "semantic_model" (o default do dbt quando nenhum nome explícito é dado).

  3. Verifique. O modelo aparece em /ai/ossie/models imediatamente após o próximo refresh de conexão do Saiku.

    Terminal window
    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. Consulte. Todo endpoint REST, ferramenta MCP e recurso do workbench agora funciona contra sua camada semântica dbt. Faça uma pergunta:

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

Essa é a integração inteira. Sem modelagem-sombra, sem re-declaração, sem pipeline de conversão.

Mantendo em sincronia

Porque o dbt escreve osi_document.json a cada compile, a integração permanece fresca automaticamente:

  • Loop de desenvolvimento. dbt compile ao salvar (ou via dbt-watch) mantém o arquivo atual enquanto você desenvolve métricas. O Saiku pega mudanças via o mesmo caminho de refresh de admin que usa para cubos OLAP.
  • CI/CD. Conecte seu job de CI do dbt para copiar target/osi_document.json para o local que sua instância Saiku lê. No Saiku Cloud, a API de admin aceita uploads diretos.
  • Jobs dbt de produção. Todo dbt run em produção escreve um documento fresco. Distribua-o ao lado dos seus artefatos dbt.

O que o dbt coloca no arquivo

Todo modelo semântico no seu projeto dbt é trazido:

  • Datasets. Um por entrada semantic_models[*] no seu YAML MetricFlow. Inclui o nome de tabela totalmente qualificado, primary key, descrição e cada dimensão como um field.
  • Metrics. Métricas simples e de razão vêm com sua expressão SQL. Métricas cumulativas emitem um aviso e são descartadas (a spec OSI 0.1.x ainda não modela semântica de janela).
  • Relationships. A inferência de join do MetricFlow (baseada em nomes de entidade correspondentes entre modelos semânticos) vira relationships Ossie explícitos. A regra de auto-join do Calcite do Saiku os pega no momento da query.
  • Labels. Os atributos label: do MetricFlow em dimensões e métricas passam adiante como labels de field OSI. NETREVENUE na coluna crua renderiza como “Net Revenue” em todos os lugares no Saiku.
  • Contexto de AI. Quaisquer blocos ai_context: que você adicionou ao seu YAML MetricFlow (descrições, sample values, synonyms) são expostos através do schema de AI do Saiku para consumidores LLM.

O que não está em v0.1.1

A spec OSI em v0.1.1 (o que o dbt 1.12 emite) ainda não cobre:

  • Métricas cumulativas / rolling / período-sobre-período
  • Métricas aninhadas / derivadas que referenciam outras métricas
  • Funções de agregação customizadas além de sum / count / avg / min / max

Estas são lacunas conhecidas na spec, não no Saiku. Conforme o OSI avança para v0.2 com participação mais ampla de fornecedores, elas chegarão. A integração as pegará automaticamente porque o Saiku lê o mesmo arquivo que o dbt escreve.

FAQ

Preciso instalar algo do lado do dbt? Não. dbt compile no dbt-core 1.12+ escreve o documento OSI sem configuração.

E versões mais antigas do dbt? Para dbt 1.10 e 1.11, você pode converter seu YAML MetricFlow para YAML Ossie com o pequeno conversor Python no repositório do Saiku. Uma vez que sua versão do dbt alcance 1.12, largue o conversor e use target/osi_document.json diretamente.

Posso misturar modelos Ossie originados no dbt e autorados à mão? Sim. Todo datasource .sds registra um modelo. Aponte alguns para target/osi_document.json, outros para YAML escrito à mão.

E se o dbt emitir um semantic_model com um nome que eu não gosto? Defina name no modelo semântico externo no seu YAML MetricFlow — o dbt o passa adiante. Se você não definir um, o dbt default para "semantic_model".

Veja também