bitflicker64 commented on code in PR #499: URL: https://github.com/apache/hugegraph-doc/pull/499#discussion_r4307094105
########## content/en/docs/language/hugegraph-cypher.md: ########## @@ -0,0 +1,198 @@ +--- +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 +``` + +On 1.7.0 and earlier, the endpoint always requires an `Authorization` header (`Basic` or `Bearer`), even when server authentication is disabled — +the credentials are forwarded to the Gremlin Server. On those versions `Basic` credentials must be encoded with URL-safe Base64 (`-` and `_` instead +of `+` and `/`), and the password must not contain `:`. On `master` (1.8.0+), authentication is optional when server auth is disabled +([#3366](https://github.com/apache/hugegraph/pull/3366)), `Basic` credentials use standard RFC 4648 Base64 (as sent by `curl -u`, +[#3290](https://github.com/apache/hugegraph/pull/3290)), and `:` in passwords is supported. +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`, and that +`person.age` has a `RANGE` index — for example the schema in `scripts/example.groovy` modified with those nullable keys +plus `schema.indexLabel("personByAge").onV("person").by("age").range().ifNotExist().create()`. The starting vertex lookup Review Comment: Minor: the rewording lost the scope of the rule. "The starting vertex lookup needs a covering index unless it is an equality on every primary key" also covers label-only lookups, which need no index: the aggregation examples on lines 142 and 147 (`MATCH (n:person) RETURN count(n)`) run on `scripts/example.groovy` without one. The CN text on lines 57-58 keeps the scope (起始顶点查找在 `WHERE` 中的属性谓词需要索引覆盖), and so does the migration table row. Requested change: write "A property predicate in `WHERE` on the starting vertex needs a covering index unless it is an equality on every primary key of the label", which matches the CN page. ########## content/en/docs/language/migrate-from-neo4j.md: ########## @@ -0,0 +1,111 @@ +--- +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`), subject to the schema and index rules below | +| 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 property indexes through the [IndexLabel REST API](/docs/clients/restful-api/indexlabel/); primary-key and property-existence constraints are defined on [VertexLabels](/docs/clients/restful-api/vertexlabel/) via `primary_keys` and non-nullable keys (Cypher carries no DDL in HugeGraph; some Neo4j node key/unique constraint rules have no standalone Cypher DDL equivalent) | Review Comment: Important: this row now separates property indexes from VertexLabel rules, but it still leaves out the direct equivalent of a Neo4j uniqueness constraint. It also points key-style constraints at a mechanism that overwrites duplicates instead of rejecting them. - HugeGraph has a `UNIQUE` index type (`IndexType.UNIQUE`, created with `.unique()` or `"index_type": "UNIQUE"`, and present since 1.0.0). `GraphIndexTransaction.updateIndex` throws `Unique constraint ... conflict is found` when a second element writes the same value. That matches `CREATE CONSTRAINT ... IS UNIQUE`, and a node key maps to non-nullable keys plus a composite `UNIQUE` index. - `primary_keys` is not a constraint in Neo4j's sense. With `PRIMARY_KEY`, the vertex id is derived from the key values, so a second `CREATE` with the same key replaces the stored vertex without an error. The guide says this itself (`hugegraph-cypher.md` line 66: "a `CREATE` with one of those names replaces the seeded vertex"). A reader who moves a Neo4j node key or uniqueness constraint to `primary_keys` loses the rejection and can silently lose the properties the second statement leaves out. - The parenthetical says nothing concrete. Cypher carries no DDL at all, so "no standalone Cypher DDL equivalent" is true of every constraint. The CN row (line 29) says something different: 部分 Neo4j 节点键与唯一约束无法仅通过索引接口表达. Requested change: map uniqueness constraints to a `UNIQUE` IndexLabel. Say that `PRIMARY_KEY` sets vertex identity and that a duplicate `CREATE` overwrites rather than fails. Mention EdgeLabel non-nullable keys for relationship property existence. Replace the parenthetical with the constraint types that really have no equivalent, if any, and use the same wording in the CN row. ########## content/en/docs/language/hugegraph-cypher.md: ########## @@ -0,0 +1,198 @@ +--- +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 +``` + +On 1.7.0 and earlier, the endpoint always requires an `Authorization` header (`Basic` or `Bearer`), even when server authentication is disabled — Review Comment: Minor: "On 1.7.0 and earlier" does not hold for 1.0.0. In 1.0.0 the endpoint is `hugegraph-api/.../api/gremlin/CypherAPI.java`. It never throws `NotAuthorizedException` and never decodes Basic credentials. It forwards whatever `Authorization` header it gets, including none, to Gremlin Server with `doPostRequest(auth, request)`. A request without the header therefore works when auth is disabled, and Basic credentials are not limited to URL-safe Base64. The header requirement, `Base64.getUrlDecoder()` and `split(":")` first appear in the `api/cypher/CypherAPI` rewrite and are the same in 1.2.0, 1.3.0, 1.5.0 and 1.7.0. Requested change: write "On 1.2.0 to 1.7.0" here, in CN `hugegraph-cypher.md` line 34, and in both `clients/restful-api/cypher.md` notes (line 10). -- 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]
