The semantic layer in Rig: bootstrap one from scratch, or import the one you already have

What a semantic layer is, and why it matters

Raw warehouse tables do not answer business questions on their own. The same word, "revenue", can mean five different things depending on which table you query and which filters you apply. A semantic layer fixes that by holding the canonical definitions in one place: every metric, the SQL behind it, the joins it relies on, and the rules that govern it.

Once those definitions live in Rig, every answer is consistent, whether it comes from an analyst, a business user asking in plain English, or an AI tool like Claude or Cursor plugged in over MCP. The metrics view is where the whole library lives, and where you certify the definitions your team can trust.

The metrics view: your whole library of certified definitions in one place.

Your top ten percent of metrics, the revenue and churn definitions everyone leans on, belong in the semantic layer. But Rig also builds the wider context graph around them: the tables, joins, and business terms that help you draft those metrics in the first place and support all the data work that does not fit neatly into a single metric. When you are chasing a transaction or logistics log for one order ID, there is no semantic metric for that, and the surrounding context is what lets Rig answer anyway.

Bootstrap a semantic layer from scratch

If you have never had a semantic layer, this is the most common place to start. Rig reads your connected warehouse, understands the shape of your tables, and helps you turn the definitions in your team's head into certified metrics. You do not need a modelling project or a migration plan, you start defining metrics on day one.

Every metric carries its full definition with it. Open one to read its description, see the exact SQL behind it, and run it inline, so anyone can check what is certified and reuse it instead of rewriting the same logic.

Open any metric to see its full definition, the SQL behind it, and run it inline.

The metric generator does the first draft for you

Inside the Rig app, click create a metric, type a name like ARR, and describe it in plain English. You do not need to remember the exact field names or write the SQL yourself. Hit Magic Hydrate and Rig's agent goes out, finds the relevant data context, and drafts the metric for you, for example sum of value from your Attio deals.

Every draft is checked against the Rig sandbox, which holds synthesized, PII-safe equivalents of your data, so you can confirm the SQL actually returns results before anything is certified. Review the generated query, run it inline to eyeball the rows, then save it as a draft or save and certify when you are confident.

Or work headless from Claude

The second way is to do exactly the same thing without leaving Claude. Because Rig connects over MCP, you can ask a question like "how do we calculate revenue?" and the agent searches your metrics, sees there is no revenue metric yet, and drafts one, returning the SQL and the measure before anything is saved.

The wider context graph pays off here too. If you notice two columns that look similar, say value and value_v2, you can ask the difference and Rig digs into the underlying data: it finds the test transactions inflating one of them, then updates the canonical SQL to exclude that DLT load. You go from a rough definition to a clean, governed metric in the same conversation, and it lands in the same library your team and every AI tool query.

Already have a semantic layer? Import it

You do not have to rebuild what you already have. If your definitions live in LookML or another semantic layer, Rig can import and migrate them, mapping each existing metric to a Rig metric with its SQL, joins, and description intact. Teams that have spent years curating LookML can move that work across in minutes rather than rewriting it by hand.

Importing also gives you a clean upgrade path. Bring your definitions in as they are, then let Rig serve them to every AI tool and business user over MCP, with the same certification and governance you would get from building from scratch.

The format under the hood: open, OSI-compatible

A semantic layer only pays off if you can trust it for years, and that means the format matters as much as the tooling. Rig stores every metric in the shape of the Open Semantic Interchange standard (OSI, now Apache Ossie: the open format started by Snowflake and backed by the major data vendors). An OSI metric is deliberately small: a name, the SQL expression tagged with its warehouse dialect, a description, and AI context. Export your whole model as one document and any OSI consumer can read it. dbt already scans OSI documents natively.

# One OSI document describes your whole semantic model
version: "0.1.1"
semantic_models:
  - name: acme
    datasets:
      - name: analytics.orders
        source: analytics.orders
    relationships:
      - from: analytics.orders
        to: analytics.customers
        from_columns: [customer_id]
        to_columns: [id]
    metrics:
      - name: net_revenue
        description: Net revenue from completed orders, refunds excluded.
        expression:
          dialects:
            - dialect: SNOWFLAKE
              expression: |
                SELECT SUM(amount - COALESCE(refund_amount, 0)) AS net_revenue
                FROM analytics.orders
                WHERE status = 'completed'
        ai_context:
          instructions: Prefer this over gross_revenue for board reporting.

Everything Rig knows beyond that core rides in the spec's own extension mechanism, custom_extensions, which every conforming tool preserves. This is where the definitions become operational: certification status so your team knows which numbers are governed, a structured measure (aggregate, expression, filter) so BI tools can receive it as a native measure rather than opaque SQL, the entity and home table, and a stable id that keeps every copy of the metric pointing at the same thing through renames and round-trips.

      # ...continuing net_revenue: the Rig extension rides in the
      # spec's own custom_extensions mechanism. Strip it and the
      # metric above is still a complete, valid OSI object.
        custom_extensions:
          - vendor_name: RIG
            data:
              id: 7c9e6679-7425-40de-963d-cbe342cf9f21   # stable identity across every sync
              readable_name: Net Revenue
              status: certified            # governance: draft -> certified
              category: revenue            # where it lives in your metric library
              entity: order                # what one row means
              measure_type: sum            # structured measure, so BI tools get a native measure:
              measure_expr: amount - COALESCE(refund_amount, 0)
              measure_filter_sql: status = 'completed'
              primary_table: analytics.orders

There is no lock-in in this design: strip the Rig extension and you still hold a complete, valid OSI model, exportable at any time. It also composes with other vendors. The OSI spec requires tools to preserve each other's extensions, and Rig honours that both ways: a document that arrives carrying another tool's extension block survives a round-trip through Rig untouched.

Sync in and out of the BI tools you already use

Because the stored format is the interchange format, syncing is serialization rather than translation. Your metrics can live in Rig, in your Git repo, or in your BI tool, and stay in step. You do not have to choose between "the semantic layer the AI uses" and "the semantic layer the dashboards use".

The sync is governed, not blind. Metrics your team has certified in Rig are protected: an edit arriving from a BI tool never silently overwrites a certified definition: it surfaces for review instead. And where a definition genuinely cannot be expressed in the target tool (a multi-table ratio pushed into a single-view measure, say), Rig reports exactly what was skipped and why, rather than quietly mangling it.

Case studies

Both paths, building from nothing and migrating an existing layer, are proven in production.