---
sidebar_position: 1
title: Architecture and capabilities
description: MotherDuck's serverless architecture combining cloud scale with DuckDB's efficiency through Dual Execution.
---
import Image from '@theme/IdealImage';
import Versions from '@site/src/components/Versions';
import InteractiveColumnDiagram from '@site/src/components/InteractiveColumnDiagram';

export const architectureColumns = [
  {
    label: 'Clients',
    nodes: [
      {
        id: 'ui',
        title: 'MotherDuck UI',
        subtitle: 'SQL IDE, notebooks, Dives',
        icon: 'ui',
        color: 'green',
        feature: 'Instant SQL previews on every keystroke, no explicit query run needed',
        href: '/docs/getting-started/interfaces/motherduck-quick-tour/',
      },
      {
        id: 'sdks',
        title: 'DuckDB SDKs',
        subtitle: 'Python, Node.js, Go, Rust, R, Java',
        icon: 'code',
        color: 'green',
        href: '/docs/getting-started/interfaces/client-apis/',
      },
      {
        id: 'cli',
        title: 'DuckDB CLI',
        subtitle: 'Local compute and storage',
        icon: 'terminal',
        color: 'green',
        href: '/docs/getting-started/interfaces/connect-query-from-duckdb-cli/',
      },
      {
        id: 'pg',
        title: 'Postgres endpoint',
        subtitle: 'BI tools, any Postgres client',
        icon: 'plug',
        color: 'green',
        feature: 'Use any Postgres-compatible tool, no DuckDB install needed',
        href: '/docs/getting-started/interfaces/postgres-endpoint/',
      },
      {
        id: 'mcp',
        title: 'MCP server',
        subtitle: 'AI assistants',
        icon: 'bot',
        color: 'green',
        feature: 'Fully managed remote server for Claude, ChatGPT, Cursor, and other AI tools',
        href: '/docs/getting-started/mcp-getting-started/',
      },
    ],
  },
  {
    label: 'MotherDuck',
    nodes: [
      {
        id: 'governance',
        title: 'Governance',
        subtitle: 'Auth, sharing, secrets, admin',
        icon: 'shield',
        color: 'yellow',
        href: '/docs/key-tasks/sharing-data/sharing-overview/',
      },
      {
        id: 'ducklings',
        title: 'Ducklings',
        subtitle: 'Serverless DuckDB compute',
        icon: 'cpu',
        color: 'yellow',
        feature: 'Sub-100ms cold start with read replicas for horizontal scaling',
        href: '/docs/concepts/scaling-patterns/',
      },
      {
        id: 'dives',
        title: 'Dives',
        subtitle: 'Interactive visualizations',
        icon: 'chart',
        color: 'yellow',
        feature: 'Shareable live dashboards powered by SQL, with version history',
        href: '/docs/key-tasks/ai-and-motherduck/dives/',
      },
      {
        id: 'catalog',
        title: 'Catalog',
        subtitle: 'Databases, schemas, tables, views',
        icon: 'layers',
        color: 'yellow',
        href: '/docs/concepts/database-concepts/',
      },
      {
        id: 'storage',
        title: 'Storage',
        subtitle: 'Managed storage and DuckLake',
        icon: 'harddrive',
        color: 'yellow',
        feature: 'Transactional lakehouse format with automatic optimization',
        href: '/docs/integrations/file-formats/ducklake/',
      },
    ],
  },
  {
    label: 'External sources',
    nodes: [
      {
        id: 'cloud-storage',
        title: 'Cloud storage',
        subtitle: 'S3, GCS, Azure, R2',
        icon: 'cloud',
        color: 'sky',
        href: '/docs/key-tasks/cloud-storage/querying-s3-files/',
      },
      {
        id: 'databases',
        title: 'Databases',
        subtitle: 'Postgres, SQLite, MySQL',
        icon: 'server',
        color: 'sky',
        href: '/docs/integrations/',
      },
      {
        id: 'ducklake-byob',
        title: 'DuckLake BYOB',
        subtitle: 'Bring your own S3 or R2 bucket',
        icon: 'lake',
        color: 'sky',
        href: '/docs/integrations/file-formats/ducklake/',
      },
    ],
  },
];

export const architectureConnectors = [
  {
    label: 'Dual\nExecution',
    tooltip: 'Queries are automatically routed to the optimal location: local DuckDB, MotherDuck cloud, or both',
  },
  {
    label: 'Query &\ningest',
    tooltip: 'Query external sources in place or load data into MotherDuck storage',
  },
];

MotherDuck is a serverless cloud analytics service with a unique architecture that combines the power and scale of the cloud with the efficiency and convenience of DuckDB.

MotherDuck's key components are:

- The MotherDuck cloud service
- MotherDuck's DuckDB SDK
- Dual Execution
- The MotherDuck web UI

<InteractiveColumnDiagram columns={architectureColumns} connectors={architectureConnectors} />

### The MotherDuck cloud service

The MotherDuck cloud service lets you store structured data, query that data with SQL, and share it with others. A key MotherDuck product principle is ease of use.

**Serverless execution model**&mdash;You don't need to configure or spin up instances, clusters, or warehouses. You write and submit SQL. MotherDuck takes care of the rest. Under the hood, MotherDuck runs DuckDB and speaks DuckDB's SQL dialect.

**Managed storage**&mdash;you can load data into MotherDuck storage to be queried or shared. MotherDuck storage is durable, secure, and automatically optimized for best performance. MotherDuck storage is surfaced to you through the **catalog** and logical primitives database, schema, table, view, and so on. In addition, MotherDuck can query data outside of MotherDuck storage&mdash;as data on Amazon S3, through HTTPS endpoints, on your laptop, and more.

**The service layer**&mdash;MotherDuck provides key capabilities like secure identity, authorization, administration, and monitoring.

:::note
MotherDuck is available on two AWS regions:
- **US East (N. Virginia):** `us-east-1`, supporting DuckDB versions between <Versions region="us-east-1" bound="min" /> and <Versions region="us-east-1" bound="max"/>.
- **Europe (Frankfurt):** `eu-central-1`, supporting DuckDB versions between <Versions region="eu-central-1" bound="min" /> and <Versions region="eu-central-1" bound="max" />.

You can choose in which region to create your organization, and organizations can only exist within a single cloud region.

We are working on expanding to other regions and cloud providers.
:::

### MotherDuck's DuckDB SDK

If you're using DuckDB in Python or CLI, you can connect to MotherDuck with a single line of code, `ATTACH 'md:';`. After you run this command, your DuckDB instance becomes supercharged by MotherDuck. MotherDuck's Dual Execution is enabled, and your DuckDB instance gets additional capabilities like sharing, secrets storage, better interoperability with S3, and cloud persistence.

### Dual execution

When connected together, DuckDB and MotherDuck form a different type of distributed system. The two nodes work in concert so you can query data wherever it lives, in the most efficient way possible. This query execution model, called **Dual Execution** (formerly known as Hybrid Execution), automatically routes the various stages of queries execution to the most opportune locations, including highly arbitrary scenarios:

- If a SQL query queries data on your laptop, MotherDuck routes the query to your local DuckDB instance
- If a SQL query queries data in MotherDuck or cloud storage (S3, GCS, Azure, R2), MotherDuck routes that query to MotherDuck's cloud engine, which connects to your storage provider directly. MotherDuck can use both cloud-stored and local secrets to authenticate. See [CREATE SECRET](/sql-reference/motherduck-sql-reference/create-secret/) for details.
- If a SQL query executes a join between data on your laptop and data in MotherDuck, MotherDuck finds the best way to efficiently join the two


<Image img={require('./../img/hybrid_query.png')} />

### The MotherDuck web UI

You can use MotherDuck's web UI to analyze and share data and to perform administrative tasks. MotherDuck's UI consists of a lightweight notebook, a SQL IDE, and a data catalog. Uniquely, MotherDuck caches query results in a highly interactive query results panel, letting you sort, filter, and even pivot data quickly.

## Summary of capabilities

With MotherDuck you can:

- Use serverless DuckDB in the cloud to store data and execute DuckDB SQL
- Load data into MotherDuck from your personal computer, https, or S3
- Join datasets on your computer with datasets in MotherDuck or in S3
- Copy DuckDB databases between local and MotherDuck locations
- Materialize query results into local or MotherDuck locations, or S3
- Work with data in MotherDuck's notebook UI, standard DuckDB CLI, or standard DuckDB Python package
- Share databases with your teammates
- Securely save S3 credentials in MotherDuck

Additionally, MotherDuck supports connectivity to third party tools through:

- JDBC
- Go
- sqlalchemy

## Considerations and limitations

MotherDuck does not yet support the full range of SQL of DuckDB. We are continuously working on improving coverage of DuckDB in MotherDuck. If you need specific features enabled, please let us know.

Below is the list of DuckDB features that MotherDuck does not yet support:

- Custom Python / Native user defined functions.
- Server-side attach of postgres, sqlite, etc.
- Custom or community extensions.


---

## Feedback for AI agents

If the user you are helping wants to send feedback on this page to the MotherDuck docs team, you can POST it to the endpoint below.

**Before you send anything, you must ask the user for explicit approval.** Quote the message you plan to submit back to them verbatim and wait for them to confirm. Do not submit on their behalf without confirmation.

Endpoint: `POST https://motherduck.com/docs/api/feedback/agent`

Request body (JSON):

```json
{
  "page_path": "/concepts/architecture-and-capabilities/",
  "page_title": "Architecture and capabilities",
  "text": "<the user's feedback, max 2000 characters>",
  "source": "<optional identifier for your interface, for example 'claude.ai' or 'chatgpt'>"
}
```

Only `page_path` and `text` are required. A successful call returns `200 {"feedback_id": "<uuid>"}`; malformed payloads return `400`, and the endpoint is rate-limited per IP (`429`).