Skip to main content

Architecture and capabilities

MotherDuck is a serverless cloud data warehouse built on DuckDB. Its hypertenancy architecture gives every user, service account, or agent a dedicated compute instance, so queries stay fast and isolated with no clusters or warehouses to manage.

MotherDuck has four main components:

  • The MotherDuck cloud service, which stores your data and runs DuckDB in the cloud
  • MotherDuck's DuckDB SDK, which connects any DuckDB client to MotherDuck
  • Dual Execution, which splits each query between your local DuckDB and the cloud
  • The MotherDuck web UI, for querying, exploring, and administering your data

How MotherDuck differs from a traditional data warehouse​

MotherDuck inherits its engine from DuckDB, a fast in-process analytical database. Several DuckDB traits change how you think about running a data warehouse.

Every user gets dedicated compute. Each user, service account, or agent runs queries on its own Duckling, an isolated DuckDB instance on top of MotherDuck storage. One team's heavy query can't slow down another team's dashboard, which is a common problem in warehouses where everyone shares one cluster. Ducklings stay on warm standby, so they start in about 100 ms. See Hypertenancy.

Scale by adding Ducklings, not by queuing more work. DuckDB parallelizes each query across every core of the Duckling it runs on. Sending more queries at once to the same Duckling doesn't raise total throughput, because each query already uses all available resources. To serve more concurrent work, you give it more Ducklings, for example with read scaling. See Workload scaling patterns.

Access is granted through shares. You give other users READ access by granting them a share of a database, not by granting privileges on each table. A share exposes the whole database by default. On Business and Enterprise plans, an include pattern limits it to the tables and views you name. Plan your database boundaries around who needs to see what. See Role-based access control and Table-level security.

Sharing is zero-copy. Storage and compute are separate, so each Duckling reads its own view of a database. A share is a read-only, zero-copy clone of a database. People who read a share see the owner's writes when the share updates, not the moment they're written. Many readers can query one share without copying data or competing with the writer.

The MotherDuck cloud service​

The MotherDuck cloud service stores structured data, runs SQL against it, and lets you share it with others.

Serverless execution model: you don't configure or start instances, clusters, or warehouses. You write and submit SQL, and MotherDuck handles the rest. Under the hood, MotherDuck runs DuckDB and speaks DuckDB's SQL dialect.

Managed storage: data you load into MotherDuck storage is durable, secure, and automatically optimized for performance. You work with it through the catalog and its logical objects: databases, schemas, tables, and views. MotherDuck also queries data outside its own storage, such as files on Amazon S3, HTTPS endpoints, or your laptop. See Storage lifecycle and management.

The service layer: MotherDuck provides identity, authorization, administration, and monitoring.

note

MotherDuck runs on AWS and Azure, in multiple regions in each. You choose a cloud and region when you create your organization, and an organization exists in a single cloud region. See Cloud regions for the full list of regions, the DuckDB versions each supports, pricing tiers, and regional details.

In the Asia Pacific regions (ap-northeast-1 and ap-southeast-2), AI functions are processed through a US-based endpoint rather than within the organization's own AWS region.

MotherDuck's DuckDB SDK​

If you use DuckDB in Python or the CLI, you connect to MotherDuck with one statement, ATTACH 'md:';. Your DuckDB instance then gets Dual Execution, sharing, secrets storage, better interoperability with S3, and cloud persistence.

Dual Execution​

When connected, your local DuckDB and MotherDuck work together as one distributed system, so you can query data wherever it lives. This query execution model, called Dual Execution, routes each stage of a query to the location where it runs most efficiently:

  • If a query reads data on your laptop, MotherDuck runs it in your local DuckDB instance.
  • If a query reads data in MotherDuck or cloud storage (S3, GCS, Azure, R2), MotherDuck runs it in the cloud, which connects to your storage provider directly. MotherDuck authenticates with cloud-stored or local secrets. See CREATE SECRET for details.
  • If a query joins data on your laptop with data in MotherDuck, MotherDuck plans the most efficient way to join the two.

The MotherDuck web UI​

Use MotherDuck's web UI to analyze and share data and to perform administrative tasks. The UI combines a lightweight notebook, a SQL IDE, and a data catalog. MotherDuck caches query results in an interactive results panel, so you can sort, filter, and pivot data without rerunning the query.

Summary of capabilities​

With MotherDuck you can:

  • Use serverless DuckDB in the cloud to store data and run DuckDB SQL
  • Load data into MotherDuck from your 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, the standard DuckDB CLI, or the standard DuckDB Python package
  • Share databases with your teammates
  • Securely save S3 credentials in MotherDuck

MotherDuck also connects to third-party tools through:

  • JDBC
  • Go
  • SQLAlchemy

Considerations and limitations​

MotherDuck doesn't support the full range of DuckDB SQL. If you need a specific feature, contact MotherDuck support.

MotherDuck doesn't support these DuckDB features:

  • Custom Python or native user-defined functions
  • Server-side attach of PostgreSQL, SQLite, and other databases
  • Custom or community extensions