bitflicker64 commented on code in PR #499:
URL: https://github.com/apache/hugegraph-doc/pull/499#discussion_r4420798866


##########
content/en/docs/language/cypher-compatibility.md:
##########
@@ -0,0 +1,119 @@
+---
+title: "Cypher Compatibility"
+linkTitle: "Cypher Compatibility"
+weight: 3
+---
+
+### Scope
+
+**The verification results below describe `master`, not a released HugeGraph 
version.** HugeGraph 1.7.0 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. Releases before 1.7.0 
expose the same two forms under
+`/graphs/{graph}/cypher`. Released versions accept no bound parameters, and a
+statement that references `$param` runs with the missing binding inlined as 
`null` rather than failing (a predicate on it matches no rows,
+while `RETURN $value AS value` still returns a row) — see
+[Known limitations](/docs/language/hugegraph-cypher/#known-limitations).
+
+This page documents the verified use cases and behavioral boundaries of the 
Cypher implementation. It does not imply complete coverage of openCypher or 
Neo4j. Cypher parameter binding and enhancements are merged starting from 1.8.0 
(Java 17, TinkerPop 3.8.1).
+
+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 — supported starting in 
1.8.0 | Query and bindings are sent separately | `testParameters` |
+
+The JSON object form below is therefore **not available in 1.7.0 and 
earlier**; it describes functionality supported starting from 1.8.0.
+On released versions a statement using `$param` runs with the missing binding 
inlined as `null`; whether it returns rows
+depends on the expression (`WHERE n.name = $name` matches nothing, `RETURN 
$value AS value` returns a row holding `null`) —
+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
+null value is valid. On the tested tree this execution error applies to every 
request form, including
+`GET ?cypher=` and raw-body `POST`: starting in 1.8.0, the server always 
attaches the
+parameters map and rejects unresolved `$param` references, replacing the 
released null-binding behaviour
+described above. Tests cover string, number, and boolean values, quotes and 
newlines, the binding names
+`id` and `label`. The current implementation accepts at most 16 top-level 
entries in `parameters`; this
+limit is fixed. Only keys in the top-level `parameters` object count toward 
it. Cypher does not support a
+`maxParameters` setting in Gremlin Server's processor configuration. Values 
remain bindings and do not
+alter query text.
+
+A Map counts as one top-level parameter. Group related values into one Map and 
reference its fields
+explicitly; the vertex label and required properties must match the graph's 
existing schema:
+
+```json
+{
+  "cypher": "CREATE (n:cypher_person {name:$props.name, age:$props.age, 
city:$props.city}) RETURN n.name",
+  "parameters": {"props": {"name": "new-person", "age": 20, "city": "Beijing"}}
+}
+```
+
+Live REST verification confirmed that one Map containing 17 entries works with 
explicit property
+references, with all 17 persisted values checked through native REST. A 
17-entry returned Map also
+succeeds, while 17 top-level bindings produce an execution error. Use the 
explicit property references
+shown above; the pinned translator does not assign a bound Map's fields 
through the shorthand CREATE form.
+
+The translator reserves the exact string `"  cypher.null"` (two leading 
spaces) as its null marker. That
+string is rejected as a binding value, including inside lists and nested maps. 
Explicit null remains
+supported. Literal query values and stored properties equal to that string 
remain a translator limitation;
+this change does not establish value preservation for those cases.
+
+Check both the HTTP status and the response body's `status.code`: an execution 
failure can retain HTTP 200
+while returning `status.code` 400 and null result data.
+
+### Verified behavior
+
+The API fixture uses a strong schema, with a `SECONDARY` index on `city` and a 
`RANGE` index on `age`.
+Acceptance results are limited to these test cases:
+
+| Area | Tested cases | Test methods |
+|---|---|---|
+| Reads | Label scans; equality and range predicates; boolean combinations; 
directed one- and two-hop patterns; empty results; whole-string regex matching 
on computed strings | `testGet`, `testExactReadsAndPredicates`, 
`testRelationQuery`, `testComputedRegexExecutesExtensionPredicate`, 
`testComputedRegexRequiresWholeStringMatch` |
+| Results | Aliases, scalar and node values, nested values, relationship ids, 
path shape, null and missing properties | `testReturnNodeIdAsPrimitiveValue`, 
`testReturnNodeDoesNotLeakInternalIdTypes`, 
`testReturnNestedIdDoesNotLeakInternalIdTypes`, 
`testReturnRelationIdDoesNotLeakInternalIdTypes`, `testReturnPathShape`, 
`testNullAndMissingProperty` |
+| Aggregation and pagination | `DISTINCT`, `count`/`sum`/`min`/`max`/`avg`, 
`ORDER BY`, `SKIP`, and `LIMIT` | `testDuplicatesDistinctAndPagination`, 
`testAggregates` |
+| Writes | Vertex and edge `CREATE`, property `SET`, edge and vertex `DELETE`; 
state checked through native REST reads | `testCreate`, 
`testCreateSetAndDeleteWithNativeReadback` |
+| Failed write | A rejected two-vertex `CREATE` left no residue during 32 
subsequent query and native-read checks | 
`testFailedWriteDoesNotLeakIntoLaterRequests` |
+| Errors and routing | Invalid syntax and request shape, content type, binding 
keys and the reserved null marker, schema values, authentication, and graph 
routing | `testInvalidRequests`, `testRejectPlainTextPost`, 
`testRejectInvalidQuery`, `testRejectInvalidBindingShapeAndKeys`, 
`testRejectTranslatorNullMarker`, `testRejectTranslatorNullSentinelInBindings`, 
`testAuthenticationAndGraphRouting`, `testSpecifiedGraphRouting` |
+
+An additional post-merge REST run on `5039e5b` re-executed the documented 
guide examples against a fresh RocksDB graph:
+reads, projection with ordering and limit, aggregation, single-vertex 
`CREATE`, `SET`/`REMOVE`, edge `DELETE`,
+`DETACH DELETE`, and every request-form contract above held, including the 
missing-binding execution error on all
+three forms. The two-vertex shorthand `CREATE (a)-[:knows]->(b)` was verified 
in the same run on a graph whose
+`person` label uses the `AUTOMATIC` id strategy; on a `PRIMARY_KEY` label the 
same statement is rejected with an
+execution error reporting that the primary keys must be set, while 
single-vertex `CREATE` on that label succeeds.
+On `PRIMARY_KEY` schemas, issue the two `CREATE` statements separately or use 
the `AUTOMATIC` id strategy for this form.
+
+Two guide examples depend on the schema. The range-predicate read (`WHERE 
n.age > 30`) needs the `RANGE` index on `age`
+declared in the fixture schema above; the `scripts/example.groovy` schema has 
only `SECONDARY` indexes on `person`
+(`city`, and `age` with `city`), so a range comparison on `age` there is 
rejected with a "not indexed" error until a
+`RANGE` index exists. The create, update and delete examples were renamed 
afterwards to `alice`, `bob` and `carol` because
+`scripts/example.groovy` already seeds `marko`, `vadas`, `josh` and `peter`, 
and on a `PRIMARY_KEY` label a `CREATE` with a seeded
+name replaces that vertex; the rename changes only data values and was not run 
as a separate verification.
+
+### Test and Implementation Boundaries
+
+Unit and integration test suites cover `CypherApiTest`, `CypherClientTest`, 
and `CypherOpProcessorTest`.
+On a schema with `PRIMARY_KEY` strategy, the shorthand `CREATE 
(a)-[:knows]->(b)` is rejected because primary keys must be set explicitly; the 
shorthand works with `AUTOMATIC` id strategy. For `PRIMARY_KEY` schemas, 
execute the two `CREATE` statements separately.

Review Comment:
   Minor: this line and line 100 say the two-vertex shorthand works with the 
`AUTOMATIC` id strategy, but `hugegraph-cypher.md` line 72 says it is still 
rejected when the label has non-null properties, as `name` is under the assumed 
schema (`GraphTransaction.checkNonnullProperty`). Add that condition here and 
on line 100, and mirror it in CN `cypher-compatibility.md` lines 88-89 and 100.



-- 
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]

Reply via email to