Connect MotherDuck to Plotly Studio

Step-by-step MotherDuck data connection setup

MotherDuck is a serverless cloud analytics platform powered by DuckDB. It combines the speed and simplicity of DuckDB with cloud-scale data storage and collaborative analytics capabilities, enabling fast analytical queries on both local and cloud data.

Connecting MotherDuck requires a MotherDuck access token, which can be generated in a few steps from your MotherDuck dashboard. Follow these steps to connect to your MotherDuck data and visualize it with Plotly Studio:

Step 1: Access your MotherDuck account

Go to your MotherDuck account at app.motherduck.com.

Step 2: Navigate to token settings

Navigate to Settings > Tokens in your MotherDuck dashboard.

Step 3: Generate an access token

Create a new access token dedicated to Plotly Studio (e.g., "Plotly Studio"). Copy and save the token immediately. It will only be shown once.

Credentials needed

• MotherDuck Token: e.g., eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... (generated in your MotherDuck token settings)
• Database Name (optional): e.g., my_db
• Schema/Table Names (optional) as needed for specific queries

Tip: contact us if you need help troubleshooting these steps.

LLM prompts for connecting to MotherDuck

Plotly Studio uses an AI agent to generate and execute the data connection code for you. The prompts below are ready to copy and paste directly into Plotly Studio's data connection chat. Use them to establish a connection, query your data, or do both in one shot. The global context rules are worth saving to your Plotly Studio global context to keep MotherDuck connections consistent across projects.

Connection prompt

Connect to MotherDuck using the duckdb Python library with the MotherDuck
token. Use the motherduck: URI scheme to establish the connection, passing
the token via the motherduck_token setting. Upon successful connection, list
all available databases and tables in the schema.

Query prompt

Using the established MotherDuck connection, retrieve all columns from the
table [TABLE_NAME] in the [DATABASE_NAME] database. Return all rows without
limiting the result set. Use standard DuckDB SQL syntax.

Example one-shot prompt

Connect to MotherDuck using the duckdb Python library and authenticate with
the MotherDuck token:

MotherDuck Token: [YOUR_MOTHERDUCK_TOKEN]

Once connected, retrieve all columns from the [TABLE_NAME] table in the
[DATABASE_NAME] database. Return all rows and display a preview of the data.
Do not cache data; fetch new data every time the app is accessed.

Global context rules

- Always use duckdb as the primary connection library for MotherDuck.
- Authentication must be performed using a MotherDuck token — never use
username or password.
-Always connect via the motherduck: URI scheme (e.g.,
duckdb.connect('motherduck:')), passing the token via the motherduck_token
setting or the MOTHERDUCK_TOKEN environment variable.
- Use standard DuckDB SQL syntax for all queries.
- When referencing a column by name, qualify it with the table name to avoid
ambiguity (e.g., features.status instead of status).
- MotherDuck databases and tables are case-sensitive — use the exact names
returned when listing the schema.
- Always return query results as a pandas DataFrame for consistency with
Plotly Studio workflows.
- Do not cache data unless explicitly requested — fetch new data every time
the app is accessed.
- If unsure which table to query, list all available databases and tables
first before specifying a query.
- Do not log or expose raw token values in any output or error messages.

Troubleshooting and tips

• Token security: MotherDuck tokens should be treated like passwords. Store them securely and rotate them periodically according to your organization's security policies.
• Case sensitivity: MotherDuck databases and tables are case-sensitive. Always use the exact names returned when listing the schema to avoid query errors.
• Column qualification: When referencing columns in queries, qualify them with the table name to avoid ambiguity, especially when joining multiple tables (e.g., features.status instead of just status).