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.