bitflicker64 commented on code in PR #499: URL: https://github.com/apache/hugegraph-doc/pull/499#discussion_r4303200591
########## content/en/docs/language/hugegraph-cypher.md: ########## @@ -0,0 +1,195 @@ +--- +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. `Basic` credentials must be encoded with URL-safe Base64 (`-` and `_` instead of `+` and `/`), and the password must not contain `:`; use +`Bearer` for accounts that cannot meet either condition. See the [Cypher REST API reference](/docs/clients/restful-api/cypher/) for the full request/response Review Comment: Important: this paragraph, added in 4290c2b for the earlier Basic-parsing thread, matches 1.7.0. On `master`, the 1.8.0 line this page also documents, all three rules have changed. The URL-safe advice now breaks Basic auth for any credential whose encoding contains `-` or `_`, which is exactly the case the advice is written for. Evidence, apache/hugegraph `master` at f5d9885: - #3290 (62faab73d) switched `CypherAPI` to `Base64.getDecoder()` (line 71) and `split(":", 2)` (line 231). Decoding the URL-safe `YWRtaW46cD4_fg==` throws `Illegal base64 character 5f`, so `toUserPass` returns null and the `E.checkNotNull` at line 209 fails. The standard form that `curl -u` sends works, and `:` in a password is accepted. - #3366 (8fe10180d) returns an anonymous client when authentication is disabled (lines 186-187), so the header is no longer required. Requested change: scope these rules to 1.7.0 and earlier, and describe the `master` behaviour as well. Mirror this in CN `hugegraph-cypher.md` line 34. As a follow-up, `clients/restful-api/cypher.md` line 10 makes the same claim that the header is always required. ########## content/en/docs/language/cypher-compatibility.md: ########## @@ -0,0 +1,165 @@ +--- +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 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 current Apache `master` at Review Comment: Minor: "current Apache `master` at `5039e5b`" is no longer current. After 5039e5b, `master` changed parts of the contract this record covers: Basic decoding and the anonymous mode (#3290, #3366), and failure responses, which now carry `status.attributes.errors` entries with a stable `code` next to `status.message` (#3259, a0aae8e7e). Readers checking this record against a fresh `master` build will see differences that the page does not explain. Requested change: drop "current" and write "Apache `master` at `5039e5b` (2026-10-08)". Add one sentence saying that later `master` commits changed authentication handling and the error envelope, and that they are not covered by this record. Apply the same change to CN `cypher-compatibility.md` line 16 ("当前 Apache `master`"). -- 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]
