# MotherDuck Documentation - Getting started > Getting started with MotherDuck serverless cloud data warehouse. Generated: 2026-09-04 MotherDuck is a serverless cloud data warehouse built on DuckDB. Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP. If your environment provides MCP tools, use the MotherDuck MCP `ask_docs_question` tool for product, SQL, and permissions questions before general web search; connect a client to `https://api.motherduck.com/mcp`. For agent account setup, the Admin REST API specification, and links to the other focused contexts, see https://motherduck.com/docs/llms-full.txt. This category is split into focused child contexts to stay within the context-size budget. ## Child contexts - [MotherDuck Tutorial full context](https://motherduck.com/docs/getting-started/e2e-tutorial/llms-full.txt): Complete end-to-end tutorial to get started with MotherDuck and DuckDB (5 pages; 27,137 bytes; ~6,774 tokens). [Index](https://motherduck.com/docs/getting-started/e2e-tutorial/llms.txt). - [Interfaces full context](https://motherduck.com/docs/getting-started/interfaces/llms-full.txt): MotherDuck Offers a variety of interfaces (APIs) for integration (21 pages; 67,391 bytes; ~16,817 tokens). [Index](https://motherduck.com/docs/getting-started/interfaces/llms.txt). - [Example Datasets full context](https://motherduck.com/docs/getting-started/sample-data-queries/llms-full.txt): A collections of open datasets and queries to get you started with DuckDB and MotherDuck (9 pages; 53,907 bytes; ~13,475 tokens). [Index](https://motherduck.com/docs/getting-started/sample-data-queries/llms.txt). ## Included documentation Source: https://motherduck.com/docs/getting-started/data-warehouse # Data Warehousing Overview > Learn to use MotherDuck as a Data Warehouse ## Introduction to MotherDuck for data warehousing MotherDuck is a serverless cloud data warehouse built on [DuckDB](https://duckdb.org/docs/sql/introduction). Its hypertenancy architecture gives every user, service account, or agent a dedicated compute instance that starts in under a second and bills per second, so your whole team, humans and agents alike, gets sub-second answers without the legacy warehouse bill or cluster tuning. On top of DuckDB's fast analytical engine, MotherDuck adds cloud storage, sharing, and collaboration, and fits the tools data and analytics engineers already use: AI-assisted SQL, dbt for transformations, and hybrid local-cloud processing. ![img_duck_stack](img/bi_tool.svg) MotherDuck integrates with popular data tools including [dltHub](/integrations/ingestion/dlt), [Estuary](https://docs.estuary.dev/reference/Connectors/materialization-connectors/motherduck/), [Fivetran](https://fivetran.com/docs/destinations/motherduck#motherduck), and [Airbyte](https://docs.airbyte.com/integrations/destinations/motherduck) for data ingestion, [dbt](/integrations/transformation/dbt) and [dbt Cloud](/integrations/transformation/dbt-cloud/) for transformations, [Tableau](/integrations/bi-tools/tableau/), [Power BI](/integrations/bi-tools/powerbi/), and [Looker](/integrations/bi-tools/looker/) for visualization, and [Airflow](https://airflow.apache.org/docs/) and [Dagster](https://docs.dagster.io/integrations/libraries/duckdb/using-duckdb-with-dagster) for orchestration. This enables teams to build data warehousing solutions using their existing tools. ## Data ingestion A quick way to get data into MotherDuck is using [ecosystem partners](/integrations/ingestion/) like [dltHub](/integrations/ingestion/dlt), [Estuary](https://docs.estuary.dev/reference/Connectors/materialization-connectors/motherduck/), [Fivetran](https://fivetran.com/docs/destinations/motherduck), and [Airbyte](https://docs.airbyte.com/integrations/destinations/motherduck). For scheduled ingest without external infrastructure, [Flights](/key-tasks/flights/) run Python pipelines natively on MotherDuck: see the guides on [ingesting S3 parquet files on a schedule](/key-tasks/flights/ingest-s3-parquet-files-on-a-schedule/) and [running a dlt ingest pipeline from a Flight](/key-tasks/flights/run-dlt-ingest-pipeline/). MotherDuck is very flexible with how to load your data: - **From data you have on your filesystem:** If you have CSVs, JSON files, or DuckDB databases sitting around, you can load them straight into your MotherDuck data warehouse. - **From a lakehouse on a cloud object store:** MotherDuck works with open table formats. Create and query [DuckLake](/concepts/ducklake) tables backed by your own object storage, or [attach an Iceberg REST catalog](/integrations/file-formats/apache-iceberg/) such as Databricks-managed Iceberg or Cloudflare R2 Data Catalog to read from and write back to Iceberg tables. DuckDB's abstractions for Secrets, Object Storage, and file formats also let you query raw parquet, CSV, and JSON files from object storage with only SQL. Though not as performant as MotherDuck's native storage layer, this lets you query your infrequently-accessed data directly from your data lake. - **Using Native APIs in many languages:** DuckDB supports numerous languages such as C++, Python, and Java, in addition to its own mostly Postgres-compatible SQL dialect. Using these languages, Data Engineers and Developers can integrate with MotherDuck without having to pick up yet-another-language. ### Best practices for programmatic loading The fastest way to load data is to load single tables in large batches, saturating the network connection between MotherDuck and the source data. DuckDB is incredibly good at handling both files and some kinds of in-memory objects, like Arrow dataframes. As an aside, Parquet files compress at 5-10x compared to CSV, which means you can get 5-10x more throughput by using Parquet files. Similarly, open table formats like Delta & Iceberg share those performance gains. On the other hand, small writes on multiple tables will lead to suboptimal performance. While MotherDuck does indeed offer [ACID compliance](https://duckdb.org/2024/09/25/changing-data-with-confidence-and-acid.html), it is not an OLTP system like Postgres! Significantly better performance can be achieved by using queues to batch writes to tables. While some latency is introduced with this methodology, the improvement in throughput should far outweigh the cost of doing small writes. Streaming workloads are better suited to be handled with queues in front of MotherDuck. ## Transforming data Once data is loaded into MotherDuck, it must be transformed into a model that matches the business purpose and needs. This can be done directly in MotherDuck using the powerful library of SQL functions offered by [DuckDB](https://duckdb.org/docs/sql/introduction.html). Many data engineers prefer to use data transformation tools like the open source [dbt Core](https://github.com/dbt-labs/dbt-core). You can connect [dbt Cloud](/integrations/transformation/dbt-cloud/) to MotherDuck through the Postgres endpoint using dbt's built-in Postgres adapter, or [run dbt transformations from a Flight](/key-tasks/flights/run-dbt-transformations-from-a-flight/) to schedule them inside MotherDuck. More details specifically about using dbt with MotherDuck can be read in the [blog on this topic](https://motherduck.com/blog/duckdb-dbt-e2e-data-engineering-project-part-2/). For more in-depth reading, the free **[DuckDB in Action eBook](https://motherduck.com/duckdb-book-brief/)** explores these concepts with real-world examples. ## Sharing data Once your data is loaded into MotherDuck and appropriately transformed for use by your analysts, you can make that data available using MotherDuck's [sharing capabilities](/key-tasks/sharing-data/sharing-overview/). Grant the Share to the Explorer role to make it available to every preset role in your organization. Queries run by Explorers use isolated compute and do not affect the data pipelines managed by Builders or Admins. ## Serving data analytics Do you want to serve reports or dashboards for your users? Connect [popular BI tools](/integrations/bi-tools/) like [Power BI](/integrations/bi-tools/powerbi/), [Tableau Cloud](/integrations/bi-tools/tableau/tableau-cloud/), and [Looker](/integrations/bi-tools/looker/) through the [Postgres endpoint](/getting-started/interfaces/postgres-endpoint/), which works with any client that speaks the PostgreSQL wire protocol. For internal dashboards, [Dives](/key-tasks/dives/) let you build interactive visualizations from natural language with an AI agent and share them with your team, no separate BI tool required. Agents are data consumers too. Connect AI assistants like Claude or Cursor through the [MotherDuck MCP Server](/sql-reference/mcp/), and use [Guides](/key-tasks/guides/), markdown documents with your metric definitions and query conventions, to keep agent answers accurate and consistent. ### Ducks all the way down: building data apps Because DuckDB is an extremely efficient SQL engine inside a ~20MB executable, you can also run it inside the web browser through [WASM](/sql-reference/wasm-client) to build highly interactive data apps and visualizations with near-zero latency. ## Scaling up & out for DWH use cases Furthermore, MotherDuck has a unique scaling model, of which there are four key concepts relevant for Data Warehousing. ### Vertical scaling Compute can scale up with larger DuckDB compute instances called Ducklings. MotherDuck offers 5 sizes: [Pulse, Standard, Jumbo, Mega, and Giga](/about-motherduck/billing/duckling-sizes/). Unlike other data warehouses, every Duckling (compute instance) is isolated from each other: one user's queries will not impact another user's from completing. This [hypertenancy](/concepts/hypertenancy) model assures you can size your warehouse correctly and use your resources very efficiently. To keep compute costs in check, [configure the Duckling cooldown period](/about-motherduck/billing/duckling-sizes/#configuring-the-cooldown-period) per user or service account, and end batch pipelines with [`SHUTDOWN`](/sql-reference/motherduck-sql-reference/shutdown-terminate/) to stop the Duckling without waiting for the cooldown. ### Horizontal scaling For serving data to BI tools or other spiky consumers, [Read Scaling Replicas](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/) can absorb the loads and maintain low latency on user interactivity. These should be owned by the same user or service accounts that run production jobs, although they can also leverage [`SHARES`](/key-tasks/sharing-data/sharing-overview/) depending on preferences. ### Hypertenancy Especially for production runs, use separate user accounts or [service accounts](/key-tasks/service-accounts-guide/create-and-configure-service-accounts/) with dedicated compute for updating and maintaining core tables. ### Distributed DuckDB DuckDB and MotherDuck work together as a distributed system that automatically optimizes query execution between local and cloud resources through Dual Execution, enabling efficient data access regardless of location. ## Orchestration To keep data up to date inside MotherDuck, start with [Flights](/key-tasks/flights/): scheduled Python jobs that run natively on MotherDuck, so you can load and transform data on a cron schedule without external infrastructure. You manage Flights through SQL, the UI, or the [MCP Server](/sql-reference/mcp/), which means an AI agent can build and maintain them for you. For more complex data engineering pipelines that span multiple systems, an external orchestrator like [Airflow](https://airflow.apache.org/) or [Dagster](https://dagster.io/) runs jobs in specific orders to load and transform data, as well as managing workflow and observability. If this is your first data warehouse, you might consider starting with [GitHub actions](https://github.com/features/actions) or cron jobs to orchestrate your data pipelines. :::info For a more in-depth guide, check out the [Data Warehousing Guide](/key-tasks/data-warehousing/) ::: ### Try MotherDuck for free Sign up and start building your data warehouse in minutes. No credit card required. [Get Started Free](https://app.motherduck.com/?auth_flow=signup) --- Source: https://motherduck.com/docs/getting-started/customer-facing-analytics # Customer-Facing Analytics Overview > Build customer-facing embedded analytics with MotherDuck. Per-user isolation, sub-second SQL dashboards, and white-label analytics for SaaS—no complex infrastructure needed. Customer-facing analytics (CFA), or embedded analytics, has requirements that traditional data architectures rarely meet. If you're building SaaS analytics dashboards, white-label reporting, or embedded data visualizations, CFA demands sub-second response times, per-customer isolation, and integration with operational applications — all while serving many concurrent end users. MotherDuck, the serverless cloud data warehouse built on DuckDB, addresses these needs through two architectural capabilities: - **[Hypertenancy](#1-hypertenancy)**: Each customer gets their own dedicated DuckDB instance (Duckling), providing full compute isolation (so no resource contention between users), predictable performance, and the ability to scale resources independently based on individual customer needs. - **[Dual Execution](#2-dual-execution-for-zero-latency-exploration)**: Enabled by DuckDB's lightweight architecture, queries can run both in the cloud and directly in the client's browser through WebAssembly, delivering near-instantaneous data exploration and filtering. This guide explains how MotherDuck's architecture addresses the [core CFA challenges](#the-cfa-challenge) and provides [implementation patterns](#implementation-patterns) you can ship. ## What is customer-facing analytics? **Customer-Facing Analytics (CFA)** embeds analytics directly into operational applications for external users—customers, partners, or end-users—rather than internal stakeholders. Traditional BI targets internal teams, runs on batch-processed data models, serves a small number of users, and tolerates higher-latency queries. | Dimension | Traditional BI | Customer-Facing Analytics | | -------------- | ------------------------------- | ------------------------------------ | | **Audience** | Internal (analysts, executives) | External (customers, partners) | | **Delivery** | BI tools (Tableau, Looker) | Embedded in application | | **Latency** | Seconds to minutes acceptable | Milliseconds to low seconds required | | **Scale** | Dozens to hundreds of users | Thousands to millions of users | | **Isolation** | Shared warehouse | Per-customer isolation needed | | **Tech Stack** | Python, BI tools | JavaScript, embedded SDKs | "Customer-facing analytics" and "embedded analytics" get used interchangeably. Both describe integrating analytical capabilities directly into a product instead of sending users to a separate BI tool. The difference is one of emphasis: customer-facing analytics focuses on the *audience* (your customers), while embedded analytics focuses on the *delivery* (built into your app). MotherDuck supports both. ### Common use cases - **SaaS analytics dashboards:** give customers self-serve analytics within your product, covering usage metrics, performance KPIs, and ROI reporting - **White-label analytics:** offer analytics under your brand that customers can explore without leaving your app - **Embedded dashboards:** drop interactive charts and tables directly into your application UI - **Multi-tenant reporting:** serve thousands of customers from one platform while keeping each tenant's data and compute isolated :::info **What about AI-driven analytics?** AI-driven analytics enables natural language interactions with data, allowing users to ask conversational questions like "What were our top-selling products last quarter?" and get immediate answers. MotherDuck's [hypertenancy](/concepts/hypertenancy) and Dual Execution make it well-suited for building AI-driven analytics solutions. The MotherDuck MCP Server includes a Dive Viewer that renders [Dives](/key-tasks/dives/) inline in AI chat clients that support MCP Apps. Learn how to [build analytics agents with MotherDuck](/key-tasks/ai-and-motherduck/building-analytics-agents/). ::: ## The CFA challenge Building customer-facing analytics systems presents three core challenges: ### Challenge 1: Technology stack mismatch For many applications, the data sits in a transactional database (OLTP database) like Postgres or MySQL. Engineers building CFA features often run analytical queries directly in a multi-tenant transactional database, which works until it fails at scale. Row-based storage and transactional databases are not designed for efficient analytical querying. ![Crying Database](./img/crying_db.webp) Operational applications often live in JavaScript/TypeScript, but traditional data tools are Python-centric. Operational teams work with OLTP databases built for transactions, while data teams use OLAP systems tuned for analytics but with their own challenges. Analytical workloads spike with user activity, while transactional loads need steady compute. ### Challenge 2: Latency requirements Users expect sub-second response times—typical for OLTP systems. Anything slower degrades the application experience. Distributed OLAP systems (BigQuery, Snowflake, Databricks) often have cold starts and coordination overhead that keep them above those targets, even for small datasets. Teams often add caching layers or refresh pipelines between OLTP and OLAP. That adds complexity, introduces another failure point, and delays data freshness. ### Challenge 3: Multi-tenancy at scale Switching to an analytics engine is the first step. Many legacy OLAP engines were designed for internal analytics and are provisioned as a single instance or cluster for all customer data, leading to downstream complexities: ![Legacy Data Warehouse](./img/legacy_data_warehouse.png) - **Overprovisioning**: Resources sized for peak load sit idle most of the time - **Noisy neighbors**: Large customer impacts small customers - **Resource contention**: Concurrency limits affect everyone - **Unpredictable performance**: Query times vary based on load - **Security concerns**: All customer data in one shared system ## Why MotherDuck for customer-facing analytics? MotherDuck's architecture aligns with the requirements of Customer-Facing Analytics. Two architectural advantages set it apart: ### 1. Hypertenancy MotherDuck provisions a Duckling (DuckDB instance) for each customer (or even for each customer's users). This [hypertenancy](/concepts/hypertenancy) model isolates customer data and delivers consistent DuckDB performance to each user. ![Happy Database](./img/happy_db.webp) **Why single-node beats distributed compute clusters for CFA** Traditional data warehouses use distributed computing with coordination overhead, data shuffling, and network latency. Even a fast query typically takes a second or more because of this overhead. DuckDB and MotherDuck use single-node, optimized columnar execution: - Zero network hops - Zero coordination overhead - Optimized vectorized execution For CFA workloads that query one customer's data at a time, single-node execution is usually faster than distributed, and MotherDuck can reach **subsecond performance**. #### Scaling analytics up and out Each customer (and possibly each of their users) has their **own MotherDuck Duckling** (DuckDB instance). One account could run hundreds or thousands of Ducklings at a time, or none. This serverless model underpins MotherDuck's advantage versus other engines. MotherDuck's **cold start time is sub ~100ms**, and **per-second billing** (1-second minimum) keeps individual queries cost-efficient. :::note While MotherDuck supports provisioning one Duckling per user, start simpler. Begin with a single Duckling per customer and introduce per-user isolation or [read scaling](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/) when monitoring shows sustained high concurrency or when you need tighter performance guarantees. ::: ![MD Router](./img/md_router.svg) This isolated Duckling approach with vertical scaling delivers: - **Perfect isolation**: No noisy neighbors - **Predictable performance**: Dedicated resources per customer - **Cost-effective**: Pay only for what each customer needs - **Easy scaling**: Vertically scale individual ducklings as needed Scale vertically by upgrading (or downgrading) the Duckling size your application uses for each customer, giving more power to higher-priority customers. If you need more compute or higher concurrency, launch [read scaling Ducklings](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/) for compute-hungry customers. MotherDuck offers several [Duckling sizes](/about-motherduck/billing/duckling-sizes/) for larger workloads. For programmatic changes to user settings, refer to our [API docs](/sql-reference/rest-api/motherduck-rest-api/). ### White-label analytics Many SaaS companies need analytics that look and feel native to their product. MotherDuck's architecture supports white-label analytics by design: - **Per-customer isolation:** each tenant gets a dedicated Duckling, with no shared infrastructure leaking through - **Flexible query layer:** use any frontend charting library (Recharts, D3, Observable Plot) with MotherDuck as the SQL backend - **No vendor branding:** unlike embedded BI tools that surface their own UI, MotherDuck powers your queries behind the scenes - **DuckDB-Wasm for client-side execution:** ship analytics that run entirely in the browser for maximum responsiveness ### 2. Dual Execution for zero-latency exploration As you build Customer-Facing Analytics into your product, you need sub-second response times so customers can explore their data quickly. Distributed data warehouses rarely meet that bar. Because MotherDuck is built on DuckDB, you can connect from any DuckDB client. DuckDB is an in-process database, so it **can run on your server (3-tier) or directly in the client's browser through WebAssembly (1.5-tier)**. This enables "Dual Execution": combining local data and compute with cloud data and compute in a single query, giving you flexibility to optimize for performance and cost. **Traditional approach has multiple network hops:** ```mermaid flowchart LR subgraph Client Side User{{"USER"}}:::green Browser["CLIENT (Browser)"] end subgraph Server Side Server["SERVER"]:::watermelon Database[("DATABASE")]:::yellow end User --> Browser Browser --> Server Server --> Database ``` **DuckDB-Wasm enables client-side execution:** ```mermaid flowchart LR subgraph Client Side User{{"USER"}}:::green subgraph Browser["CLIENT (Browser)"] LocalDB[("DATABASE")]:::database end end subgraph Server Side CloudDB[("DATABASE")]:::database end User --> Browser Browser --> CloudDB ``` Because the same DuckDB SQL engine runs on both MotherDuck Ducklings and on your customers' machines, you can offload data processing to their laptops and provide fast data exploration, filtering, and sorting using SQL. Customers do not need to install anything because DuckDB runs inside the web browser using WebAssembly (Wasm). You can see this experience in [Column Explorer](/getting-started/interfaces/motherduck-quick-tour/) and [Instant SQL](https://motherduck.com/blog/introducing-instant-sql/) in the MotherDuck UI. Here's a teaser of it in action: ![Instant SQL](./img/fast_queries.gif) ## Implementation patterns MotherDuck enables three architectural patterns for customer-facing analytics: ### Embedded Dives **Best for:** Shipping customer-facing dashboards without building a frontend. Create a [Dive](/key-tasks/dives/) with a natural language prompt or [as code](/key-tasks/dives/managing-dives-as-code/), mint an embed session from your backend, and drop a sandboxed iframe into your app. The Dive brings its own charts, filters, and queries, so there's no frontend data plumbing to build. Embedding Dives requires the Business plan. **Architecture:** ```mermaid flowchart LR Backend["Application Server"] Dive["Embedded Dive (iframe)"]:::green MotherDuck[("MotherDuck (Cloud Database)")]:::yellow Backend -->|"Mint embed session"| MotherDuck Backend -->|"Session string"| Dive Dive -->|"Live SQL queries"| MotherDuck ``` **Key Benefits:** - No charting code to write or maintain: iterate on the dashboard with natural language instead of frontend releases - Per-tenant data: override `required_resources` per session to point the same Dive at each tenant's database - Deep links: seed filters and selections per session with `initial_state` - Production stability: pin a specific Dive version per embed session - Host-page integration: data exports and viewer state sync through `postMessage` - Fresh data: embedded Dives run on read scaling connections that sync about once a minute, and `REFRESH DATABASE` pulls the latest writes on demand **When to use:** - You want dashboards in your product without building and maintaining a charting frontend - One dashboard definition serves many tenants, each against their own data - Interactions can live inside the Dive, with `postMessage` covering host-page integration - Your organization is on the Business plan Follow the [embedding Dives guide](/key-tasks/dives/embedding-dives/) for the full setup, from creating the embed session to handling exports and state updates. ### 3-tier architecture **Best for:** Applications requiring server-side authorization, business logic, or deployments to stateful platforms. **Typical web application architecture:** ```mermaid flowchart LR Frontend["Browser (React Frontend)"] Backend["Application Server (Express / FastAPI)"] MotherDuck[("MotherDuck (Cloud Database)")]:::yellow Frontend -->|"API Requests"| Backend Backend -->|"Persistent Connection, SQL Queries"| MotherDuck ``` **Key Benefits:** - Persistent database connection (connection pooling saves ~200ms per request) - Fast query performance (~50-100ms) - Server-side security and authorization - Works with any DuckDB client (Node.js, Python, Go, Rust, Java) **Performance optimizations:** 1. Intermediate table results: Pre-aggregate data on MotherDuck for faster queries 2. Prefer one well-structured SQL statement that returns all needed metrics (using SELECT with multiple aggregates, CASE/FILTER, or UNION ALL). 3. For multi-step workflows, wrap statements in a BEGIN … COMMIT transaction to ensure atomicity. 4. For data movement, use bulk operations (COPY, INSERT … SELECT) instead of many row-by-row calls. MotherDuck is analytical, not transactional: if queries feel slow, [set the right expectations](/key-tasks/query-performance/#set-the-right-expectations) and reshape OLTP-style write patterns into batches. 5. Application Caching: Cache rarely-changing data on your server to avoid any extra queries on MotherDuck **When to use:** - You need server-side authorization and business logic - You want a traditional, battle-tested architecture - You're deploying to stateful services (Cloud Run, ECS, Kubernetes) - Your team works with multiple languages ### Ready to build? Follow the hands-on Builder's Guide to set up a 3-tier CFA application step by step. [Go to Builder's Guide](/docs/key-tasks/customer-facing-analytics/3-tier-cfa-guide/) ### 1.5-tier architecture (DuckDB-Wasm) **Best for:** Read-heavy dashboards with `<1GB` data per user where you need maximum performance. This works well for embedded dashboards with interactive charts, tables, and filters that respond in under 10ms because queries execute locally in the user's browser. **Architecture:** ```mermaid flowchart LR Browser["Browser
(React + MotherDuck Wasm SDK)"] MotherDuck[("MotherDuck
(Cloud Database)")]:::yellow Browser -->|"Initial data fetch
Query execution"| MotherDuck ``` **Key Benefits:** - Sub-10ms query latency (queries run locally in browser) - Near-zero server costs (just data transfer) - Offline support after initial data load - Infinite scalability (users provide compute) **Performance optimizations:** 1. **Optimize Initial Load**: Use Parquet compression, limit to `<50MB` 2. **IndexedDB Persistence**: Data survives page reloads 3. **Incremental Sync**: Only fetch new data since last sync **When to use:** - Read-heavy dashboards with frequent filtering/drilling - Want `<10ms` query latency - Data per user is `<1GB` - Want to minimize server costs #### Hands-on example See our [1.5-tier architecture example](https://github.com/motherduckdb/wasm-client/tree/main/examples/nypd-complaints) demonstrating best practices for building a 1.5-tier analytics application using TypeScript, React and the MotherDuck Wasm SDK. ### Comparing the patterns | Factor | Embedded Dives | 3-Tier | 1.5-Tier (DuckDB-Wasm) | | --------------------- | ------------------------- | ------------------- | ---------------------- | | **Frontend to build** | None (iframe embed) | Custom UI | Custom UI | | **Query latency** | Sub-second (cloud) | ~50-100ms | ~5-20ms ⚡ | | **Server cost** | $ (session minting only) | $$ (per request) | $ (data transfer only) | | **Scalability** | High (read scaling) | High (auto-scaling) | ♾️ Unlimited | | **Data per user** | Any size | Any size | `<1GB` optimal | | **Offline support** | ❌ No | ❌ No | ✅ Yes | | **Server-side logic** | ❌ Limited (per session) | ✅ Yes | ❌ Limited | | **Plan availability** | Business plan | All plans | All plans | | **Best for** | Dashboards, fast shipping | Complex logic, auth | Read-heavy dashboards | ### Try MotherDuck for free Sign up and start building customer-facing analytics in minutes. No credit card required. [Get Started Free](https://app.motherduck.com/?auth_flow=signup) ### Additional resources - [Embedding Dives in your web application](/key-tasks/dives/embedding-dives/) - [Building Analytics Agents with MotherDuck](/key-tasks/ai-and-motherduck/building-analytics-agents/) - [Read Scaling Ducklings](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/) - [Duckling Sizes](/about-motherduck/billing/duckling-sizes/) ## FAQ ### What is embedded analytics? Embedded analytics means putting data visualizations, dashboards, and interactive reports directly inside a software application. Users explore data in the product they already use rather than switching to a separate BI tool. MotherDuck powers embedded analytics with sub-second SQL queries and per-user compute isolation. ### What is the difference between embedded analytics and traditional BI? Traditional BI is built for internal teams using standalone tools like Tableau or Looker. Embedded analytics is for your external customers, living inside your product. That difference creates harder technical requirements: you need lower latency, higher concurrency (potentially thousands of simultaneous users), and per-tenant data isolation. MotherDuck's Duckling architecture handles all three. ### What is white-label analytics? White-label analytics lets you offer data analytics under your own brand. Your customers see dashboards that match your product's look and feel, with no third-party logos visible. MotherDuck supports this by providing a SQL query engine (DuckDB) that runs behind your UI — there's no user-facing vendor footprint. ### How do you add analytics to a SaaS product? The fastest path is embedding a Dive: an interactive dashboard served through an iframe, with no frontend to build. If you're building your own frontend, there are two main approaches. In a 3-tier architecture, your server queries MotherDuck and returns results to the frontend. This works well when you have complex auth or business logic. In a 1.5-tier architecture, DuckDB runs directly in the browser through WebAssembly, which is a better fit for read-heavy dashboards where each user's data stays under 1GB. Both approaches give you fast query performance. ### What is multi-tenant analytics? Multi-tenant analytics means serving multiple customers from one shared platform while keeping each customer's data separate. MotherDuck works differently, through Hypertenancy — every tenant gets a dedicated DuckDB instance (a Duckling). This avoids noisy-neighbor problems and keeps performance predictable while maintaining data isolation between each customer. ### Can I embed dashboards without building a frontend? Yes. Create a [Dive](/key-tasks/dives/) with a natural language prompt or as code, then embed it: your backend mints an embed session through the MotherDuck API and your frontend loads the Dive in a sandboxed iframe. The Dive handles the charts, filters, and queries, and you can point the same Dive at each tenant's database per session. Embedding Dives requires the Business plan. See [embedding Dives in your web application](/key-tasks/dives/embedding-dives/) for the full setup. --- Source: https://motherduck.com/docs/getting-started/mcp-getting-started # Talk to Your Data with AI > Get started with the MotherDuck MCP Server to analyze your data using natural language with Claude, ChatGPT, and other AI assistants The MotherDuck **remote** MCP Server lets you analyze your data using natural language and generate interactive visualizations, all without writing SQL. Connect your favorite AI assistant (Claude, ChatGPT, Cursor, or others) and start asking questions about your databases, then turn insights into shareable [Dives](/key-tasks/dives) with a single prompt. :::info[Connection URL] The remote MCP server is hosted at `https://api.motherduck.com/mcp`. Claude Desktop's connector uses this URL automatically; for clients that need manual configuration, see the [setup guide](/key-tasks/ai-and-motherduck/mcp-setup/). ::: :::note This guide covers the **remote MCP server** (fully managed by MotherDuck). If you need to work with local DuckDB files or want full control over the server, see the [local MCP server](/key-tasks/ai-and-motherduck/mcp-setup/#remote-vs-local-mcp-server). ::: In this guide, you'll connect the MCP server in Claude Desktop, query your data, and create a Dive visualization, all in under 5 minutes. ## What you'll learn - Connect the MotherDuck MCP Server to Claude Desktop - List your databases - Ask analytical questions about your data - Create an interactive Dive visualization from your analysis ## Prerequisites - A MotherDuck account ([sign up free](https://app.motherduck.com/)) - Claude Desktop installed ([download](https://claude.ai/download)) :::tip[Using a different AI client?] This guide uses Claude Desktop, but the remote MCP Server works with ChatGPT, Cursor, Claude Code, and other MCP-compatible clients. See the [full setup guide](/key-tasks/ai-and-motherduck/mcp-setup/) for instructions for your preferred client. ::: ## Step 1: Add the MCP server to Claude Desktop Open Claude Desktop settings and add the MotherDuck remote MCP Server: 1. Open **Claude Desktop** → **Settings** → **Connectors** 2. Click **Browse Connectors** and search for "MotherDuck" 3. Click **Add** to install the MotherDuck connector 4. A browser window opens for authentication with your MotherDuck account ## Step 2: Verify the connection and permissions After adding the connector, confirm Claude has access to the MotherDuck tools: 1. Open **Claude Desktop** → **Settings** → **Connectors** 2. Select **MotherDuck** and click on **Configure** You should see tools like `query`, `list_databases`, and `ask_docs_question` available. You can configure tool permissions to control how Claude uses each tool. See [Configuring tool permissions](/key-tasks/ai-and-motherduck/mcp-setup/#configuring-tool-permissions) for details. ## Step 3: List your databases Test the connection by asking Claude to list your databases: **Try this prompt:** ```text List all my databases on MotherDuck. ``` Claude will use the MCP tools to connect to MotherDuck and return your database list. ## Step 4: Analyze your data Now let's run an actual analysis. If you don't have data yet, you can attach the sample Hacker News database: **Attach the sample database:** ```text Attach this db 'md:_share/hacker_news/de11a0e3-9d68-48d2-ac44-40e07a1d496b' give me some analytics. ``` The `hacker_news` database contains Hacker News stories, comments, and metadata from 2016 to 2025. You'll see that even with a minimal prompt, you get great results for a first data exploration. For more tips on effective prompting and workflow patterns, check out the [MCP Workflows Guide](/key-tasks/ai-and-motherduck/mcp-workflows/).
:::info[Sample databases] The `hacker_news` database is one of several sample datasets available. See [Sample Data & Queries](/getting-started/sample-data-queries/datasets) for more datasets to explore. ::: ## Step 5: Create visualizations with Dives Now that you've explored your data, turn your insights into a persistent, interactive visualization. [Dives](/key-tasks/dives) are shareable visualizations that live in your MotherDuck workspace and stay up to date with your data. **Try this prompt:** ```text Create a Dive based on these insights. ``` Claude renders the Dive inline in the conversation with the Dive Viewer MCP App, using the same components as the MotherDuck UI and running against live data. Iterate conversationally: *"add a filter for the last 30 days"*, *"switch to a bar chart"*. Each edit saves as a separate version. ```text Save it to MotherDuck. ``` The Dive is saved to your workspace. You can open it in the MotherDuck UI, share it with your team, and it will always query live data. ## Next steps You're now ready to analyze your data and create visualizations with AI. Here are some ways to go deeper: - **[MCP Workflows Guide](/key-tasks/ai-and-motherduck/mcp-workflows/)**: Best practices and workflow patterns, including [how it works under the hood](/key-tasks/ai-and-motherduck/mcp-workflows/#how-it-works) - **[Creating Visualizations with Dives](/key-tasks/dives/)**: Go deeper into Dives by iterating on visualizations, sharing with your team, and managing version history - **[Connect to MCP Server](/key-tasks/ai-and-motherduck/mcp-setup/)**: Setup instructions for ChatGPT, Cursor, Claude Code, and other clients - **[MCP Server Reference](/sql-reference/mcp/)**: Server capabilities, available tools, and regional availability - **[Building Analytics Agents](/key-tasks/ai-and-motherduck/building-analytics-agents/)**: Build custom AI agents that programmatically query your data - **[Work with agents through the CLI](/getting-started/interfaces/motherduck-cli/agents/)**: For coding agents with a terminal, when the MotherDuck CLI beats MCP on tokens and why --- Source: https://motherduck.com/docs/getting-started/getting-started # MotherDuck documentation > Getting started with MotherDuck serverless cloud data warehouse. MotherDuck is the serverless cloud data warehouse built on DuckDB. Its hypertenancy architecture gives every user or AI agent an isolated compute instance, so you get sub-second analytics with no infrastructure to manage, no resource contention, and lower costs. Build a modern data warehouse for internal business intelligence, power customer-facing analytics in your application, or build agent-driven analytics tools. Develop and iterate locally, then share and scale in the cloud when you need it. ## Choose your path - [MotherDuck Tutorial](/docs/getting-started/e2e-tutorial/): Build an end-to-end workflow: load data, transform it, and share results - [Data Warehousing Overview](/docs/getting-started/data-warehouse/): Build a modern warehouse with ingestion and transformation - [Customer-Facing Analytics Overview](/docs/getting-started/customer-facing-analytics/): Build analytics apps with the MotherDuck Wasm client - [Talk to Your Data with AI](/docs/getting-started/mcp-getting-started/): Analyze your data with natural language using the remote MCP Server - [Create Visualizations with Dives](/docs/key-tasks/dives/): Generate interactive, shareable dashboards from natural language prompts - [Automate Data Pipelines with Flights](/docs/key-tasks/flights/): Run Python jobs on a schedule for ingest, transformation, and operational tasks ### Try MotherDuck for free Sign up and start querying in minutes. No credit card required. [Get Started Free](https://app.motherduck.com/?auth_flow=signup) ## Connect to MotherDuck Connect to MotherDuck using official drivers and APIs for various programming languages. - [Python](/docs/getting-started/interfaces/client-apis/python/installation-authentication/) - [MotherDuck UI](/docs/getting-started/interfaces/motherduck-quick-tour/) - [Node.js](https://duckdb.org/docs/stable/clients/node_neo/overview.html) - [WebAssembly](/docs/sql-reference/wasm-client/) - [Golang](/docs/integrations/language-apis-and-drivers/go-driver/) - [Postgres endpoint](/docs/getting-started/interfaces/postgres-endpoint/) - [View all clients and drivers →](/docs/integrations/language-apis-and-drivers/) ## Load data to MotherDuck Load your data from other databases and object storage - [S3](/docs/integrations/cloud-storage/amazon-s3/) - [PostgreSQL](/docs/key-tasks/loading-data-into-motherduck/loading-data-from-postgres/) - [BigQuery](/docs/integrations/databases/bigquery/) - [View supported ingestion tools →](/docs/integrations/ingestion/) ## Integrate with your data stack Connect with a lot of common tools from the modern data stack. - [dbt](/docs/integrations/transformation/dbt/) - [Fivetran](https://fivetran.com/docs/destinations/motherduck#motherduck) - [Tableau](/docs/integrations/bi-tools/tableau/) - [View all integrations →](/docs/integrations/) ## Common tasks Some common tasks and use cases to get you started. - [Connect to Power BI](/docs/integrations/bi-tools/powerbi/): Use the DuckDB Power Query connector for Power BI - [Authenticate](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/): Log in or use access tokens for CLI and drivers - [Query from DuckDB CLI](/docs/getting-started/interfaces/connect-query-from-duckdb-cli/): Install the DuckDB CLI and connect directly to MotherDuck - [Use SQLAlchemy](/docs/integrations/language-apis-and-drivers/python/sqlalchemy/): Connect to MotherDuck with Python & SQLAlchemy - [Connect to DuckLake](/docs/integrations/file-formats/ducklake/): Use DuckLake to build a data lake on top of your own files --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fgetting-started%2F&page_title=MotherDuck%20Documentation%20-%20Getting%20started&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.