n24q02m commented on code in PR #499: URL: https://github.com/apache/hugegraph-doc/pull/499#discussion_r4245950416
########## content/en/docs/language/hugegraph-cypher.md: ########## @@ -0,0 +1,160 @@ +--- +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. Review Comment: Good catch, you're right. Re-read `CypherAPI` and it uses `Base64.getUrlDecoder()` and then needs exactly two parts after `split(":")`. The page now says Basic credentials need URL-safe Base64 and a password without `:`, and points to Bearer otherwise (EN and CN). Fixed in 4290c2b. ########## content/en/docs/language/hugegraph-cypher.md: ########## @@ -0,0 +1,160 @@ +--- +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. +They assume the labels declare `nullableKeys("age", "city")` on `person` and nullable properties on `knows` — +for example the schema in `scripts/example.groovy` modified with those nullable keys. On a schema without them +(the released default marks `age` and `city` non-null on `person`), the create and update examples below fail +the non-null property check: set every non-null property in each statement, or declare the labels with +`nullableKeys` first. If the `person` label uses the `PRIMARY_KEY` id strategy, the two-vertex shorthand +`CREATE (a)-[:knows]->(b)` below is rejected with an execution error reporting that the primary keys must be set +(verified on `master` with [#3289](https://github.com/apache/hugegraph/pull/3289) merged): issue the two +`CREATE` statements separately or use the `AUTOMATIC` id strategy for that form. + +#### Read — MATCH / WHERE / RETURN + +```cypher +// All persons named "marko" +MATCH (n:person) WHERE n.name = 'marko' RETURN n +``` + +```cypher +// Projection with ordering and limit +MATCH (n:person) +WHERE n.age > 30 +RETURN n.name AS name, n.age AS age +ORDER BY age DESC +LIMIT 10 +``` + +```cypher +// Relationship pattern +MATCH (a:person)-[:knows]->(b:person) +WHERE a.name = 'marko' +RETURN b.name AS friend +``` + +#### Create — CREATE + +```cypher +// Create a vertex +CREATE (n:person {name: 'josh', age: 32, city: 'beijing'}) +``` + +```cypher +// Create two vertices and an edge between them +CREATE (a:person {name: 'peter'})-[:knows]->(b:person {name: 'lop'}) Review Comment: Agreed, the shorthand fails on the `primaryKeys("name")` schema we recommend. I checked it against master with #3289 and the two-vertex `CREATE` is rejected there, while it works with AUTOMATIC ids. The example now creates the two vertices first, then `MATCH (a:person), (b:person) WHERE ... CREATE (a)-[:knows]->(b)`, which is the shape `CypherApiTest` uses. EN and CN, 4290c2b. ########## content/en/docs/language/migrate-from-neo4j.md: ########## @@ -0,0 +1,99 @@ +--- +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 +[Known limitations](/docs/language/hugegraph-cypher/#known-limitations) for what +released HugeGraph versions do, and the +[Cypher compatibility notes](/docs/language/cypher-compatibility/) for the +development-tree verification record 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 | Review Comment: Fixed. The row now links the IndexLabel page (`/docs/clients/restful-api/indexlabel/`, CN `/cn/docs/clients/restful-api/indexlabel/`) and is labelled "IndexLabel REST API". 4290c2b. ########## content/cn/docs/language/cypher-compatibility.md: ########## @@ -0,0 +1,136 @@ +--- +title: "Cypher 兼容性" +linkTitle: "Cypher 兼容性" +weight: 3 +--- + +### 范围 + +**下文验证结果描述的是 `master`，不能直接套用于已发布版本。** HugeGraph 1.7.0 在 +`/graphspaces/{graphspace}/graphs/{graph}/cypher` 上只提供两种请求形式：`GET ?cypher=<URL 编码的语句>` +和 `POST application/json`（请求体为原始 Cypher 文本）。1.7.0 之前的版本在 `/graphs/{graph}/cypher` 下 +提供同样的两种形式。已发布版本不接受绑定参数，引用 `$param` 的语句 +不会报错，而是返回空结果——参见[已知限制](/cn/docs/language/hugegraph-cypher/#已知限制)。 + +本页记录当前 Cypher 开发改动实际验证过的用例，不代表完整支持 openCypher 或 Neo4j，也不代表所有已发布 +版本的 HugeGraph 都具备相同行为。测试代码基于当前 Apache `master` 的 +[`5039e5b`](https://github.com/apache/hugegraph/commit/5039e5b67d26ea305b8509d3a414877749baaebb)， +该提交声明 HugeGraph `1.8.0`，使用 Java 17 和 TinkerPop `3.8.1`，且 Cypher 改动 +（[ASF PR #3289](https://github.com/apache/hugegraph/pull/3289)）已合入。运行栈使用 Java `17.0.20.1`（Temurin）、 +TinkerPop `3.8.1`、`org.opencypher.gremlin:translation:1.0.4` 和 RocksDB。合入前在 +[`af3c686`](https://github.com/apache/hugegraph/commit/af3c6867f4bfa3f95e63ad472c12a88c63529c1b) +上的验证仍见下文。 + +接口路径为 `/graphspaces/{graphspace}/graphs/{graph}/cypher`。一般用法见 +[HugeGraph Cypher 指南](/cn/docs/language/hugegraph-cypher/)。 + +### 请求形式与参数 + +| 请求 | 是否存在于已发布版本 | 测试栈上已验证行为 | 测试方法 | +|---|---|---|---| +| `GET ?cypher=<URL 编码的语句>` | 是 | 保留原有查询参数形式 | `testGet` | +| `POST application/json`，请求体为原始 Cypher 文本 | 是 | 保留旧的原始文本请求形式 | `testPost` | +| `POST text/plain`，任意请求体 | 否 | 返回 HTTP 415 | `testRejectPlainTextPost` | +| `POST application/json`，请求体为 JSON 对象 | 否 — 由 [#3289](https://github.com/apache/hugegraph/pull/3289) 引入 | 查询语句与参数分开传入 | `testParameters` | + +因此下面的 JSON 对象形式**在任何已发布的 HugeGraph 版本中都不可用**，它描述已合入 `master`（1.8.0 开发线）的改动。 +在已发布版本上，引用 `$param` 的语句会把该参数绑定为 `null` 并返回空结果——参见 +[已知限制](/cn/docs/language/hugegraph-cypher/#已知限制)。 + +```json +{ + "cypher": "MATCH (n:cypher_person) WHERE n.name = $name RETURN n.name", + "parameters": {"name": "marko"} +} +``` + +JSON 数组、字符串、数字、布尔值或 null 请求体会返回 HTTP 400。 +格式错误的 JSON 对象和尾随内容也会产生请求错误，不会回退为原始 Cypher 文本。 + +JSON 对象中的 `cypher` 必须是非空字符串；`parameters` 若提供，必须是对象。省略 `parameters` 表示空参数表。 Review Comment: Fixed, CN now says 非空白字符串 to match `isBlank()` and the EN text. 4290c2b. ########## content/en/docs/language/cypher-compatibility.md: ########## @@ -0,0 +1,154 @@ +--- +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` returns no rows rather than failing — see Review Comment: Thanks, that was too broad. I reworded it in the intro and the other repeated spots in both languages: a missing binding is inlined as `null`, so an equality predicate on it matches no rows, `RETURN $value` returns one row with `null`, and a write stores `null`. One caveat on evidence: I did not run a live 1.7.0 server. This comes from `CypherOpProcessor` using the inline-parameters translator plus the master tests after #3289, so please correct me if 1.7.0 behaves differently. 4290c2b. -- 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]
