Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đã đóng
  • Có gì không ổn?
#2,992 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@contrueCT đang làm issue này rồi.

Từ ngày 13/4/2026.

  • #2994 của @contrueCT — đang mở

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
java
Lĩnh vực
databases

Hướng nghiên cứu

Bắt đầu với ConditionQuery.condition(Object key), sau đó kiểm tra các caller được liệt kê: GraphTransaction.constructEdgesQuery(), GraphTransaction.matchPartialEdgeSortKeys(), GraphIndexTransaction.queryByLabel(), BinarySerializer.writeQueryEdgePrefix() và HugeTraverser. So sánh caller nào cần các điều kiện thô và caller nào cần một label được resolve duy nhất, sử dụng #2933 và PR #2990 làm ngữ cảnh. Được xem là hoàn thành khi API contract phân biệt được các kết quả absent, unique, empty và multiple, đồng thời các caller không còn dựa vào ngữ nghĩa null mơ hồ.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

api feature improvement

Background

While fixing #2933, we found that ConditionQuery.condition() currently mixes multiple different semantics into a single API.

The immediate bug in #2933 has been fixed separately, but this method still has unclear behavior boundaries and several callers implicitly rely on assumptions that are not obvious from the method contract.

Current behavior

ConditionQuery.condition(Object key) may currently produce different kinds of results depending on how conditions are stored:

  1. Return null

    • when there is no condition for the given key

  2. Return null

    • when conditions exist for the key, but the intersection becomes empty

  3. Return a single value

    • for example, a single EQ

  4. Return the whole IN list

    • when there is one IN condition and no EQ

  5. Throw IllegalStateException

    • when the intersection still contains multiple candidates

That means the same method is currently used for:

  • raw condition lookup
  • unique-value extraction
  • empty-intersection signaling
  • multi-value conflict signaling

Why this is a problem

These states are semantically different, but the API does not distinguish them clearly.

For example:

ConditionQuery q1 = new ConditionQuery(HugeType.EDGE);
// no LABEL condition

ConditionQuery q2 = new ConditionQuery(HugeType.EDGE);
q2.eq(HugeKeys.LABEL, label1);
q2.eq(HugeKeys.LABEL, label2);
// conflicting LABEL conditions, intersection is empty

Both of these may currently lead to:

q1.condition(HugeKeys.LABEL) == null
q2.condition(HugeKeys.LABEL) == null

But they do not mean the same thing:

  • q1: no such condition exists
  • q2: the condition exists, but it is contradictory

Also, for LABEL, the method can return a raw IN list in some cases, even though many callers use it as if it were always either a unique Id or null.

Evidence in current code

LABEL can be stored as IN

Multi-label edge queries are constructed like this:

query.query(Condition.in(HugeKeys.LABEL, edgeLabels));

See:

  • GraphTransaction.constructEdgesQuery(...)
many callers assume unique label or null

Examples:

  • GraphTransaction.matchPartialEdgeSortKeys(...)
  • GraphIndexTransaction.queryByLabel(...)
  • BinarySerializer.writeQueryEdgePrefix(...)
  • HugeTraverser

These call sites typically do:

Id label = query.condition(HugeKeys.LABEL);

which means they implicitly expect condition(HugeKeys.LABEL) to behave like a "resolved unique label" API, not a raw condition accessor.

Suggested direction

This issue is not about changing behavior immediately in a bugfix PR. It is about clarifying and improving the API contract.

Possible follow-up directions:

  1. Split responsibilities into different APIs

    • one API for raw condition retrieval
    • one API for unique-value resolution / intersection result

  2. Introduce an explicit result type

    • absent
    • unique value
    • empty intersection
    • multiple values

  3. Audit call sites of condition(HugeKeys.LABEL)

    • identify which ones want raw values
    • identify which ones want a unique resolved label
    • remove reliance on ambiguous null semantics

Scope

This issue is a follow-up design / refactor task exposed by the fix for #2933.

Related:

  • #2933
  • PR #2990

I’d be happy to follow up on this as a separate improvement issue and work on a later refinement PR.

Ngôn ngữ chính
Java
Star
3.2k
Fork
641
Merge trung bình
1 ngày 9 giờ
Pull request đã merge (30 ngày)
74

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của apache/hugegraph

Tất cả issue của apache/hugegraph

Issue tương tự

Thêm issue về Java

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.