fix(query): clarify condition resolution semantics for label queries

[contrueCT]

Purpose of the PR

• close [Improve]: clarify ConditionQuery.condition() semantics for missing, conflicting, and multi-value conditions #2992

ConditionQuery.condition() currently mixes several different meanings in one API, including:

• no condition
• conflicting conditions resolved to empty
• a unique resolved value
• a raw multi-value result
• an exception for ambiguous resolved values

This PR keeps the legacy condition() behavior unchanged, adds explicit condition-resolution APIs, and migrates the high-risk LABEL call sites to use the clearer semantics.

Main Changes

• Add explicit condition-resolution APIs to ConditionQuery
  • containsCondition(Object key)
  • conditionValues(Object key)
  • conditionValue(Object key)
• Keep the legacy condition() method backward-compatible
• Document the semantic differences between the legacy API and the new explicit APIs
• Migrate LABEL-related high-risk callers to the new APIs in:
  • graph/index transactions
  • serializers
  • traversers
  • in-memory / hstore paths
• Preserve the old behavior for non-LABEL legacy usages in this first step

Verifying these changes

Added and extended regression coverage for the new semantics:

• QueryTest#testConditionWithoutLabel
• QueryTest#testConditionWithEqAndIn
• QueryTest#testConditionWithSingleInValues
• QueryTest#testConditionWithConflictingEqAndIn
• QueryTest#testConditionWithMultipleMatchedInValues

Added a targeted regression for the label-index fallback path:

• VertexCoreTest#testCollectMatchedIndexesByJointLabelsWithIndexedProperties

This test verifies:

• a multi-label query can conservatively fall back and still match the indexed label
• conflicting label conditions produce no matched indexes

Existing label-query regressions were also rechecked to ensure no behavior regression:

• EdgeCoreTest#testQueryInEdgesOfVertexByLabels
• EdgeCoreTest#testQueryInEdgesOfVertexByConflictingLabels
• EdgeCoreTest#testQueryInEdgesOfVertexBySortkey
• VertexCoreTest#testQueryByJointLabels

• Trivial rework / code cleanup without any test coverage. (No Need)
• Already covered by existing tests, such as (please modify tests here).
• Need tests and can be verified as follows:
  • mvn -pl hugegraph-server/hugegraph-test -am -P core-test,memory -DfailIfNoTests=false -Dtest='QueryTest#testConditionWithoutLabel+testConditionWithEqAndIn+testConditionWithSingleInValues+testConditionWithConflictingEqAndIn+testConditionWithMultipleMatchedInValues' test
  • mvn -pl hugegraph-server/hugegraph-test -am -P core-test,memory -DfailIfNoTests=false -Dtest='EdgeCoreTest#testQueryInEdgesOfVertexByLabels+testQueryInEdgesOfVertexByConflictingLabels+testQueryInEdgesOfVertexBySortkey' test
  • mvn -pl hugegraph-server/hugegraph-test -am -P core-test,memory -DfailIfNoTests=false -Dtest='VertexCoreTest#testQueryByJointLabels+testCollectMatchedIndexesByJointLabelsWithIndexedProperties' test

Does this PR potentially affect the following parts?

• Dependencies (add/update license info & regenerate_known_dependencies.sh)
• Modify configurations
• The public API
• Other affects (typed here)
• Nope

Documentation Status

• Doc - TODO
• Doc - Done
• Doc - No Need

[codecov]

Codecov Report

❌ Patch coverage is 0% with 245 lines in your changes missing coverage. Please review.
✅ Project coverage is 1.47%. Comparing base (1f61c48) to head (9e24432).
⚠️ Report is 6 commits behind head on master.

Files with missing lines	Patch %	Lines
...apache/hugegraph/backend/query/ConditionQuery.java	0.00%	66 Missing ⚠️
...he/hugegraph/backend/tx/GraphIndexTransaction.java	0.00%	57 Missing ⚠️
...che/hugegraph/store/client/NodeTxSessionProxy.java	0.00%	29 Missing ⚠️
...va/org/apache/hugegraph/backend/page/IdHolder.java	0.00%	23 Missing ⚠️
...a/org/apache/hugegraph/backend/page/QueryList.java	0.00%	14 Missing ⚠️
...he/hugegraph/traversal/optimize/TraversalUtil.java	0.00%	14 Missing ⚠️
...ava/org/apache/hugegraph/store/client/NodeTkv.java	0.00%	13 Missing ⚠️
.../apache/hugegraph/backend/tx/GraphTransaction.java	0.00%	11 Missing ⚠️
...ache/hugegraph/backend/page/PageEntryIterator.java	0.00%	5 Missing ⚠️
...hugegraph/backend/serializer/BinarySerializer.java	0.00%	5 Missing ⚠️
... and 3 more

❗ There is a different number of reports uploaded between BASE (1f61c48) and HEAD (9e24432). Click for more details.

HEAD has 2 uploads less than BASE

Flag	BASE (1f61c48)	HEAD (9e24432)
	3	1

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #2994       +/-   ##
============================================
- Coverage     36.11%   1.47%   -34.64%     
+ Complexity      338      21      -317     
============================================
  Files           803     781       -22     
  Lines         68234   65894     -2340     
  Branches       8964    8550      -414     
============================================
- Hits          24640     975    -23665     
- Misses        40936   64835    +23899     
+ Partials       2658      84     -2574     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[imbajin]

I found one correctness issue in the latest revision. The CI failures were posted separately as a PR-level reminder.

CI/status checks are failing on the latest head (cc9af24929e42af1c90e1f55f3e60adc351e0318). Could you check the failed jobs before the next review round?

Failed checks include:

• build-server (memory, 11): https://github.com/apache/hugegraph/actions/runs/26448131941/job/77861497015

[imbajin]

I don't see a clear blocking correctness issue in the latest head, and the previous LABEL-resolution comments look addressed. One remaining merge risk is that the latest checks are still red: hstore failed in VertexCoreTest#testQueryByDateProperty.

Since this PR also touches HstoreStore, could you rerun or clarify whether the hstore failure is an existing flaky/environment issue?

[contrueCT]

Thanks for your patience. The hstore CI failure exposed an existing latent issue in hstore's range-index query path. For range-index scans with limit/paging, the upper layer assumed that backend scan results were globally ordered by the range-index key and that the returned page state could be reused as a HugeGraph range cursor. In hstore, multi-node/tablet scans can return entries in backend iterator order, and the page state is an internal storage cursor, so those assumptions may lead to unstable ordering or skipped results. This PR keeps the fix intentionally scoped: hstore range-index queries whose visible result depends on limit/offset/paging are sorted and sliced in the index layer, while unbounded scans still use the original streaming path to avoid disturbing count, joint-index, and cleanup paths. I think this is enough for the current PR, but the underlying hstore scan/page-state contract should be handled in a dedicated follow-up, ideally by defining whether range scans must be globally ordered and fixing the hstore iterator/page-state semantics at the storage-client layer.

[imbajin]

Blocking: yes. Summary: HStore range-index offset queries can skip too many sorted results. Evidence: static review of GraphIndexTransaction/query offset handling.

[contrueCT]

Thanks. I fixed this by resetting scanQuery.offset(0L) before the full sorted range-index scan, so the fallback now reads the complete matched range first and lets the original query apply offset/limit only once after sorting. I also added range-offset coverage to VertexCoreTest#testQueryByDateProperty to guard the double-skip case. Local checks passed with git diff --check, hugegraph-core compile, and VertexCoreTest#testQueryByDateProperty under the rocksdb core-test profile.

[imbajin]

Blocking: yes. Summary: HStore range-index ordering is still bypassed for finite non-paging and large-page scans. Evidence: static review plus local unit/store-client tests.

---

🔗 Latest-head CI/status still has visible failures; please check hstore, codecov/patch, and codecov/project: https://github.com/apache/hugegraph/actions/runs/27525154399/job/81350967135

[imbajin]

‼️ Keep ordered range scans on every order-sensitive HStore path

Evidence: GraphIndexTransaction.keepBackendIndexOrder() marks HStore range indexes as order-sensitive whenever the original query has a finite limit/offset, but this gate only enables the new globally ordered merge for paging && limit <= net.kv.scanner.page.size. The fallback below still calls session.scan(...), which reaches the legacy mergeRangeScanIterators() path in NodeTxSessionProxy; its existing test asserts partition/top-work order like 3,1,4,2, not global range-key order.

Impact: multi-partition HStore range-index queries can still return the wrong first n ids, skip the wrong ids for range()/offset, or page incorrectly when the requested page size is above the scanner page size. Please route all order-sensitive HStore range-index scans through the ordered merge, or make the graph layer fall back to a correctness-preserving full ordered scan before applying offset/limit.

[imbajin]

Blocking: no. Summary: No obvious issues found in the current head. Evidence: git diff --check; QueryTest/QueryResultsTest/GraphIndexTransactionTest 14 tests passed; VertexCoreTest/EdgeCoreTest 438 tests passed; HstoreTableTest 2 tests passed; latest GitHub checks passed.