Learned Query Optimization
The learned optimizer uses execution feedback to adjust cardinality estimates and cost information. It also contains optional learned join-order selection. These components help adapt planning to observed workloads; they do not guarantee that every query becomes faster.
Cardinality Estimation
Traditional estimates use table and column statistics with predicate and join heuristics. Learned corrections use observed execution results. The service-managed blend weight is the fraction of the traditional estimate:
| Value | Meaning |
|---|---|
0.0 | Learned estimate when available |
0.7 (default) | 70% traditional, 30% learned |
1.0 | Traditional estimate |
Readiness checks and regression safeguards still govern whether a learned estimate is active. A blend setting alone does not establish that enough observations exist for a useful correction.
Plan Selection
Learned join-order selection is independently enabled by the service. It is not implied by cardinality correction. When enabled, the selector uses observed query patterns to help choose among candidate orders. The normal optimizer remains the fallback for unsupported or insufficiently observed cases.
Cost Model Tuning
Execution samples inform CPU and I/O cost corrections. Inspect sample counts and multipliers before attributing a changed plan to learning. Data layout, statistics freshness, and ordinary cost-based optimization can also change a plan.
Regression Detection
The regression detector compares learned predictions with baseline predictions and observed outcomes. Its states include Active, Warning, RolledBack, and Cooldown. A rollback suspends the learned path according to the detector's recovery rules; it is not a guarantee that all workload regressions are detected.
Configuration
The learned optimizer and MLP cardinality correction default to enabled. Learned join ordering is a separate opt-in. The configuration reference explains which settings Gnok manages and which diagnostics customers can use.
MLP retraining
Cardinality retraining advances the MLP version and invalidates planning state derived from older versions. The update reaches the whole query service asynchronously; it is not a synchronous, all-at-once update.
Per-tenant fast-path selector
SHOW FAST PATH SELECTOR;
This reports shard, reverted, win_rate, sample_count, revert_count, and reactivation_count. Use the sample count alongside the win rate; sparse history is not strong evidence of performance. The reverted flag identifies a selector that has fallen back.
Monitoring
SHOW LEARNED OPTIMIZER;
The result is one row per optimizer shard (tenant or configured pool). Useful fields include:
| Fields | Interpretation |
|---|---|
enabled, ml_active, kill_switch_enabled | Configured and current runtime state |
query_count, cardinality_samples, cardinality_patterns | Amount and coverage of observations |
cardinality_predictions, cardinality_avg_confidence | Cardinality correction activity |
cost_tuner_samples, cost_tuner_cpu_multiplier, cost_tuner_io_multiplier | Cost correction state |
regression_state, regression_rollbacks, regression_consecutive_errors | Regression and recovery evidence |
ml_win_rate, ml_error_ratio | Learned-versus-baseline comparison |
mlp_enabled, mlp_predictions, mlp_version, last_retrained_at | MLP activity and freshness |
plan_selector_patterns, plan_selector_executions | Plan selector coverage and use |
Compare plans and measured latency on a representative workload before changing settings. Keep data snapshots, concurrency, and cache conditions comparable. A model version increment proves that retraining occurred, not that query performance improved.