Adaptive indexing in XLOG is a persistent build-side hash-index cache inside the runtime executor. It is not a broad physical-design subsystem. It exists to reuse expensive join indexes when the same relation generation, schema, key columns, and CUDA device recur across evaluations.

​
What Is Cached

JoinIndexCache keys an index by:
  • relation ID;
  • relation-store generation;
  • key column list;
  • schema signature, including column types and row width;
  • CUDA device ordinal.
That key prevents a stale index from being reused after a relation update, schema change, key change, or provider/device mismatch.

​
Build Decision

The executor considers building a persistent index when:
  • the build-side relation is hot enough;
  • estimated index bytes fit the cache budget;
  • the relation is stable for the current generation;
  • the runtime configuration allows persistent hash indexes.
If those conditions are not met, the join uses the ordinary path and the cache records a miss or deferred build.

​
Cache Lifetime

Indexes are invalidated when a relation is replaced or removed. The runtime also clears relevant cache entries when state resets would make cached relation metadata unsafe. The cache is byte-bounded. Insertions can evict older entries until the new index fits. If it still cannot fit, the build is skipped.

​
Configuration

Runtime configuration can enable or disable persistent hash indexes explicitly. When configuration is unset, environment defaults decide the behavior. Background build mode can request an index build through the recorded provider path and make the result available to later evaluations instead of blocking the current join.

​
Telemetry

Executor stats distinguish:
  • hits and misses;
  • builds and deferred builds;
  • evictions;
  • invalidations;
  • stale rejections;
  • background build requests and completions.
Use those counters to verify reuse. Do not infer adaptive indexing from a faster second run unless the cache stats show a hit or completed build.

​
Boundaries

Adaptive indexing does not currently promise:
  • arbitrary secondary-index selection;
  • sort-merge planning;
  • global physical-design tuning;
  • correctness changes.
It is a cache for reusable hash-join build structures. Correctness remains the same as the ordinary join route.