docs: clarify property-query index coverage

content/cn/docs/clients/restful-api/edge.md

@@ -422,12 +422,22 @@ 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` 时，该标签需有与查询条件匹配的属性索引；若指定的是未单独建索引的子边标签，可以使用其查询可见的父标签上的匹配索引，并自动过滤掉同级其他子标签的边。
+候选标签是可直接存边且声明了全部待查非 OLAP 属性的边标签，也包括目前没有边的标签。普通查询不可见的标签（包括正在删除的标签）不需要索引覆盖。如果存在候选标签但全部都不可见或正在删除（或指定的候选 `label` 不可见或正在删除），查询返回空结果，不报索引错误；若没有任何 Schema 标签声明待查属性，仍会报索引错误。
+未指定 `label` 时，`base` 父边标签不直接存边，子标签全部被覆盖时，无需再为父标签单独建立索引。可以用当前查询可见的父标签上的匹配索引覆盖子标签，也可以为每个候选子标签建立匹配的索引。如果父标签因隐藏或正在删除而被当前查询排除，其索引不能用于覆盖子标签。仅有标签索引不等于属性已建立索引。
+
+查询值与声明的属性类型兼容时，没有匹配索引或仅覆盖部分候选标签都会报索引错误，完整覆盖时通过索引执行。
+部分覆盖检查报错、子边标签复用父标签索引，以及候选标签不可见或正在删除时返回空结果的机制，适用于包含 [apache/hugegraph#3243](https://github.com/apache/hugegraph/pull/3243) 的版本；早期版本仅使用指定标签自身建立的索引，在未指定 `label` 时仅返回命中索引标签的匹配结果，且在没有标签具备匹配索引（包括正在删除的标签）时会直接报索引错误。
+类型不兼容的值在找到匹配索引后，可能返回空结果，不再检查部分覆盖；没有匹配索引时仍会报索引错误。如果只需查询某个边标签，可以指定 `label`；否则需建立匹配的属性索引，覆盖所有候选标签。查询不会自动回退到全量扫描。
+
+指定 `vertex_id` 时，查询过滤该顶点的邻接边，不适用上述全图查询的索引覆盖要求。
+
 属性键值对由 JSON 格式的属性名称和属性值组成，允许多个属性键值对作为查询条件，属性值支持精确匹配和范围匹配，精确匹配时形如 `properties={"weight":0.8}`，范围匹配时形如 `properties={"age":"P.gt(0.8)"}`，范围匹配支持的表达式如下：
 
 | 表达式                                | 说明                               |

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.eq`、`P.within` 或 `P.contains` 之外的条件（如 `P.neq`、`P.gt`、`P.between`、`P.textcontains` 等），查询会在属性索引查询前被拒绝，即使存在匹配的属性索引也不例外；在主键字段上使用 `P.contains` 时会直接按单个元素走 ID 查找路径，而不会被拦截报错。
+
+其他 `properties` 查询中，如果指定了 `label`，该顶点标签需要有与查询条件匹配的属性索引。候选标签是声明了全部待查非 OLAP 属性的顶点标签，也包括目前没有顶点的标签。
+普通查询不可见的标签（包括正在删除的标签）不需要索引覆盖。如果存在候选标签但全部都不可见或正在删除（或指定的候选 `label` 不可见或正在删除），查询返回空结果，不报索引错误；若没有任何 Schema 标签声明待查属性，仍会报索引错误。仅有标签索引不等于属性已建立索引。
+若查询包含 OLAP 属性且读取模式已开放 OLAP 数据，HugeGraph 将使用全局共享的 OLAP 索引，此类 OLAP 属性无需每个候选标签单独声明或建立索引。
+
+查询值与声明的属性类型兼容时，没有匹配索引或仅覆盖部分候选标签都会报索引错误，完整覆盖时通过索引执行。
+部分覆盖检查报错以及候选标签不可见或正在删除时返回空结果的机制，适用于包含 [apache/hugegraph#3243](https://github.com/apache/hugegraph/pull/3243) 的版本；早期版本仅返回命中索引标签的匹配结果，且在没有标签具备匹配索引（包括正在删除的标签）时会直接报索引错误。
+类型不兼容的值在找到匹配索引后，可能返回空结果，不再检查部分覆盖；没有匹配索引时仍会报索引错误。如果只需查询某个顶点标签，可以指定 `label`；否则需为所有候选标签建立匹配的属性索引。查询不会自动回退到全量扫描。
+
 属性键值对由属性名称和属性值组成 JSON 格式的对象，可以使用多个属性键值对作为查询条件，属性值支持精确匹配和范围匹配，精确匹配的形式如`properties={"age":29}`，范围匹配的形式如`properties={"age":"P.gt(29)"}`，范围匹配支持以下表达式：
 
 | 表达式                                | 说明                              |

content/en/docs/clients/restful-api/edge.md

@@ -416,12 +416,33 @@ 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, that label needs a property index compatible with the query
+conditions; 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.
+Candidate labels are edge labels that can hold edges and declare all queried non-OLAP properties, including labels that currently have no edges. Labels hidden
+from normal query results, including those being deleted, do not require coverage. If candidate labels exist but all of them are hidden or being deleted (or
+the specified candidate `label` is hidden or being deleted), the query returns an empty result instead of an index error; if no schema label declares the
+queried properties, the index error still applies. When `label` is omitted, 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, and compatible indexes on every candidate
+sub-label are also sufficient. Indexes on hidden or deleting parents excluded from the query cannot provide this 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
+the indexes. The partial-coverage error, parent-index fallback for sub-edge labels, and the empty result for hidden or deleting candidate labels apply from
+the release containing [apache/hugegraph#3243](https://github.com/apache/hugegraph/pull/3243); earlier versions use only indexes created on the specified
+label, return only the matches from indexed labels when `label` is omitted, and raise an index error when no label has a compatible index (including labels
+being deleted).
+A type-incompatible value may return an empty result after a matching index is found, before partial coverage is checked. If no index matches, the index error
+still applies. Specify `label` when querying only one edge label, or create compatible property indexes to cover every candidate label. The query does not
+automatically fall back to a full scan.
+
+With `vertex_id`, the query filters that vertex's adjacent edges; the global index-coverage requirement above does not apply.
+
 Key-value pairs of properties consist of the property name and value in JSON format. Multiple key-value pairs are allowed as query conditions. Property values support exact matching and range matching. For exact matching, it is in the form `properties={"weight":0.8}`. For range matching, it is in the form `properties={"age":"P.gt(0.8)"}`. The expressions supported by range matching are as follows:
 
 | Expression                         | Description                                                                      |

content/en/docs/clients/restful-api/vertex.md

@@ -367,14 +367,36 @@ 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 uses a condition other than `P.eq`, `P.within` or `P.contains` (`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; `P.contains` on a primary-key
+field takes the primary-key lookup path using a single element rather than being rejected.
+
+For other `properties` queries, the specified `label` needs a property index compatible with the query conditions. Candidate labels are vertex labels that
+declare all queried non-OLAP properties, including labels that currently have no vertices. Labels hidden from normal query results, including those being
+deleted, do not require coverage. If candidate labels exist but all of them are hidden or being deleted (or the specified candidate `label` is hidden or
+being deleted), the query returns an empty result instead of an index error; if no schema label declares the queried properties, the index error still
+applies. A label index alone does not index properties.
+When the query includes OLAP properties and the read mode exposes OLAP data, HugeGraph uses shared OLAP indexes; such OLAP properties do not require
+per-label coverage declarations or individual indexes on each candidate label.
+
+For query values compatible with the declared property types, no compatible index or partial candidate coverage produces an index error; complete coverage uses
+the indexes. The partial-coverage error and the empty result for hidden or deleting candidate labels apply from the release containing
+[apache/hugegraph#3243](https://github.com/apache/hugegraph/pull/3243); earlier versions return only the matches from indexed labels and raise an index error
+when no label has a compatible index (including labels being deleted).
+A type-incompatible value may return an empty result after a matching index is found, before partial coverage is checked. If no index matches, the index error
+still applies. Specify `label` when querying only one vertex label, or create compatible property indexes for every candidate label. The query does not
+automatically fall back to a full scan.
+
 Property key-value pairs consist of the property name and value in JSON format. Multiple property key-value pairs are allowed as query conditions. The property value supports exact matching, range matching, and fuzzy matching. For exact matching, use the format `properties={"age":29}`, for range matching, use the format `properties={"age":"P.gt(29)"}`, and for fuzzy matching, use the format `properties={"city": "P.textcontains("ChengDu China")}`. The following expressions are supported for range matching:
 
 | Expression                        | Explanation                                    |