fix(query): clarify condition resolution semantics for label queries by contrueCT · Pull Request #2994 · apache/hugegraph

contrueCT · 2026-04-13T11:15:30Z

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 · 2026-05-06T03:21:33Z

Codecov Report

❌ Patch coverage is 0% with 95 lines in your changes missing coverage. Please review.
✅ Project coverage is 1.56%. Comparing base (f56462a) to head (2e82f83).
⚠️ Report is 2 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%	12 Missing ⚠️
...hugegraph/backend/serializer/BinarySerializer.java	0.00%	5 Missing ⚠️
...e/hugegraph/backend/serializer/TextSerializer.java	0.00%	5 Missing ⚠️
.../apache/hugegraph/backend/tx/GraphTransaction.java	0.00%	5 Missing ⚠️
...g/apache/hugegraph/backend/store/ram/RamTable.java	0.00%	2 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (f56462a) and HEAD (2e82f83). Click for more details.

HEAD has 1 upload less than BASE

Flag BASE (f56462a) HEAD (2e82f83)

3 2

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #2994       +/-   ##
============================================
- Coverage     35.94%   1.56%   -34.39%     
+ Complexity      338      43      -295     
============================================
  Files           803     781       -22     
  Lines         68053   65586     -2467     
  Branches       8907    8469      -438     
============================================
- Hits          24465    1026    -23439     
- Misses        40967   64474    +23507     
+ Partials       2621      86     -2535

☔ View full report in Codecov by Sentry.
📢 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.

Add explicit condition resolution APIs to ConditionQuery while preserving the legacy condition() behavior. Introduce containsCondition(Object), conditionValues(Object), and conditionValue(Object) so callers can distinguish missing, empty, unique, and multi-value results without overloading null semantics. Migrate LABEL-specific consumers in graph/index transactions, serializers, traversers, and stores to use the new APIs for unique-label resolution and conservative fallback behavior. Extend QueryTest and VertexCoreTest to cover absent, conflicting, and multi-value label conditions as well as collectMatchedIndexes() behavior for multi-label and conflicting label queries.

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 · 2026-05-29T08:00:49Z

        List<? extends SchemaLabel> schemaLabels;
-        if (label != null) {
-            // Query has LABEL condition
+        if (hasLabel && labels.isEmpty()) {


‼️ This now treats non-EQ/IN label predicates as an empty label intersection.

containsCondition(HugeKeys.LABEL) returns true for any top-level LABEL relation, but conditionValues(HugeKeys.LABEL) only collects EQ/IN relations. For a query such as has(T.label, P.neq("author")).has("name", ...), TraversalUtil can produce a Condition.neq(HugeKeys.LABEL, ...); hasLabel becomes true, labels is empty, and this branch returns no matched indexes immediately.

Before this change, query.condition(HugeKeys.LABEL) would not resolve a single label for this shape, so collectMatchedIndexes() fell back to scanning candidate schema labels and let the remaining conditions filter results. With the new branch, indexed user-property queries combined with a non-EQ/IN label predicate can incorrectly fail with no matched index / no result path.

Please distinguish "LABEL EQ/IN conditions resolved to an empty intersection" from "LABEL exists but has no EQ/IN-resolvable value". The latter should keep the conservative fallback, or add regression coverage for a label neq / non-EQ label predicate combined with an indexed user property.

dosubot Bot added the size:L This PR changes 100-499 lines, ignoring generated files. label Apr 13, 2026