---

name: query-engine description: "Guide Wren governed SQL and cube queries, dry-plan and dry-run diagnostics, connectors, SQL policy, and the WrenEngine Python API." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Wren Query Engine

Use this route for a business-data query, a planning error, a cube query, a connector decision, or Python code that embeds Wren's semantic engine.

Safe Query Order

1. Confirm the project and compiled target:

   wren context show
   test -f target/mdl.json
   

2. Fetch schema/business context through the memory-knowledge route when available; write SQL against MDL model/view names, not raw tables.
3. For a complex query, inspect generated SQL before execution:

   wren dry-plan --sql 'SELECT ...'
   

4. Execute only after the plan and profile are correct:

   wren query --sql 'SELECT ...' --output table --limit 100
   

5. Use wren dry-run for a live database validation with no returned rows.
6. Store a successful, meaningful NL→SQL pair through the memory route only after it is accepted as correct.

Choose the Interface

• wren --sql is the short form of wren query.
• wren dry-plan is a semantic/dialect plan and does not need a live query.
• wren dry-run checks the planned SQL against the live datasource.
• wren cube query is preferred for a covered measure/dimension/time query.
• WrenEngine returns a PyArrow table to Python callers.
• For a new or unfamiliar query shape, inspect the resulting plan before an execution path that could access a costly or production datasource.

Fast Error Recovery

• Model/column error in a dry plan: read project context or memory first; correct one semantic name/relationship issue, then rerun the plan.
• Plan succeeds but a query fails: preserve the emitted dialect SQL and check the selected profile, connector extra, permissions, and database error.
• Aggregation request: ask whether a cube already covers it before writing raw GROUP BY SQL.
• Local file/table issue: confirm the model physical reference and the connector's file/catalog conventions; do not change semantic model names just to hide an attachment mismatch.

Route Elsewhere

• Project/profile/MDL authoring: ../cli-projects/SKILL.md.
• Memory/knowledge context: ../memory-knowledge/SKILL.md.
• Framework agent tools: ../sdk-integrations/SKILL.md.

References and Helpers

• Read references/query-workflows.md for query and error-recovery order.
• Read references/python-api.md for verified Python signatures and low-level planning behavior.
• Read references/connectors.md before selecting optional datasource packages.
• Read references/cubes.md for structured aggregation syntax.
• Read references/troubleshooting.md when the plan or execution fails.
• Run scripts/check_wren_environment.py for package/CLI checks and scripts/dry_plan_smoke.py --mdl <path> --datasource <name> --sql '...' for a no-database planning smoke.

Guardrails

• A successful dry-plan does not prove database permissions, connectivity, or query cost.
• A CPU import does not verify a remote connector or cloud credential.
• Respect configured strict_mode and denied_functions; do not bypass them by changing query text or using unmodeled tables.