Skip to content

Feature: Add .explain_plan() method to QueryBuilder and SQL objects #219

@cofin

Description

@cofin

Feature Request

Add an .explain_plan() method to QueryBuilder and SQL objects to help users understand query execution strategies, especially for complex MERGE and bulk operations.

Proposed API

# QueryBuilder usage
plan = (
    sql.merge()
       .into('products')
       .using(bulk_data)
       .on('t.id = src.id')
       .when_matched_then_update(name='src.name')
       .explain_plan()
)

# Output example:
{
    'strategy': 'json_populate_recordset',
    'row_count': 500,
    'param_count': 1,
    'estimated_cost': 'medium',
    'sql_preview': 'MERGE INTO products AS t USING (...) AS src...'
}

Use Cases

  1. Debugging bulk operations - Understand which bulk strategy was selected
  2. Performance tuning - See parameter counts and strategy choices
  3. Learning - Help users understand how their query will execute
  4. Documentation - Show examples in guides

Implementation Notes

  • Should work on all QueryBuilder subclasses (Select, Insert, Update, Delete, Merge)
  • Should show database-specific execution details
  • Should not execute the query, only analyze it
  • Optional verbose=True for detailed output

Related

  • Deferred from merge-bulk-upsert implementation (Phase 3)
  • Would complement .to_sql(show_parameters=True) method

Priority

Medium - Nice to have for developer experience, not critical for functionality

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions