bitflicker64 commented on code in PR #503: URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4251306711
########## content/en/docs/clients/restful-api/vertex.md: ########## @@ -367,14 +367,27 @@ PUT http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices/"1 #### Params - label: Vertex type -- properties: Property key-value pairs (precondition: indexes are created for property queries) +- properties: Property key-value pairs (see index coverage below) - keep_start_p: Default is false. When set to true, the range matching input expression will not be automatically escaped. For example, `properties={"age":"P.gt(18)"}` will be interpreted as an exact match, i.e., the age property is equal to the string "P.gt(18)" - offset: Offset, default is 0 - limit: Maximum number of results, default is 100 - page: Page number All of the above parameters are optional. `page` can not be combined with a non-zero `offset`, everything else can be combined in any way. +If `label` selects a vertex label with the `PRIMARY_KEY` ID strategy and `properties` supplies exact values for all its primary-key fields, the query looks up +the vertex by ID and checks additional property conditions on that vertex without a property index. If all primary-key fields have conditions but any of them +uses a range condition, the query is rejected before property-index lookup, even if a matching property index exists. + +For other `properties` queries, the specified `label` needs a property index compatible with the query conditions. If `label` is omitted, candidate labels are +query-visible vertex labels that declare all queried properties, including labels that currently have no vertices. Labels hidden from normal query results, +including those being deleted, do not require coverage. A label index alone does not index properties. + +For query values compatible with the declared property types, no compatible index or partial candidate coverage produces an index error; complete coverage uses Review Comment: Important: the coverage rules on these pages carry no version, but the partial-coverage error exists only in the open apache/hugegraph#3243. Checked on 2026-10-13: apache/hugegraph `master` at 68fb045 has no `checkIndexCoverage`; `GraphIndexTransaction.queryByUserprop()` calls `collectMatchedIndexes(query)` (line 369), and the 1.7.0 tag does the same. An unlabeled query with partial coverage returns only the matches from indexed labels and raises no error. A reader on 1.7.0 who sees no error will take that partial result for a complete one, because this sentence says an error would have been raised. Requested change: add a version note beside this paragraph on all four pages, in the "Since 1.7.0" style the docs already use, for example: "The partial-coverage error applies from <the release that contains #3243>. Earlier versions return only the matches from indexed labels and raise no error." The other lines are EN edge.md 432, CN vertex.md 426 and CN edge.md 434. The description already commits to merging with or after #3243. Since then #3243 received a new `Blocking: yes` review (imbajin, 2026-10-02, on 7f5a917) asking for an empty result when every candidate label is hidden or deleting. If that lands, this sentence and "If no index matches, the index error still applies" need a qualifier for that case, so please re-check them after #3243 merges. ########## content/en/docs/clients/restful-api/edge.md: ########## @@ -416,12 +416,26 @@ It is not possible to delete an attribute that is not set as nullable. - vertex_id: Vertex ID - direction: Edge direction (OUT | IN | BOTH), default is BOTH - label: Edge label -- properties: Key-value pairs of properties (requires pre-built indexes for property queries) +- properties: Key-value pairs of properties (see index coverage below) - keep_start_p: Default is false. When set to true, the range matching input expression will not be automatically escaped. For example, `properties={"age":"P.gt(0.8)"}` will be interpreted as an exact match, i.e., the age property is equal to "P.gt(0.8)" - offset: Offset, default is 0 - limit: Number of queries, default is 100 - page: Page number +Without `vertex_id`, a `properties` query searches edges globally. The specified `label` needs a property index compatible with the query conditions. If `label` +is omitted, candidate labels are query-visible edge labels that can hold edges and declare all queried properties, including labels that currently have no +edges. Labels hidden from normal query results, including those being deleted, do not require coverage. A base (parent) edge label has no direct edges and does +not need a separate index when its sub-labels are covered. A compatible index on a query-visible parent label can cover its sub-labels; compatible indexes on Review Comment: Minor: the parent and sub-label sentences are not tied to the omitted-label case, so a reader who passes `label` can apply "A compatible index on a query-visible parent label can cover its sub-labels" to their own query. At apache/hugegraph#3243 head 7f5a917, `GraphIndexTransaction.collectMatchedIndexes()` uses `ImmutableList.of(schemaLabel)` when the query has a label, and `collectMatchedIndex()` reads only that label's `indexLabels()`; `IndexLabelBuilder` attaches an index to its own base label only. From reading the code (not from a run): - `label=<sub-label>` with an index only on the parent fails with `not indexed in label '<sub-label>'`. - `label=<parent>` with indexes only on the sub-labels fails the same way for the parent. Requested change: start the parent sentences with "When `label` is omitted," and add "When `label` is specified, only indexes created on that label are used." Mirror it in content/cn/docs/clients/restful-api/edge.md line 432. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
