bitflicker64 commented on code in PR #499:
URL: https://github.com/apache/hugegraph-doc/pull/499#discussion_r4164017358
##########
content/en/docs/language/cypher-compatibility.md:
##########
@@ -0,0 +1,97 @@
+---
+title: "Cypher Compatibility"
+linkTitle: "Cypher Compatibility"
+weight: 3
+---
+
+### Scope
+
+**No statement on this page describes a released HugeGraph version.** A
released build exposes exactly two
+request forms on `/graphspaces/{graphspace}/graphs/{graph}/cypher`: `GET
?cypher=<URL-encoded statement>`
Review Comment:
Minor: "A released build exposes exactly two request forms on
`/graphspaces/{graphspace}/graphs/{graph}/cypher`" holds only for 1.7.0.
`CypherAPI` at tags 1.0.0, 1.2.0, 1.3.0 and 1.5.0 is
`@Path("graphs/{graph}/cypher")`; the graphspace path first appears in 1.7.0.
Please say "1.7.0 exposes..." or mention that earlier releases use
`/graphs/{graph}/cypher`. CN lines 9 to 10 make the same claim.
##########
content/en/docs/language/migrate-from-neo4j.md:
##########
@@ -0,0 +1,62 @@
+---
+title: "Migrating from Neo4j"
+linkTitle: "Migrating from Neo4j"
+weight: 4
+---
+
+### Who this page is for
+
+Neo4j users evaluating HugeGraph. HugeGraph's Cypher coverage is defined by
+the [`cypher-for-gremlin`](https://github.com/opencypher/cypher-for-gremlin)
+translator and is not 1:1 with Neo4j — see the
+[Cypher compatibility notes](/docs/language/cypher-compatibility/) for the
+verified and unverified areas and
+[HugeGraph Cypher](/docs/language/hugegraph-cypher/) for usage.
+
+### What carries over directly
+
+| Neo4j concept | HugeGraph equivalent |
+|---|---|
+| Property graph model (nodes / relationships / properties) | Same — vertex
labels / edge labels / properties |
+| Core Cypher: `MATCH`/`WHERE`/`RETURN`/`CREATE`/`SET`/`DELETE` | Works as-is
(REST `/cypher` endpoint or Java client `CypherManager`) |
+| Simple aggregations (`count`/`sum`/`min`/`max`/`avg`) | Works as-is |
+| Traversal-heavy queries | Gremlin traversals or the [traverser REST
APIs](/docs/clients/restful-api/traverser/) (k-out, shortest path,
personalrank, ...) |
+
+### Habits you need to change
+
+| In Neo4j | In HugeGraph |
+|---|---|
+| `CREATE INDEX` / `CREATE CONSTRAINT` | Create indexes/constraints through
the [schema REST APIs](/docs/clients/restful-api/schema/); Cypher carries no
DDL |
+| Implicit schema (add properties freely) | **Strong schema**: define
VertexLabel / EdgeLabel / PropertyKey before writing data |
+| Parameterized queries `$param` | Released versions send the raw statement
only — a missing binding evaluates to `null` (empty result), so validate values
client-side; JSON-bound parameters land in [PR
#238](https://github.com/hugegraph/hugegraph/pull/238) |
+| `CALL dbms.*` / `CALL algo.*` procedures | Equivalent capabilities live in
the [traverser](/docs/clients/restful-api/traverser/),
[task](/docs/clients/restful-api/task/), and other REST APIs |
+| Driver: Neo4j Bolt driver |
[hugegraph-client](/docs/clients/hugegraph-client/) (`CypherManager`) or any
HTTP client |
+| Transaction boundaries inside a Cypher statement | One statement per
request; bulk imports use the [HugeGraph
Loader](/docs/quickstart/toolchain/hugegraph-loader/) |
+
+### Suggested migration path
+
+1. **Inventory your queries**: classify the Cypher in your application against
Review Comment:
Important: Step 1 tells readers to classify their queries into "works as-is
/ rewrite as Gremlin / switch to a REST API" against the compatibility notes,
and line 12 points there for "the verified and unverified areas". After 6f52040
that page opens with "No statement on this page describes a released HugeGraph
version" and contains only the test record for the unmerged
hugegraph/hugegraph#238 change: request forms, fixture test methods, and a list
of unverified constructs. It has no per-construct classification a Neo4j user
can apply to a released server, so the first step of the migration path cannot
be followed.
Requested change: point step 1 and line 12 at the Known limitations section
of `hugegraph-cypher.md` (which does describe released behaviour), or add a
short released-version classification to the guide and link that. Same change
in the CN page, lines 12 and 37 to 38.
##########
content/en/docs/language/cypher-compatibility.md:
##########
@@ -0,0 +1,97 @@
+---
+title: "Cypher Compatibility"
+linkTitle: "Cypher Compatibility"
+weight: 3
+---
+
+### Scope
+
+**No statement on this page describes a released HugeGraph version.** A
released build exposes exactly two
+request forms on `/graphspaces/{graphspace}/graphs/{graph}/cypher`: `GET
?cypher=<URL-encoded statement>`
+and `POST application/json` with a raw Cypher body. Released versions accept
no bound parameters, and a
+statement that references `$param` returns no rows rather than failing — see
+[Known limitations](/docs/language/hugegraph-cypher/#known-limitations).
+
+This page records the cases verified for the current Cypher development
change. It does not claim full
+openCypher or Neo4j compatibility, or compatibility across every released
HugeGraph version. The tested
+working tree is based on
+[`apache/hugegraph@27a7c9b`](https://github.com/apache/hugegraph/commit/27a7c9b42274d6d4f95eabed6d2051d393ae0eaf),
+a TinkerPop 3.8 development commit that is **not an ancestor of `master`**: it
has diverged, 10 commits
+ahead and 5 behind. `master` currently declares `tinkerpop.version` `3.5.1`
and its `CypherAPI` accepts
Review Comment:
Minor: "10 commits ahead and 5 behind" is already out of date. `gh api
repos/apache/hugegraph/compare/master...27a7c9b` returns `diverged ahead=10
behind=6` today, and the count changes with every master merge. The same
applies to "`master` currently declares `tinkerpop.version` `3.5.1`", which
stops being true when the TinkerPop upgrade lands. Please drop the ahead/behind
counts and anchor the master statements to a commit or a release (for example
"as of 1.7.0"). CN line 17 has the same counts.
##########
content/en/docs/language/hugegraph-cypher.md:
##########
@@ -0,0 +1,150 @@
+---
+title: "HugeGraph Cypher"
+linkTitle: "Cypher Query Language"
+weight: 2
+---
+
+### Overview
+
+HugeGraph supports [Cypher](https://opencypher.org/), the declarative graph
query language originally created by Neo4j and standardized as
[openCypher](https://github.com/opencypher/openCypher). While Gremlin is an
imperative traversal language, Cypher lets you describe the graph pattern you
want (`MATCH`, `WHERE`, `RETURN`) and lets the engine decide how to execute it.
+
+HugeGraph executes Cypher by translating the statement to Gremlin through the
[cypher-for-gremlin](https://github.com/opencypher/cypher-for-gremlin)
transpiler, then running the resulting traversal on the TinkerPop stack. This
means Cypher support in HugeGraph covers the openCypher 9 surface that the
transpiler implements — see [Known limitations](#known-limitations) below.
+
+### When to use Cypher vs Gremlin
+
+| Use Cypher when | Use Gremlin when |
+|---|---|
+| You are migrating from Neo4j or already know Cypher | You need the full
HugeGraph feature surface |
+| You want declarative pattern matching (`MATCH (a)-[:KNOWS]->(b)`) | You need
fine-grained traversal control, custom steps, or lambdas |
+| Your queries are read-mostly patterns and projections | You need graph
algorithms, OLAP, or features Cypher does not expose |
+
+For anything Cypher cannot express, the equivalent Gremlin query always works
— examples below show both.
+
+### Calling the Cypher API
+
+Cypher statements are submitted to the HugeGraph Server through the REST
endpoint:
+
+```http
+GET /graphspaces/{graphspace}/graphs/{graph}/cypher?cypher={statement}
+POST /graphspaces/{graphspace}/graphs/{graph}/cypher
+```
+
+The endpoint always requires an `Authorization` header (`Basic` or `Bearer`),
even when server authentication is disabled — the credentials are forwarded to
the Gremlin Server. See the [Cypher REST API
reference](/docs/clients/restful-api/cypher/) for the full request/response
format.
+
+Example:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+
"http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/cypher?cypher=MATCH%20(n:person)%20RETURN%20n.name%20LIMIT%2010"
+```
+
+From the Java client, use `CypherManager` (see
[hugegraph-client](/docs/clients/hugegraph-client/)):
+
+```java
+ResultSet resultSet = hugeClient.cypher().execute("MATCH (n:person) RETURN
n.name LIMIT 10");
+```
+
+### Basic examples
+
+The examples below assume a graph with `person` vertices (`name`, `age`,
`city` properties) and `knows` edges.
Review Comment:
Important: The write examples fail on the schema HugeGraph ships for this
graph. `scripts/example.groovy` (master and 1.7.0) defines `person` with
`properties("name", "age", "city").primaryKeys("name")` and no `nullableKeys`,
and `knows` with properties `date` and `weight`. On that schema:
- `CREATE (a:person {name: 'peter'})-[:knows]->(b:person {name: 'lop'})`
(line 83) translates with transpiler 1.0.4 to
`g.addV('person').property(single, 'name', 'peter')...addE('knows')`.
`GraphTransaction.checkNonnullProperty` rejects it with "All non-null property
keys [age, city] of vertex label 'person' must be set". The edge without
`date`/`weight` hits the same check in `HugeVertex`.
- `REMOVE n.city` (line 91) translates to
`sideEffect(__.properties('city').drop())`. `HugeVertexProperty.remove()`
throws "Can't remove non-null vertex property", so the whole SET/REMOVE
statement fails.
- The Gremlin table row `CREATE (n:person {name:'x'})` /
`g.addV('person').property('name','x')` (line 129) fails the same way.
A reader who loads the bundled example graph and runs these gets errors, and
in the example data `lop` is a `software` vertex.
Requested change: state the exact schema the examples assume, including
`nullableKeys("age", "city")` on `person` and a `knows` label whose properties
are nullable, or change the examples to set every non-null property and drop
the `REMOVE` (or show it on a nullable key). Apply the same change to the CN
page, lines 49, 83, 91 and 129.
--
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]
