You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@hugegraph.apache.org by "contrueCT (via GitHub)" <gi...@apache.org> on 2026/09/28 15:54:18 UTC
[PR] docs: clarify property-query index coverage [hugegraph-doc]
contrueCT opened a new pull request, #503:
URL: https://github.com/apache/hugegraph-doc/pull/503
## Summary
Document the property-query index coverage rule alongside the existing REST API properties parameters in the English and Chinese vertex and edge pages.
- Explain no, partial, and complete compatible index coverage and the label or index remedies.
- Clarify that the global edge rule applies when vertex_id is absent; vertex_id-bounded adjacency filtering does not use that global coverage rule.
- Preserve the existing routes and page structure.
This documents apache/hugegraph#3243, which fixes apache/hugegraph#3201. Please merge this documentation with or after the code PR: current released behavior may still silently omit matches under partial coverage.
## Validation
- git diff --check
- Strict production build with Hugo Extended 0.165.0 and Go 1.27.0: scripts/hugo.sh build passed (English and Chinese pages rendered).
- Content-only change; no navigation or visual assets changed.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "imbajin (via GitHub) via issues" <is...@hugegraph.apache.org>.
imbajin merged PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
bitflicker64 commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4307094373
##########
content/en/docs/clients/restful-api/vertex.md:
##########
@@ -367,14 +367,29 @@ 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.
Review Comment:
Minor: "any of them uses a range condition, the query is rejected" is broader than the server behaviour, because the table on this page lists `P.eq` and `P.within` as range-matching expressions and neither is rejected on a primary-key field.
At apache/hugegraph#3243 head 83ac535:
- `P.eq(x)` becomes an `EQ` relation (`TraversalUtil.convCompare2Relation`), which `ConditionQuery.userpropValuesString()` accepts.
- `P.within(a,b)` becomes an `IN` relation on the property (`TraversalUtil.convIn2Relation`). `GraphTransaction.optimizeQueries()` calls `ConditionQueryFlatten.flatten()` before `optimizeQuery()`, and `convIn2Or()` always turns a userprop `IN` into `EQ` branches (it keeps `IN` only for `OWNER_VERTEX`/`ID`). Each branch then takes the primary-key `IdQuery` path.
- Only relations other than `EQ`/`CONTAINS` reach the `E.checkState` in `userpropValuesString()`: `P.neq`, `P.gt`/`P.gte`/`P.lt`/`P.lte`, `P.between`/`P.inside`/`P.outside`, and `P.textcontains`.
So `GET .../vertices?label=person&properties={"name":"P.within(\"marko\",\"josh\")"}` on a label whose primary key is `name` returns both vertices by ID lookup, while a reader of this sentence would expect it to be rejected.
Requested change: name the rejected predicates instead of "range condition", for example "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 ... `P.eq` and `P.within` count as exact values." Mirror it in content/cn/docs/clients/restful-api/vertex.md line 422 ("其中使用了范围条件").
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4316690678
##########
content/en/docs/clients/restful-api/vertex.md:
##########
@@ -367,14 +367,33 @@ 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:
⚠️ Blocking: no. Summary: This promise also covers an explicitly selected hidden or deleting label that does not declare every queried non-OLAP property, but that path does not return an empty result. Evidence: At apache/hugegraph#3243 head 3b597b76, isIndexQueryCandidate() returns false, so hadCandidates stays false; queryByUserprop() skips the visibility-only empty return and throws NoIndexException when no index matches. Please scope this to hidden/deleting labels that would otherwise be query candidates, or adjust the runtime behavior, and mirror the clarification across the four EN/CN Vertex/Edge pages.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
bitflicker64 commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4140683336
##########
content/cn/docs/clients/restful-api/edge.md:
##########
@@ -422,12 +422,19 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:ma
- vertex_id: 顶点 id
- direction: 边的方向 (OUT | IN | BOTH)，默认为 BOTH
- label: 边的标签
-- properties: 属性键值对 (根据属性查询的前提是预先建立了索引)
+- properties: 属性键值对（索引覆盖要求见下文）
- keep_start_p: 默认为 false，当设置为 true 后，不会自动转义范围匹配输入的表达式，例如此时 `properties={"age":"P.gt(0.8)"}` 会被理解为精确匹配，即 age 属性等于 "P.gt(0.8)"
- offset：偏移，默认为 0
- limit: 查询数目，默认为 100
- page: 页号
+未指定 `vertex_id` 时，`properties` 在全图范围查询边。如果指定了 `label`，该边标签需要有与查询条件匹配的属性索引。如果未指定 `label`，所有声明了全部待查属性的边标签
Review Comment:
Minor: This line breaks between "边标签" and "都需要" in the middle of a phrase. hugo.yaml does not enable `markup.goldmark.extensions.cjk.eastAsianLineBreaks`, so Goldmark emits the soft break as a newline and Chrome and Safari render it as a space: "所有声明了全部待查属性的边标签 都需要有匹配的索引覆盖". Lines 432 and 433 here and lines 422 and 425 in vertex.md break after "，" or "；", which also leaves a space inside a sentence. Please wrap the new Chinese paragraphs only after a sentence-ending "。", as vertex.md line 426 already does.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "contrueCT (via GitHub)" <gi...@apache.org>.
contrueCT commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4129311849
##########
content/en/docs/clients/restful-api/vertex.md:
##########
@@ -367,14 +367,20 @@ 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.
+For a `properties` query, the specified `label` needs a property index compatible with the query conditions. If `label` is omitted, every
Review Comment:
Updated both English and Chinese Vertex REST API pages in 1e679825. They now describe the labeled PRIMARY_KEY direct-ID lookup when all primary-key fields have exact values, including post-lookup filtering of additional properties; the index-coverage rule is scoped to other property queries. The Edge guidance is unchanged.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4174106350
##########
content/en/docs/clients/restful-api/edge.md:
##########
@@ -416,12 +416,25 @@ 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 parent index can cover its sub-labels; compatible indexes on every candidate sub-label
Review Comment:
🧹 Blocking: no. Summary: The parent-index alternative omits the parent's visibility requirement. In the paired server change, hidden or deleting parents are excluded before indexes are collected, so a visible child without its own compatible index still fails coverage; please qualify the sentence and mirror it in Chinese. Evidence: apache/hugegraph#3243 at 7f5a917; GraphIndexTransaction.collectMatchedIndexes() filters labels using rootOriginQuery() before checkIndexCoverage().
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
bitflicker64 commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4164971919
##########
content/en/docs/clients/restful-api/vertex.md:
##########
@@ -367,14 +367,26 @@ 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. Additional property conditions are checked on that vertex and do not need a property index.
+
+For other `properties` queries, the specified `label` needs a property index compatible with the query conditions. If `label` is omitted, candidate labels are
Review Comment:
Minor: "For other `properties` queries, the specified `label` needs a property index" does not hold when every primary-key field has a condition but at least one is not an exact value.
At apache/hugegraph#3243 head 7f5a917, `GraphTransaction.optimizeQuery()` takes the primary-key path whenever `query.matchUserpropKeys(vertexLabel.primaryKeys())` is true. `matchUserpropKeys()` only checks that the keys are present (`conditionKeys.containsAll(keys)`), not the relation. The path then calls `query.userpropValuesString(keys)`, which runs `E.checkState(r.relation == EQ || r.relation == CONTAINS, "... relation must be EQ or CONTAINS, but got %s")`. So `GET .../vertices?label=person&properties={"name":"P.gt(\"a\")"}` on a label whose primary key is `name` fails with that error even when a range index on `name` exists. The query never reaches `GraphIndexTransaction`, so the index coverage rule in this paragraph does not apply to it.
Requested change: add one sentence after the PRIMARY_KEY paragraph saying that when `label` is set and `properties` has a condition on every primary-key field, all of those conditions must be exact values; a range or other predicate on a primary-key field is rejected, and a property index does not help. Mirror it in content/cn/docs/clients/restful-api/vertex.md (line 424).
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4323411638
##########
content/en/docs/clients/restful-api/vertex.md:
##########
@@ -367,14 +367,34 @@ 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` (provided it declares all queried non-OLAP properties), or every candidate
+label, is hidden or being deleted, the query returns an empty result instead of an index error. A label index alone does not index properties.
Review Comment:
⚠️ 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.
##########
content/en/docs/clients/restful-api/vertex.md:
##########
@@ -367,14 +367,34 @@ 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.
Review Comment:
⚠️ 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.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
bitflicker64 commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4314136602
##########
content/en/docs/clients/restful-api/edge.md:
##########
@@ -416,12 +416,29 @@ 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. When `label` is specified, only indexes created on that label are used, and that label needs
Review Comment:
Important: "When `label` is specified, only indexes created on that label are used" no longer matches apache/hugegraph#3243 for sub-edge labels. Its newest head 3b597b7 ("fix(server): complete sub-edge index plans", committed 2026-10-19 10:06 UTC, after this doc head) lets an explicit sub-label query use the parent's index.
At 3b597b7:
- `GraphIndexTransaction.querySchemaLabels()` returns `[subLabel, father]` when the single `LABEL` condition is a sub-edge label (`hasFather()`), so the parent goes through the same visibility filter and index matching.
- `collectMatchedIndexes()` stops at the sub-label's own index when it has a compatible one; otherwise the parent's `MatchedIndex` is used, and `prepareIndexQuery()` rewrites the query to `SUB_LABEL = <sub-label>` so sibling sub-labels are filtered out.
- `SourceIndexCoverageTest.testLabeledSubEdgeUsesParentIndex` creates an index only on the base label `parentEdge` and asserts that `E().hasLabel("subA").has("coverageName", "same")` returns the `subA` edge and not the `subB` one. With `parentEdge` set to `DELETING` the same query throws `NoIndexException`. `testLabeledSubEdgeUsesParentRangeJointAndSearchIndexes` covers range, joint and search indexes. The memory and RocksDB server test jobs passed at 3b597b7.
- `EdgeAPI.list` builds `g.traversal().E().hasLabel(label)` for `label` without `vertex_id`, so `GET .../graph/edges?label=subA&properties={"coverageName":"same"}` takes this path.
So once #3243 merges at this head, a reader who passes a sub-edge `label` will expect an index error, or create a redundant index on the sub-label, when the parent index already serves the query. The "When `label` is omitted," qualifier on line 429 was added for the earlier 7f5a917 behaviour, and that behaviour has now changed. On `master` (fd8d06c) and 1.7.0, `collectMatchedIndexes()` still reads only the specified label's `indexLabels()`, so the current sentence is right only for released versions.
Requested change: describe the #3243 behaviour and put the old behaviour under the existing version note, for example: "When `label` is specified, that label needs a compatible property index; for a sub-edge label without one, a compatible index on its query-visible parent label is used and edges of sibling sub-labels are filtered out." Then add to the version note on lines 433-434: "earlier versions use only indexes created on the specified label." Mirror it in content/cn/docs/clients/restful-api/edge.md line 431 ("指定 `label` 时，仅使用该标签上建立的索引") and its version note on line 436. If #3243 changes this again before it merges, please re-check this paragraph against its final head.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4126133248
##########
content/en/docs/clients/restful-api/vertex.md:
##########
@@ -367,14 +367,20 @@ 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.
+For a `properties` query, the specified `label` needs a property index compatible with the query conditions. If `label` is omitted, every
Review Comment:
🧹 The blanket index requirement misses the PRIMARY_KEY fast path. When the selected vertex label uses PRIMARY_KEY and properties supplies every primary-key field, GraphTransaction.optimizeQuery() builds an IdQuery; any additional property predicates are filtered after that direct lookup. Please qualify this rule with the complete-primary-key exception and mirror it in the Chinese page.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4312049185
##########
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
Review Comment:
⚠️ Important: These coverage rules also include OLAP properties, but HugeGraph shares OLAP indexes when the read mode exposes OLAP data. In GraphIndexTransaction, requiredIndexProperties() removes OLAP keys from per-label coverage and collectMatchedIndex() adds schema-wide OLAP indexes, so a query can use the shared index without each candidate label declaring or indexing that property. Please qualify this guidance for the shared OLAP path and mirror the exception in Chinese.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4130708054
##########
content/en/docs/clients/restful-api/edge.md:
##########
@@ -416,12 +416,21 @@ 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, every edge label that declares all queried properties needs compatible index coverage, even if that label
Review Comment:
🧹 Blocking: no. Summary: A parent edge label with no direct edges does not need a separate index when each data-bearing sub-label has a compatible index. Evidence: `GraphIndexTransaction.checkIndexCoverage()` at apache/hugegraph#3243 head 0de33ed skips father labels, and `SourceIndexCoverageTest` confirms a global query succeeds with compatible indexes on both sub-labels after removing the parent index. Please clarify that the coverage rule excludes base labels with no direct edges and that a parent index can cover sub-labels; otherwise, compatible indexes on each data-bearing sub-label are sufficient.
##########
content/en/docs/clients/restful-api/vertex.md:
##########
@@ -367,14 +367,23 @@ 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. Additional property conditions are checked on that vertex and do not need a property index.
+
+For other `properties` queries, the specified `label` needs a property index compatible with the query conditions. If `label` is omitted,
+every vertex label that declares all queried properties needs a compatible index, even if that label currently has no vertices. A label index
+alone does not index the properties. No compatible index produces an index error; partial coverage also produces an index error instead of
Review Comment:
🧹 Blocking: no. Summary: Partial coverage does not always produce an index error when a query value has the wrong property type. Evidence: At apache/hugegraph#3243 head 0de33ed, `collectMatchedIndexes(..., true)` calls `checkIndexCoverage` only when `validQueryConditionValues(...)` returns true; `SourceIndexCoverageTest.testInvalidValuePrecedesPartialCoverageError` confirms an invalid value returns an empty result. Please qualify this guarantee for type-valid query values and mirror the clarification across the English and Chinese vertex and edge pages.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "contrueCT (via GitHub)" <gi...@apache.org>.
contrueCT commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4163105816
##########
content/en/docs/clients/restful-api/vertex.md:
##########
@@ -367,14 +367,23 @@ 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. Additional property conditions are checked on that vertex and do not need a property index.
+
+For other `properties` queries, the specified `label` needs a property index compatible with the query conditions. If `label` is omitted,
+every vertex label that declares all queried properties needs a compatible index, even if that label currently has no vertices. A label index
+alone does not index the properties. No compatible index produces an index error; partial coverage also produces an index error instead of
Review Comment:
Fixed in 4eb19f4d across all four English/Chinese Vertex/Edge pages. The coverage guarantee is now explicitly scoped to values compatible with declared property types. The text explains that a type-incompatible value may return an empty result after an index matches, before partial coverage is checked, while no matching index still raises the index error. It also describes query-visible candidates in line with the paired code fix. Strict Hugo build and rendered-content checks passed.
##########
content/en/docs/clients/restful-api/edge.md:
##########
@@ -416,12 +416,21 @@ 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, every edge label that declares all queried properties needs compatible index coverage, even if that label
Review Comment:
Fixed in 4eb19f4d in both Edge pages. Candidates are query-visible labels that can directly hold edges, including currently empty labels. A base parent has no direct edges and needs no additional index when its sub-labels are covered; either a compatible parent index or compatible indexes on every candidate sub-label can provide coverage. Ordinary empty labels are still candidates. Strict Hugo build and rendered-content checks passed.
##########
content/cn/docs/clients/restful-api/edge.md:
##########
@@ -422,12 +422,19 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:ma
- vertex_id: 顶点 id
- direction: 边的方向 (OUT | IN | BOTH)，默认为 BOTH
- label: 边的标签
-- properties: 属性键值对 (根据属性查询的前提是预先建立了索引)
+- properties: 属性键值对（索引覆盖要求见下文）
- keep_start_p: 默认为 false，当设置为 true 后，不会自动转义范围匹配输入的表达式，例如此时 `properties={"age":"P.gt(0.8)"}` 会被理解为精确匹配，即 age 属性等于 "P.gt(0.8)"
- offset：偏移，默认为 0
- limit: 查询数目，默认为 100
- page: 页号
+未指定 `vertex_id` 时，`properties` 在全图范围查询边。如果指定了 `label`，该边标签需要有与查询条件匹配的属性索引。如果未指定 `label`，所有声明了全部待查属性的边标签
Review Comment:
Fixed in 4eb19f4d. The new Chinese Vertex/Edge paragraphs now wrap only after sentence-ending punctuation, including the PRIMARY_KEY paragraph. No site-wide CJK configuration change was needed. The strict Hugo Extended 0.165.0/Go 1.27.1 build passed; checks on the rendered coverage paragraphs and sentence-ending source wraps passed for both Chinese pages.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
bitflicker64 commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4322277499
##########
content/cn/docs/clients/restful-api/edge.md:
##########
@@ -422,12 +422,23 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:ma
- vertex_id: 顶点 id
- direction: 边的方向 (OUT | IN | BOTH)，默认为 BOTH
- label: 边的标签
-- properties: 属性键值对 (根据属性查询的前提是预先建立了索引)
+- properties: 属性键值对（索引覆盖要求见下文）
- keep_start_p: 默认为 false，当设置为 true 后，不会自动转义范围匹配输入的表达式，例如此时 `properties={"age":"P.gt(0.8)"}` 会被理解为精确匹配，即 age 属性等于 "P.gt(0.8)"
- offset：偏移，默认为 0
- limit: 查询数目，默认为 100
- page: 页号
+未指定 `vertex_id` 时，`properties` 在全图范围查询边。指定 `label` 时，该标签需有与查询条件匹配的属性索引；若指定的是未单独建索引的子边标签，可以使用其查询可见的父标签上的匹配索引，并自动过滤掉同级其他子标签的边。
+未指定 `label` 时，候选标签是查询可见、可直接存边且声明了全部待查属性的边标签，也包括目前没有边的标签。普通查询不可见的标签（包括正在删除的标签）不需要索引覆盖。如果指定的 `label`（前提是已声明全部待查非 OLAP 属性）或全部候选标签都不可见或正在删除，查询返回空结果，不报索引错误。
+未指定 `label` 时，`base` 父边标签不直接存边，子标签全部被覆盖时，无需再为父标签单独建立索引。可以用当前查询可见的父标签上的匹配索引覆盖子标签，也可以为每个候选子标签建立匹配的索引。如果父标签因隐藏或正在删除而被当前查询排除，其索引不能用于覆盖子标签。仅有标签索引不等于属性已建立索引。
+
+查询值与声明的属性类型兼容时，没有匹配索引或仅覆盖部分候选标签都会报索引错误，完整覆盖时通过索引执行。
+部分覆盖检查报错、子边标签复用父标签索引，以及候选标签不可见或正在删除时返回空结果的机制，适用于包含 [apache/hugegraph#3243](https://github.com/apache/hugegraph/pull/3243) 的版本；
Review Comment:
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 "；".
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: clarify property-query index coverage [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #503:
URL: https://github.com/apache/hugegraph-doc/pull/503#discussion_r4302906836
##########
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:
Updated in 5e93292: Added a version note indicating that the partial-coverage error applies from the release containing apache/hugegraph#3243, while earlier versions return matches from indexed labels without raising an error, across all four pages (EN/CN vertex and edge docs).
##########
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:
Updated in 5e93292: Explicitly clarified that when `label` is specified, only indexes created on that label are used; when `label` is omitted, parent/sub-label coverage rules apply, in both EN and CN edge docs.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org