bitflicker64 commented on code in PR #561: URL: https://github.com/apache/hugegraph-doc/pull/561#discussion_r4501079061
########## content/en/docs/language/hugegraph-gremlin.md: ########## @@ -138,3 +138,50 @@ please refer to the [Apache TinkerPop 3.8.1 official documentation](https://tink | `V` | Traversal steps between vertices and edges: `V`, `E`, `out`, `in`, `both`, `outE`, `inE`, `bothE`, `outV`, `inV`, `bothV`, and `otherV` | [vertex steps](https://tinkerpop.apache.org/docs/3.8.1/reference/#vertex-steps) | | `where` | Filters traversal results. Supports `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, and `between` operators. | [where step](https://tinkerpop.apache.org/docs/3.8.1/reference/#where-step) | {.wide .expand} + +### Numeric Literal Coercion in Gremlin-Groovy Predicates + +In Gremlin-Groovy, an unsuffixed decimal literal such as `1.0` or `1.5` is parsed as +`java.math.BigDecimal`, and an unsuffixed integer literal such as `1` is parsed as +`java.lang.Integer`. Before executing `has` predicates (`P.eq`, `P.neq`, `P.lt`, `P.lte`, +`P.gt`, `P.gte`, `P.between`, `P.within`, `P.without`), HugeGraph converts predicate values +to the target `PropertyKey` schema type (`TraversalUtil.convAllHasSteps` → +`validPropertyValue` → `DataType.valueToNumber`) and flattens `IN` / `NOT_IN` conditions into +value-compared `EQ` / `NEQ` relations (`ConditionQueryFlatten` / `NumericUtil.compareNumber`): + +- **`DOUBLE` and `FLOAT` properties:** Both integer literals (`1`) and decimal literals + (`1.0`, `1.5`) convert by numeric value via `Double.valueOf(value.toString())` / + `Float.valueOf(value.toString())`. An unsuffixed predicate such as + `has('weight', P.within(1.0))` or `has('weight', P.lt(1.5))` matches a stored `DOUBLE` + `1.0d` when `weight` is indexed. +- **`LONG`, `INT`, and `BYTE` properties:** Integer literals within range convert via + `Long.valueOf` / `Integer.valueOf` / `Byte.valueOf`, whereas decimal literals such as `1.0` + (`BigDecimal`) fail integer parsing and throw `IllegalArgumentException`. +- **Index requirement:** Filtering `g.V()` or `g.E()` by a user property requires an index on Review Comment: Minor: `g.V().hasLabel('author').has('id', 1)` runs without an index when `id` is the primary key of `author`, because `GraphTransaction.optimizeQuery` turns label plus primary-key values into an id query (`VertexCoreTest.testQueryByPrimaryValues`). Exclude vertex queries that name the label and all its primary keys from the index requirement. ########## content/cn/docs/language/hugegraph-gremlin.md: ########## @@ -134,3 +134,45 @@ HugeGraph 支持 Gremlin 遍历规范定义的各项步骤。完整说明与高 | `V` | 顶点检索与端点跳转基础步骤：`V`、`E`、`out`、`in`、`both`、`outE`、`inE` 等 | [vertex steps](https://tinkerpop.apache.org/docs/3.8.1/reference/#vertex-steps) | | `where` | 使用表达式或谓词（`eq`、`neq`、`gt` 等）进行条件筛选过滤 | [where step](https://tinkerpop.apache.org/docs/3.8.1/reference/#where-step) | {.wide .expand} + + +### Gremlin-Groovy 数值字面量与属性谓词转换规则 + +在通过 Gremlin-Groovy（例如 HTTP `/gremlin` 接口、HugeGraph-Console 或 HugeGraph-Hubble） +执行图查询时，Groovy 默认将不带类型后缀的小数字面量（如 `1.0` 或 `1.5`）解析为 +`java.math.BigDecimal`，将不带后缀的整数字面量（如 `1`）解析为 `java.lang.Integer`。在执行 +`has` 属性谓词（`P.eq`、`P.neq`、`P.lt`、`P.lte`、`P.gt`、`P.gte`、`P.between`、`P.within`、 +`P.without`）前，HugeGraph 会先将谓词参数按目标 `PropertyKey` 数据类型转换 +（`TraversalUtil.convAllHasSteps` → `validPropertyValue` → `DataType.valueToNumber`），并将 +`IN` / `NOT_IN` 条件展开为按数值比较的 `EQ` / `NEQ` 条件（`ConditionQueryFlatten` / +`NumericUtil.compareNumber`）： + +- **`DOUBLE` 与 `FLOAT` 属性键：** 整数字面量（`1`）与小数字面量（`1.0`、`1.5`）均会通过 + `Double.valueOf(value.toString())` / `Float.valueOf(value.toString())` 按数值完成转换。只要属性键已建立索引，不带后缀的 `has('weight', P.within(1.0))` 或 `has('weight', P.lt(1.5))` 即可按数值匹配存储的 `DOUBLE` 值 `1.0d`。 +- **`LONG`、`INT` 与 `BYTE` 属性键：** 取值范围内的整数字面量可通过 `Long.valueOf` / + `Integer.valueOf` / `Byte.valueOf` 转换；但传入带小数点的字面量（如 `1.0`，类型为 `BigDecimal`）会因整型解析失败而抛出 `IllegalArgumentException`。 +- **索引要求：** 在 `g.V()` 或 `g.E()` 上按用户属性过滤时，必须先为该属性键建立索引（例如数值属性的 `.range()` 范围索引）；未建索引时，无论字面量是否带后缀，HugeGraph 均会抛出 `NoIndexException`。 Review Comment: Minor: same overstatement as the English page: a vertex query that names the label and all its primary keys, such as `g.V().hasLabel('author').has('id', 1)`, becomes an id query in `GraphTransaction.optimizeQuery` and needs no index. Exclude that case from the index requirement. -- 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]
