Skip to content
M↓ View as Markdown ↗

MotherDuck

Connect a MotherDuck cloud database to Actian AI Analyst so you can build Models on its tables and let your AI Analysts query them.

Availability

  • Who can do this: members with the Edit capability in the active Workspace. If your organization turns on Restrict connection management, you also need the Manage organization capability.
  • Plan: available unless your organization's plan excludes the MotherDuck connector.
  • Deployment: Actian SaaS and self-managed deployments, unless the deployment's operator has turned the MotherDuck connector off.

What you need

  • A MotherDuck access token
  • The name of your MotherDuck database (the part after md:)

Read-only access

AI Analyst opens your MotherDuck database in read-only mode, so the database itself refuses writes. See Read-only access.

Network access

MotherDuck is a hosted service, so you do not add an inbound firewall rule on your side. On a self-managed deployment, the installation needs outbound access to MotherDuck. See Network access.

1. Get an access token from MotherDuck

  1. Sign in to your MotherDuck account.
  2. Go to Settings → Integrations → Access Tokens.
  3. Click Create Access Token.
  4. Copy the generated token. You paste it into AI Analyst in the next step.

Warning

Treat the token like a password.

2. Set up the connection in AI Analyst

  1. In Studio, open Connections and click the plus button (Add connection).
  2. Under Warehouses, select MotherDuck.
  3. Under Connection details, enter a Name (for example, Marketing Analytics) and, optionally, a Description. Select Private to this Workspace if only the current Workspace should use the connection. See Connections and Workspaces.
  4. Under Credentials, fill in:
    • Database: the name of your MotherDuck database without the md: prefix. For example, if your database is md:my_database, enter my_database.
    • Access token: the token you copied from MotherDuck.
  5. Click Test connection.
  6. When the test succeeds, select the Schemas to expose for browsing and model authoring. The first schema is preselected.
  7. Click Save connection.

Note

  • Save connection stays unavailable until the test passes. A successful test is valid for five minutes, and changing a connection field resets it. If either happens, test again.
  • The access token is encrypted at rest and never shown again after you save.

Paste a connection string

Instead of typing each field, you can click Paste a connection string, paste a MotherDuck connection string, and click Fill the form:

md:my_database?motherduck_token=<token>

AI Analyst fills Database and Access token. Nothing is sent until you test the connection.

Troubleshooting

When a test fails, the form shows a short summary of the problem. Expand it to see the error that MotherDuck returned.

Symptom Likely cause What to do
The test fails with an authentication error The token is wrong, expired or revoked. Create a new token in MotherDuck and paste it again.
The test fails because the database is not found Database includes the md: prefix, or the name is misspelled. Enter the database name only, such as my_database.

For connections that already exist, see Manage connections and Data source health monitoring.

Next steps

Create Models on the tables you want to analyze (see Creating models) and add them to an AI Analyst (see Models).