motherduck tutorial

rilldata · royendo · Aug 1, 2025 · Aug 1, 2025 · Aug 7, 2025 · Aug 7, 2025
commit a7f31f288e0a9bbaa28ed430f796a5f9fe607e31
diff --git a/docs/docs/guides/rill-clickhouse/3-r_ch_metrics-view.md b/docs/docs/guides/rill-clickhouse/3-r_ch_metrics-view.md
@@ -1,15 +1,13 @@
 ---
-title: "3. Create Metrics View Dashboard in Rill"
-sidebar_label: "3. Create Metrics View Dashboard in Rill"
+title: "3. Create Metrics View in Rill"
+sidebar_label: "3. Create Metrics View in Rill"
 sidebar_position: 3
 hide_table_of_contents: false
 tags:
   - OLAP:ClickHouse
   - Tutorial
 ---
 
-## Create the Metrics View.
-
 If you noticed in the previous screenshot, we had a table called `uk_price_paid`. This is a dataset that is used in ClickHouse's Learning portal, so we thought it was fitting to go ahead and continue on this dataset.
 
 :::note

diff --git a/docs/docs/guides/rill-clickhouse/4-r_ch_dashboard.md b/docs/docs/guides/rill-clickhouse/4-r_ch_dashboard.md
@@ -8,9 +8,6 @@ tags:
   - Tutorial
 ---
 
-
-### Create the explore dashboard
-
 When you're ready, you can create the visualization on top of the metric layer. Let's select `Create Explore dashboard`. This will create a simple explore-dashboards/uk_price_paid_metrics_explore.yaml file that reads in all the dimensions and measures. For more information on the available key-pairs, please refer to the [reference documentation.](https://docs.rilldata.com/reference/project-files/explore-dashboards)
 
 ---

diff --git a/docs/docs/guides/rill-clickhouse/5-r_ch_deploy.md b/docs/docs/guides/rill-clickhouse/5-r_ch_deploy.md
@@ -9,21 +9,20 @@ tags:
 ---
 :::tip Rill Cloud Trial
 
-If this is the first time you have deployed a project onto Rill Cloud, you will automatically start your [Rill Cloud Trial] () upon deployment of your Rill project. Your trial will last for 30 days. Please refer [here] () for more information on the details of your trial.
+If this is the first time you have deployed a project onto Rill Cloud, you will automatically start your [Rill Cloud Trial](/other/FAQ#rill-cloud-trial) upon deployment of your Rill project. Your trial will last for 30 days. Please refer [here](/other/FAQ#rill-cloud-trial) for more information on the details of your trial.
 
 :::
 
 ## Deploy via the UI!
 
-Select the `Deploy to share` button in the top right corner of a dashboard.
+Select the `Deploy` button in the top right corner of a dashboard.
 
 <img src = '/img/tutorials/rill-basics/deploy-ui.gif' class='rounded-gif' />
 <br />
 
 Steps to deploy to Rill Cloud:
-1. Select the `Deploy to share` button.
-2. Select `continue` on the free trial [link to article of free trial explanation]
-    - If you have multiple organizations, please select Rill_Learn and `continue`.
+1. Select the `Deploy` button.
+2. Select `continue` on the [free trial UI](/other/account-management/billing#trial-plan).
 3. Select `continue` on user invites.
 4. You will be navigated to the /status page of your deployed project.
 

diff --git a/docs/docs/guides/rill-motherduck/1-r_md_launch.md b/docs/docs/guides/rill-motherduck/1-r_md_launch.md
@@ -15,12 +15,15 @@ You will need to [install Rill](https://docs.rilldata.com/home/install).
 curl https://rill.sh | sh
 ```
 
-You need access to either a [locally running ClickHouse Server](https://clickhouse.com/docs/en/install) or [ClickHouse Cloud](https://docs.rilldata.com/reference/olap-engines/clickhouse#connecting-to-clickhouse-cloud). We recommend using ClickHouse Cloud as this will make deploying to Rill Cloud easier. Please review the documentation, [here](https://docs.rilldata.com/reference/olap-engines/clickhouse).
+You need a MotherDuck token to connect to your MotherDuck database. 
+Check our MotherDuck's documentation on [how to generate an access token](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#authentication-using-an-access-token).
+
+
 :::
 ## Start Rill Developer
 
 ```yaml
-rill start my-rill-clickhouse
+rill start my-rill-motherduck
 ```
 
 After running the command, Rill Developer should automatically open in your default browser. If not, you can access it via the following url:

diff --git a/docs/docs/guides/rill-motherduck/2-r_md_connect.md b/docs/docs/guides/rill-motherduck/2-r_md_connect.md
@@ -7,134 +7,60 @@ tags:
   - OLAP:MotherDuck
   - Tutorial
 ---
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 
 ## Default OLAP connection and Connect to MotherDuck
 
 Within Rill you can set the default OLAP connection on the [project level](https://docs.rilldata.com/reference/project-files/rill-yaml) or the [dashboard level](https://docs.rilldata.com/reference/project-files/explore-dashboards). 
 For this course, we will set it up on the project level so all of our dashboards will be based on our MotherDuck table.
 
-:::tip
-You have two options for your MotherDuck server:
-1. Use a [local running MotherDuck server](https://MotherDuck.com/docs/en/install)
-2. Use [MotherDuck Cloud](https://MotherDuck.com/docs/en/cloud/overview)
-
-Depending what you choose, the contents of your connection will change and I recommend looking through [our MotherDuck documentation](https://docs.rilldata.com/reference/olap-engines/MotherDuck) for further information.
-
-:::
-
 ### Connect to MotherDuck
-We can create the MotherDuck connection by selection `+Add Data` > `MotherDuck` and fill in the components on the UI.
-
-<img src = '/img/tutorials/ch/MotherDuck-connector.png' class='rounded-gif' />
-<br />
-:::tip
-You can obtain the credentials from your MotherDuck Cloud account by clicking the `Connect` button in the left panel.:
-
-<img src = '/img/tutorials/ch/MotherDuck-cloud-credential.png' class='rounded-gif' />
-<br />
-```
-"https://<hostname>:<port>?username=<username>&password=<password>&secure=true&skip_verify=true"
-```
-
-:::
-Once this is created, a `MotherDuck.yaml` file will appear in the `connectors` folder and the following will be added to your rill.yaml.
-
-```yaml
-compiler: rillv1
-
-title: "Rill and MotherDuck Project"
-olap_connector: MotherDuck #automatically added
-```
-
-Example for a locally running MotherDuck server:
-```yaml
-host: "localhost"
-port: "9000"
-```
-or 
-```yaml
-dsn: "MotherDuck://localhost:9000"
-```
+We can create the MotherDuck connection by modifying the connectors/duckdb.yaml.
 
 
- You can either add the credentials in plain text or dsn via the yaml file or add the credentials via the CLI.
-
-
-Please see our documentation to find the DSN for [your MotherDuck Cloud instance](https://docs.rilldata.com/reference/olap-engines/MotherDuck#connecting-to-MotherDuck-cloud). 
-
-### How to pass the credentials to Rill
-There are a few way to define the credentials within Rill.
-
-<Tabs>
-<TabItem value="yaml" label="via yaml" default>
-Please create a file called MotherDuck.yaml and add the following contents.
 ```yaml
 type: connector
-driver: MotherDuck
+driver: duckdb
 
-host: "localhost"
-port: "9000"
-```
-or 
-```yaml
-type: connector
-driver: MotherDuck
+path: "md:my_db"
 
-dsn: "MotherDuck://localhost:9000"
+init_sql: |
+  INSTALL 'motherduck';
+  LOAD 'motherduck';
+  SET motherduck_token= '{{.env.connector.motherduck.token}}'
 ```
 
+<img src = '/img/tutorials/md/MotherDuck-connector.png' class='rounded-gif' />
+<br />
 
+:::tip change the connector name
+While not necessary, I personally like to change the name to motherduck.yaml to make it clear which connector to use.
 
-</TabItem>
-<TabItem value="variable" label="via variables">
-Navigate back to the Terminal and stop the Rill process. You can run the following to add a variable and use this is within Rill.
-
-```
-rill start --env host='localhost' --env  port='9000'
-```
+:::
+### Rill Project Default
 
-Afterwards, create a file called MotherDuck.yaml and add the following contents:
+By default, we explicitly set the project OLAP_connector to duckdb. This is based on the connector.yaml name. If you make any changes to the filename, don't forget to change the name in your rill.yaml file.
 
 ```yaml
-type: connector
-driver: MotherDuck
+compiler: rillv1
 
-host: '{{ .env.host }}'
-port: '{{ .env.port }}'
+title: "Rill and MotherDuck Project"
+olap_connector: motherduck #default set to duckdb, only change if you modified the filename
 ```
 
+For more information, take a look at our [MotherDuck documentation](/reference/project-files/connectors#motherduck).
 
+### Securing Your MotherDuck Token
 
-  </TabItem>
-
-
-  <TabItem value="env" label="via .env">
-There's a few way to generate the .env file. Making a source that requires credentials will automatically generate it. Else, you can create it using `touch .env` in the rill directory.
-
-```yaml
-connector.MotherDuck.host="localhost"
-connector.MotherDuck.port=9000
-connector.MotherDuck.username 
-connector.MotherDuck.password 
-connector.MotherDuck.ssl 
+We do not recommend plain text passwords in the connector file, as you likely noticed in the sample YAML, and screenshot. To use the sample, you'll need to create a `.env` in the root directory and add the following:
 
-or
 
-connector.MotherDuck.dsn="..."
+```
+connector.motherduck.token="eyJhb....SAMPLETOKEN"
 ```
 
-  </TabItem>
-</Tabs>
-
-:::tip Via the UI
-
-If you connect to MotherDuck via the UI, this will automatically create a template with connectors/MotherDuck.yaml as well as a reference of your DSN to the .env folder. This will automatically get pushed along with your project to Rill Cloud. 
-
-:::
+## Confirm Connection to MotherDuck
 
-You should now be able to see the contents of your MotherDuck database in the left panel of your UI.
+You'll see a change in the bottom left connector that gives you a look into your MotherDuck tables. 
 
-<img src = '/img/tutorials/ch/olap-connector.png' class='rounded-gif' />
+<img src = '/img/tutorials/md/MotherDuck-confirm.png' class='rounded-gif' />
+<br />
diff --git a/docs/docs/guides/rill-motherduck/3-r_md_metrics-view.md b/docs/docs/guides/rill-motherduck/3-r_md_metrics-view.md
@@ -1,26 +1,24 @@
 ---
-title: "3. Create Metrics View Dashboard in Rill"
-sidebar_label: "3. Create Metrics View Dashboard in Rill"
+title: "3. Create Metrics View in Rill"
+sidebar_label: "3. Create Metrics View in Rill"
 sidebar_position: 3
 hide_table_of_contents: false
 tags:
   - OLAP:MotherDuck
   - Tutorial
 ---
 
-## Create the Metrics View.
-
-If you noticed in the previous screenshot, we had a table called `uk_price_paid`. This is a dataset that is used in MotherDuck's Learning portal, so we thought it was fitting to go ahead and continue on this dataset.
+You'll need to use a table that exists in your database. In this tutorial, we'll be using `rill_auction_data`.
 
 :::note
-In the case that you have not already added this table to your local or Cloud database, please follow the steps on [MotherDuck's site](https://MotherDuck.com/docs/en/getting-started/example-datasets/uk-price-paid) for the steps to do so!
+Don't have any good dataset to use? See [Ingest into MotherDuck](./r_md_ingest.md) to ingest directly into MotherDuck from Rill.
 :::
 
 ### Create metrics view
 
 Let's create a metrics view based on the table via the `Generate metrics via AI`.
 
-<img src = '/img/tutorials/ch/ai-generate.gif' class='rounded-gif' />
+<img src = '/img/tutorials/md/MotherDuck-metrics-ai.png' class='rounded-gif' />
 <br />
 
 ### What are we looking at?
@@ -35,10 +33,11 @@ This is our metrics view, where we can define measures and dimensions to be used
 version: 1
 type: metrics_view
 
-title: UK Price Paid Metrics
-connector: MotherDuck
-table: uk_price_paid
-timeseries: date
+display_name: Auction Data Raw Metrics
+connector: motherduck
+model: auction_data_raw
+timeseries: __time
+
 
 dimensions:
     ...

diff --git a/docs/docs/guides/rill-motherduck/4-r_md_dashboard.md b/docs/docs/guides/rill-motherduck/4-r_md_dashboard.md
@@ -8,32 +8,25 @@ tags:
   - Tutorial
 ---
 
-
-### Create the explore dashboard
-
-When you're ready, you can create the visualization on top of the metric layer. Let's select `Create Explore dashboard`. This will create a simple explore-dashboards/uk_price_paid_metrics_explore.yaml file that reads in all the dimensions and measures. For more information on the available key-pairs, please refer to the [reference documentation.](https://docs.rilldata.com/reference/project-files/explore-dashboards)
+When you're ready, you can create the visualization on top of the metric layer. Let's select `Create Explore dashboard`. This will create a simple dashboards/rill_auction_data_metrics_explore.yaml file that reads in all the dimensions and measures. For more information on the available key-pairs, please refer to the [reference documentation.](https://docs.rilldata.com/reference/project-files/explore-dashboards)
 
 ---
 
 ### What can we do in Rill?
-In our case, as we have generated this with AI, so we can look through the description of the populated measures for more information. Based on this, we can find some specific information on the UK properties dataset at a glance, such as:
 
-1. In 2023, What was the minimum/maximum detached property sold in London? [46.5K, 65.0M]
-2. In 2023, What was the average price of detached properties sold in London? How many? [2.5M, 981]
+Rill provides a powerful and intuitive slice-and-dice explore dashboard that transforms your raw data into actionable business decisions. With its analytical capabilities, you can drill down into specific dimensions, compare metrics across different segments, and uncover hidden patterns that drive informed decision-making. The interactive interface allows you to pivot, filter, and aggregate your data on-the-fly, giving you the flexibility to explore your MotherDuck tables from every possible angle and extract meaningful insights that can directly impact your business outcomes.
 
-
-<img src = '/img/tutorials/ch/2023-london.png' class='rounded-gif' />
+### [Compare dimension values](/explore/dashboard-101/)
+<img src = '/img/tutorials/md/MotherDuck-compare.png' class='rounded-gif' />
 <br />
 
-If we wanted to go further into details, we can even compare detached vs flat vs terraced properties using our compare feature. Based on the x-axis, we can drill down futher from the 2023 year into a specific month, week, or even day.
-
 
-<img src = '/img/tutorials/ch/2023-london-compare.png' class='rounded-gif' />
+### [Dig deeper into specific measures](/explore/dashboard-101/tdd)
+<img src = '/img/tutorials/md/MotherDuck-tdd.png' class='rounded-gif' />
 <br />
 
-Or, if you want to compare time periods 2022 to 2023's total transactions. In the below screenshot, we selected the Total Transactions metric and enable the time-compare feature to see the delta, delta percent of change from two time periods.
 
-<img src = '/img/tutorials/ch/time-compare.png' class='rounded-gif' />
+#### [View your data in a traditional pivot or flat table ](/explore/dashboard-101/pivot)
+<img src = '/img/tutorials/md/MotherDuck-pivot.png' class='rounded-gif' />
 <br />
 
-These are just a few examples of what we can do with Rill, the options expand further and are discussed further in [Rill Advanced](https://docs.rilldata.com/tutorials/rill_learn_200/201_0). If you're interested I recommended reviewing the contents after finishing up this course.
diff --git a/docs/docs/guides/rill-motherduck/5-r_md_deploy.md b/docs/docs/guides/rill-motherduck/5-r_md_deploy.md
@@ -9,34 +9,23 @@ tags:
 ---
 :::tip Rill Cloud Trial
 
-If this is the first time you have deployed a project onto Rill Cloud, you will automatically start your [Rill Cloud Trial] () upon deployment of your Rill project. Your trial will last for 30 days. Please refer [here] () for more information on the details of your trial.
+If this is the first time you have deployed a project onto Rill Cloud, you will automatically start your [Rill Cloud Trial](/other/FAQ#rill-cloud-trial) upon deployment of your Rill project. Your trial will last for 30 days. Please refer [here](/other/FAQ#rill-cloud-trial) for more information on the details of your trial.
 
 :::
 
 ## Deploy via the UI!
 
-Select the `Deploy to share` button in the top right corner of a dashboard.
+Select the `Deploy` button in the top right corner of a dashboard.
 
-<img src = '/img/tutorials/rill-basics/deploy-ui.gif' class='rounded-gif' />
+<img src = '/img/tutorials/md/MotherDuck-deploy.png' class='rounded-gif' />
 <br />
 
 Steps to deploy to Rill Cloud:
-1. Select the `Deploy to share` button.
-2. Select `continue` on the free trial [link to article of free trial explanation]
-    - If you have multiple organizations, please select Rill_Learn and `continue`.
+1. Select the `Deploy` button.
+2. Select `continue` on the [free trial UI](/other/account-management/billing#trial-plan).
 3. Select `continue` on user invites.
 4. You will be navigated to the /status page of your deployed project.
 
 
 Take note of the following features in the UI:
 <img src = '/img/tutorials/rill-basics/ui-explained.gif' class='rounded-gif' />
-
-## In case of the following error:
-
-```bash
-connection: dial tcp 127.0.0.1:9000: connect: connection refused
-```
-
-This is likely due to using a locally running MotherDuck server. If so, you will not be able to access your locally running server from Rill Cloud. Instead, we suggest using [MotherDuck Cloud](https://MotherDuck.com/cloud). 
-
-For steps to setup MotherDuck Cloud, please refer to [our documentation](https://docs.rilldata.com/reference/olap-engines/MotherDuck#connecting-to-MotherDuck-cloud).
diff --git a/docs/docs/guides/rill-motherduck/index.md b/docs/docs/guides/rill-motherduck/index.md
@@ -11,15 +11,26 @@ tags:
 <br />
 
 
-In this tutorial, we will discuss how to use MotherDuck as the default OLAP database with Rill to visualize your MotherDuck tables in as little as a few clicks. 
+
+
+In this tutorial, you'll learn how to use MotherDuck as your OLAP database with Rill to create powerful visualizations from your MotherDuck tables. Since both Rill and MotherDuck are built on DuckDB, they work seamlessly together, providing you with a smooth and efficient analytics experience.
+
+
 
 The overall steps of the tutorial are:
 1. Launch Rill Developer
-2. Connect to your MotherDuck server whether it is locally run or via MotherDuck Cloud
+2. Connect to your MotherDuck server via a Rill live connector.
 3. Create a metrics view based on a table in MotherDuck
 4. Create an explore dashboard via Generative AI
 5. Deploy the dashboard to Rill Cloud, and share to colleagues
 
 Once completed, you will have a basic understanding of how to use Rill Developer with MotherDuck and can customize the Rill Developer project to create further metrics views based on MotherDuck tables and create more dashboards. 
 
-### Let's get started!
+### Let's get started!
+
+:::tip Direct Ingestion into MotherDuck via Rill
+
+While we won't go over it directly in this tutorial, you can use Rill as an ingestor into MotherDuck. See the list of our [supported connectors](/build/connect) for more information.
+
+:::
+
-Original file line number
+Diff line change
@@ Expand Up / @@ -8,9 +8,6 @@ tags: @@
       - Tutorial
     ---
-    ### Create the explore dashboard
     When you're ready, you can create the visualization on top of the metric layer. Let's select `Create Explore dashboard`. This will create a simple explore-dashboards/uk_price_paid_metrics_explore.yaml file that reads in all the dimensions and measures. For more information on the available key-pairs, please refer to the [reference documentation.](https://docs.rilldata.com/reference/project-files/explore-dashboards)
     ---
@@ Expand Down @@