Skip to content

Export marts as portable OSI YAML

If you want consumers outside dbt — Snowflake Cortex, ThoughtSpot, RelationalAI, or any future tool that reads the Open Semantic Interchange format — to consume your warehouse semantics, OSI is the published view. dbt MetricFlow stays the source of truth; OSI is the regenerable export.

TL;DR

# 1. Build your dbt models so the warehouse has marts to introspect.
tycoon data transform build

# 2. Generate the OSI file.
tycoon semantics scaffold

# 3. Edit metrics + relationships by hand (the scaffold leaves these empty).
$EDITOR dbt_project/semantic/osi.yaml

# 4. Validate against the OSI v0.1.1 schema before shipping.
tycoon semantics doctor

The output lives at dbt_project/semantic/osi.yaml.

What gets scaffolded

For every table prefixed mart_*, fct_*, dim_*, or obt_* in your warehouse:

- name: mart_orders
  source: warehouse.main.mart_orders
  primary_key:
    - id
  fields:
    - name: id
      expression:
        dialects:
          - dialect: ANSI_SQL
            expression: id
      dimension: {}
    - name: customer_id
      expression:
        dialects:
          - dialect: ANSI_SQL
            expression: customer_id
      dimension: {}            # FK pattern → dimension despite INTEGER type
    - name: order_date
      expression:
        dialects:
          - dialect: ANSI_SQL
            expression: order_date
      dimension:
        is_time: true          # DATE → time dimension
    - name: total_amount
      expression:
        dialects:
          - dialect: ANSI_SQL
            expression: total_amount
                                # No `dimension:` → measure-eligible

What you fill in

Tycoon doesn't scaffold metrics or relationships — those are SQL expressions and join definitions tycoon can't reasonably guess. Add them under the semantic_model block:

semantic_model:
  - name: my-project
    datasets: [...]                # tycoon-generated
    metrics:
      - name: total_revenue
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: SUM(mart_orders.total_amount)
      - name: paid_order_count
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: COUNT(CASE WHEN mart_orders.is_paid THEN 1 END)
    relationships:
      - name: orders_to_customer
        from: mart_orders
        to: dim_customer
        from_columns: [customer_id]
        to_columns: [id]

Preserving your edits across re-runs

The first line of the generated file is the sentinel:

# @generated by tycoon semantics — remove this line to opt out of regeneration

If you've added metrics and relationships and want them safe from re-run:

  1. Remove the sentinel line — tycoon semantics scaffold will skip the file going forward.
  2. Or use --force only when you explicitly want to regenerate.

A future tycoon may preserve metrics + relationships across re-runs. For v0.1.6, the rule is binary: sentinel = regenerable, no sentinel = yours.

Auto-regenerate after every dbt build

Useful once you've stabilized your metric definitions:

# tycoon.yml
transform:
  auto_osi_scaffold: true

tycoon data transform run and tycoon data transform build will re-emit the OSI file after a successful dbt run. Failures never bubble into the dbt command's success path. Default is off — opt in when you're confident the Conservative scaffold matches your project.

Validating before you ship

tycoon semantics doctor
# ✓ /Users/me/proj/dbt_project/semantic/osi.yaml is valid OSI v0.1.1.

Exits 0 on success, 1 on any schema violation. Use in CI:

# .github/workflows/ci.yml
- run: tycoon semantics doctor

tycoon doctor runs the same check non-fatally as part of the regular environment audit, so you'll catch breakage on your own machine without setting up CI first.

What's deferred

  • Rill auto-generated metrics_views from OSI. Deferred until Rill joins the OSI consortium.
  • tycoon semantics push <consumer>. Direct push to consumer registries (Snowflake Cortex, ThoughtSpot, RelationalAI). Possible v0.1.7+. For now, ship osi.yaml to consumers via whatever mechanism they support.