bitflicker64 commented on code in PR #499: URL: https://github.com/apache/hugegraph-doc/pull/499#discussion_r4219047376
########## content/en/docs/language/migrate-from-neo4j.md: ########## @@ -0,0 +1,83 @@ +--- +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) | Review Comment: Minor: The last commit moved the guide and the compatibility page to the Apache change. `hugegraph-cypher.md` line 139 now says bound parameters "are proposed in the unmerged ASF PR #3289, carried over from PR #238", and the compatibility page names #3289 as the standalone code change. This row still says JSON-bound parameters "land in PR #238". #238 is on the `hugegraph/hugegraph` organization repository, so no Apache HugeGraph release will ship from it. The CN row (line 30) has the same text. Requested change: in both languages, point this row at apache/hugegraph#3289, worded the way the guide words it (unmerged, carried over from #238). ########## content/en/docs/language/cypher-compatibility.md: ########## @@ -0,0 +1,112 @@ +--- +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 current Apache `master` at +[`e62c961`](https://github.com/apache/hugegraph/commit/e62c961e00221569d4f955abbadf60faee45b283), +which uses Java 17 and TinkerPop `3.8.1`. This is a standalone Cypher change on that baseline. The runtime +uses Java `17.0.20.1`, TinkerPop `3.8.1`, `org.opencypher.gremlin:translation:1.0.4`, and RocksDB. + +The endpoint is `/graphspaces/{graphspace}/graphs/{graph}/cypher`. General usage is covered in the +[HugeGraph Cypher guide](/docs/language/hugegraph-cypher/). + +### Request forms and parameters + +| Request | In a released version | Verified contract on the tested tree | Test method | +|---|---|---|---| +| `GET ?cypher=<URL-encoded statement>` | Yes | Existing query-string form | `testGet` | +| `POST application/json` with raw Cypher text | Yes | Legacy raw-body form remains available | `testPost` | +| `POST text/plain` with any body | No | Rejected with HTTP 415 | `testRejectPlainTextPost` | +| `POST application/json` with a JSON object | No — introduced by [#3289](https://github.com/apache/hugegraph/pull/3289) | Query and bindings are sent separately | `testParameters` | + +The JSON object form below is therefore **not available in any released HugeGraph version**; it describes the +open change only. On released versions a statement using `$param` runs with that binding bound to `null` and +returns no rows — see [Known limitations](/docs/language/hugegraph-cypher/#known-limitations). + +```json +{ + "cypher": "MATCH (n:cypher_person) WHERE n.name = $name RETURN n.name", + "parameters": {"name": "marko"} +} +``` + +POST bodies containing JSON arrays, strings, numbers, booleans, or null are rejected with HTTP 400. +Malformed JSON objects and trailing tokens also produce request errors; they do not fall back to raw Cypher. + +For the JSON-object form, `cypher` must be a nonblank string and `parameters`, if present, must be an object. +Omitting `parameters` means an empty map. A referenced but missing binding is an execution error; an explicit Review Comment: Minor: This scopes the missing-binding error to the JSON-object form, and the request table describes GET and raw-body POST as unchanged ("Existing query-string form", "Legacy raw-body form remains available"). In #3289 at fd8f4a6 the error also applies to those two forms. `CypherAPI.query` and the raw-body path of `CypherAPI.post` pass `Collections.emptyMap()`, `CypherClient.createRequest` always adds that map as `ARGS_BINDINGS`, and `CypherOpProcessor.validateParameters` throws `Missing Cypher parameter: <name>` for every `Parameter` node in the AST that has no entry in the map. So once #3289 merges, `GET ?cypher=MATCH (n:person) WHERE n.name = $name RETURN n` changes from the released behaviour that lines 11 to 12 and 35 to 36 describe (null binding, no rows) to an execution error. No test in the table covers `$param` through GET or raw POST, so this comes from reading the code, not from a test result. Requested change: say that on the tested tree a missing binding is an execution error for every request form, including GET and raw-body POST, and that this replaces the released null-and-no-rows behaviour. Add the same note to the Known limitations bullet in `hugegraph-cypher.md` (line 139), and make the same change on the CN pages (compatibility line 47, guide line 139). -- 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]
