Rill

https://docs.rilldata.com
Admin
Rill is a data analysis and visualization platform for building fast, interactive dashboards by...
Tokens:248,346
Snippets:3,509
Trust Score:8.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and Start Rill Project

Source: https://docs.rilldata.com/

Use this command to install Rill and then start a new project. For alternative installation methods, consult the full installation guide.

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

```

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

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

### Clone and Start Rill Developer Example Project

Source: https://docs.rilldata.com/notes/page/71

Clone the example project from GitHub, navigate into the directory, and start the Rill application. This is the recommended way to try out Rill Developer.

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

```

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

### Install or Start Rill

Source: https://docs.rilldata.com/developers/deploy/deploy-dashboard/github-101

Run this command in your local repository's directory to install Rill. If Rill is already installed, this command will start the Rill development server.

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

```bash
rill start
```

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

### Start Rill with Environment Variables

Source: https://docs.rilldata.com/developers/tutorials/rill-clickhouse/r_ch_connect

Start the Rill process and pass connection details as environment variables.

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

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

### Complete Service Token Creation Example

Source: https://docs.rilldata.com/guide/administration/access-tokens/service-tokens

A comprehensive example demonstrating the creation of a service token for automated reporting, including organization, project, role, and custom attributes. The output shows the created service name and the access token.

```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"}'  
```

```text
Created service "reporting-service" in org "my-org".  
Access token: rill_svc_[TOKEN_HERE]  
```

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

### GET Request with Query Parameters

Source: https://docs.rilldata.com/developers/build/custom-apis/calling

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

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

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

### Complete Rill Project Configuration Example

Source: https://docs.rilldata.com/developers/build/project-configuration

A comprehensive `rill.yaml` example demonstrating various project configurations including OLAP connector, environment variables, model refresh settings, metrics view defaults, explore settings, canvas configurations, 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

```

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

### Navigate to Local Repository

Source: https://docs.rilldata.com/developers/deploy/deploy-dashboard/github-101

After cloning a repository, use this command in your terminal to navigate to the local copy of your project. This is necessary before running Rill installation or start commands.

```bash
cd Documents/GitHub/rill-poc/testrepo
```

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

### Local GET Request Testing

Source: https://docs.rilldata.com/developers/build/custom-apis/calling

Example of testing a custom API with a GET request during local development. Authentication is not required.

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

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

### Install Ubuntu 22.04 LTS on Windows with WSL

Source: https://docs.rilldata.com/developers/get-started/install

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

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

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

### Install Project Dependencies

Source: https://docs.rilldata.com/developers/tutorials/github-analytics

Install project dependencies using Poetry (recommended) or pip with a virtual environment. This ensures all necessary libraries like pandas and pydriller are available.

```bash
# Using Poetry (recommended)  
poetry install  
  
# Or using pip with venv  
python -m venv venv  
source venv/bin/activate  # On Windows: venv\Scripts\activate  
pip install pandas pydriller  

```

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

### GET Request with Query Parameters

Source: https://docs.rilldata.com/developers/build/custom-apis/calling

Example of making a GET request to a custom API using curl, including authorization and query parameters for filtering.

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

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

### Install Rill CLI and Issue Token

Source: https://docs.rilldata.com/guide/ai/mcp

Install the Rill CLI using curl and then issue a new token for authentication. This is a prerequisite for manual token management.

```bash
# Install the Rill CLI if you haven't already  
curl https://rill.sh | sh  
  
# Create a token  
rill token issue  
```

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

### Calling API with Multiple Query Parameters

Source: https://docs.rilldata.com/developers/build/custom-apis/templating

Example of calling the API with both domain and publisher specified as query parameters.

```bash
curl "http://localhost:9009/v1/instances/default/api/my-api?domain=google.com&publisher=Facebook"

```

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

### Rill Start Command Usage

Source: https://docs.rilldata.com/reference/cli/start

Basic syntax for the 'rill start' command. Specify a path to the project directory if it's not the current directory.

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

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

### Iframe Response Example: GetTheme

Source: https://docs.rilldata.com/developers/embed/postmessage

Example response from the iframe when `getTheme` is called, showing the applied theme name.

```json
{ "id": 5, "result": {"theme": "my-custom-theme"} }  

```

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

### MySQL DSN Examples with Special Characters

Source: https://docs.rilldata.com/reference/project-files/connectors

Examples of MySQL DSNs demonstrating how to handle special characters in the password using percent-encoding.

```text
mysql://user:pa%40ss@localhost:3306/my-db   # password contains '@'
mysql://user:pa%3Ass@localhost:3306/my-db   # password contains ':'
```

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

### Iframe Response Example: GetTheme (No Theme Set)

Source: https://docs.rilldata.com/developers/embed/postmessage

Example response from the iframe when `getTheme` is called and no custom theme is set, defaulting to 'default'.

```json
{ "id": 5, "result": {"theme": "default"} }  

```

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

### Calling API with No Parameters

Source: https://docs.rilldata.com/developers/build/custom-apis/templating

Example of calling the API without any parameters, returning all publishers.

```bash
curl "http://localhost:9009/v1/instances/default/api/my-api"

```

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

### Verify Rill Installation

Source: https://docs.rilldata.com/developers/get-started/install

Runs the Rill CLI help command to verify the installation succeeded. This will display a list of available commands.

```bash
rill --help  
```

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

### Calling API with Both Parameters

Source: https://docs.rilldata.com/developers/build/custom-apis/templating

Example of calling the API with both publisher and domain parameters to filter results.

```bash
curl "http://localhost:9009/v1/instances/default/api/my-api?publisher=Google&domain=news.google.com"

```

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

### Calling API with Query Parameter

Source: https://docs.rilldata.com/developers/build/custom-apis/templating

Example of how to call the API with a domain specified as a query parameter.

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

```

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

### Start Rill in Preview Mode

Source: https://docs.rilldata.com/developers/get-started/ai-quickstart

Launch Rill Developer in preview mode with `rill start --preview`. This provides a dashboard-only view while the AI agent manages code.

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

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

### Configure Slack Connector

Source: https://docs.rilldata.com/reference/project-files/connectors

Example configuration for the Slack connector. Requires a bot token for authentication.

```yaml
type: connector # Must be `connector` (required) 
driver: slack # Must be `slack` _(required)_
bot_token: "{{ .env.SLACK_BOT_TOKEN }}" # Bot token used for authenticating Slack API requests  

```

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

### Clone and Start OpenRTB Analytics Project

Source: https://docs.rilldata.com/developers/tutorials/openrtb-analytics

Clone the OpenRTB Analytics demo project from GitHub and start the Rill Developer server. Visit the provided URL to access the analytics dashboard.

```bash
# Clone the OpenRTB Analytics demo
git clone https://github.com/rilldata/rill-examples.git
cd rill-examples/rill-openrtb-prog-ads

# Start Rill Developer
rill start

```

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

### Start Rill Developer Server

Source: https://docs.rilldata.com/developers/tutorials/clone-a-project

Starts the Rill developer server, which includes initiating data source ingestion, building models and dashboards, and displaying errors or warnings.

```bash
# Start Rill Developer  
rill start  
```

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

### Full Example API with OpenAPI

Source: https://docs.rilldata.com/developers/build/custom-apis/openapi

A comprehensive example of a custom Rill API that includes metrics SQL, security settings, and a detailed OpenAPI specification with request and response schemas.

```APIDOC
## Full Example API with OpenAPI Documentation

### Description
This example demonstrates a complete custom Rill API definition, including SQL for metrics, security configuration, and a robust OpenAPI specification for documentation and client generation.

### OpenAPI Fields
- `openapi.summary`: Query ad bid metrics by domain with optional publisher filter
- `openapi.request_schema`: Defines the expected structure and types for incoming request parameters.
  - `type`: object
  - `required`: [domain]
  - `properties`:
    - `domain` (string): Domain to filter metrics by (e.g., "google.com")
    - `publisher` (string): Optional publisher to filter by (e.g., "Facebook")
    - `limit` (integer): Max results to return (default 25, max 1000)
    - `offset` (integer): Pagination offset (default 0)
- `openapi.response_schema`: Defines the structure and types for the API response.
  - `type`: object
  - `properties`:
    - `publisher` (string): Publisher name
    - `domain` (string): Domain name
    - `total_records` (integer): Total number of records
    - `avg_bid_price` (number): Average bid price in USD

### Example API Definition
```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
```
```

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

### Clone GitHub Analytics Project

Source: https://docs.rilldata.com/developers/tutorials/github-analytics

Clone the Rill examples repository to get started with the GitHub analytics project. Navigate into the project directory.

```bash
# Clone the GitHub Analytics project  
git clone https://github.com/rilldata/rill-examples.git  
cd rill-examples/rill-github-analytics  

```

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

### Calling API with POST Body

Source: https://docs.rilldata.com/developers/build/custom-apis/templating

Example of how to call the API with a domain specified in the POST request body.

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

```

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

### Start a Deployment by Branch

Source: https://docs.rilldata.com/reference/cli/project/deployment/start

Initiates a deployment for a given project and branch. Use this command to deploy specific branches of your project.

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

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

### Local Testing - GET Request

Source: https://docs.rilldata.com/developers/build/custom-apis/calling

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

```APIDOC
## Local Testing - GET Request
```curl
"http://localhost:9009/v1/instances/default/api/my-api?domain=google.com"
```
```

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

### Initialize a New Rill Project

Source: https://docs.rilldata.com/developers/get-started/ai-quickstart

Use `rill init` to create a new Rill project. The interactive setup prompts for project name, OLAP engine, and agent instructions.

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

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

### ISO 8601 Week Correction Example

Source: https://docs.rilldata.com/reference/time-syntax

Demonstrates ISO 8601 week rules where weeks start on Monday and week 1 contains the first Thursday. This example shows how the start of week 1 varies based on the boundary day.

```rilltime
W1 as of 2025-01-01T00:00:00Z
```

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

### Project Deployment Response Sample

Source: https://docs.rilldata.com/api/admin

This JSON response provides details about a project's deployment status and configuration. It includes information about the runtime environment and associated project.

```json
{
  "deployment": {
    "branch": "string",
    "createdOn": "2019-08-24T14:15:22Z",
    "editable": true,
    "environment": "string",
    "id": "string",
    "ownerUserId": "string",
    "projectId": "string",
    "runtimeHost": "string",
    "runtimeInstanceId": "string",
    "status": "DEPLOYMENT_STATUS_UNSPECIFIED",
    "statusMessage": "string",
    "updatedOn": "2019-08-24T14:15:22Z"
},
  "jwt": "string",
  "project": {
    "annotations": {
      "property1": "string",
      "property2": "string"
},
    "archiveAssetId": "string",
    "createdByUserId": "string",
    "createdOn": "2019-08-24T14:15:22Z",
    "description": "string",
    "devSlots": "string",
    "directoryName": "string",
    "frontendUrl": "string",
    "gitRemote": "string",
    "id": "string",
    "managedGitId": "string",
    "name": "string",
    "orgId": "string",
    "orgName": "string",
    "primaryBranch": "string",
    "primaryDeploymentId": "string",
    "prodSlots": "string",
    "prodTtlSeconds": "string",
    "prodVersion": "string",
    "provisioner": "string",
    "public": true,
    "subpath": "string",
    "updatedOn": "2019-08-24T14:15:22Z"
},
  "projectPermissions": {
    "admin": true,
    "createAlerts": true,
    "createBookmarks": true,
    "createMagicAuthTokens": true,
    "createReports": true,
    "manageAlerts": true,
    "manageBookmarks": true,
    "manageDev": true,
    "manageMagicAuthTokens": true,
    "manageProd": true,
    "manageProject": true,
    "manageProjectAdmins": true,
    "manageProjectMembers": true,
    "manageProvisionerResources": true,
    "manageReports": true,
    "readDev": true,
    "readDevStatus": true,
    "readProd": true,
    "readProdStatus": true,
    "readProject": true,
    "readProjectMembers": true,
    "readProvisionerResources": true
}

}
```

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

### Configure Postgres Connector with Individual Properties

Source: https://docs.rilldata.com/reference/project-files/connectors

Set up a PostgreSQL connection using individual properties. This example shows how to specify host, port, database name, user, password, and SSL mode.

```yaml
type: connector  
driver: postgres  
host: localhost  
port: 5432  
dbname: mydatabase  
user: myusername  
password: "{{ .env.POSTGRES_PASSWORD }}"  
sslmode: prefer  

```

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

### Using Glob Partition Reference

Source: https://docs.rilldata.com/developers/build/models/partitioned-models

Demonstrates using the `{{ .partition.uri }}` reference in a SQL query when using glob partitioning with a specified connector.

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

```

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

### Period-to-Date Interval Examples

Source: https://docs.rilldata.com/reference/time-syntax

Shows period-to-date intervals, which span from the start of the current period to the reference point, using the 'TD' suffix.

```markdown
Syntax| Expansion| Description  
---|---|---  
`sTD`| `ref/s to ref`| Current second  
`mTD`| `ref/m to ref`| Minute to date  
`hTD`| `ref/h to ref`| Hour to date  
`DTD`| `ref/D to ref`| Day to date (today so far)  
`WTD`| `ref/W to ref`| Week to date  
`MTD`| `ref/M to ref`| Month to date  
`QTD`| `ref/Q to ref`| Quarter to date  
`YTD`| `ref/Y to ref`| Year to date  

**Examples:**
Given `now = 2025-05-15T10:32:36Z`:

Expression| Start| End  
---|---|---  
`DTD`| `2025-05-15T00:00:00Z`| `2025-05-15T10:32:36Z`  
`MTD`| `2025-05-01T00:00:00Z`| `2025-05-15T10:32:36Z`  
`YTD`| `2025-01-01T00:00:00Z`| `2025-05-15T10:32:36Z`  
`MTD as of watermark`| `2025-05-01T00:00:00Z`| `2025-05-13T06:32:36Z`  

```

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

### Connect to a Sample Dataset

Source: https://docs.rilldata.com/developers/get-started/quickstart

Connects Rill to a sample dataset hosted on Google Cloud Storage for tutorial purposes. Rill automatically detects the schema, previews data, and analyzes patterns.

```bash
gs://rilldata-public/auction_data.parquet

```

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

### Initialize a New Rill Project Interactively

Source: https://docs.rilldata.com/notes/page/3

Use this command to start a new Rill project. It interactively prompts for project name, OLAP engine, and agent instructions.

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

```

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

### Fetch Results with Custom Page Size

Source: https://docs.rilldata.com/developers/build/custom-apis/templating

Example cURL command to fetch results with a custom limit and offset, allowing for a specific page size and starting point.

```bash
curl "http://localhost:9009/v1/instances/default/api/my-api?limit=10&offset=20"
```

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

### Watermark Boundary Examples

Source: https://docs.rilldata.com/reference/time-syntax

Demonstrates how time expressions resolve when the 'watermark' is exactly on a period boundary (e.g., midnight for day, start of week for week). This shows the effect of adding or not adding time units.

```rilltime
1h as of watermark/h
```

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

```rilltime
1D as of watermark/D
```

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

```rilltime
2D as of watermark/D
```

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

```rilltime
2W as of watermark/W
```

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

### Clone Cost Monitoring Analytics Project

Source: https://docs.rilldata.com/developers/tutorials/cost-monitoring-analytics

Clone the demo project from GitHub and navigate to its directory. This sets up the project locally for further exploration.

```bash
# Clone the Cost Monitoring Analytics project  
git clone https://github.com/rilldata/rill-examples.git  
cd rill-examples/rill-cost-monitoring  

```

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

### Quick Install Rill

Source: https://docs.rilldata.com/developers/get-started/install

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

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

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

### Install unzip package in WSL

Source: https://docs.rilldata.com/developers/get-started/install

Installs the 'unzip' package within your WSL Linux instance. This is required before running the Rill curl installer.

```bash
sudo apt-get update  
```

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

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

### Project-Level AI Instructions and Visualization Tips

Source: https://docs.rilldata.com/developers/build/ai-configuration

Add instructions to your `rill.yaml` file to guide AI in presenting data effectively. These instructions affect both Rill Chat and external AI clients via the MCP Server. For client-specific visualization tips, consider configuring them in client-specific files.

```yaml
ai_instructions: |
  # Visualization Guidelines
  - When presenting time series data, use sparklines or trend indicators (e.g. 📈/📉) to show direction.
  - For comparisons, clearly state the percentage change and absolute difference.
  - Use bar charts for categorical comparisons when there are fewer than 10 categories.
  - When showing tables, always include a header row and align numeric columns to the right.
    
  # Example Formatting
  - Bar Charts using block characters:
    Q1 ████████░░ 411
    Q2 ██████████ 514
    Q3 ██████░░░░ 300
    Q4 ████████░░ 400
  
  - Horizontal progress bars: Project Progress:
    Frontend ▓▓▓▓▓▓▓▓░░ 80%
    Backend ▓▓▓▓▓▓░░░░ 60%
    Testing ▓▓░░░░░░░░ 20%
    
  - Using different block densities: Trends:
    Jan ▁▂▃▄▅▆▇█ High
    Feb ▁▂▃▄▅░░░ Medium
    Mar ▁▂░░░░░░ Low
      
  - Sparklines with Unicode Basic sparklines:
    Stock prices: ▁▂▃▅▂▇▆▃▅▇
    Website traffic: ▁▁▂▃▅▄▆▇▆▅▄▂▁
    CPU usage: ▂▄▆█▇▅▃▂▄▆█▇▄▂
      
  - Trend indicators:
    AAPL ▲ +2.3%
    GOOG ▼ -1.2%
    MSFT ► +0.5%
    TSLA ▼ -3.1%
    
  - Simple trend arrows:
    Sales ↗️ (+15%)
    Costs ↘️ (-8%)
    Profit ⤴️ (+28%)

```

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

### Install Specific Rill Version

Source: https://docs.rilldata.com/developers/get-started/install

Installs a specific version of Rill Developer using the installation script. Replace `<insert_version_number>` with the desired version, e.g., `v0.40.1`.

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

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

### Define a Basic SQL API

Source: https://docs.rilldata.com/developers/build/custom-apis

Create a YAML file in the `apis/` directory to define a custom API. This example defines an API that returns the top 10 publishers by record count.

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

```

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

### Iframe Response Example: Success

Source: https://docs.rilldata.com/developers/embed/postmessage

Example of a successful response from the iframe for a request that included an ID.

```json
{ "id": 1, "result": true }  

```

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

### List Projects

Source: https://docs.rilldata.com/reference/cli/project/list

Use this command to list all projects. You can specify flags to control pagination and output format.

```bash
rill project list [flags]
```

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

### Example of Less Clear Test Naming

Source: https://docs.rilldata.com/developers/build/models/data-quality-tests

Shows examples of test names that are too generic and lack clarity.

```yaml
# Less clear names
- name: Test 1
- name: Check Data
- name: Validation
```

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

### Initialize Rill Project with AI Agent Templates

Source: https://docs.rilldata.com/developers/build/ide

Use `rill init` with specific templates to add instructions for AI coding agents like Claude Code or Cursor to your project.

```bash
rill init --template claude
```

```bash
rill init --template cursor
```

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

### Start a New Rill Project

Source: https://docs.rilldata.com/developers/tutorials/rill-basics/launch

Initiate a new Rill project with a specified name. This command sets up the basic project structure.

```bash
rill start my-rill-tutorial  
```

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

### Interactive Rill Project Initialization

Source: https://docs.rilldata.com/reference/cli/init

Run `rill init` without any arguments to start an interactive session. You will be prompted to provide all necessary details for your new Rill project.

```bash
rill init
```

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

### Iframe Response Example: GetThemeMode

Source: https://docs.rilldata.com/developers/embed/postmessage

Example response from the iframe when `getThemeMode` is called, indicating the current theme mode.

```json
{ "id": 3, "result": {"themeMode": "light"} }  

```

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

### Create Service Account Key File using gcloud CLI

Source: https://docs.rilldata.com/developers/build/connectors/data-source/gcs

Create a JSON key file for the service account. 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
```

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

### Iframe Response Example: GetState

Source: https://docs.rilldata.com/developers/embed/postmessage

Example response from the iframe when `getState` is called, containing the current dashboard state.

```json
{ "id": 2, "result": { "state": "view=pivot&tr=PT24H&grain=hour" } }  

```

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

### Initialize Google Cloud CLI

Source: https://docs.rilldata.com/developers/build/connectors/data-source/bigquery

Run this command to initialize and authenticate your local Google Cloud CLI for local development purposes.

```bash
gcloud init  

```

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

### Assert Test Examples

Source: https://docs.rilldata.com/developers/build/models/data-quality-tests

Examples of assert tests for checking null values, range validation, value constraints, and multiple conditions.

```yaml
tests:  
  # Check for null values  
  - name: No Null Campaign ID  
    assert: campaign_id IS NOT NULL  
  
  # Range validation  
  - name: Valid Bid Price  
    assert: bid_price >= 0 AND bid_price <= 100  
  
  # Value constraints  
  - name: Valid Ad Status  
    assert: status IN ('active', 'paused', 'completed', 'draft')  
  
  # Multiple conditions  
  - name: Valid Impression Count  
    assert: impressions >= 0 AND impressions <= 1000000000  

```

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

### Configure Leaderboard Widget

Source: https://docs.rilldata.com/developers/build/dashboards/canvas-widgets/data

Set up a leaderboard to show ranked data, highlighting top performers. Specify the number of rows and dimensions to display.

```yaml
- leaderboard:
   measures:
     - requests
   metrics_view: auction_metrics
   num_rows: 7
   dimensions:
     - app_site_name

```

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

### Customize Time Configuration Parameters

Source: https://docs.rilldata.com/developers/build/metrics-view/time-series

Set custom parameters for the start of the year and the start of the week to define non-standard reporting periods.

```yaml
timeseries: transaction_date  
first_month_of_year: 7  # July start  
first_day_of_week: 2    # Monday start  

```

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

### ClickHouse Connector Configuration

Source: https://docs.rilldata.com/reference/project-files/connectors

Configure the ClickHouse connector with connection details, authentication, and SSL settings. This example shows how to provision a connector using the default provisioner and enable read-write mode.

```yaml
type: connector # Must be `connector` (required) 
driver: clickhouse # Must be `clickhouse` _(required)_
managed: false # Provision the connector using the default provisioner 
mode: "readwrite" # Enable model creation and table mutations 
username: "myusername" # Username for authentication 
password: "{{ .env.CLICKHOUSE_PASSWORD }}" # Password for authentication 
host: "localhost" # Hostname of the ClickHouse server 
port: 9000 # Port number of the ClickHouse server 
database: "mydatabase" # Name of the ClickHouse database 
ssl: true # Enable SSL for secure connection 
cluster: "mycluster" # Cluster name  

```

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

### Reference Point Examples

Source: https://docs.rilldata.com/reference/time-syntax

Illustrates how different reference points (now, watermark, latest, earliest) affect time range calculations, with specific examples.

```markdown
Given: `now = 2025-05-15T10:32:36Z`, `watermark = 2025-05-13T06:32:36Z`, `latest = 2025-05-14T06:32:36Z`

Expression| Start| End  
---|---|---  
`7D`| `2025-05-08T10:32:36Z`| `2025-05-15T10:32:36Z`  
`7D as of now`| `2025-05-08T10:32:36Z`| `2025-05-15T10:32:36Z`  
`7D as of watermark`| `2025-05-06T06:32:36Z`| `2025-05-13T06:32:36Z`  
`7D as of now/D`| `2025-05-08T00:00:00Z`| `2025-05-15T00:00:00Z`  
`7D as of watermark/H+1H`| `2025-05-06T07:00:00Z`| `2025-05-13T07:00:00Z`  

```

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

### Full API Example with OpenAPI

Source: https://docs.rilldata.com/developers/build/custom-apis/openapi

A complete API definition including OpenAPI documentation, templating, and security settings. It defines metrics, request parameters, and response schemas.

```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  

```

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

### rill user whitelist setup flags

Source: https://docs.rilldata.com/reference/cli/user/whitelist/setup

These flags allow you to specify the organization, project, and role for the whitelist setup. The role defaults to 'viewer'.

```bash
      --org string       Organization  
      --project string   Project name  
      --role string      Role of the user (default "viewer")  
```

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

### Install Rill Nightly Build

Source: https://docs.rilldata.com/reference/cli/upgrade

Use the `--nightly` flag to install the latest development build of Rill. This is useful for testing upcoming features.

```bash
--nightly          Install the latest nightly build  
```

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

### Staging Model Configuration with Multiple Connectors

Source: https://docs.rilldata.com/reference/project-files/models

Set up a staging model that reads from one connector (e.g., Snowflake), stages data temporarily (e.g., S3), and outputs to another (e.g., ClickHouse). This is useful for cross-connector data ingestion.

```yaml
type: model
connector: snowflake
# Use DuckDB to generate a range of days from 1st Jan to today
partitions:
    connector: duckdb
    sql: SELECT range as day FROM range(TIMESTAMPTZ '2024-01-01', now(), INTERVAL 1 DAY)
# Don't reload previously ingested partitions on every refresh
incremental: true
# Query Snowflake for all events belonging to the current partition
sql: SELECT * FROM events WHERE date_trunc('day', event_time) = '{{ .partition.day }}'
# Since ClickHouse can't ingest from Snowflake or vice versa, we use S3 as a temporary staging connector
stage:
    connector: s3
    path: s3://bucket/temp-data
# Produce the final output into ClickHouse, requires a clickhouse.yaml connector defined.
output:
    connector: clickhouse

```

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

### Install Rill CLI

Source: https://docs.rilldata.com/notes/page/85

Install the Rill CLI globally using npm. This command provides the `rill` command-line interface for interacting with Rill Developer.

```bash
npm install -g @rilldata/rill
```

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

### Create a Project Deployment

Source: https://docs.rilldata.com/reference/cli/project/deployment/create

Use this command to create a deployment for a specific branch. Specify the project name (optional), the branch name, and any relevant flags.

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

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

### SQL Test Examples

Source: https://docs.rilldata.com/developers/build/models/data-quality-tests

Examples of SQL tests for row count validation, aggregate validation, duplicate detection, referential integrity, and data completeness.

```yaml
tests:  
  # Row count validation  
  - name: Minimum Impression Count  
    sql: SELECT 'Too few impressions' WHERE (SELECT COUNT(*) FROM model) < 1000  
  
  # Aggregate validation  
  - name: Positive Total Spend  
    sql: SELECT 'Negative spend detected' WHERE (SELECT SUM(spend) FROM model) < 0  
  
  # Duplicate detection  
  - name: No Duplicate Impression IDs  
    sql: |
      SELECT impression_id, COUNT(*) as count  
      FROM model  
      GROUP BY impression_id  
      HAVING COUNT(*) > 1  
  
  # Referential integrity  
  - name: Valid Campaign References  
    sql: |
      SELECT i.campaign_id  
      FROM model i  
      LEFT JOIN campaigns c ON i.campaign_id = c.id  
      WHERE c.id IS NULL  
  
  # Data completeness  
  - name: All Expected Ad Formats Present  
    sql: |
      SELECT missing_format FROM (  
        VALUES ('banner'), ('video'), ('native')  
      ) AS expected(missing_format)  
      WHERE missing_format NOT IN (SELECT DISTINCT ad_format FROM model)  

```

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

### Initialize Rill Project with Different Agent Options

Source: https://docs.rilldata.com/developers/get-started/ai-quickstart

Initialize a Rill project specifying the AI agent. Options include 'cursor', 'agentsmd' for tool-agnostic format, or 'all' for multiple formats.

```bash
# Cursor rules  
rill init my-project --agent cursor  
  
# Tool-agnostic AGENTS.md format  
rill init my-project --agent agentsmd  
  
# All formats at once  
rill init my-project --agent all  
```

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

### Install Specific Rill Version

Source: https://docs.rilldata.com/reference/cli/upgrade

Specify a version number with the `--version` flag to install a particular release of Rill. Replace 'string' with the desired version.

```bash
--version string   Install a specific version of Rill  
```

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

### Show Project Details

Source: https://docs.rilldata.com/reference/cli/project/show

Displays details for a specified project. If no project name is provided, it defaults to the current project.

```bash
rill project show [<project-name>] [flags]
```

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

### Configure S3 Connector

Source: https://docs.rilldata.com/reference/project-files/connectors

Example configuration for connecting to an S3 bucket. Ensure AWS credentials are provided via environment variables.

```yaml
type: connector # Must be `connector` (required) 
driver: s3 # Must be `s3` _(required)_
aws_access_key_id: "{{ .env.AWS_ACCESS_KEY_ID }}" # AWS Access Key ID used for authentication 
aws_secret_access_key: "{{ .env.AWS_SECRET_ACCESS_KEY }}" # AWS Secret Access Key used for authentication 
aws_access_token: "{{ .env.AWS_ACCESS_TOKEN }}" # Optional AWS session token for temporary credentials 
endpoint: "https://my-s3-endpoint.com" # Optional custom endpoint URL for S3-compatible storage 
region: "us-east-1" # AWS region of the S3 bucket  

```

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

### Install Rill via Brew on macOS

Source: https://docs.rilldata.com/developers/get-started/install

Installs Rill on macOS using Homebrew. It's recommended to use only this method to avoid conflicts and manage upgrades.

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

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

### Install Nightly Rill Release

Source: https://docs.rilldata.com/developers/get-started/install

Installs the latest nightly build of Rill Developer on macOS and Linux. Use this for the most up-to-date version, but be aware it may not be production-ready.

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

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

### List Project Deployments Command

Source: https://docs.rilldata.com/reference/cli/project/deployment/list

Use this command to list all deployments for a given project. You can optionally specify the project name.

```bash
rill project deployment list [<project>] [flags]
```
Tokens:
Raw