bitflicker64 commented on code in PR #557: URL: https://github.com/apache/hugegraph-doc/pull/557#discussion_r4435961700
########## 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: R2 status at `01b8113f`: **fixed**. The raw-text POST now requires `application/json` and mentions the 415 for `text/plain`, and the error envelope separates HTTP 400 for malformed bodies from HTTP 200 with `status.code` 400. One reviewer noted that "`result` is null" (it is actually `result.data`) was already in base; it is not counted against this PR. ########## 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: R2 status at `01b8113f`: `edge.md` and `vertex.md` are no longer changed, so this note is **resolved**. Similar version notes are still removed from `restful-api/_index.md`, `auth.md` and `graphs.md`; see https://github.com/apache/hugegraph-doc/pull/557#discussion_r4435960373. ########## content/en/docs/clients/restful-api/cypher.md: ########## @@ -7,7 +7,8 @@ description: "Cypher REST API: Execute OpenCypher declarative graph query langua ### 9.1 Cypher -> The Cypher API always needs an `Authorization` header, either `Basic` or `Bearer`. A request without one is rejected with `401`, even when the server runs without authentication. The credentials are forwarded to the Gremlin Server through `conf/remote-objects.yaml`. +> When authentication is disabled, no `Authorization` header is required; when enabled, `Basic` (standard RFC 4648 Base64) or `Bearer` tokens are supported. Review Comment: Correction: this R1 comment was **wrong**, and I am sorry for the extra change it prompted. Since apache/hugegraph#3366, `CypherAPI#client` returns the anonymous client when `requireAuthentication()` is false. On master, Cypher requests without an `Authorization` header therefore succeed when auth is disabled, and the original wording was correct for master. The current text at `01b8113f` (no header needed when auth is off, with a note that 1.2.0 to 1.7.0 always required one) is accurate for master. The R2 summary discloses this correction. -- 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]
