Rill: BI as YAML and SQL, Built for Coding Agents

What Rill Replaces, and for Whom

Most BI tools split a project across two places. Transformations live in a repository; dashboards and metric definitions live in a vendor's UI, where they are edited by hand and reviewed by nobody. Rill puts both halves in the same Git-backed project. The README describes the project as "Agent-first, human-friendly business intelligence", and the repository layout supports that claim: a top-level `runtime/` directory holds the Go service, `cli/` holds the command line entry point, and `web-local/`, `web-common/` and `web-admin/` hold the SvelteKit front ends. A project you create is a directory of YAML and SQL files, not a database row in someone else's cloud.

The audience is narrower than "everyone who wants dashboards". It is data engineers and analytics engineers who are comfortable writing SQL, who already version their transformations, and who want the metric definitions to be reviewable in a pull request. The second audience is newer: teams wiring coding agents into their analytics workflow. The README states that "BI-as-code (YAML + SQL) means coding agents like Claude Code and Cursor can author projects, dashboards, and security policies end-to-end", and the repository carries `.claude/` and `.cursor/` directories at the top level, which is consistent with that positioning.

If your organisation's dashboard authors are business analysts who expect to drag fields onto a canvas, Rill is the wrong shape. Nothing in the README describes a visual dashboard builder. The dashboard file is a YAML document listing which dimensions and measures to expose; the visualisation choices are configuration, not clicks.

The Semantic Layer Is the Actual Product

Strip away the connectors and the UI and what remains is a metrics view. The README's own example shows the pattern: a `metrics/events_metrics.yaml` file declares a version, a type of `metrics_view`, the model it reads from, a `timeseries` column, then lists `dimensions` and `measures`. Each measure has a `name` and an `expression`, such as `count(*)` or `sum(price * quantity)`. The README describes this as a "Single source of truth for dimensions, measures, and time grains, defined in YAML, generating SQL at query time against your OLAP engine".

That last clause is the mechanism worth understanding. Rill does not precompute a cube. When a dashboard or an agent asks for revenue by country over the last quarter, the runtime composes SQL from the metrics view definition and pushes it down to the OLAP engine. This is why the choice of engine matters so much, and why the README splits engines by scale: "ClickHouse for billions of rows, DuckDB for smaller datasets and fast iteration".

Data flows in three hops. A model file, for example `models/events.yaml`, declares a `connector` and a `sql` block. The README's example uses `connector: duckdb` with `materialize: true` and a `read_parquet` call against a public GCS bucket. The model materialises into the engine. The metrics view then references that model by name, and dashboards reference the metrics view. Each layer is a separate file, so a change to a measure does not require touching the dashboard that consumes it.

Two capabilities sit on top of this and are easy to miss. Row access policies are documented as "Per-user, per-group data access control", which means the security boundary is expressed in the same YAML as the metrics, not configured separately in a UI. Incremental ingestion is described as loading "only new data on each run to keep large datasets current without full refreshes", which is the difference between a viable and an unviable setup on a large event table.

Installing Rill and Building a First Dashboard

The README gives a two-line install. The first line fetches a shell script from `rill.sh` and pipes it to `sh`; the second creates a project and opens the UI. Note that piping a remote script into a shell is a decision you should make deliberately, and the README does not document a checksum or signature for that script.

curl https://rill.sh | sh
rill start my-project

If you prefer a scaffolded start, the README shows `rill init` running interactively. It prompts for a project name, an OLAP engine (the example answer is `duckdb`) and agent instructions (the example answer is `claude`). The README's sample output says the command creates the project directory and, for the Claude case, adds instructions in `.claude` and `.mcp.json`, then tells you to run `rill start` on the new directory.

rill init

Once a project exists, the smallest useful unit is a model. The README's example reads a Parquet file directly from a public bucket, which means you can try the tool without credentials:

type: model
connector: duckdb
materialize: true

sql: |
  select * from read_parquet('gs://rilldata-public/auction_data.parquet')

On top of that model you declare the metrics view. This is the file that turns a table into named, reusable measures:

version: 1
type: metrics_view
model: events
timeseries: timestamp

dimensions:
  - name: country
    column: country
  - name: device
    column: device_type

measures:
  - name: total_events
    expression: count(*)
  - name: revenue
    expression: sum(price * quantity)
    description: Total revenue

The dashboard file is the thinnest of the three. It names the metrics view and selects which dimensions and measures to surface, using `"*"` to take everything:

type: explore

display_name: "Events Dashboard"
metrics_view: events_metrics

dimensions: "*"
measures: "*"

Publishing is a single command, and the README states that the metrics view becomes queryable on Rill Cloud immediately afterwards:

rill deploy

What you should see locally, per the README, is an interactive dashboard you can preview before deploying. The README does not describe what `rill deploy` does about authentication on first run, nor does it document a rollback path for a bad deployment.

Where Rill Stops Being the Right Tool

The most concrete limitation is the one the README states as a feature: everything is code. There is no described path for a business user to create a new measure without editing YAML and getting it merged. That is a deliberate trade, and it is the correct trade for a team that wants review on metric definitions, but it means Rill does not remove the analytics engineering bottleneck. It relocates it into a repository.

The second limitation is engine coupling. The README lists DuckDB as included, managed ClickHouse, or external engines including ClickHouse Cloud, Druid, Pinot and MotherDuck. If your data already lives in a warehouse that is not on that list, you are looking at moving data or running a connector into one of the supported engines, and the README does not describe a generic passthrough. The Go module file shows the breadth of what the runtime actually connects to, including BigQuery, Athena, Redshift, Databricks and Kafka clients, but connector availability in the module graph is not the same as a documented, supported path in the product, and the README's connector section only says "S3, GCS, databases, and 20+ sources" without enumerating them.

Third, the local experience and the cloud experience are different products with different names. Rill Developer runs locally; Rill Cloud is where deployment, embedding, alerts and the MCP server live. A team that wants conversational BI or agent access is committing to the cloud side, and the README does not describe a self-hosted equivalent of that surface.

Finally, the README does not document rollback, version pinning for the `rill.sh` installer, or an upgrade procedure. Given that releases arrive frequently (v0.89.1 on 2026-08-25, v0.89.2 on 2026-08-26, v0.89.4 on 2026-09-01), a team adopting this should confirm its own upgrade and rollback story rather than assume one exists.

Rill Against a Warehouse-Native BI Tool

The obvious comparison is a warehouse-native BI tool such as Looker or Metabase. The difference is where the metric definition lives and what executes it.

Metabase is a self-hosted application with a web UI as the primary authoring surface. You connect it to a database, and people build questions and dashboards by clicking, with SQL available as an escape hatch. The definitions live in Metabase's own application database, and moving them between environments means exporting and importing application state. Metabase's strength is exactly Rill's weakness: a non-technical person can build a chart in ten minutes without a pull request.

Looker sits closer to Rill in that LookML is a code-defined semantic layer, and it is also Git-backed. The difference in approach is execution and packaging. Rill generates SQL at query time and pushes it to an engine you choose, with DuckDB as a local option that needs no server at all, which is what makes the local-first loop possible. Looker's semantic layer is bound to its own platform. Rill's Apache-2.0 licence and single-binary CLI mean you can run the whole developer experience on a laptop and read the source when something behaves unexpectedly.

The honest summary: choose Rill when the semantic layer should be a file in your repository and the engine should be swappable. Choose a click-based tool when the people writing the questions are not the people writing the SQL.

Editorial conclusion

Adopt Rill if your team already keeps data transformations in Git and wants dashboards, metrics and agent access to live in the same repository; the YAML metrics view is the piece that makes that work. Do not adopt it if you need a point-and-click dashboard builder for non-technical authors, because the README shows no such editor. Before committing, verify two things yourself: that your OLAP engine is one the documentation lists as supported, and that `rill init` produces the agent instructions for the client you actually use.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. rilldata/rill on GitHub