Saltearse al contenido
Saiku Cloud

Conexión dbt / MetricFlow

Si ya está ejecutando dbt con modelos semánticos de MetricFlow, puede traerlos a Saiku sin remodelar nada. dbt Core 1.12 emite un documento de Open Semantic Interchange junto a sus artefactos de build habituales, y Saiku carga ese archivo tal cual a través de su flujo normal de registro de datasources.

Una vez conectado, todo lo que Saiku expone sobre un modelo Ossie funciona contra su capa semántica dbt: el workbench, la API AI Query tipada, las herramientas MCP, la capa de lenguaje natural /ask, los endpoints de anomalías y forecast.

Prerrequisitos

  • Un proyecto dbt con modelos semánticos de MetricFlow
  • dbt Core 1.12 o más reciente — las versiones anteriores no emiten el documento OSI
  • El mismo warehouse al que apunta su proyecto dbt
  • Una instancia de Saiku en ejecución (Saiku Cloud o auto-alojada) — necesita acceso de escritura al directorio de datasources en el host, o acceso a la API de admin

El recorrido

  1. Compile su proyecto dbt. El documento OSI se emite como parte de cualquier comando que dispare un parseo completo — dbt compile, dbt run, dbt build.

    Ventana de terminal
    cd path/to/your-dbt-project
    dbt compile

    El resultado aterriza en target/osi_document.json. Es un único archivo JSON que contiene cada modelo semántico que declara su proyecto, en el formato OSI v0.1.1.

  2. Apunte Saiku a él. Registre un datasource apuntando al archivo JSON y al warehouse al que apunta dbt. En un launcher auto-alojado esto es un archivo .sds; en Saiku Cloud puede registrarlo mediante la 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>

    Dos cosas a tener en cuenta:

    • El elemento <ossieYaml> acepta cualquier archivo que el parser YAML de Jackson acepte — YAML y JSON. Apúntelo al archivo exacto que dbt escribió; sin paso de conversión.
    • El valor de <schema> es el campo name del modelo semántico que dbt emite. Para un proyecto nuevo eso es típicamente "semantic_model" (el por defecto de dbt cuando no se da un nombre explícito).

  3. Verifique. El modelo aparece en /ai/ossie/models inmediatamente después del siguiente refresco de conexión de Saiku.

    Ventana 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. Consulte. Cada endpoint REST, herramienta MCP y funcionalidad del workbench funciona ahora contra su capa semántica dbt. Haga una pregunta:

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

Esa es toda la integración. Sin modelado en la sombra, sin re-declaración, sin pipeline de conversión.

Mantenerse sincronizado

Como dbt escribe osi_document.json en cada compilación, la integración se mantiene fresca automáticamente:

  • Bucle de desarrollo. dbt compile al guardar (o mediante dbt-watch) mantiene el archivo actual mientras desarrolla métricas. Saiku recoge los cambios a través de la misma ruta de refresco de admin que usa para cubos OLAP.
  • CI/CD. Conecte su job de CI de dbt para copiar target/osi_document.json a la ubicación que su instancia de Saiku lee. En Saiku Cloud, la API de admin acepta subidas directas.
  • Jobs de dbt en producción. Cada dbt run en producción escribe un documento fresco. Envíelo junto a sus artefactos de dbt.

Qué pone dbt en el archivo

Cada modelo semántico de su proyecto dbt viene:

  • Datasets. Uno por entrada semantic_models[*] en su YAML de MetricFlow. Incluye el nombre de tabla completamente cualificado, la clave primaria, la descripción, y cada dimensión como un campo.
  • Métricas. Las métricas simples y de ratio vienen con su expresión SQL. Las métricas acumulativas emiten una advertencia y se descartan (la especificación OSI 0.1.x aún no modela la semántica de ventana).
  • Relaciones. La inferencia de joins de MetricFlow (basada en nombres de entidad coincidentes entre modelos semánticos) se convierte en relaciones Ossie explícitas. La regla de auto-join de Calcite de Saiku las recoge en tiempo de consulta.
  • Etiquetas. Los atributos label: de MetricFlow en dimensiones y métricas se trasladan como labels de campo OSI. NETREVENUE en la columna cruda se renderiza como “Net Revenue” en todas partes de Saiku.
  • Contexto de IA. Cualquier bloque ai_context: que haya añadido a su YAML de MetricFlow (descripciones, valores de muestra, sinónimos) se expone a través del schema de IA de Saiku para consumidores LLM.

Qué no está en v0.1.1

La especificación OSI en v0.1.1 (lo que dbt 1.12 emite) aún no cubre:

  • Métricas acumulativas / rodantes / período-sobre-período
  • Métricas anidadas / derivadas que referencian otras métricas
  • Funciones de agregación personalizadas más allá de sum / count / avg / min / max

Estas son lagunas conocidas en la especificación, no en Saiku. A medida que OSI avanza hacia v0.2 con mayor participación de proveedores, estas aterrizarán. La integración las recogerá automáticamente porque Saiku lee el mismo archivo que dbt escribe.

FAQ

¿Necesito instalar algo en el lado de dbt? No. dbt compile en dbt-core 1.12+ escribe el documento OSI sin configuración.

¿Y las versiones antiguas de dbt? Para dbt 1.10 y 1.11, puede convertir su YAML de MetricFlow a YAML de Ossie con el pequeño conversor de Python en el repositorio de Saiku. Una vez que su versión de dbt alcance 1.12, deje el conversor y use target/osi_document.json directamente.

¿Puedo mezclar modelos Ossie provenientes de dbt y escritos a mano? Sí. Cada datasource .sds registra un modelo. Apunte algunos a target/osi_document.json, otros a YAML escrito a mano.

¿Qué pasa si dbt emite un semantic_model con un nombre que no me gusta? Defina name en el modelo semántico externo en su YAML de MetricFlow — dbt lo traslada. Si no define uno, dbt usa por defecto "semantic_model".

Ver también