> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evidence.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# MotherDuck

> Query your MotherDuck (cloud DuckDB) database directly from Evidence without syncing data.

The MotherDuck direct connector lets Evidence run queries live against a [MotherDuck](https://motherduck.com) database. It connects over MotherDuck's [Postgres-wire endpoint](https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/postgres-endpoint/) — the connection method MotherDuck recommends for applications and serverless environments — so no local DuckDB engine is involved.

<Note>
  This is the **direct** connector. It authenticates with a service token and queries your database live, so any table or view in it is available without a sync. You still write **DuckDB SQL** — the Postgres endpoint is only the transport.
</Note>

## Connecting

You'll create a MotherDuck access token, find your database name, then enter both in Evidence.

### Prerequisites

* A **MotherDuck account** with a **database** that holds the data you want Evidence to query.
* Permission to **create access tokens** in your MotherDuck organization.

### 1. Create an access token

Evidence authenticates with a MotherDuck **access token** rather than a username/password, which keeps the credential headless and scoped.

<Steps>
  <Step title="Open token settings">
    In the [MotherDuck UI](https://app.motherduck.com), open **Settings → Access Tokens**.
  </Step>

  <Step title="Create a read-scoped token">
    Click **Create token**, give it a name like `Evidence`, and choose a **read-scoped** token where possible (sufficient for querying). Copy the token value immediately — it's only shown once.
  </Step>
</Steps>

### 2. Find your database name

Your database name is the one shown in the MotherDuck UI's database explorer. This is what you enter as **Database** in Evidence.

<Note>
  MotherDuck's Postgres endpoint is region-specific. The connector defaults to `pg.us-east-1-aws.motherduck.com`; if your database lives in another region, override the **Host** field with that region's endpoint.
</Note>

### 3. Configure the connector in Evidence

<Steps>
  <Step title="Open the connectors page">
    Go to **Connectors** in the sidebar. In the **Warehouse** card at the top, select **MotherDuck**.
  </Step>

  <Step title="Enter connection details">
    Fill in the **Database** (your MotherDuck database name) and the **Service Token** you created. Leave **Host** at its default unless your database is in a non-us-east-1 region.
  </Step>

  <Step title="Test and save">
    Click **Test Connection**. Once it passes, click **Save**.
  </Step>
</Steps>

## Configuration reference

<Tabs>
  <Tab title="Studio">
    #### Credentials

    <ResponseField name="Service token" type="string" required>
      MotherDuck access (service) token. Sent as the password when connecting to the MotherDuck Postgres endpoint.
    </ResponseField>

    <ResponseField name="Database" type="string" required>
      MotherDuck database name to query.
    </ResponseField>

    <ResponseField name="Host" type="string">
      MotherDuck Postgres endpoint host. Region-specific; the default targets us-east-1. Override for other regions (e.g. pg.eu-west-1-aws.motherduck.com). Default: `"pg.us-east-1-aws.motherduck.com"`.
    </ResponseField>

    #### Visibility

    <ResponseField name="Schemas" type="string[]">
      Allowlist of schemas exposed to the editor and schema browser. Default: `[]`.
    </ResponseField>
  </Tab>

  <Tab title="CLI (connection.yaml)">
    ```yaml theme={null}
    type: motherduck
    token: your-motherduck-service-token
    database: my_database
    # schemas: [main, analytics]
    ```

    #### Credentials

    <ResponseField name="token" type="string" required>
      MotherDuck access (service) token. Sent as the password when connecting to the MotherDuck Postgres endpoint.
    </ResponseField>

    <ResponseField name="database" type="string" required>
      MotherDuck database name to query.
    </ResponseField>

    <ResponseField name="host" type="string">
      MotherDuck Postgres endpoint host. Region-specific; the default targets us-east-1. Override for other regions (e.g. pg.eu-west-1-aws.motherduck.com). Default: `"pg.us-east-1-aws.motherduck.com"`.
    </ResponseField>

    #### Visibility

    <ResponseField name="schemas" type="string[]">
      Allowlist of schemas exposed to the editor and schema browser. Default: `[]`.
    </ResponseField>
  </Tab>
</Tabs>

## SQL dialect

MotherDuck runs [DuckDB](https://duckdb.org) SQL (PostgreSQL-flavoured). A few things worth knowing when writing queries:

* Row limiting uses `LIMIT <n> [OFFSET <m>]`, and `GROUP BY ALL` groups by every non-aggregate select expression.
* Strings concatenate with `||`; use `ILIKE` for case-insensitive matches and `IS NOT DISTINCT FROM` for null-safe equality.
* Dates: `DATE_TRUNC('month', col)`, `col + INTERVAL 7 DAY`, `DATE_DIFF('day', start, end)`, `STRFTIME(col, '%Y-%m-%d')`.
* Lists and structs are first-class: `[1, 2, 3]`, `{'a': 1}`, `UNNEST(arr)` to expand, `LIST()`/`ARRAY_AGG()` to aggregate.

## Security Considerations

Evidence executes queries against your MotherDuck database. Take pragmatic steps to protect it against misuse, whether accidental or malicious.

1. Use a **read-scoped** access token rather than a read-write token where your workflow allows it.
2. Point Evidence at a database (or share) that exposes only the tables you intend to query.
3. Rotate the access token on a schedule.