Skip to main content

Rill project files

When you create sources, models, and metrics versions we create code-representations on your behalf on the file system. You can see these files in your source, models and dashboards folders in your project.

Projects can be "re-hydrated" from Rill project files into an explorable data application - figuring out the dependencies, pulling down data, & validating your model queries and metrics configurations. The result is a set of functioning exploratory dashboards.

You can see an example project by visiting our example github repository.

Source connections

In your Rill project directory, create a source.yaml file in the sources directory containing a type and location (uri or path). Rill will automatically detect and ingest the source next time you run rill start.

type — the type of connector you are using for the source (required). Possible values include:

  • https — public files available on the web.
  • s3 — a file available on amazon s3.
  • gcs — a file available on google cloud platform.
  • local_file — a locally available file.

uri — the URI of the remote connector you are using for the source (required for type: http, s3, gcs). Rill also supports glob patterns as part of the URI for S3 and GCS.

  • s3://your-org/bucket/file.parquet — the s3 URI of your file
  • gs://your-org/bucket/file.parquet — the gsutil URI of your file
  • https://data.example.org/path/to/file.parquet — the web address of your file

path — the local path of the connector you are using for the source relative to your project's root directory. (required for type: file)

  • /path/to/file.csv — the path to your file

region — Optionally sets the cloud region of the bucket you want to connect to. Only available for S3.

  • us-east-1 — the cloud region identifer

glob.max_total_size — Applicable if the URI is a glob pattern. The max allowed total size (in bytes) of all objects matching the glob pattern.

  • default value is 10737418240 (10GB)

glob.max_objects_matched — Applicable if the URI is a glob pattern. The max allowed number of objects matching the glob pattern.

  • default value is 1,000

glob.max_objects_listed — Appplicable if the URI is a glob pattern. The max number of objects to list and match against glob pattern (excluding files excluded by the glob prefix).

  • default value is 1,000,000

See our Using Rill guide for an example.

Model transformation

Data transformations in Rill Developer are powered by DuckDB and their dialect of SQL (duckSQL). Under the hood, data models are created as views in DuckDB. Please visit their documentation for insight into how to write your queries.

In your Rill project directory, create a model_name.sql file in the models directory containing a duckSQL SELECT statement. Rill will automatically detect and parse the model next time you run rill start.

Dashboard metrics

In your Rill project directory, create a dashboard_name.yaml file in the dashboards directory. Rill will ingest the dashboard definition next time you run rill start.

model — the model name powering the dashboard with no path (required)

display_name — the display name for the dashboard (required)

timeseries — column from your model that will underlie x-axis data in the line charts (required)

dimensions: — for exploring segments and filtering the dashboard (required)

  • property — a categorical column (required)
  • label — a label for your dashboard dimension (optional)
  • description — a freeform text description of the dimension for your dashboard (optional)

measures: — numeric aggregates of columns from your data model (required)

  • expression — a combination of operators and functions for aggregations (required)
  • label — a label for your dashboard measure (optional)
  • description — a freeform text description of the dimension for your dashboard (optional)
  • format_preset — one of a set of values that format dashboard measures. (optional; default is humanize). Possible values include:
    • humanize — round off numbers in an opinionated way to thousands (K), millions (M), billions B), etc
    • none — raw output
    • currency_usd — output rounded to 2 decimal points prepended with a dollar sign
    • percentage — output transformed from a rate to a percentage appended with a percentage sign
    • comma_separators — output transformed to decimal formal with commas every 3 digits

See our Using Rill guide for an example.

Project definition

  • name — the name of your project which will be displayed in the upper left hand corner
  • compiler — the version of the runtime compiler that is compatible with the artifacts (ex: rill-beta)
  • rill_version — the version of Rill Developer that is compatible with the artifacts (ex: v0.16)