# Cube
> Cube is a semantic layer for building and visualizing data. It integrates with MotherDuck for dashboards, semantic models, and embedded analytics workflows.
## How it works with MotherDuck

Cube connects to MotherDuck through Cube's DuckDB data source. Use this setup when you want Cube's semantic layer, APIs, dashboards, or embedded analytics to query data that lives in MotherDuck.

## Prerequisites

- A Cube project, either self-hosted or in Cube Cloud.
- A MotherDuck service token or access token. For production deployments, use a dedicated service account token.
- The MotherDuck database and schema Cube should use for its models.

## Setup

### Manual setup

In a self-hosted Cube project, configure the DuckDB data source and pass the MotherDuck token to Cube:

```bash
CUBEJS_DB_TYPE=duckdb
CUBEJS_DB_DUCKDB_MOTHERDUCK_TOKEN=<motherduck_token>
```

Keep the token in your deployment secret manager rather than committing it to `.env`.

### Cube Cloud setup

In Cube Cloud, choose **DuckDB** when creating the database connection, then paste your MotherDuck token into the **MotherDuck Token** field.

![Cube Cloud DuckDB connection form with a MotherDuck Token field](./img/cube-cloud-motherduck-connection.webp)

Leave the MotherDuck token blank only when you are connecting Cube to a local DuckDB database instead of MotherDuck.

## Authentication and configuration

- Use a read/write token if Cube needs to create or refresh objects in MotherDuck. Use a read token for read-only dashboard workloads.
- Configure Cube's DuckDB schema setting if your Cube models should default to a specific MotherDuck schema.
- If your Cube deployment reads private files from object storage through DuckDB, configure those storage credentials in Cube separately from the MotherDuck token.

## Important notes

- Cube's DuckDB documentation includes S3, extension, and pre-aggregation settings. Those settings are Cube/DuckDB deployment details, not required for a basic MotherDuck connection.
- For production, keep the MotherDuck token out of connection strings and application logs.
- If you use Cube Cloud, allowlist the Cube Cloud IPs shown in the connection screen if your network policy requires it.

## Use cases

- Build a governed semantic layer on top of MotherDuck tables.
- Serve embedded analytics from Cube APIs while querying MotherDuck.
- Prototype dashboard models locally and move the same Cube project to Cube Cloud.

## Related content

- [Read the Cube blog on DuckDB and MotherDuck integrations](https://cube.dev/blog/introducing-duckdb-and-motherduck-integrations)
- [View the full Cube DuckDB and MotherDuck setup guide](https://cube.dev/docs/product/configuration/data-sources/duckdb)
- [MotherDuck authentication](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `POST https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

Payload:

```json
{
  "page_path": "/integrations/bi-tools/cube/",
  "page_title": "Cube",
  "text": "<the user's feedback, max 2000 characters>",
  "source": "<optional identifier for your interface, for example 'claude.ai' or 'chatgpt'>"
}
```

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed payloads, and `429` when rate-limited.