-
-
Notifications
You must be signed in to change notification settings - Fork 6
Open
Labels
enhancementNew feature or requestNew feature or request
Description
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
- Debugging bulk operations - Understand which bulk strategy was selected
- Performance tuning - See parameter counts and strategy choices
- Learning - Help users understand how their query will execute
- 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=Truefor 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
Labels
enhancementNew feature or requestNew feature or request