Django Query Plan Reading

Use this skill when the expensive unit is a specific SQL statement or queryset. The goal is to explain why the database is doing work, not to guess from the ORM code.

Workflow

1. Get the exact query.

   • Prefer the queryset that produced it.
   • If starting from logged SQL, include bound parameters or representative literals.

2. Generate a plan.

   • Use queryset.explain() for ORM-owned SQL.
   • Use database EXPLAIN for raw SQL, views, materialized views, or SQL copied from logs.
   • Use analyze=True only in a safe environment because the database executes the query.

3. Read from the deepest node outward.

   • Identify table scans, index scans, joins, sorts, aggregations, and limits.
   • Compare estimated rows with actual rows when using analyze.
   • Look for high-cost nodes that feed many rows to later nodes.