You are viewing a plain text version of this content. The canonical link for it is here.
Posted to reviews@iotdb.apache.org by "Young-Leo (via GitHub)" <gi...@apache.org> on 2026/04/15 10:31:02 UTC
[PR] feat(queryengine): adaptive Plan Cache for table model queries [iotdb]
Young-Leo opened a new pull request, #17490:
URL: https://github.com/apache/iotdb/pull/17490
## Description
Introduce an adaptive Plan Cache that caches optimized logical plans for table model queries,
skipping repeated Logical Plan Generation and Logical Optimization for structurally identical SQL.
### Core mechanism
- **Query fingerprinting**: Parameterize literals in SQL and generate an MD5 cache key, so
`SELECT * FROM t WHERE device_id = 'd1'` and `device_id = 'd2'` share the same template.
- **Three-state machine per template**: MONITOR → ACTIVE → BYPASS. Each template independently
accumulates EWMA samples before promotion; low-benefit templates are bypassed with a cooldown.
- **Safe plan reuse**: Only the logical plan is cached. On HIT, literals are re-bound and
`adjustSchema` re-resolves devices, time filters, and partition info — Distribution Plan is
never cached, avoiding stale region/shard topology.
- **LRU eviction**: `LinkedHashMap(accessOrder=true)` with dual limits (1000 entries, 64 MB).
### Admission control
| Transition | Condition |
|---|---|
| MONITOR → ACTIVE | `sampleCount ≥ 5` ∧ `ewmaPlanCost ≥ 1 ms` ∧ `benefitRatio ≥ 30%` |
| MONITOR → BYPASS | `sampleCount ≥ 5` ∧ (`planCost < 1 ms` ∨ `benefitRatio < 20%`) |
| ACTIVE → MONITOR | `benefitRatio < 30%` ∨ `planCost < 1 ms` (reset & re-evaluate) |
| BYPASS → MONITOR | cooldown expires (default 10 min) |
HIT-path latency tracking: during sustained cache hits, `firstResponseLatency` is still
recorded and `ewmaBenefitRatio` is refreshed using historical `ewmaReusablePlanningCost`,
enabling natural degradation when execution cost grows.
### Observability
`EXPLAIN ANALYZE VERBOSE` outputs Plan Cache diagnostics:
Plan Cache State: ACTIVE
Plan Cache Saved: 5.23 ms
EWMA Reusable Planning Cost: 5.23 ms (threshold: 1.00 ms)
EWMA First Response Latency: 11.80 ms
EWMA Benefit Ratio: 0.4434 (admit: 0.30, bypass: 0.20)
Profile Counters: samples=7, hits=12, misses=0, bypasses=0
### Files changed (production)
| File | Change |
|---|---|
| `PlanCacheManager.java` | **New.** LRU cache + three-state machine + EWMA evaluation |
| `CachedValue.java` | **New.** Cached plan container with deep-clone and memory estimation |
| `LiteralMarkerReplacer.java` | **New.** AST visitor for literal parameterization |
| `TableNameRewriter.java` | **New.** AST rewriter for table name normalization in cache key |
| `TableLogicalPlanner.java` | Integrate cache lookup / write-back / statistics feedback |
| `IoTDBConfig.java` / `IoTDBDescriptor.java` | 10 new config properties (`smart_plan_cache_*`) |
| `MPPQueryContext.java` | Bridge planner diagnostics → EXPLAIN ANALYZE output |
| `QueryPlanStatistics.java` | New fields for EWMA metrics and profile counters |
| `QueryExecution.java` | Record execution time back to `PlanCacheManager` |
| `FragmentInstanceStatisticsDrawer.java` | Render Plan Cache diagnostics in VERBOSE mode |
| `ExplainAnalyzeOperator.java` | Pass `verbose` flag to statistics renderer |
| `Literal.java` / `StringLiteral` / `LongLiteral` / `BinaryLiteral` | Add `generalizedCopy()` for parameterization |
| `SymbolAllocator.java` | Expose `setNextId()` for cached symbol counter restore |
| `PushPredicateIntoTableScan.java` | Minor adjustment for cached plan compatibility |
| `ExpressionFormatter.java` | Support formatting of parameterized marker literals |
### Tests
- `PlanCacheTest.java` — unit tests for state machine transitions and cache eviction
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@iotdb.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org