n24q02m commented on code in PR #499: URL: https://github.com/apache/hugegraph-doc/pull/499#discussion_r4107946352
########## content/en/docs/language/cypher-compatibility.md: ########## @@ -0,0 +1,82 @@ +--- +title: "Cypher Compatibility" +linkTitle: "Cypher Compatibility" +weight: 3 +--- + +### Scope + +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 based on [`hugegraph/hugegraph@27a7c9b`](https://github.com/hugegraph/hugegraph/commit/27a7c9b42274d6d4f95eabed6d2051d393ae0eaf) +and uses Java `17.0.20.1`, TinkerPop `3.8.1`, `org.opencypher.gremlin:translation:1.0.4`, and RocksDB. + +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 | Verified contract | Test method | +|---|---|---| +| `GET ?cypher=<URL-encoded statement>` | Existing query-string form | `testGet` | +| `POST application/json` with raw Cypher text | Legacy raw-body form remains available | `testPost` | +| `POST text/plain` with raw Cypher text | Plain-text form | `testPlainTextPost` | +| `POST application/json` with a JSON object | Query and bindings are sent separately | `testParameters` | + +```json +{ + "cypher": "MATCH (n:cypher_person) WHERE n.name = $name RETURN n.name", + "parameters": {"name": "marko"} +} +``` + +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. Tests cover string, number, and boolean values, quotes and newlines, the binding names +`id` and `label`, and the default limit of 16 parameters. Values remain bindings and do not alter query text. + +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 | Review Comment: The page was restructured as a verification record of the dev change, and the PR description now matches that scope, so the per-row evidence-tier matrix promise is removed. ########## content/en/docs/language/hugegraph-cypher.md: ########## @@ -0,0 +1,135 @@ +--- +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. + +#### Read — MATCH / WHERE / RETURN + +```cypher +// All persons named "marko" +MATCH (n:person) WHERE n.name = 'marko' RETURN n + +// 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 + +// 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'}) + +// Create two vertices and an edge between them +CREATE (a:person {name: 'peter'})-[:knows]->(b:person {name: 'lop'}) +``` + +#### Update — SET / REMOVE + +```cypher +MATCH (n:person) WHERE n.name = 'josh' +SET n.age = 33 +REMOVE n.city +``` + +#### Delete — DELETE / DETACH DELETE + +```cypher +// Delete an edge +MATCH (a:person)-[r:knows]->(b:person) +WHERE a.name = 'peter' AND b.name = 'lop' +DELETE r + +// Delete a vertex and all its edges +MATCH (n:person) WHERE n.name = 'josh' +DETACH DELETE n +``` + +#### Aggregation + +```cypher +MATCH (n:person) RETURN count(n) AS total +MATCH (n:person) RETURN n.city AS city, count(*) AS cnt ORDER BY cnt DESC +``` + +### Gremlin equivalents + +Every Cypher statement is translated to Gremlin internally. When a Cypher feature is unsupported, write the traversal directly: + +| Cypher | Gremlin equivalent | +|---|---| +| `MATCH (n:person) WHERE n.name='marko' RETURN n` | `g.V().hasLabel('person').has('name','marko')` | +| `MATCH (a)-[:knows]->(b) RETURN b` | `g.V().out('knows')` | +| `CREATE (n:person {name:'x'})` | `g.addV('person').property('name','x')` | +| `MATCH (n) DETACH DELETE n` | `g.V().drop()` | +| `MATCH (n:person) RETURN count(n)` | `g.V().hasLabel('person').count()` | + +### Known limitations + +Cypher support in HugeGraph is bounded by the transpiler layer, which is based on openCypher 9 era tooling. Known gaps: + +- **No parameterized queries** — the API accepts a raw statement string only; `$param` placeholders are not supported. Sanitize/escape values on the client side before interpolating them into the statement. Review Comment: Reworded in debb318: null evaluation instead of failure, JSON POST bindings documented as landing in #238, and the raw-string caveat scoped to released versions. ########## content/en/docs/language/migrate-from-neo4j.md: ########## @@ -0,0 +1,60 @@ +--- +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 the +[Cypher compatibility matrix](/docs/language/cypher-compatibility/) for the +feature-level differences 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 | +| Implicit schema (add properties freely) | **Strong schema**: define VertexLabel / EdgeLabel / PropertyKey before writing data | +| Parameterized queries `$param` | Not supported — escape/validate values client-side and interpolate literals | Review Comment: Reworded in debb318 to the null-evaluation contract with a #238 pointer instead of interpolation advice. ########## content/cn/docs/language/cypher-compatibility.md: ########## @@ -0,0 +1,76 @@ +--- +title: "Cypher 兼容性" +linkTitle: "Cypher 兼容性" +weight: 3 +--- + +### 范围 + +本页记录当前 Cypher 开发改动实际验证过的用例，不代表完整支持 openCypher 或 Neo4j，也不代表所有已发布 +版本的 HugeGraph 都具备相同行为。测试代码基于 +[`hugegraph/hugegraph@27a7c9b`](https://github.com/hugegraph/hugegraph/commit/27a7c9b42274d6d4f95eabed6d2051d393ae0eaf)， +使用 Java `17.0.20.1`、TinkerPop `3.8.1`、`org.opencypher.gremlin:translation:1.0.4` 和 RocksDB。 + +接口路径为 `/graphspaces/{graphspace}/graphs/{graph}/cypher`。一般用法见 +[HugeGraph Cypher 指南](/cn/docs/language/hugegraph-cypher/)。 + +### 请求形式与参数 + +| 请求 | 已验证行为 | 测试方法 | +|---|---|---| +| `GET ?cypher=<URL 编码的语句>` | 保留原有查询参数形式 | `testGet` | +| `POST application/json`，请求体为原始 Cypher 文本 | 保留旧的原始文本请求形式 | `testPost` | +| `POST text/plain`，请求体为原始 Cypher 文本 | 支持纯文本请求 | `testPlainTextPost` | Review Comment: The page is now a verification record; the PR description was updated to match, dropping the per-row evidence-tier promise. ########## content/cn/docs/language/migrate-from-neo4j.md: ########## @@ -0,0 +1,53 @@ +--- +title: "从 Neo4j 迁移" +linkTitle: "从 Neo4j 迁移" +weight: 4 +--- + +### 本页面向谁 + +正在评估 HugeGraph 的 Neo4j 用户。HugeGraph 的 Cypher 覆盖面由 +[cypher-for-gremlin](https://github.com/opencypher/cypher-for-gremlin) 转译器决定， +与 Neo4j 并非 1:1 等价 —— 逐项差异见 +[Cypher 兼容性矩阵](/cn/docs/language/cypher-compatibility/)， +用法见 [HugeGraph Cypher](/cn/docs/language/hugegraph-cypher/)。 + +### 可以直接带过来的部分 + +| Neo4j 概念 | HugeGraph 对应 | +|---|---| +| 属性图模型（节点/关系/属性） | 相同 —— 顶点标签 / 边标签 / 属性 | +| 基础 Cypher：`MATCH`/`WHERE`/`RETURN`/`CREATE`/`SET`/`DELETE` | 直接可用（REST `/cypher` 端点或 Java 客户端 `CypherManager`） | +| 简单聚合（`count`/`sum`/`min`/`max`/`avg`） | 直接可用 | +| 依赖图遍历的查询需求 | Gremlin 遍历或 [traverser REST API](/cn/docs/clients/restful-api/traverser/)（k-out、最短路、personalrank 等） | + +### 需要改变习惯的部分 + +| 在 Neo4j 里 | 在 HugeGraph 里 | +|---|---| +| `CREATE INDEX` / `CREATE CONSTRAINT` | 通过 [schema REST API](/cn/docs/clients/restful-api/schema/) 建索引/约束；Cypher 不承载 DDL | +| 隐式 schema（属性随意添加） | **强 schema**：先定义 VertexLabel/EdgeLabel/PropertyKey，再写数据 | +| 参数化查询 `$param` | 暂不支持 —— 在客户端转义/校验后拼接字面量 | +| `CALL dbms.*` / `CALL algo.*` 过程 | 对应功能分散在 [traverser](/cn/docs/clients/restful-api/traverser/)、[task](/cn/docs/clients/restful-api/task/) 等 REST API | +| 驱动：Neo4j Bolt driver | [hugegraph-client](/cn/docs/clients/hugegraph-client/)（`CypherManager`）或任意 HTTP 客户端 | +| 事务边界在 Cypher 语句内 | 每次请求一个语句；批量写入用 [Loader](/cn/docs/guides/toolchain/) 或 bulkport | Review Comment: Fixed in debb318: documented Loader link, `bulkport` removed. -- 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]
