Skip to content

Resolve EQUALITY keys via hash lookup during search - #10

Closed
anantsahrawat wants to merge 2 commits into
PhonePe:mainfrom
anantsahrawat:feature/equality-key-hash-lookup
Closed

anantsahrawat wants to merge 2 commits into
PhonePe:mainfrom
anantsahrawat:feature/equality-key-hash-lookup

Conversation

@anantsahrawat

Copy link
Copy Markdown
Collaborator

Problem

To find the keys that a request satisfies, DNFMatcher and CNFMatcher evaluate every key in the inverted index (map.keySet().stream().filter(CaveatEnforcer...)). Search cost therefore grows with the number of distinct keys in the index, even when only a few criteria match. Indexes with many distinct EQUALITY values are hit hardest: one id per criteria (e.g. geo-fence ids) or large value lists (e.g. allowed plan ids).

Change

  • EqualityKeyLookup (mustang-models) buckets EQUALITY keys whose value is a string, boolean or standard number. Buckets are keyed by (path, preOperations) first, then by normalised value. All other keys (other caveats, or other value types) stay in a scan list.

  • MatchingKeyResolver (mustang-core), used by both matchers:

    • applies each group's preOperations to the request value once;
    • resolves that group's EQUALITY keys with a hash lookup;
    • evaluates the scan-list keys exactly as before.

    The merge, scoring and tautology handling are unchanged.

  • Normalisation mirrors Utils.compare:

    • numbers compare by doubleValue() (-0.0 folded, NaN never matches);
    • booleans match only booleans, and strings only strings;
    • a list request value is compared using its first element;
    • null or unsupported values match nothing;
    • empty or non-list collections fall back to the regular caveat check.
  • The lookup is derived from each posting-list map and cached in InvertedIndex (@JsonIgnore, excluded from equals/hashCode/toString). The indexers always install a new map instance, so the cache is rebuilt lazily when the map changes. No changes were needed in add/update/delete/replace/import, and snapshot/export output is unchanged.

  • Enabled by default. It can be turned off with MustangEngine.builder().equalityKeyLookupEnabled(false). SearchFacade keeps its existing 4-argument search overload.

Compatibility

  • Search results are identical with the flag on or off.
  • MustangEngine has one new builder field, so its all-args constructor signature changes. Nothing in the repository calls it directly.

Tests

  • Existing suite passes: 250 tests in mustang-core and 8 in mustang-dw-bundle. Many SearchTest cases also run ratify(), which cross-checks search against scan.
  • New EqualityKeyLookupSearchTest (11 tests) compares lookup-enabled and lookup-disabled engines on the same index. It covers:
    • numeric type normalisation; booleans vs strings; list values (first element); missing and object values;
    • a 200-value list predicate;
    • MODULO, chained MODULO + ADDITION, and SIZE preOperations;
    • EXCLUDED equality mixed with RANGE and REGEX; CNF;
    • lookup rebuild after update, add and delete;
    • 1,000 distinct values on one path, with ratification;
    • a randomised parity run (400 mixed DNF/CNF criteria, 1,000 requests).

Benchmarks

Laptop, JDK 21. Indicative numbers.

New MustangEqualitySearchBenchmark (average time per search, 1 thread, -prof gc):

Shape Index size Lookup on Lookup off Speed-up Alloc/op on vs off
One distinct value per criteria 1,000 0.86 µs 10.3 µs ~12× 5.5 KB vs 21 KB
One distinct value per criteria 10,000 0.90 µs 81.7 µs ~90× 5.4 KB vs 165 KB
One distinct value per criteria 20,000 0.97 µs 193 µs ~200× 5.4 KB vs 325 KB
50-value lists + tenant 1,000 3.2 µs 140 µs ~44× 9.4 KB vs 168 KB
50-value lists + tenant 10,000 5.9 µs 8,116 µs ~1,370× 9.4 KB vs 1.6 MB

Existing benchmarks (README defaults: throughput, Threads.MAX, 1 iteration; now parameterised over the flag):

Benchmark Size On (ops/s) Off (ops/s)
MustangOnlyCNFSearchBenchmark 10 / 100 / 1000 / 10000 2.07M / 1.14M / 465K / 45.7K 2.22M / 962K / 172K / 23.3K
MustangOnlyDNFSearchBenchmark 10 / 100 / 1000 / 10000 1.33M / 541K / 43.4K / 2.25K 1.26M / 426K / 35.6K / 2.20K
MustangSearchBenchmark 10 / 100 / 1000 / 10000 2.13M / 591K / 73.6K / 3.60K 1.90M / 527K / 58.6K / 3.15K

The existing benchmarks draw values from [0, 100) across 26 paths, so they have at most ~2.6K distinct keys and long posting lists. The gains there are smaller (up to ~2.7× for CNF). Merging dominates for large DNF indexes.

Run:

mvn install -DskipTests && cd benchmarking && mvn clean package -DskipTests
java -jar target/benchmarks.jar MustangEqualitySearchBenchmark -p shape=DISTINCT_VALUES -p indexSize=1000,10000,20000 -prof gc
java -jar target/benchmarks.jar MustangEqualitySearchBenchmark -p shape=VALUE_LISTS -prof gc
java -jar target/benchmarks.jar "Mustang(Search|OnlyDNFSearch|OnlyCNFSearch)Benchmark"

Not in scope

  • RANGE, REGEX, VERSIONING and set caveats are still evaluated one by one.
  • Index build time (sorting all keys on every add) is unchanged.

Search used to evaluate every key of the inverted index against the request to find matching keys, so its cost grew with the number of distinct keys even when few criteria matched. EQUALITY keys with string, boolean or standard numeric values are now bucketed by (path, preOperations) and normalised value, and resolved with a hash lookup; all other keys are still evaluated one by one. Value normalisation mirrors Utils.compare, so results are unchanged.

The lookup is derived lazily from each posting-list map and rebuilt when the indexers replace the map. It is not serialised. The behaviour can be turned off with MustangEngine.builder().equalityKeyLookupEnabled(false).

Adds parity tests against the previous scan behaviour and an equality-heavy JMH benchmark, and parameterises the existing benchmarks over the flag.
@anantsahrawat
anantsahrawat force-pushed the feature/equality-key-hash-lookup branch from affefe3 to 3f6220f Compare October 30, 2026 09:49
@anantsahrawat

Copy link
Copy Markdown
Collaborator Author

Superseded by #12, raised from a branch in this repository so CI can use repository secrets. Closing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant