[contrueCT]

Summary

Clarify the property-index query rules beside the existing properties parameters in the English and Chinese Vertex and Edge REST API pages.

• Define query-visible candidate labels, including empty labels and the parent/sub-edge coverage rule. A parent index can cover sub-labels only when the parent is visible to the query.
• Distinguish no/partial/complete compatible coverage for type-valid values and the empty-result exception for type-incompatible values after an index matches.
• Explain labeled PRIMARY_KEY direct lookup, rejection of range conditions when all primary-key fields are supplied, and vertex_id-bounded adjacency.
• Wrap added prose close to 160 characters per line, allowing shorter paragraph endings; keep Chinese line breaks at sentence endings and related conditions in the same paragraph.

Related code: apache/hugegraph#3243. Related scope: apache/hugegraph#3201; its selective fallback optimization remains open. Publish this documentation with or after #3243: released versions can still silently omit matches under partial coverage.

Validation

• git diff --check and added-prose line-length / Chinese sentence-boundary checks passed.
• bash dist/validate-links.sh passed.
• Strict production scripts/hugo.sh build passed locally on macOS arm64 with Hugo Extended 0.165.0 and Go 1.27.1; the pinned OINK v1.1.0 module and checksums were verified with scripts/oink_module.py.
• Rendered English/Chinese Vertex/Edge paragraphs checked for the primary-key range restriction and parent visibility qualification, including placement next to the existing rules and Chinese whitespace.
• Content-only change; routes, navigation, configuration and visual assets are unchanged.

Conceptual overview

Conceptual documentation overview of property-index coverage and the boundaries of primary-key and adjacency queries. This diagram is not query-performance or release acceptance evidence.

[imbajin]

Blocking: no. Summary: The index-coverage guidance matches the paired query fix, with one exception for labeled primary-key lookups. Evidence: In apache/hugegraph#3243 head f435a1f, GraphTransaction.optimizeQuery() converts a labeled query containing every primary-key field into an IdQuery, bypassing property-index lookup.

[imbajin]

Blocking: no. Summary: The index-coverage guidance is clear overall, with two minor edge cases noted inline. Evidence: Static review against GraphIndexTransaction.java and SourceIndexCoverageTest.java at apache/hugegraph#3243 head 0de33ed.

[bitflicker64]

Blocking: no. Summary: The coverage rules match GraphIndexTransaction.checkIndexCoverage() and GraphTransaction.optimizeQuery() at apache/hugegraph#3243 head 0de33ed, including the PRIMARY_KEY direct lookup and the vertex_id adjacency path; one Chinese line break renders as a stray space. The two open Minor threads on invalid values and parent edge labels still apply at this head and are not repeated here. Evidence: static review of 1e67982 against GraphIndexTransaction.java (queryIndex, queryByUserprop, collectMatchedIndexes, checkIndexCoverage), GraphTransaction.optimizeQuery(), HugeVertexStep (resetUserpropConditions for adjacency filters), EdgeAPI.list and SourceIndexCoverageTest at 0de33ed; hugo.yaml markup.goldmark has no cjk extension.

[bitflicker64]

Blocking: no. Summary: The coverage rules match GraphIndexTransaction at apache/hugegraph#3243 head 7f5a917, including the new hidden/deleting label filter, the father-label skip and the invalid-value ordering. One gap remains: a labeled PRIMARY_KEY query with a non-exact condition on a primary-key field is rejected by the server, not routed to a property index as the new text implies. Evidence: static review of c87d249 against GraphTransaction.optimizeQuery(), ConditionQuery.matchUserpropKeys() and ConditionQuery.userpropValuesString() at 7f5a917; no server was run.

[imbajin]

Blocking: no. Summary: The edge coverage guidance needs one visibility qualification for parent indexes. Evidence: apache/hugegraph#3243 at 7f5a917; GraphIndexTransaction.collectMatchedIndexes() filters labels using rootOriginQuery() visibility before checkIndexCoverage().

[bitflicker64]

Blocking: yes. Summary: The coverage, PRIMARY_KEY, parent/sub-label, invalid-value and vertex_id rules match apache/hugegraph#3243 at 7f5a917 and the English and Chinese pages agree, but the pages carry no version note although master and 1.7.0 return partial results without an error, and #3243 has since received a Blocking: yes review on the hidden/deleting case. Evidence: read the full diff at bf47acf (4 files, +44/-4) and the surrounding sections of all four pages; static comparison with GraphIndexTransaction (queryByUserprop, collectMatchedIndexes, checkIndexCoverage, updateEdgeIndex), GraphTransaction.optimizeQuery(), ConditionQuery.matchUserpropKeys()/userpropValuesString(), VertexAPI.list, EdgeAPI.list, HugeVertexStep.constructEdgesQuery() and SourceIndexCoverageTest at 7f5a917; GraphIndexTransaction.java on apache/hugegraph master at 68fb045 and at tag 1.7.0 has no checkIndexCoverage. No server was run and the PR reports no CI checks at this head.

[bitflicker64]

Blocking: no. Summary: The coverage, PRIMARY_KEY, parent/sub-label, invalid-value, vertex_id and version-note text matches apache/hugegraph#3243 at its current head 83ac535, and the English and Chinese pages agree. One case the server now handles is missing: when every candidate label is hidden or being deleted, the query returns an empty result, not the index error these pages promise. Evidence: read the full diff at 5e93292 (4 files, +51/-4) and the surrounding sections of all four pages; static comparison with GraphIndexTransaction.queryByUserprop(), querySchemaLabels() and checkIndexCoverage(), GraphTransaction.optimizeQuery(), ConditionQuery.userpropValuesString(), VertexAPI.list, EdgeAPI.list, SourceIndexCoverageTest and docs/server-runtime.md at 83ac535. master at f5d9885 still has no checkIndexCoverage. No server was run and the PR reports no CI checks at this head.

[bitflicker64]

Blocking: no. Summary: The coverage, visibility, all-candidates-hidden, base/sub edge label, invalid-value, version-note and vertex_id rules match apache/hugegraph#3243 at its current head 83ac535, and the English and Chinese pages agree. One sentence in the PRIMARY_KEY paragraph calls the rejected case a "range condition", but this page's own range-matching table includes P.eq and P.within, which take the primary-key ID lookup and are not rejected. Evidence: read the full diff at 519999d (4 files) and the surrounding sections of all four pages; static comparison with GraphIndexTransaction.queryByUserprop(), isIndexQueryCandidate() and checkIndexCoverage(), GraphTransaction.optimizeQueries()/optimizeQuery(), ConditionQuery.matchUserpropKeys()/userpropValuesString(), ConditionQueryFlatten.convIn2Or(), TraversalUtil.convIn2Relation(), EdgeAPI.list, HugeVertexStep, SourceIndexCoverageTest and docs/server-runtime.md at 83ac535. No server was run; the site build workflow at this head is waiting for maintainer approval.

[bitflicker64]

Blocking: no. Summary: The new P.eq/P.within wording in the PRIMARY_KEY paragraph matches apache/hugegraph#3243 at 83ac535, and the coverage, visibility, base/sub edge label, invalid-value and vertex_id rules still match it; the English and Chinese pages agree. Two small points remain: the rewritten Chinese PRIMARY_KEY paragraph breaks mid-sentence again, and the hidden/deleting empty-result sentence is not covered by the version note although released servers raise an index error in that case. Evidence: read the full diff at 6ac76d8 (4 files, +57/-4) and the incremental change ef3bf8e since the last review; static comparison with GraphIndexTransaction.queryByUserprop(), isIndexQueryCandidate() and checkIndexCoverage(), GraphTransaction.optimizeQueries()/optimizeQuery(), ConditionQueryFlatten.convIn2Or(), EdgeAPI.list and HugeVertexStep.constructEdgesQuery() at 83ac535, and queryByUserprop() on apache/hugegraph master c2ec570; hugo.yaml at this head has no goldmark cjk extension. No server or site build was run; the exact-head site build run is action_required and has not run.

[imbajin]

Blocking: no. Summary: The vertex index coverage guidance omits the shared OLAP index path; see the inline comment. Evidence: Exact-head paired source review of apache/hugegraph#3243 at 83ac535, including GraphIndexTransaction.java.

[bitflicker64]

Blocking: yes. Summary: At c1aa831 the PRIMARY_KEY, visibility, all-candidates-hidden, OLAP, invalid-value, version-note and vertex_id rules match apache/hugegraph#3243, the English and Chinese pages agree, and every earlier review thread is addressed. One sentence went stale an hour after this head was pushed: #3243 head 3b597b7 now lets an explicit sub-edge label use a compatible query-visible parent index, while these edge pages say only indexes on the specified label are used. #3243 is still open and master has none of this behaviour, which the version note already says. Evidence: read the full diff at c1aa831 (4 files, +61/-4) and the surrounding sections of all four pages; static comparison with GraphIndexTransaction (queryByUserprop, querySchemaLabels, collectMatchedIndexes, prepareIndexQuery, isIndexQueryCandidate, requiredIndexProperties, checkIndexCoverage, collectMatchedIndex), GraphTransaction.optimizeQueries()/optimizeQuery(), EdgeAPI.list and SourceIndexCoverageTest at 3b597b7, and with GraphIndexTransaction on apache/hugegraph master fd8d06c. I ran no server or site build; the #3243 server memory and RocksDB jobs passed at 3b597b7, and this PR's site build run is action_required.

[imbajin]

Blocking: no. Summary: The hidden-label empty-result guarantee is broader than current server behavior for an explicitly selected label that is not a coverage candidate. Evidence: Static control-flow trace on apache/hugegraph#3243 at 3b597b76.

[bitflicker64]

Blocking: no. Summary: At 25d1d94 the PRIMARY_KEY, visibility, sub-edge parent-index, base-label, OLAP, invalid-value, version-note and vertex_id text matches apache/hugegraph#3243 as merged to master (86c05ef, same GraphIndexTransaction as head 3b597b7), the English and Chinese pages agree, and every earlier review thread is addressed. One regression: the last commit split the Chinese version note after "；" on both Chinese pages, so the rendered sentence gets a stray space again (inline). Evidence: read the full diff df23ce2..25d1d94 (4 files, +67/-4), the incremental change c1aa831..25d1d94, and the surrounding sections of all four pages; static comparison with GraphIndexTransaction.queryByUserprop(), querySchemaLabels(), collectMatchedIndexes(), isIndexQueryCandidate(), requiredIndexProperties(), checkIndexCoverage(), collectMatchedIndex() and prepareIndexQuery(), GraphTransaction.optimizeQueries()/optimizeQuery(), ConditionQuery.matchUserpropKeys()/userpropValuesString() and ConditionQueryFlatten.convIn2Or() at apache/hugegraph 86c05ef; hugo.yaml at this head has no goldmark cjk extension; git diff --check is clean. No server or site build was run; the site build run at this head is action_required.

[bitflicker64]

Minor: 25d1d94 split the version note after "；", so this sentence renders with a stray space: "...适用于包含 apache/hugegraph#3243 的版本； 早期版本仅使用...". hugo.yaml at this head still has no markup.goldmark.extensions.cjk setting, so Goldmark keeps the soft break as a newline and browsers show it as a space between the two Chinese clauses. This is the same rendering issue settled in the earlier line-break threads, where the Chinese paragraphs were agreed to break only after "。"; at c1aa831 this note was still one line. The same split was added in content/cn/docs/clients/restful-api/vertex.md line 430.

Requested change: join lines 436 and 437 here, and lines 430 and 431 in the Chinese vertex.md, back into one line each, or end the first part with "。" instead of "；".

[imbajin]

Blocking: no. Summary: The index-coverage guidance misses two PRIMARY_KEY and candidate-visibility edge cases. Evidence: apache/hugegraph master 86c05ef GraphTransaction, ConditionQuery, GraphIndexTransaction and TraversalUtil.

[imbajin]

⚠️ Important: This says every non-exact primary-key condition is rejected, but the PRIMARY_KEY fast path calls userpropValuesString(), which explicitly accepts RelationType.CONTAINS. The REST predicate parser maps P.contains to that relation, and multi-valued primary-key properties are not rejected by schema validation; a contains query can therefore build an ID from one member and miss the stored vertex instead of returning the promised error. Please handle P.contains separately here and in Chinese, or reject it before the optimizer takes the primary-key path.

[imbajin]

⚠️ Important: The docs define candidates after filtering to query-visible labels, then say every candidate being hidden or deleting returns an empty result. In the server, that empty path requires at least one schema label to otherwise match the queried properties and all such labels to be excluded; if no schema label declares those properties, the query raises NoIndexException. Please define candidates before visibility filtering and state this condition across the EN/CN Vertex and Edge pages.