bitflicker64 commented on code in PR #557:
URL: https://github.com/apache/hugegraph-doc/pull/557#discussion_r4435090937
##########
content/cn/docs/clients/client/hugegraph-client.md:
##########
@@ -1,18 +1,412 @@
---
title: "HugeGraph Java Client"
-linkTitle: "HugeGraph Java Client"
-weight: 2
+linkTitle: "Java 客户端"
+weight: 1
+aliases:
+ - /cn/docs/quickstart/client/hugegraph-client/
Review Comment:
**Important: the CN aliases get a double `/cn` prefix, so the old CN client
URLs return 404.**
Hugo already prefixes aliases with the language path.
`content/cn/docs/introduction/_index.md:8` notes this, and other CN pages write
their aliases without `/cn`. With Hugo 0.168.0 extended, a strict build writes
these redirects to `public/cn/cn/docs/quickstart/client/...` and
`public/cn/cn/docs/clients/hugegraph-client/`. Nothing is generated at
`/cn/docs/quickstart/client/hugegraph-client/`, and `data/home/cn.yaml:47`
still links there. This is the missing target behind the latest-version CI
failure on `cn/index.html`.
The same pattern appears in `clients/client/_index.md`,
`hugegraph-client-go.md` and `hugegraph-client-python.md` (CN).
Suggested fix: drop the leading `/cn` from all five CN aliases. Optionally
point `data/home/{en,cn}.yaml` at `docs/clients/client/` to skip the redirect
hop.
```suggestion
- /docs/quickstart/client/hugegraph-client/
- /docs/clients/hugegraph-client/
```
##########
data/version_routes.json:
##########
@@ -1381,28 +1479,28 @@
"1.0": "docs/quickstart/"
},
"en:quickstart/client": {
- "latest": "docs/quickstart/client/",
+ "latest": null,
"1.7": "docs/quickstart/client/",
"1.5": "docs/quickstart/client/",
"1.3": "docs/quickstart/client/",
"1.0": "docs/quickstart/client/"
},
"en:quickstart/client/hugegraph-client": {
Review Comment:
**Important: from the old Java quickstart, switching to latest now falls
back to the docs home page.**
`en:quickstart/client/hugegraph-client` (and the CN equivalent) now has
`latest: null`. The new equivalents group (around line 1738) pairs
`clients/client/hugegraph-client` only with `clients/hugegraph-client`. A
reader on `/docs/quickstart/client/hugegraph-client/` in 1.7, 1.5, 1.3 or 1.0
who selects latest therefore reaches `/docs/#hg-version-fallback`
(`layouts/_partials/version-target.html`), not the merged page. Base routed
this switch directly.
Adding the quickstart ID to the same group trips the existing ambiguity
check for 1.7, because two old pages then map to one new page. This many-to-one
merge needs an explicit rule. Please also confirm that `scripts/versioning.py
routes` regenerates the committed map.
##########
content/en/docs/clients/client/hugegraph-client.md:
##########
@@ -81,7 +470,7 @@ The client also reports what the connected server supports,
so callers can branc
### 2 Schema
Review Comment:
**Minor: the EN section numbering is only half updated.**
`### 2 Schema`, `### 3 Graph` and `### 4 GraphSpace` (lines 471, 916 and
952) follow `### 5`, while their subsections are numbered 6.x, 7.x and 8.x. The
CN page uses 6, 7 and 8, so the EN table of contents shows 2, 3 and 4 twice.
The text around line 464 (EN and CN) still says "see section 4" for GraphSpace.
A related issue: old anchors such as `#22-propertykey` from the former API
reference page no longer exist. Redirected deep links therefore land at the top
of the page. If those anchors matter, consider adding explicit heading IDs.
##########
content/en/docs/language/_index.md:
##########
@@ -1,7 +1,41 @@
---
-title: "Query Languages"
-linkTitle: "Query Languages"
+title: "Graph Query Languages"
+linkTitle: "Graph Query Languages"
weight: 7
---
-HugeGraph supports Gremlin and Cypher. This section mainly covers Gremlin; see
the [Cypher API](/docs/clients/restful-api/cypher/) for the Cypher HTTP
interface.
+HugeGraph supports two mainstream graph query languages: **Gremlin**
(imperative traversal language) and **Cypher** (declarative pattern matching
language).
+
+- **Gremlin**: The core graph traversal language of Apache TinkerPop, offering
rich traversal primitives and fine control over complex topological paths.
+- **Cypher**: The declarative query language standardized by openCypher,
featuring intuitive SQL-like patterns (`MATCH ... WHERE ... RETURN`) for Neo4j
parity.
+
+## Language Guides & References
+
+- [HugeGraph-Gremlin](/docs/language/hugegraph-gremlin/)
+
+ Gremlin traversal fundamentals, CRUD query examples, and TinkerPop feature
support.
+- [HugeGraph Cypher](/docs/language/hugegraph-cypher/)
+
+ Cypher language support via cypher-for-gremlin, read/write statement
examples, execution mechanics, and constraints.
+- [Cypher Compatibility](/docs/language/cypher-compatibility/)
+
+ Coverage matrix for Cypher clauses and functions, known behavior
differences, and workarounds for unsupported features.
+- [Migrate from Neo4j](/docs/language/migrate-from-neo4j/)
+
+ Core differences between Neo4j and HugeGraph in graph modeling, ID
strategies, multiple labels, and query translation.
+- [Sample Graph Data](/docs/language/hugegraph-example/)
+
+ The classic 6-vertex 6-edge TinkerPop sample graph dataset used across query
examples.
Review Comment:
**Minor: this card describes the wrong dataset.**
`hugegraph-example.md` is the TitanDB "Graph of the Gods" example (saturn,
jupiter and so on, with 12 vertices). It is not the 6-vertex, 6-edge TinkerPop
"modern" graph. The CN card has the same text.
##########
content/en/docs/language/cypher-compatibility.md:
##########
@@ -0,0 +1,67 @@
+---
+title: "Cypher Compatibility"
+linkTitle: "Cypher Compatibility"
+weight: 3
+---
+
+### Scope and Overview
+
+HugeGraph executes openCypher 9 queries on top of the TinkerPop engine using
the
+[cypher-for-gremlin](https://github.com/opencypher/cypher-for-gremlin)
transpiler.
+This page summarizes supported request forms, parameter binding rules, syntax
coverage, and behavioral boundaries.
+
+The endpoint is `/graphspaces/{graphspace}/graphs/{graph}/cypher`. For query
examples and Gremlin equivalents, see the
+[HugeGraph Cypher Guide](/docs/language/hugegraph-cypher/).
+
+### Request Forms and Parameter Bindings
+
+| Request Form | Content-Type | Description |
+|---|---|---|
+| `POST` (Recommended) | `application/json` | JSON body `{"cypher": "...",
"parameters": {...}}`, supports parameter bindings |
+| `POST` | `application/json` | Raw Cypher text string body (for
unparameterized raw statements) |
+| `GET` | — | Query parameter `?cypher=<URL-encoded statement>`, suitable for
simple read queries |
+{.wide}
+
+Example JSON parameterized request:
+
+```json
+{
+ "cypher": "MATCH (n:person) WHERE n.name = $name RETURN n.name",
+ "parameters": {"name": "marko"}
+}
+```
+
+#### Parameter Binding Rules
+
+- **Parameter Format**: The `cypher` field must be a non-empty string;
`parameters`, if provided, must be a JSON object (omitted means an empty map).
+- **Parameter Count**: The top-level `parameters` object accepts at most 16
keys. For more properties, group them into a nested Map and reference fields
+ explicitly in the statement (e.g. `$props.name`).
+- **Unbound Variables**: Referencing an undeclared `$param` raises an
execution error and is rejected (explicit `null` is supported).
+- **Reserved Marker**: The exact string `" cypher.null"` (two leading spaces)
is reserved by the translator as an internal sentinel and is rejected in
+ parameter values.
+- **Error Response**: On validation or execution errors, the server returns
HTTP 400 (or `status.code` 400 with null result), with structured details
Review Comment:
**Minor: this bullet merges two different error shapes.**
A malformed request body returns a real HTTP 400 with the standard error
body (`CypherApiTest.java`, around lines 424-434). Translation and execution
errors return HTTP 200 with `status.code` 400 and details in
`status.attributes.errors` (around lines 766-775). `migrate-from-neo4j.md`
already describes this correctly.
A related inconsistency: this page correctly lists the raw-text POST as
`application/json`, because `CypherAPI` is `@Consumes(APPLICATION_JSON)`. The
renamed "POST raw text" section in `restful-api/cypher.md` still calls it plain
text and names no header, but a `text/plain` request gets HTTP 415.
##########
content/en/docs/language/cypher-compatibility.md:
##########
@@ -0,0 +1,67 @@
+---
+title: "Cypher Compatibility"
+linkTitle: "Cypher Compatibility"
+weight: 3
+---
+
+### Scope and Overview
+
+HugeGraph executes openCypher 9 queries on top of the TinkerPop engine using
the
+[cypher-for-gremlin](https://github.com/opencypher/cypher-for-gremlin)
transpiler.
+This page summarizes supported request forms, parameter binding rules, syntax
coverage, and behavioral boundaries.
+
+The endpoint is `/graphspaces/{graphspace}/graphs/{graph}/cypher`. For query
examples and Gremlin equivalents, see the
+[HugeGraph Cypher Guide](/docs/language/hugegraph-cypher/).
+
+### Request Forms and Parameter Bindings
+
+| Request Form | Content-Type | Description |
+|---|---|---|
+| `POST` (Recommended) | `application/json` | JSON body `{"cypher": "...",
"parameters": {...}}`, supports parameter bindings |
+| `POST` | `application/json` | Raw Cypher text string body (for
unparameterized raw statements) |
+| `GET` | — | Query parameter `?cypher=<URL-encoded statement>`, suitable for
simple read queries |
+{.wide}
+
+Example JSON parameterized request:
+
+```json
+{
+ "cypher": "MATCH (n:person) WHERE n.name = $name RETURN n.name",
+ "parameters": {"name": "marko"}
+}
+```
+
+#### Parameter Binding Rules
+
+- **Parameter Format**: The `cypher` field must be a non-empty string;
`parameters`, if provided, must be a JSON object (omitted means an empty map).
+- **Parameter Count**: The top-level `parameters` object accepts at most 16
keys. For more properties, group them into a nested Map and reference fields
+ explicitly in the statement (e.g. `$props.name`).
+- **Unbound Variables**: Referencing an undeclared `$param` raises an
execution error and is rejected (explicit `null` is supported).
+- **Reserved Marker**: The exact string `" cypher.null"` (two leading spaces)
is reserved by the translator as an internal sentinel and is rejected in
+ parameter values.
+- **Error Response**: On validation or execution errors, the server returns
HTTP 400 (or `status.code` 400 with null result), with structured details
+ (`code`, `message`, `hint`) in `status.attributes.errors`.
+
+### Syntax and Feature Support Matrix
+
+| Category | Supported Features | Notes |
+|---|---|---|
+| Reads & Patterns | Label scans, equality and range predicates, boolean logic
(AND/OR/NOT), directed 1-hop and multi-hop patterns, regex matching (`=~` full
match) | Range comparisons require corresponding indexes |
+| Results & Projection | Node and scalar projections, aliases (`AS`), property
access, nested structures, relationship IDs, path expressions, null handling |
Results are mapped to standard JSON structures |
+| Aggregation & Ordering | `count`, `sum`, `min`, `max`, `avg`, `DISTINCT`,
`ORDER BY`, `SKIP`, `LIMIT` | Transpiled directly to Gremlin traversal steps |
+| Data Writes | Vertex and edge `CREATE`, property `SET` / `REMOVE`, edge and
vertex `DELETE` / `DETACH DELETE` | Create vertices with required properties
before creating connecting edges |
+{.wide}
+
+### Write Constraints and Considerations
+
+On schemas with non-nullable properties or `PRIMARY_KEY` strategy, the
shorthand `CREATE (a)-[:knows]->(b)` fails
+due to non-null property validation (`checkNonnullProperty`) or missing
primary keys.
+Execute vertex and edge creations separately, ensuring required vertex
attributes are fully specified.
+
+### Unsupported Features
+
+The following advanced features are not currently supported by the transpiler
layer; use Gremlin or the respective REST APIs:
+- **Complex Clauses**: `MERGE`, `OPTIONAL MATCH`, `WITH`, `UNWIND`, `UNION`,
variable-length paths (`*1..3`);
Review Comment:
**Important: this list includes clauses that the server supports.**
`OPTIONAL MATCH` and `WITH` run through the REST endpoint in
`hugegraph-server/hugegraph-test/.../api/CypherApiTest.java` (around lines
285-299), and that test asserts the result rows. `UNWIND … WITH …` is
translated in the openCypher unit tests. The server's own error hint
(`CypherApiTest.java:737`) tells users to "Declare the variable in a MATCH,
UNWIND or WITH clause". Readers migrating from Neo4j would rewrite working
queries in Gremlin.
Please remove `OPTIONAL MATCH`, `WITH` and `UNWIND`. The reviewers did not
verify `MERGE`, `UNION` or variable-length paths either way, so either verify
them or describe them as untested instead of unsupported. The CN page has the
same bullet.
Reviewers rated this differently, Important in one review and Minor in the
other.
##########
content/en/docs/clients/restful-api/edge.md:
##########
@@ -435,10 +435,6 @@ When `label` is omitted: a base (parent) edge label has no
direct edges and does
**Error trigger rules**: when query values are type-compatible, missing a
matching index or covering only some candidate labels raises an index error;
only full coverage proceeds through the index. When query values are
type-incompatible, a matching index may return an empty result
(partial-coverage check skipped); with no matching index, the index error still
applies. The query never falls back to a full scan.
-> [!NOTE]
Review Comment:
**Minor: a version caveat is removed in a navigation PR.**
This note said that the partial-coverage and parent-index behavior applies
from 1.8.0. The same note is removed from `vertex.md`, and `graphs.md` §6.3.5
drops the line saying released packages lack the LOADING-owner protocol (EN and
CN). The new text is correct for master, but readers of the 1.7 release lose
the warning. Please keep a one-line "since 1.8.0" note, unless latest docs are
intended to describe unreleased master only.
--
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]
