perf(ebean-dao): implement config-controlled multi-aspect batch read

[darshilbhayani92]

Summary

Implements the config-controlled multi-aspect batch read on top of the API surface + routing introduced in the base PR (#641). This collapses N per-aspect SELECTs into a single bundled SELECT of all requested aspect columns per entity table — the read-latency optimization for META-24100.

Stacked on #641 (base branch = dbhayani/multi-aspect-read-primitive). It only makes the MULTI_ASPECT / DUAL paths functional; the default strategy is still PER_ASPECT, so behavior is unchanged unless explicitly opted in.

Review #641 first — this PR's diff is only the implementation delta on top of it.

What's included

File	Change
SQLStatementUtils.java	createMultiAspectReadSql(...) — build one bundled SELECT of all aspect columns per table; urns escaped via escapeReservedCharInUrn; row-level deleted_ts IS NULL filter; also selects deleted_ts when includeSoftDeleted
EbeanLocalAccess.java	batchGetUnionMultiAspect(...) — group keys by entity table, run one query per table, then row-driven mapping back to aspects (see below)
InstrumentedEbeanLocalAccess.java, UsageTrackingEbeanLocalAccess.java	implement the stubbed decorator overrides to delegate the new read (metrics instrumentation + usage emission), required now that the routing seam actually invokes it

Mapping semantics (row-driven, matches the per-aspect path)

Rather than reverse-looking-up rows by the requested urn string, the mapping iterates the returned rows (like the per-aspect path) and emits one aspect per requested (urn, aspect) pair:

• Case-insensitive urn matching — requested pairs are keyed on a lower-cased urn (matchKey), so an aspect is not silently dropped when the stored urn differs from the requested urn by canonical/case. The returned aspect's urn is derived from the row itself, matching per-aspect output.
• Duplicate keys collapse — requested pairs live in a Set (requestedPairs); requestedPairs.remove(...) both restricts output to requested pairs and deduplicates repeated (urn, aspect) keys, matching the per-aspect Set<Urn> grouping.
• Skip semantics preserved — missing column → skip (single validator.columnExists check during key collection), no row / null cell → skip.

Soft-delete semantics

A bundled query can't AND per-column JSON soft-delete checks without dropping the whole row when any single aspect is soft-deleted. So soft-delete is handled in two layers:

• row level in SQL (deleted_ts IS NULL, dropped when includeSoftDeleted), and
• per-cell during mapping via EBeanDAOUtils.isSoftDeletedAspect.

This preserves parity with the per-aspect path.

Validation in prod without member impact (DUAL)

The DUAL strategy (in #641's newSchemaBatchGet) reads both paths, compares them via EBeanDAOUtils.compareResults (order-insensitive; logs a WARN on mismatch, never throws), and returns the per-aspect (primary) result only. So multi-aspect can be shadow-validated in production with zero member-facing risk before flipping to MULTI_ASPECT. Comparison is by aspect identity (urn, aspect, version), which catches the real read-path risks (missing / extra / duplicate aspects, count and soft-delete-filtering differences).

Tests

The two stub tests from #641 are upgraded to full assertions, plus new coverage for the review feedback:

• SQLStatementUtilsTest.testCreateMultiAspectReadSql — asserts the exact bundled SQL for includeSoftDeleted false/true, using real production dataset URNs (from the PR test(ebean-dao): baseline benchmark for pre-#622 multi-aspect read [META-24100] #640 read benchmark).
• EbeanLocalAccessTest.testBatchGetUnionMultiAspectMatchesPerAspect — per-aspect vs multi-aspect result parity, including missing-column and non-existent-urn skip.
• EbeanLocalAccessTest.testBatchGetUnionMultiAspectExcludesSoftDeletedAspect — soft-delete behavior (requested in review): a soft-deleted aspect is excluded when includeSoftDeleted=false and returned/flagged when true, with per-aspect parity.
• EbeanLocalAccessTest.testBatchGetUnionMultiAspectDeduplicatesRepeatedKeys — duplicate (urn, aspect) keys collapse to one result, matching the per-aspect path.

All pass locally (only the unrelated pre-existing macOS-only testParseLocalRelationshipField flake fails).

Review feedback addressed

• Case-insensitive / canonical urn matching (row-driven mapping).
• Duplicate (urn, aspect) key parity (+ test).
• Removed redundant second validator.columnExists pass.
• Soft-delete behavior test (carried over from the reference PR perf(ebean-dao): collapse N per-aspect SQL queries into 1 in batchGetUnion #622 review).

Notes / follow-up

• URN chunking for very large IN (...) lists is intentionally not included here and can be added in a later change.
• Multi-aspect filter (list / listUrns) support is a separate follow-up (PR 3), reusing readSqlRowForAspect.
• Rollout stays gated behind AspectReadStrategy (PER_ASPECT default → DUAL compare → MULTI_ASPECT).

[ZihanLi58]

Just curious, which of the decorator we are using now? we have instrumental one and the usage tracking ones..

[darshilbhayani92]

It's host-configured and the two compose in EbeanLocalDAO — base EbeanLocalAccess, optionally wrapped by InstrumentedEbeanLocalAccess (setBenchmarkMetrics) and/or UsageTrackingEbeanLocalAccess (setUsageEmitter, one-shot, skipped for NoOpDaoUsageEmitter), in either order. So at runtime it can be none / either / both.

The important guarantee is that the new read behaves identically under any of those configs. I verified batchGetUnionMultiAspect has exact parity with batchGetUnion in both decorators:

• UsageTracking: delegates + emitRead("batchGetUnionMultiAspect", ...) with the same emissionEnabled() && !isTestMode && !DaoReadContext.isInternalRead() gating.
• Instrumented: instrument("batchGetUnionMultiAspect", ..., bucketCount(keys.size()), ...) — same pattern.

So usage events still fire and benchmark timings are still recorded for the multi-aspect path regardless of which decorator(s) are active — no coverage gap. No code change needed.

[ZihanLi58]

Is this check needed? or we can do it by check the sqlRow directly?

[darshilbhayani92]

Cleaned up — the previous version called validator.columnExists(...) twice (once when grouping keys, once again in the mapping pass). The rewrite computes it once during key collection; the mapping pass is now purely row-driven and reads columns straight off the SqlRow (skipping null cells via sqlRow.get(columnName) == null), so the redundant second check is gone. (cb39303)

[ZihanLi58]

sqlRow.getString("urn") might not match entityUrn.toString(), as we have canical urn stuff, you might want to make it case insensitive.

[ZihanLi58]

check with @mridul111998 for more context on this

[darshilbhayani92]

Good catch — fixed. The old code did an exact-string urnToRow.get(entityUrn.toString()) lookup, which would silently drop an aspect if the stored urn differed from the requested urn by canonical/case. I reworked the mapping to be row-driven (like the per-aspect path): it now iterates the returned rows and matches each against the requested (urn, aspect) pairs via a case-insensitive key (matchKey lower-cases the urn). The returned aspect's urn is derived from the row itself, so it matches per-aspect output exactly. (cb39303)

[chmeng0]

the fix looks clean.
not blocking: might worth noting that it relies on the urn column being case-insensitively collated so WHERE urn IN (...) returns case-variant rows for matchKey - mysql's default utf8mb4 collation is _ci, which is fine, if we ever need to use this with TiDB (default utf8mb4_bin, case sensitive), might need to explicitly pin ci collation

[ZihanLi58]

Small edge-case:  If a direct  IEbeanLocalAccess  caller passes duplicate  (urn, aspect)  keys, the multi-aspect path returns duplicates while the per-aspect path returns one result because it groups into  Set. Not an issue for  EbeanLocalDAO.get(...)  if all callers go through the  Set  API, but worth either matching the per-aspect behavior or documenting/testing the expected direct-access behavior.

[darshilbhayani92]

Fixed as part of the same row-driven rewrite. Requested (urn, aspect) pairs now go into a requestedPairs Set, and the mapping loop uses requestedPairs.remove(...) — which both restricts output to requested pairs and collapses duplicate keys to a single result, matching the per-aspect path's Set<Urn> grouping. Added testBatchGetUnionMultiAspectDeduplicatesRepeatedKeys asserting parity when the same key is passed twice. (cb39303)

[chmeng0]

LGTM