bitflicker64 commented on code in PR #503: URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4303201026
########## content/en/docs/clients/restful-api/vertex.md: ########## @@ -367,14 +367,28 @@ 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. Review Comment: Minor: these pages do not cover the case where every candidate label is excluded by visibility. The server then returns an empty result, but the text here says a missing index produces an index error. Evidence, from apache/hugegraph#3243 at 83ac535 (the head this page is meant to ship with): - `GraphIndexTransaction.queryByUserprop()` line 384 returns an empty `IdHolderList` when candidates existed but none is visible (`hadCandidates && !hasVisibleCandidates`). That is before index matching, so the `noIndexException` at line 396 is never reached. - `SourceIndexCoverageTest.testAllVertexCandidatesDeletingReturnEmpty` (line 541) marks both labels `DELETING` and asserts an empty result for both `V().has("coverageName", "same")` and `V().hasLabel("coverageA").has(...)`. Lines 565-568 remove both index labels and still assert empty. `testOnlyEdgeCandidateDeletingReturnsEmpty` (line 583) asserts the same for edges. - The server's own `docs/server-runtime.md` line 267 has the row "Every candidate is excluded by visibility: the query returns an empty result, including after those labels' indexes have been removed". So a user who queries a label while it is being deleted (`label=X`, or unlabeled with `X` as the only label declaring the property) gets an empty result. This page says "the specified `label` needs a property index" and "no compatible index ... produces an index error", so they would expect an error. The earlier review on line 386 asked for this to be re-checked once the hidden/deleting change landed in #3243, and it has now landed there. Requested change: after this sentence, add "If the specified `label`, or every candidate label, is hidden or being deleted, the query returns an empty result instead of an index error." Mirror it in content/en/docs/clients/restful-api/edge.md (after the same sentence on lines 427-428), content/cn/docs/clients/restful-api/vertex.md line 424 and content/cn/docs/clients/restful-api/edge.md line 432, for example "如果指定的 `label` 或全部候选标签都不可见或正在删除，查询返回空结果，不报索引错误。" -- 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]
