Visivo v1.0.76-78: The Semantic Layer Lands

Visivo v1.0.76 is the release where the semantic layer lands. Metrics, dimensions, and relations arrive as real, first-class objects in your project, the Insights foundation and a notebook-style Explorer ship alongside them, and the source list gains ClickHouse plus automatic schema introspection. The two follow-on patches that same week, v1.0.77 and v1.0.78, harden the installer for Python 3.14 and add job-ID run tracking. This is the foundation that everything in the road to 2.0 is built on.

Here is the full picture, feature by feature, and why each one matters.

The release that reshapes Visivo

Most releases add a feature. This one changes the shape of the product. Before v1.0.76, a Visivo project described charts and the data behind them in a fairly direct way: you pointed a visualization at a query and styled it. That worked, but it left every metric definition stranded inside the chart that used it, which is the exact pattern that causes metrics to drift across an organization.

v1.0.76 introduces a layer between your raw data and your visualizations: a semantic layer where metrics, dimensions, and relationships are defined once and referenced everywhere. It is the largest single expansion of the Visivo model we have shipped, and it is the groundwork for the Insights system that becomes the only way to build in 2.0. Read this recap as the origin story for the rest of the year.

Metrics, dimensions, and relations: the semantic layer

The headline is three new object types attached to your models: metrics, dimensions, and relations.

A metric is a named aggregation. A dimension is a named way to slice. Defined together on a model, they turn a raw table into a queryable, governed surface:

models:
  - name: orders
    sql: "SELECT * FROM orders"
    metrics:
      - name: net_revenue
        expression: "SUM(amount - refunds - discounts)"
      - name: order_count
        expression: "COUNT(*)"
    dimensions:
      - name: order_month
        expression: "DATE_TRUNC('month', created_at)"
      - name: customer_segment
        expression: "segment"

A relation declares how two models join, once, so nobody has to re-write that join in every query:

relations:
  - name: orders_to_customers
    condition: ${ref(orders).customer_id} = ${ref(customers).id}

The payoff is the one we keep coming back to. net_revenue now has exactly one definition, in one file, that everything reads from. Change it once and every chart that references it is correct on the next run. This is the single source of truth for metrics made real in the product, and it is what makes safe self-serve possible, the subject of last week's post on governance without gatekeeping.

The Insights foundation

Metrics and dimensions are the nouns. Insights are how you turn them into a chart. An Insight references the semantic layer through ?{ ... } query expressions and describes what you want to see:

insights:
  - name: monthly-revenue
    description: "Net revenue by month"
    props:
      type: bar
      x: ?{ ${ref(orders).order_month} }
      y: ?{ ${ref(orders).net_revenue} }
    interactions:
      - split: ?{ ${ref(orders).customer_segment} }
      - sort: ?{ ${ref(orders).order_month} ASC }

Two things make this different from pointing a chart at a query. First, the Insight does not contain the definition of revenue, it references it, so the drift problem is gone by construction. Second, the interactions block makes filters, splits, and sorts declarative, so a stakeholder can re-slice the data in the viewer without anyone rebuilding the chart. v1.0.76 ships the foundation of this system; the releases through 2.0 build it out and eventually make it the only path. It is the same logic that has made dbt™ the backbone of the warehouse, carried up into the visualization layer.

A notebook-style Explorer

Defining metrics in YAML is the durable, reviewable path, but it is not always how exploration starts. Sometimes you want to poke at the data first and formalize later. v1.0.76 ships a notebook-style Explorer for exactly that.

The Explorer is an interactive surface where you can query a source, see results, and iterate cell by cell, the way you would in a data notebook. It is the on-ramp to the semantic layer: explore until you understand the shape of the data, then promote what you learned into a metric or dimension that the rest of the project can reuse. This release lands the foundation of the Explorer; subsequent releases add a SQL editor, pivotable tables, and a full redesign on top of it.

ClickHouse joins the source list

v1.0.76 adds ClickHouse as a supported data source. ClickHouse is a column-oriented database built for fast analytical queries over large volumes, and it is an increasingly common choice for teams that have outgrown a transactional database for analytics workloads.

With the new source you point a Visivo project at ClickHouse the same way you would point it at PostgreSQL, BigQuery, Snowflake, DuckDB, or any other supported source: define the connection, reference its tables in your models, and build metrics and Insights on top. The semantic layer sits above the source, so the modeling work you do is identical regardless of where the data physically lives.

Automatic source schema introspection

The most quietly useful feature in the release is automatic source schema introspection. When you connect a source, Visivo can now read the database's own structure, its tables, columns, and types, directly, instead of making you transcribe all of that into config by hand.

Hand-typing a schema is slow, error-prone, and goes stale the moment the database changes underneath you. Introspection removes that toil: Visivo asks the source what it contains and uses the answer to accelerate modeling. It makes onboarding a new database dramatically faster, and it sets up the Explorer schema jobs that arrive in a later release. We go deeper on why this matters in a dedicated post on schema introspection.

Plus Python 3.14 and a hardened installer (v1.0.77)

Two days after v1.0.76, v1.0.77 shipped on January 30 with the kind of work that does not make headlines but keeps the project healthy. It adds support for Python 3.14, so teams on the newest interpreter can run Visivo without pinning to an older runtime.

It also hardens the install script. The curl -fsSL https://visivo.sh | bash path now has automated installer tests behind it, so the very first thing a new user touches, getting Visivo onto their machine, is covered by CI rather than tested by hope. A smooth install is the most underrated part of developer experience, because every friction point at the front door is a user you never see again.

Job-ID run tracking and ssl:false (v1.0.78)

The next day, v1.0.78 (January 31) added two practical improvements. The first is job-ID-based run tracking: each run now carries a job identifier, which makes it far easier to follow a single run through logs and tie artifacts back to the execution that produced them. As projects grow and runs get scheduled, being able to point at one run by ID is the difference between debugging and guessing.

The second is that sources now honor ssl: false. Some databases, particularly in local development and inside private networks, are reachable only without TLS, and forcing SSL made them impossible to connect to. Respecting ssl: false removes that blocker for the environments where it is the right call.

What it unlocks

Step back and the through-line is clear. v1.0.76 does not just add features, it establishes the model that the rest of the year refines. A semantic layer means one definition per metric. Insights mean charts that reference those definitions instead of re-deriving them. The Explorer means a fast on-ramp into that layer. Introspection means you fill the layer from the real database instead of by hand. And ClickHouse plus the v1.0.77 and v1.0.78 hardening mean the whole thing runs reliably across more sources, more runtimes, and more network setups.

Everything that comes next, relations as a deep feature, the SQL editor, pivot tables, the Explorer redesign, and finally Visivo 2.0 committing to Insights as the only way to build, stands on this release. If you want to feel it, /get-started takes you from install to your first metric in minutes, the examples gallery is built entirely on this model, and the full reference lives in the Visivo documentation.

Previously in Visivo

This release is the product backing for the argument in governance without gatekeeping: safe self-serve analytics. The semantic layer that lands here is precisely the substrate that makes self-serve safe. For the broader thesis, see why your metrics belong in a semantic layer.