motherduck-query · git:20261025.b709403 · 2026-10-25 · sha256 18e5e6762890ffe4
motherduck-query git:20261025.b709403A
Immutable. This exact content never changes and is served at /api/v1/blob/18e5e6762890ffe4.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_tn55r2ae76qzll2x/18e5e6762890ffe48315c9f7d6fdd934564e28e9c81dc806844717f48014a58a.json
Then /plugin install motherduck-query@markdownregistry-tn55r2ae76qzll2x in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: motherduck-query description: Write, run, optimize, or troubleshoot DuckDB SQL against MotherDuck, including AI functions such as prompt_jev for in-SQL classification. Use for any SQL that targets MotherDuck. license: MIT --- # Query MotherDuck ## Prerequisites - An established MotherDuck connection (or an active MotherDuck MCP server) - Target database and tables identified ## Default Posture - When MotherDuck MCP is available and the SQL answers a business question, call `get_query_guide` first, then read only the relevant Guide topics and validate their claims against the live schema. - Write DuckDB SQL, not PostgreSQL SQL, even when using the PG endpoint. - Prefer fully qualified `"database"."schema"."table"` names; they are required once more than one database or share is attached. - Preserve result grain and check join cardinality before optimizing or materializing a query. - Filter early, aggregate early, and prefer serving tables or summaries for repeated reads. - Keep SQL obvious, multi-line, and explicit about grain, filters, and output shape. - Treat DDL, DML, `ATTACH`, `DETACH`, recovery commands such as `CREATE SNAPSHOT`, `ALTER DATABASE ... SET SNAPSHOT`, `UNDROP DATABASE`, and lifecycle commands such as `SHUTDOWN` as writes. Use the MotherDuck MCP `query_rw` tool when the user's change request authorizes the write. Ask for confirmation only when the action is destructive, externally visible, or outside the stated scope. - Tag long-lived integrations with `custom_user_agent` when the connection path supports it; the tag appears per query in the Duckling Overview and in query history. - For classification, scoring, routing, or yes/no judgments over text or images, use `prompt_jev()`: it returns typed probabilities and labels, bills input tokens only, and batches rows. Use `prompt()` for generated text or open extraction with `struct` or `json_schema`. Both are per-row billable calls: test on a small `LIMIT`, store results in a table, and rerun only `NULL` rows. ## Workflow 1. Confirm the actual tables, columns, and grain before writing SQL. 2. Load relevant Guide context when MCP is available, without treating it as a substitute for schema inspection. 3. Write the query in SQL first, then wrap it in Python or TypeScript only if needed. 4. Use DuckDB-native patterns when they simplify the query; a simple lookup does not need a CTE or a materialization. 5. Verify result shape and key aggregates. When performance is part of the request or execution shows a problem, check `EXPLAIN ANALYZE` and `md_information_schema.query_history` (`wait_time`, `bytes_spilled_to_disk`, `instance_type`) before changing the query or the Duckling size. 6. Materialize expensive repeated queries into serving tables or light views when warranted. ## References Read only the reference sections needed for the current task. - Read `references/QUERY_PLAYBOOK.md` for DuckDB query patterns, exploration SQL, performance rules, common analytical shapes, and common mistakes - Read `references/AI_FUNCTIONS.md` when a query calls `prompt_jev()`, `prompt()`, or `embedding()` - Read `references/PERFORMANCE.md` when a query is slow, spills, runs out of memory, or a Duckling looks undersized ## Related Skills Load related skills only for missing capabilities; reuse established context. - `motherduck-connect` for session setup - `motherduck-duckdb-sql` for syntax and function reference - `motherduck-explore` for understanding the source schema before writing queries - `motherduck-manage-guides` when semantic definitions or reusable query rules need to be read or maintained