### Install Rill and Start a Project

Source: https://github.com/rilldata/rill/blob/main/README.md

Installs Rill using a curl command and starts a new project, opening the UI.

```bash
curl https://rill.sh | sh        # install
rill start my-project            # create a project and open the UI
```

--------------------------------

### Clone and Start Rill Example Project

Source: https://github.com/rilldata/rill/blob/main/docs/blog/0.16.md

Clone the example project from GitHub, navigate into the directory, and start the Rill application to experience the new features.

```bash
git clone https://github.com/rilldata/rill-developer-example.git
cd rill-developer-example
rill start
```

--------------------------------

### Install and Start Rill Project

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/get-started/get-started.md

Use this command to install Rill and then start a new project. For more installation methods, refer to the complete installation instructions.

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

--------------------------------

### Clone and Run OpenRTB Example

Source: https://github.com/rilldata/rill/blob/main/web-common/tests/projects/openrtb/README.md

Clone the Rill examples repository and navigate to the OpenRTB project directory to start the demo. Rill will build the project and launch it in your browser.

```bash
git clone https://github.com/rilldata/rill-examples.git
cd rill-examples/rill-openrtb-prog-ads
rill start
```

--------------------------------

### Authenticate and Deploy Example Project

Source: https://github.com/rilldata/rill/blob/main/cli/cmd/devtool/README.md

Authenticates and deploys a specified example project to your cloud development environment.

```bash
rill devtool seed cloud
```

--------------------------------

### Manual Orb Webhook Setup

Source: https://github.com/rilldata/rill/blob/main/admin/billing/README.MD

Example command to set up an ngrok forwarder for manual Orb webhook configuration. This is useful for development and testing Orb event handling.

```shell
ngrok http --domain=<ngrok-provided-ip> 8080
```

--------------------------------

### Full Example with Multiple Time Dimensions

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/metrics-view/dimensions/time-dimensions.md

A comprehensive example demonstrating the setup of a metrics view with a primary timeseries column and several additional time dimensions for filtering.

```yaml
version: 1
type: metrics_view

model: sales_model
timeseries: transaction_date

dimensions:
  # Time dimensions
  - name: transaction_date
    display_name: Transaction Date
    column: transaction_date
    type: time

  - name: fulfillment_date
    display_name: Fulfillment Date
    column: fulfillment_date
    type: time

  - name: return_date
    display_name: Return Date
    column: return_date
    type: time

  # Categorical dimensions
  - name: product_category
    display_name: Product Category
    column: category

  - name: store_location
    display_name: Store Location
    column: store_id

measures:
  - name: total_sales
    display_name: Total Sales
    expression: SUM(amount)

  - name: order_count
    display_name: Order Count
    expression: COUNT(*)
```

--------------------------------

### Start Development Environment (excluding admin)

Source: https://github.com/rilldata/rill/blob/main/admin/README.md

Run this command from the repository root to start a full development environment, excluding the admin service. Use --reset for a clean start.

```bash
rill devtool start cloud --except admin # optional: --reset 
```

--------------------------------

### PostgreSQL Connection String Example

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/connectors/data-source/postgres.mdx

Example of a PostgreSQL connection string format.

```bash
host=localhost port=5432 dbname=postgres_db user=postgres_user password=postgres_pass
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/tutorials/github-analytics.md

Install project dependencies using Poetry (recommended) or pip with a virtual environment.

```bash
# Using Poetry (recommended)
poetry install
```

```bash
# Or using pip with venv
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install pandas pydriller
```

--------------------------------

### Example .env File Contents

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/connectors/credentials.md

This is an example of a .env file, showcasing how to store AWS, Google Cloud, and database credentials, along with custom variables.

```bash
# AWS S3 credentials
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# Google Cloud credentials
GOOGLE_APPLICATION_CREDENTIALS={"type":"service_account","project_id":"my-project"}

# Database connections
POSTGRES_PASSWORD=mypassword
SNOWFLAKE_PASSWORD=mysnowflakepassword

# Custom variables
my_custom_variable=some_value
```

--------------------------------

### Install Rill CLI

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/deploy/deploy-dashboard/github-101.md

Run this command in your local repository's directory after cloning to install the Rill CLI. This command can also be used to start Rill if it's already installed.

```bash
curl https://rill.sh | sh
```

```bash
rill start
```

--------------------------------

### PostgreSQL Connection URI Example

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/connectors/data-source/postgres.mdx

Example of a PostgreSQL connection URI format.

```bash
postgresql://postgres_user:postgres_pass@localhost:5432/postgres_db
```

--------------------------------

### Install npm Packages

Source: https://github.com/rilldata/rill/blob/main/docs/README.md

Installs necessary packages for building the documentation. Run this command from the root of the docs folder.

```bash
npm install
```

--------------------------------

### Complete Service Token Creation Example

Source: https://github.com/rilldata/rill/blob/main/docs/docs/guide/administration/access-tokens/service-tokens.md

This example demonstrates creating a service token for automated reporting, specifying organization, project, role, and custom attributes for metadata.

```bash
# Create a service for automated reporting
rill service create reporting-service \
  --org my-org \
  --project analytics-dashboard \
  --project-role viewer \
  --attributes '{"purpose":"reporting","schedule":"daily","region":"us-east"}'
```

--------------------------------

### Making GET Requests

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/custom-apis/calling.md

Example of making a GET request to a custom API with query parameters and authentication.

```APIDOC
## GET Request Example

### Description
Calls a custom API using the GET method with query parameters.

### Method
GET

### Endpoint
https://api.rilldata.com/v1/organizations/<org>/projects/<project>/runtime/api/my-api?domain=google.com&limit=10

### Headers
- Authorization: Bearer <token>

### Query Parameters
- **domain** (string) - Description of the domain parameter
- **limit** (integer) - Description of the limit parameter
```

--------------------------------

### Start Rill Project CLI

Source: https://github.com/rilldata/rill/blob/main/docs/docs/reference/cli/start.md

Builds the project and starts the web application. Optionally specify a path to the project directory.

```bash
rill start [<path>] [flags]
```

--------------------------------

### Start Local Development Environment

Source: https://github.com/rilldata/rill/blob/main/cli/cmd/devtool/README.md

Starts a local development environment for Rill.

```bash
rill devtool start local
```

--------------------------------

### Start Cloud Environment with Specific Services

Source: https://github.com/rilldata/rill/blob/main/cli/cmd/devtool/README.md

Starts a cloud development environment including only the specified services, such as the admin server and external dependencies.

```bash
rill devtool start cloud --only admin,deps
```

--------------------------------

### Start Clean Cloud Development Environment

Source: https://github.com/rilldata/rill/blob/main/cli/cmd/devtool/README.md

Starts a cloud development environment from a clean state, resetting any existing configurations.

```bash
rill devtool start cloud --reset
```

--------------------------------

### Start Debug Server

Source: https://github.com/rilldata/rill/blob/main/runtime/pkg/debugserver/README.md

Starts an HTTP server that serves net/http/pprof endpoints on port 6060. If running `rill start`, the `--debug` flag must be passed.

--------------------------------

### Configure DuckDB Extensions

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/connectors/olap/duckdb.md

Enable DuckDB extensions by listing them in the `init_sql` property of your `connectors/duckdb.yaml` file. This example installs and loads the `httpfs` and `spatial` extensions.

```yaml
# connectors/duckdb.yaml
type: connector
driver: duckdb
init_sql: |
  INSTALL httpfs;
  LOAD httpfs;
  INSTALL spatial;
  LOAD spatial;
```

--------------------------------

### Run Playwright Setup Project

Source: https://github.com/rilldata/rill/blob/main/web-admin/tests/README.md

Execute the Playwright setup project to initialize the Rill Cloud environment, log in, create an organization, deploy projects, and wait for data ingestion.

```bash
npx playwright test --project=setup
```

```bash
npm run test:setup
```

--------------------------------

### Development Workflow: Start Frontend

Source: https://github.com/rilldata/rill/blob/main/web-admin/tests/README.md

Start the frontend development server. Use 'npm run dev' to avoid port conflicts with Playwright.

```bash
npm run preview  # or npm run dev
```

--------------------------------

### Install Smee Client

Source: https://github.com/rilldata/rill/blob/main/admin/README.md

Install the Smee client globally to proxy Github webhooks to your local development environment.

```bash
npm install --global smee-client
```

--------------------------------

### Complete Rill Project Configuration Example

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/project-configuration.md

A comprehensive `rill.yaml` example demonstrating various configurations including OLAP connector, environment variables, model defaults, metrics view settings, explore defaults, canvas settings, mock users, and feature flags.

```yaml
compiler: rillv1

display_name: Rill Project Dev

# The project's default OLAP connector.
# Learn more: https://docs.rilldata.com/reference/olap-engines
olap_connector: duckdb

# Project variables for templating
env:
  numeric_var: 10
  string_var: "string_value"

# Project Defaults
models:
    refresh:
        cron: '0 * * * *'
        run_in_dev: true
metrics_views:
    first_day_of_week: 1
    smallest_time_grain: month
explores:
    defaults:
        time_range: P24M
    time_zones:
        - UTC
        - America/Los_Angeles
        - America/New_York
        - Europe/London
        - Europe/Paris
        - Asia/Tokyo
        - Australia/Sydney
    time_ranges:
        - PT24H
        - P6M
        - P12M
canvases:
  defaults:
      time_range: P24M
  time_zones:
      - UTC
      - America/Los_Angeles
      - America/New_York
      - Europe/London
      - Europe/Paris
      - Asia/Tokyo
  time_ranges:
      - PT24H
      - P7D
      - P14D
      - P30D
      - P3M
      - P6M
      - P12M

# These are example mock users to test your security policies.
# Learn more: https://docs.rilldata.com/developers/build/metrics-view/security
mock_users:
  - email: john@yourcompany.com
  - email: jane@partnercompany.com
  - email: your_email@domain.com
    groups:
      - tutorial-admin
  - email: embed@rilldata.com
    name: embed
    custom_variable_1: Value_1 #this is passed at embed creation
    custom_variable_2: Value_2 #this is passed at embed creation

features:
  - cloudDataViewer
```

--------------------------------

### Kubernetes Provisioner Configuration Example

Source: https://github.com/rilldata/rill/blob/main/admin/provisioner/kubernetes/README.md

Example provisioner spec for the Kubernetes provisioner. Configure settings like timeout, data directory, host, namespace, image, and template paths.

```json
{
  "kubernetes-example":
    {
      "type": "kubernetes",
      "spec":
        {
          "timeout_seconds": 30,                              // Maximum time to wait for the runtime to become ready
          "data_dir": "/mnt/data",                            // Directory to use for data storage like DB files etc.
          "host": "http://node-*.localhost",                  // The wildcard '*' will be replaced with the deployment's 'provision_id'
          "namespace": "cloud-runtime",                       // Namespace to use in the K8s cluster
          "image": "rilldata/rill",                           // Rill Docker image
          "kubeconfig_path": "kubeconfig.yaml",               // K8s config file to authenticate against the cluster
          "template_paths":
            {
              "http_ingress": "templates/http_ingress.yaml",  // Ingress resource template for HTTP
              "grpc_ingress": "templates/grpc_ingress.yaml",  // Ingress resource template for GRCP
              "service": "templates/service.yaml",            // Service resource template
              "deployment": "templates/deployment.yaml",      // Deployment resource template
              "pvc": "templates/pvc.yaml"                     // PVC resource template
            }
        }
    }
}
```

--------------------------------

### Start Cloud Environment Excluding Runtime

Source: https://github.com/rilldata/rill/blob/main/cli/cmd/devtool/README.md

Starts a cloud development environment but excludes the runtime service.

```bash
rill devtool start cloud --except runtime
```

--------------------------------

### Start Runtime Server

Source: https://github.com/rilldata/rill/blob/main/runtime/README.md

This command starts the Rill runtime server. It is typically run in a separate terminal when developing for a cloud environment.

```bash
go run ./cli runtime start
```

--------------------------------

### MCP Server Configuration Example

Source: https://context7.com/rilldata/rill/llms.txt

An example of a .mcp.json file generated by 'rill init --agent claude', which configures the MCP server for Rill.

```json
{
  "mcpServers": {
    "rill": { "url": "http://localhost:9009/mcp" }
  }
}
```

--------------------------------

### Start Cloud Development Environment

Source: https://github.com/rilldata/rill/blob/main/cli/cmd/devtool/README.md

Starts a cloud development environment. This command automatically refreshes the .env file and sets the CLI to 'dev' mode.

```bash
rill devtool start cloud
```

--------------------------------

### Full Metrics View Example

Source: https://github.com/rilldata/rill/blob/main/runtime/ai/instructions/data/resources/metrics_view.md

A comprehensive example of a metrics view configuration, including display metadata, data source, time series, dimensions, and measures.

```yaml
# metrics/orders.yaml
type: metrics_view

# Display metadata
display_name: Orders Analytics
description: Analyze order performance by various dimensions

# Data source - references the 'orders' model in the project
model: orders

# Time column for time-series charts and filtering
timeseries: order_date
smallest_time_grain: day

# Dimensions for grouping and filtering
dimensions:
  - name: order_date
    display_name: Order Date
    column: order_date

  - name: country
    display_name: Country
    column: shipping_country

  - name: product_category
    display_name: Product Category
    column: category
    description: High-level product grouping

  - name: customer_segment
    display_name: Customer Segment
    expression: |
      CASE
        WHEN lifetime_value > 1000 THEN 'High Value'
        WHEN lifetime_value > 100 THEN 'Medium Value'
        ELSE 'Low Value'
      END

  - name: is_repeat_customer
    display_name: Repeat Customer
    expression: CASE WHEN order_number > 1 THEN 'Yes' ELSE 'No' END

# Measures for aggregation
measures:
  - name: total_orders
    display_name: Total Orders
    expression: COUNT(*)
    format_preset: humanize

  - name: total_revenue
    display_name: Total Revenue
    expression: SUM(order_total)
    format_preset: currency_usd
    description: Gross revenue before refunds

  - name: average_order_value
    display_name: Avg Order Value
    expression: SUM(order_total) / NULLIF(COUNT(*), 0)
    format_preset: currency_usd
    valid_percent_of_total: false

  - name: unique_customers
    display_name: Unique Customers
    expression: COUNT(DISTINCT customer_id)
    format_preset: humanize

  - name: items_per_order
    display_name: Items per Order
    expression: SUM(item_count) / NULLIF(COUNT(*), 0)
    format_d3: ",.1f"
    valid_percent_of_total: false
```

--------------------------------

### Example HTTP URI

Source: https://github.com/rilldata/rill/blob/main/docs/docs/reference/project-files/sources.md

Use this format for web addresses of files.

```text
https://data.example.org/path/to/file.parquet
```

--------------------------------

### Druid Connection String (DSN) Example

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/connectors/olap/druid.md

Example of a Druid connection string (DSN) format for the DRUID_DSN environment variable. Special characters in user or password should be URL encoded.

```bash
DRUID_DSN="https://user:password@localhost:8888/druid/v2/sql"
```

--------------------------------

### Rill Provisioner Configuration Example

Source: https://github.com/rilldata/rill/blob/main/admin/provisioner/README.md

This JSON configuration defines named sets of provisioners. It shows examples for both 'static' and 'kubernetes' provisioner types, detailing their respective configuration parameters. Use this to set up multiple provisioner configurations, for instance, for different Kubernetes clusters.

```json
{
  "static-example":
    {
      "type": "static",
      "spec":
        {
          "runtimes":
            [
              {
                "host": "http://localhost:8081",          // Runtime host
                "slots": 50,                              // Amount of slots in the pre-provisioned runtime
                "data_dir": "/mnt/data",                  // Directory to use for data storage like DB files etc.
                "audience_url": "http://localhost:8081"   // Audience URL (JWT)
              }
            ]
        }
    },

  "kubernetes-example":
    {
      "type": "kubernetes",
      "spec":
        {
          "timeout_seconds": 30,                              // Maximum time to wait for the runtime to become ready
          "data_dir": "/mnt/data",                            // Directory to use for data storage like DB files etc.
          "host": "http://node-*.localhost",                  // The wildcard '*' will be replaced with the deployment's 'provision_id'
          "namespace": "cloud-runtime",                       // Namespace to use in the K8s cluster
          "image": "rilldata/rill",                           // Rill Docker image
          "kubeconfig_path": "kubeconfig.yaml",               // K8s config file to authenticate against the cluster
          "template_paths":
            {
              "http_ingress": "templates/http_ingress.yaml",  // Ingress resource template for HTTP
              "grpc_ingress": "templates/grpc_ingress.yaml",  // Ingress resource template for GRCP
              "service": "templates/service.yaml",            // Service resource template
              "deployment": "templates/deployment.yaml",      // Deployment resource template
              "pvc": "templates/pvc.yaml"                     // PVC resource template
            }
        }
    }
}
```

--------------------------------

### Start Local Docs Development Server

Source: https://github.com/rilldata/rill/blob/main/docs/README.md

Starts the Docusaurus documentation server with hot reloading enabled for local development. Run this command from the root of the docs folder.

```bash
npm run dev
```

--------------------------------

### Install Ubuntu 22.04 LTS for WSL

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/get-started/install.md

Installs the Ubuntu 22.04 LTS distribution on Windows using WSL. This is a prerequisite for running Rill on Windows.

```powershell
wsl --install -d ubuntu-22.04
```

--------------------------------

### Build and Preview Production Docs

Source: https://github.com/rilldata/rill/blob/main/docs/README.md

Builds a production version of the documentation and starts a local server to preview it. Run these commands from the root of the docs folder.

```bash
npm run build
npm run preview
```

--------------------------------

### Rill Project File Structure Example

Source: https://github.com/rilldata/rill/blob/main/runtime/ai/instructions/data/development.md

An example listing of files for a small Rill project, illustrating the typical organization of configuration, connectors, models, metrics, and dashboards.

```plaintext
.env
connectors/duckdb.yaml
connectors/s3.yaml
models/events_raw.yaml
models/events.sql
metrics/events.yaml
dashboards/events.yaml
rill.yaml
```

--------------------------------

### Local Testing - GET Request

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/custom-apis/calling.md

Example of making a GET request to a custom API during local development.

```APIDOC
## Local Testing - GET Request

### Description
Tests a custom API locally using a GET request.

### Method
GET

### Endpoint
http://localhost:9009/v1/instances/default/api/my-api?domain=google.com
```

--------------------------------

### Start Rill Developer

Source: https://context7.com/rilldata/rill/llms.txt

Launch Rill Developer to start a local project and open the browser UI. Creates the project directory if it doesn't exist. Supports preview mode and passing environment variables.

```bash
# Create a new project and open the UI
rill start my-rill-project
```

```bash
# Start an existing project
rill start ./existing-project
```

```bash
# Dashboard-only preview mode (no file editor — useful when an AI agent handles code)
rill start my-project --preview
```

```bash
# Pass environment variables at start time
rill start my-project --env DB_HOST=localhost --env DB_PORT=5432
```

--------------------------------

### Install and Create Rill Token via CLI

Source: https://github.com/rilldata/rill/blob/main/docs/docs/guide/ai/mcp.md

Install the Rill CLI and then use it to issue a personal access token. This is an alternative to generating tokens via the Rill Cloud UI.

```bash
curl https://rill.sh | sh

# Create a token
rill token issue
```

--------------------------------

### Interval-Based Monitoring Example

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/alerts.md

An example demonstrating interval-based monitoring to validate metrics across multiple time periods. It checks hourly aggregates for the last 24 hours for zero event counts, running 5 minutes past each hour.

```yaml
# alerts/hourly_metrics.yaml
type: alert
display_name: Hourly Metrics Check
description: Validate metrics for each hour

refresh:
  cron: "5 * * * *"  # 5 minutes past each hour

intervals:
  duration: PT1H      # 1 hour intervals
  limit: 24           # Check last 24 intervals
  check_unclosed: false

data:
  sql: |
    SELECT *
    FROM hourly_aggregates
    WHERE hour_start = DATE_TRUNC('hour', NOW() - INTERVAL '1 hour')
      AND event_count = 0

notify:
  slack:
    channels:
      - "#monitoring"
```

--------------------------------

### Create a Service Account Key File

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/connectors/data-source/gcs.mdx

Create a JSON key file for the service account, which will be used for authentication. Replace `[PROJECT_ID]` with your project ID.

```bash
gcloud iam service-accounts keys create rill-service-account.json \
    --iam-account rill-service-account@[PROJECT_ID].iam.gserviceaccount.com
```

--------------------------------

### Install and Launch Rill Developer

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/get-started/quickstart.md

Installs Rill Developer and starts a new project. Assumes you are using the default embedded engine, DuckDB.

```bash
curl https://rill.sh | sh

```

```bash
rill start my-rill-project
```

--------------------------------

### GET Request with Query Parameters

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/custom-apis/calling.md

Example of making a GET request to a custom API using curl. Authentication is provided via a Bearer token in the Authorization header.

```bash
curl "https://api.rilldata.com/v1/organizations/<org>/projects/<project>/runtime/api/my-api?domain=google.com&limit=10" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Ordinal Expressions with Reference Points

Source: https://github.com/rilldata/rill/blob/main/docs/docs/reference/time-syntax/time-syntax.md

Examples of ordinal time expressions and their calculated start and end times relative to a watermark.

```text
W1
2025-04-28T00:00:00Z to 2025-05-05T00:00:00Z
```

```text
W1 as of -2M
2025-03-03T00:00:00Z to 2025-03-10T00:00:00Z
```

```text
D2 as of watermark/W
2025-05-13T00:00:00Z to 2025-05-14T00:00:00Z
```

```text
D2 as of -1W as of watermark/W
2025-05-06T00:00:00Z to 2025-05-07T00:00:00Z
```

```text
W2 as of -1M as of latest/M
2025-06-09T00:00:00Z to 2025-06-16T00:00:00Z
```

```text
W2 as of -1Q as of latest/Q
2025-04-07T00:00:00Z to 2025-04-14T00:00:00Z
```

```text
W2 as of -1Y as of 2024
2023-01-09T00:00:00Z to 2023-01-16T00:00:00Z
```

```text
M2 as of -2Q/Q as of watermark/Q
2024-11-01T00:00:00Z to 2024-12-01T00:00:00Z
```

```text
Q2 as of -2Y/Y as of watermark/Y
2023-04-01T00:00:00Z to 2023-07-01T00:00:00Z
```

--------------------------------

### Local Testing GET and POST Requests

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/custom-apis/calling.md

Examples for testing custom APIs locally using curl. Local development does not require authentication.

```bash
# GET request
curl "http://localhost:9009/v1/instances/default/api/my-api?domain=google.com"

# POST request
curl -X POST http://localhost:9009/v1/instances/default/api/my-api \
  -H "Content-Type: application/json" \
  -d '{"domain": "google.com"}'
```

--------------------------------

### Watermark Boundary Examples

Source: https://github.com/rilldata/rill/blob/main/docs/docs/reference/time-syntax/time-syntax.md

Demonstrates how 'as of watermark' expressions define time ranges relative to a specific 'watermark' timestamp, showing precise start and end times.

```rill
1h as of watermark/h
```

```rill
1h as of watermark/h+1h
```

```rill
1D as of watermark/D
```

```rill
1D as of watermark/D+1D
```

```rill
2D as of watermark/D
```

```rill
2D as of watermark/D+1D
```

```rill
2W as of watermark/W
```

--------------------------------

### Combine --debug and --verbose Flags

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/debugging/index.md

Combine both `--debug` and `--verbose` flags with `rill start` to get the most comprehensive debugging information, including detailed logs and additional diagnostic data.

```bash
rill start --debug --verbose
```

--------------------------------

### Install Rill

Source: https://context7.com/rilldata/rill/llms.txt

Install Rill on macOS/Linux using curl. Supports standard, nightly, and specific version installations. Homebrew installation is also available. Verify installation with `rill --help` and `rill version`. Upgrade with `rill upgrade` and uninstall with `rill uninstall`.

```bash
# Install on macOS / Linux
curl https://rill.sh | sh
```

```bash
# Install nightly (recommended for AI agents)
curl https://rill.sh | sh -s -- --nightly
```

```bash
# Install a specific version
curl https://rill.sh | sh -s -- --version v0.85.0
```

```bash
# Homebrew (macOS only)
brew install rilldata/tap/rill
```

```bash
# Verify installation
rill --help

```

```bash
rill version
```

```bash
# Upgrade
rill upgrade
```

```bash
# Uninstall
rill uninstall
```

--------------------------------

### Install Rill using Homebrew on macOS

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/get-started/install.md

Installs Rill Developer on macOS using Homebrew. Ensure you do not mix this with other installation methods.

```bash
brew install rilldata/tap/rill
```

--------------------------------

### Start Admin Service

Source: https://github.com/rilldata/rill/blob/main/admin/README.md

Separately start the admin service. This command can be used to start and stop the service when making code changes.

```bash
go run ./cli admin start
```

--------------------------------

### Install unzip package in WSL

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/get-started/install.md

Installs the 'unzip' package within your WSL Linux instance, which is required for Rill's curl installer.

```bash
sudo apt-get update
sudo apt-get install unzip
```

--------------------------------

### End-to-End Example: Multi-tenant API

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/custom-apis/security.md

Demonstrates building a multi-tenant API that serves different data to different customers based on token attributes.

```APIDOC
## End-to-end example: multi-tenant API

This walkthrough shows how to build an API that serves different data to different customers.

### Step 1: Create the API

Create `apis/customer-orders.yaml`:

```yaml
type: api
sql: |
  SELECT
    order_id,
    product_name,
    quantity,
    total_price,
    order_date
  FROM orders
  WHERE customer_id = '{{ .user.customer_id }}'
  ORDER BY order_date DESC
  LIMIT {{ default 50 .args.limit }}
  OFFSET {{ default 0 .args.offset }}
security:
  access: true
```

### Step 2: Create service tokens for each customer

```bash
# Token for Acme Corp
rill service create acme-api \
  --project my-project \
  --project-role viewer \
  --attributes '{"customer_id": "acme-corp"}'
# Returns: rill_svc_abc123...

# Token for Globex Inc
rill service create globex-api \
  --project my-project \
  --project-role viewer \
  --attributes '{"customer_id": "globex-inc"}'
# Returns: rill_svc_def456...
```

### Step 3: Call the API

**Acme sees only their orders:**
```bash
curl "https://api.rilldata.com/v1/organizations/my-org/projects/my-project/runtime/api/customer-orders" \
  -H "Authorization: Bearer rill_svc_abc123..."
```

```json
[
  {"order_id": "A-1001", "product_name": "Widget Pro", "quantity": 50, "total_price": 2500, "order_date": "2025-01-15"},
  {"order_id": "A-1002", "product_name": "Gadget Plus", "quantity": 25, "total_price": 1250, "order_date": "2025-01-14"}
]
```

**Globex sees only their orders:**
```bash
curl "https://api.rilldata.com/v1/organizations/my-org/projects/my-project/runtime/api/customer-orders" \
  -H "Authorization: Bearer rill_svc_def456..."
```

```json
[
  {"order_id": "G-2001", "product_name": "Sprocket X", "quantity": 100, "total_price": 5000, "order_date": "2025-01-16"},
  {"order_id": "G-2002", "product_name": "Bolt Kit", "quantity": 200, "total_price": 800, "order_date": "2025-01-13"}
]
```

Same API, same endpoint — different data based on the token's `customer_id` attribute.
```

--------------------------------

### Install Specific Rill Version

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/get-started/install.md

Installs a specific version of Rill Developer using the installation script. Replace `<insert_version_number>` with the desired version.

```bash
curl https://rill.sh | sh -s -- --version <insert_version_number>
```

--------------------------------

### Install Rill Developer using curl

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/get-started/install.md

Installs Rill Developer using the official installation script. This is the recommended method for macOS and Linux.

```bash
curl https://rill.sh | sh
```

--------------------------------

### Starting Rill with MCP Server

Source: https://context7.com/rilldata/rill/llms.txt

This command starts the Rill project with the MCP server enabled, which is typically auto-started with 'rill start'. The MCP server is accessible at http://localhost:9009/mcp.

```bash
rill start my-project --preview
```

--------------------------------

### SQL Partition Reference Example

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/models/partitioned-models.md

Demonstrates how to reference partition values in a model's SQL query using the `{{ .partition.<column_name> }}` syntax. This is useful when the partition column name differs from the desired reference name.

```yaml
partitions:
  sql: SELECT range AS num FROM range(0,10)
sql: SELECT {{ .partition.num }} AS num, now() AS inserted_on {{if dev}} limit 1000 {{end}}
```

--------------------------------

### Glob Partition URI Reference Example

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/models/partitioned-models.md

Shows how to use the predefined `{{ .partition.uri }}` reference within a model's SQL query when using glob partitioning. This allows direct access to the matched file path.

```yaml
partitions:
  glob:
    connector: gcs
    path: gs://path/to/file/**/*.parquet
sql: SELECT * FROM read_parquet('{{ .partition.uri }}')
```

--------------------------------

### Full API Example with OpenAPI

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/custom-apis/openapi.md

A complete API definition including OpenAPI documentation, templating, and security settings.

```yaml
type: api

metrics_sql: |
  SELECT publisher, domain, total_records, avg_bid_price
  FROM ad_bids_metrics
  WHERE domain = '{{ .args.domain }}'
  {{ if hasKey .args "publisher" }}
    AND publisher = '{{ .args.publisher }}'
  {{ end }}
  ORDER BY total_records DESC
  LIMIT {{ default 25 .args.limit }}
  OFFSET {{ default 0 .args.offset }}

security:
  access: true

openapi:
  summary: Query ad bid metrics by domain with optional publisher filter

  request_schema:
    type: object
    required:
      - domain
    properties:
      domain:
        type: string
        description: Domain to filter metrics by (e.g., "google.com")
      publisher:
        type: string
        description: Optional publisher to filter by (e.g., "Facebook")
      limit:
        type: integer
        description: Max results to return (default 25, max 1000)
      offset:
        type: integer
        description: Pagination offset (default 0)

  response_schema:
    type: object
    properties:
      publisher:
        type: string
        description: Publisher name
      domain:
        type: string
        description: Domain name
      total_records:
        type: integer
        description: Total number of records
      avg_bid_price:
        type: number
        description: Average bid price in USD

```

--------------------------------

### Interactive Project Initialization with `rill init`

Source: https://github.com/rilldata/rill/blob/main/docs/blog/0.84.md

Use `rill init` to interactively set up a new Rill project. This command guides you through project naming, OLAP engine selection, and agent instruction configuration.

```bash
rill init
? Project name my-rill-project
? OLAP engine clickhouse
? Agent instructions claude
```

--------------------------------

### Verify Rill Installation

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/get-started/install.md

Checks if the Rill CLI is installed correctly by displaying available commands.

```bash
rill --help
```

--------------------------------

### Benchmark All Queries

Source: https://github.com/rilldata/rill/blob/main/runtime/queries/README.md

Run benchmarks for all queries in the runtime/queries directory. Ensure you are in the repo root when executing this command.

```bash
go test -bench=. -benchmem ./runtime/queries/...
```

--------------------------------

### Complete rill.yaml Example

Source: https://github.com/rilldata/rill/blob/main/runtime/ai/instructions/data/resources/rillyaml.md

A comprehensive rill.yaml file demonstrating common configurations including project metadata, default OLAP connector, mock users, environment variables, resource defaults, and path management.

```yaml
display_name: Sales Analytics
description: Sales performance dashboards with partner access controls

olap_connector: duckdb

# Non-sensitive environment variables
env:
  default_lookback: P30D
  data_bucket: gs://my-company-data

# Mock users for testing security policies locally
mock_users:
  - email: admin@mycompany.com
    name: Admin User
    admin: true
  - email: partner@external.com
    groups:
      - partners
  - email: viewer@mycompany.com
    tenant_id: xyz

# Project-wide defaults for models
models:
  refresh:
    cron: 0 0 * * *

# Project-wide defaults for metrics views
metrics_views:
  smallest_time_grain: day

# Project-wide defaults for explore dashboards
explores:
  defaults:
    time_range: P3M
  time_zones:
    - UTC
    - America/New_York
    - Europe/London
  time_ranges:
    - PT24H
    - P7D
    - P30D
    - P3M
    - P12M

# Exclude non-Rill files from parsing
ignore_paths:
  - /docs
```

--------------------------------

### Show Deployment Command Syntax

Source: https://github.com/rilldata/rill/blob/main/docs/docs/reference/cli/project/deployment/show.md

Use this command to display details of a project deployment. Specify the project name and the branch for which to show deployment details.

```bash
rill project deployment show [<project>] <branch> [flags]
```

--------------------------------

### Dimension Filter Examples

Source: https://github.com/rilldata/rill/blob/main/web-common/src/features/dashboards/url-state/filters/README.md

Examples of simple dimension filters using IN, NOT IN, and equality operators. These can be combined with AND and OR logic.

```sql
country IN ('US','IN') AND state = 'ABC'
```

```sql
country NOT IN ('US','IN') AND (state = 'ABC' OR lat >= 12.56)
```

--------------------------------

### Build Rill CLI (Production)

Source: https://github.com/rilldata/rill/blob/main/cli/README.md

Builds the Rill CLI binary for production. Embeds the SPA and examples. Outputs the binary to ./rill.

```bash
# Build the binary and output it to ./rill
make
```

```bash
# To output usage:
./rill
```

```bash
# To run start:
./rill start dev-project
```

--------------------------------

### Install Nightly Rill Build

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/get-started/install.md

Installs the latest nightly build of Rill Developer. Use with caution as these are not production-ready.

```bash
curl https://rill.sh | sh -s -- --nightly
```

--------------------------------

### List Services with Global Flags

Source: https://github.com/rilldata/rill/blob/main/docs/docs/reference/cli/service/list.md

Demonstrates using global flags for authentication, output format, and interactivity when listing services.

```bash
rill service list --api-token "<your-token>" --format json --org "<your-org>"
```

--------------------------------

### Rill Start CLI Flags

Source: https://github.com/rilldata/rill/blob/main/docs/docs/reference/cli/start.md

Configure environment variables, data ingestion, and runtime behavior for the 'rill start' command.

```bash
  -e, --env strings               Set environment variables
```

```bash
      --environment string        Environment name (default "dev")
```

```bash
      --reset                     Clear and re-ingest source data
```

```bash
      --pull-env                  Pull environment variables from Rill Cloud before starting the project (default true)
```

```bash
      --no-open                   Do not open browser
```

```bash
      --verbose                   Sets the log level to debug
```

```bash
      --preview                   Start in dashboard-only view (no code editor)
```

```bash
      --port int                  Port for HTTP (default 9009)
```

```bash
      --port-grpc int             Port for gRPC (internal) (default 49009)
```

```bash
      --no-ui                     Serve only the backend
```

```bash
      --debug                     Collect additional debug info
```

```bash
      --log-format string         Log format (options: "console", "json") (default "console")
```

```bash
      --tls-cert string           Path to TLS certificate
```

```bash
      --tls-key string            Path to TLS key file
```

```bash
      --allowed-origins strings   Override allowed origins for CORS
```

--------------------------------

### Define a Basic SQL API

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/build/custom-apis/index.md

Create a YAML file in the `apis/` directory to define a custom API. This example shows a simple SQL query to retrieve the top 10 publishers and their record counts.

```yaml
type: api
sql: |
  SELECT publisher, COUNT(*) as total_records
  FROM ad_bids
  GROUP BY publisher
  ORDER BY total_records DESC
  LIMIT 10
```

--------------------------------

### DuckDB Pre/Post Execution SQL Example

Source: https://github.com/rilldata/rill/blob/main/docs/docs/reference/project-files/models.md

Demonstrates the use of `pre_exec` and `post_exec` for managing DuckDB connections and queries. Ensure `pre_exec` queries are idempotent and use `IF NOT EXISTS` when applicable. Similarly, ensure `post_exec` queries are idempotent and use `IF EXISTS` when applicable.

```yaml
pre_exec: ATTACH IF NOT EXISTS 'dbname=postgres host=localhost port=5432 user=postgres password=postgres' AS postgres_db (TYPE POSTGRES);
sql: SELECT * FROM postgres_query('postgres_db', 'SELECT * FROM USERS')
post_exec: DETACH DATABASE IF EXISTS postgres_db
```

--------------------------------

### Rill Start with Environment Variables

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/tutorials/rill-clickhouse/2-r_ch_connect.md

Starts the Rill process while passing environment variables for host and port. These can then be referenced in the YAML configuration.

```bash
rill start --env host='localhost' --env  port='9000'
```

--------------------------------

### Measure Filter Example

Source: https://github.com/rilldata/rill/blob/main/web-common/src/features/dashboards/url-state/filters/README.md

An example of a measure filter using the NIN (Not In) operator and a HAVING clause to filter based on a measure's value.

```sql
country NIN ('US','IN') and state having (lat >= 12.56)
```

--------------------------------

### AI Agent Prompt: Create Model

Source: https://github.com/rilldata/rill/blob/main/docs/docs/developers/get-started/ai-quickstart.md

Ask the AI agent to create a data model. This example includes filtering null bids and adding a 'bid_bucket' column.

```bash
> "Create a model that cleans the auction data — filter out null bids and add a `bid_bucket` column that groups bids into $0-1, $1-5, $5-10, and $10+ ranges"
```

--------------------------------

### Install Rill Developer Nightly Build

Source: https://github.com/rilldata/rill/blob/main/docs/blog/0.10.md

Use this command to install the latest nightly build of Rill Developer. This script supports switching between production and nightly versions. Note that M1 Mac users may be prompted to install an x64 build using Rosetta 2.

```bash
curl -s https://cdn.rilldata.com/install.sh | bash -s -- --nightly
```