bitflicker64 commented on code in PR #503: URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4307447742
########## content/cn/docs/clients/restful-api/vertex.md: ########## @@ -411,14 +411,25 @@ PUT http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices/"1 **请求参数说明：** - label: 顶点的类型 -- properties: 属性键值对（查询属性的前提是该属性已经建立了索引） +- properties: 属性键值对（索引覆盖要求见下文） - keep_start_p: 默认为 false，设置为 true 时不会自动转义范围匹配表达式，例如 `properties={"age":"P.gt(18)"}` 会被当作精确匹配，即 age 属性等于字符串 "P.gt(18)" - offset: 偏移量，默认为 0 - limit: 查询结果的最大数目，默认为 100 - page: 分页的页号 以上参数都是可选的，page 不能与非 0 的 offset 同时使用，其余参数之间可以任意组合。 +如果 `label` 指定的顶点标签使用 `PRIMARY_KEY` ID 策略，且 `properties` 为全部主键字段提供精确值（`P.eq` 与 `P.within` 均视作精确值）， +查询会直接按 ID 查找顶点，并在取回后检查其他属性条件，无需属性索引。如果包含全部主键字段，但任一字段不是精确值条件 +（如 `P.neq`、`P.gt`、`P.between`、`P.textcontains` 等），查询会在属性索引查询前被拒绝，即使存在匹配的属性索引也不例外。 Review Comment: Minor: ef3bf8e rewrapped this paragraph mid-sentence, so the rendered Chinese text gets stray spaces again. Line 422 now ends after "，" and line 423 ends inside the phrase "不是精确值条件" before "（如". `hugo.yaml` at this head still has no `markup.goldmark.extensions.cjk` setting, so Goldmark keeps each soft break as a newline and browsers show it as a space: "...均视作精确值）， 查询会..." and "...不是精确值条件 （如 `P.neq`...". The other new Chinese lines on this page and in edge.md break only after "。", as agreed in the earlier line-break thread. Could this paragraph break only after the first "。"? ```suggestion 如果 `label` 指定的顶点标签使用 `PRIMARY_KEY` ID 策略，且 `properties` 为全部主键字段提供精确值（`P.eq` 与 `P.within` 均视作精确值），查询会直接按 ID 查找顶点，并在取回后检查其他属性条件，无需属性索引。 如果包含全部主键字段，但任一字段不是精确值条件（如 `P.neq`、`P.gt`、`P.between`、`P.textcontains` 等），查询会在属性索引查询前被拒绝，即使存在匹配的属性索引也不例外。 ``` ########## content/en/docs/clients/restful-api/vertex.md: ########## @@ -367,14 +367,30 @@ 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 (`P.eq` and +`P.within` count as exact values), 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 is not an exact value (`P.neq`, `P.gt`, `P.between`, `P.textcontains` and similar), 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. If the specified `label`, or every candidate label, is hidden or being deleted, the query returns Review Comment: Minor: the empty-result rule for hidden or deleting labels exists only in apache/hugegraph#3243, but the version note on line 389 scopes only the partial-coverage error. - At #3243 head 83ac535, `GraphIndexTransaction.queryByUserprop()` filters `schemaLabels` by `rootOriginQuery()` visibility and returns an empty `IdHolderList` when `hadCandidates && !hasVisibleCandidates`, before `collectMatchedIndexes()` and `noIndexException()`. - On apache/hugegraph `master` (c2ec570) and 1.7.0, `queryByUserprop()` calls `collectMatchedIndexes(query)` over all labels with no visibility filter and throws `noIndexException()` when nothing matches. The #3243 description also says its hidden/deleting regressions failed with `NoIndexException` before the fix. So a 1.7.0 user who queries `label=X` while `X` is being deleted, and `X` has no compatible index, gets the index error this sentence says will not happen. "Labels hidden from normal query results ... do not require coverage" is moot there, since released versions check no coverage at all. Requested change: put this sentence under the same version note, for example "The partial-coverage error and the empty result for hidden or deleting labels apply from the release containing apache/hugegraph#3243; earlier versions return only the matches from indexed labels and raise the index error when no label has a compatible index, including labels being deleted." Mirror it in content/en/docs/clients/restful-api/edge.md (lines 428 and 434), content/cn/docs/clients/restful-api/vertex.md (lines 427 and 430) and content/cn/docs/clients/restful-api/edge.md (lines 432 and 436). -- 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]
