Copilot commented on code in PR #499: URL: https://github.com/apache/hugegraph-doc/pull/499#discussion_r4104317709
########## content/cn/docs/language/hugegraph-cypher.md: ########## @@ -0,0 +1,135 @@ +--- +title: "HugeGraph Cypher" +linkTitle: "Cypher 查询语言" +weight: 2 +--- + +### 概述 + +HugeGraph 支持 [Cypher](https://opencypher.org/) —— 最初由 Neo4j 创建、并由 [openCypher](https://github.com/opencypher/openCypher) 标准化的声明式图查询语言。Gremlin 是命令式的遍历语言，而 Cypher 只需描述想要的图模式（`MATCH`、`WHERE`、`RETURN`），由引擎决定如何执行。 + +HugeGraph 通过 [cypher-for-gremlin](https://github.com/opencypher/cypher-for-gremlin) 转译器将 Cypher 语句翻译为 Gremlin，再在 TinkerPop 技术栈上执行。因此 HugeGraph 的 Cypher 能力覆盖转译器所实现的 openCypher 9 语法面 —— 详见下文[已知限制](#已知限制)。 + +### 何时用 Cypher、何时用 Gremlin + +| 适合用 Cypher | 适合用 Gremlin | +|---|---| +| 正在从 Neo4j 迁移，或已熟悉 Cypher | 需要 HugeGraph 的完整功能面 | +| 需要声明式模式匹配（`MATCH (a)-[:KNOWS]->(b)`） | 需要精细的遍历控制、自定义步骤或 lambda | +| 查询以读模式和投影为主 | 需要图算法、OLAP 或 Cypher 未暴露的功能 | + +凡是 Cypher 表达不了的，等价的 Gremlin 查询总是可用 —— 下文示例同时给出两种写法。 + +### 调用 Cypher API + +Cypher 语句通过 HugeGraph Server 的 REST 端点提交： + +```http +GET /graphspaces/{graphspace}/graphs/{graph}/cypher?cypher={statement} +POST /graphspaces/{graphspace}/graphs/{graph}/cypher +``` + +该端点始终要求 `Authorization` 头（`Basic` 或 `Bearer`），即使服务端未开启认证 —— 凭据会被转发给 Gremlin Server。完整的请求/响应格式见 [Cypher REST API 参考](/cn/docs/clients/restful-api/cypher/)。 + +示例： + +```bash +curl -H "Authorization: Bearer $TOKEN" \ + "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/cypher?cypher=MATCH%20(n:person)%20RETURN%20n.name%20LIMIT%2010" +``` + +Java 客户端使用 `CypherManager`（见 [hugegraph-client](/cn/docs/clients/hugegraph-client/)）： + +```java +ResultSet resultSet = hugeClient.cypher().execute("MATCH (n:person) RETURN n.name LIMIT 10"); +``` + +### 基础示例 + +以下示例假设图中存在 `person` 顶点（`name`、`age`、`city` 属性）和 `knows` 边。 + +#### 查询 — MATCH / WHERE / RETURN + +```cypher +// 所有名为 "marko" 的 person +MATCH (n:person) WHERE n.name = 'marko' RETURN n + +// 投影 + 排序 + 限制条数 +MATCH (n:person) +WHERE n.age > 30 +RETURN n.name AS name, n.age AS age +ORDER BY age DESC +LIMIT 10 + +// 关系模式 +MATCH (a:person)-[:knows]->(b:person) +WHERE a.name = 'marko' +RETURN b.name AS friend +``` + +#### 创建 — CREATE + +```cypher +// 创建顶点 +CREATE (n:person {name: 'josh', age: 32, city: 'beijing'}) + +// 创建两个顶点及它们之间的边 +CREATE (a:person {name: 'peter'})-[:knows]->(b:person {name: 'lop'}) +``` + +#### 更新 — SET / REMOVE + +```cypher +MATCH (n:person) WHERE n.name = 'josh' +SET n.age = 33 +REMOVE n.city +``` + +#### 删除 — DELETE / DETACH DELETE + +```cypher +// 删除边 +MATCH (a:person)-[r:knows]->(b:person) +WHERE a.name = 'peter' AND b.name = 'lop' +DELETE r + +// 删除顶点及其所有边 +MATCH (n:person) WHERE n.name = 'josh' +DETACH DELETE n +``` + +#### 聚合 + +```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 写法 + +每条 Cypher 语句在内部都会被翻译为 Gremlin。当某个 Cypher 特性不受支持时，可直接编写遍历： + +| Cypher | 等价 Gremlin | +|---|---| +| `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()` | + +### 已知限制 + +HugeGraph 的 Cypher 能力受转译层约束，该层基于 openCypher 9 时代的工具链。已知缺口： + +- **不支持参数化查询** —— API 只接受原始语句字符串，不支持 `$param` 占位符。请在客户端先对值做转义/净化再拼接到语句中。 Review Comment: The Chinese guide repeats the same contradiction: the compatibility page verifies JSON POST bindings via `{cypher, parameters}`, so `$param` placeholders are not universally unsupported. Document the binding form and limit the raw-string caveat to GET/legacy raw POST, or qualify this statement by version. ########## 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 PR description promises a feature-level compatibility matrix with an evidence tier on every row and Gremlin workarounds, but this page only lists request forms and tested cases; it never classifies language features or provides those fallbacks. Add the promised matrix/tier and workaround content, or update the PR description and scope before presenting this as the compatibility matrix. ########## 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 | + +### 建议的迁移路径 + +1. **盘点查询**：把应用里的 Cypher 按 + [兼容性矩阵](/cn/docs/language/cypher-compatibility/) 分成 + "直接可用 / 需改写为 Gremlin / 需换 REST API" 三类。 +2. **先建 schema**：用 schema API 建好 VertexLabel/EdgeLabel/PropertyKey 和索引 —— + HugeGraph 在写入前要求 schema 存在。 +3. **导入数据**：小数据集用 REST；大批量用 + [HugeGraph Loader](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader)。 +4. **灰度切换**：Cypher 能表达的查询保持不动， translator 不支持的改写为 + Gremlin（等价写法见 [对照表](/cn/docs/language/hugegraph-cypher/#等价的-gremlin-写法)）。 + +### 已知限制速查 + +- Cypher 语句不支持参数绑定、多语句脚本与 `CALL` 过程。 Review Comment: This limitation list repeats the same incorrect claim: the current compatibility record verifies bound parameters through the JSON POST form. Keeping `参数绑定` in the unsupported list makes the Chinese migration guide contradict the compatibility page; retain only the raw GET/POST, multi-statement, and `CALL` limitations here. ########## 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: This migration advice contradicts the compatibility page's verified JSON-POST binding contract: `{cypher, parameters}` supports `$param` bindings in the current development change. Replace the instruction to interpolate literals with the supported binding form, while noting that GET and legacy raw-body POST do not carry parameters. ########## 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 | +| `CALL dbms.*` / `CALL algo.*` procedures | Equivalent capabilities live in the [traverser](/docs/clients/restful-api/traverser/), [task](/docs/clients/restful-api/task/), and other REST APIs | +| Driver: Neo4j Bolt driver | [hugegraph-client](/docs/clients/hugegraph-client/) (`CypherManager`) or any HTTP client | +| Transaction boundaries inside a Cypher statement | One statement per request; bulk writes use the [Loader](/docs/guides/toolchain/) or bulkport | + +### Suggested migration path + +1. **Inventory your queries**: classify the Cypher in your application against + the [compatibility matrix](/docs/language/cypher-compatibility/) into + "works as-is / rewrite as Gremlin / switch to a REST API". +2. **Create the schema first**: define VertexLabel / EdgeLabel / PropertyKey + and indexes through the schema API — HugeGraph requires the schema to + exist before data is written. +3. **Import data**: REST for small datasets; the + [HugeGraph Loader](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader) + for bulk loads. +4. **Switch incrementally**: keep the queries Cypher can express, and rewrite + translator-unsupported constructs as Gremlin — the + [equivalents table](/docs/language/hugegraph-cypher/#gremlin-equivalents) + shows the mapping. + +### Known limitations at a glance + +- Cypher statements support neither parameter binding, multi-statement + scripts, nor `CALL` procedures. Review Comment: This limitation list repeats the same incorrect claim: the current compatibility record verifies bound parameters through the JSON POST form. Keeping `parameter binding` in the unsupported list makes the migration guide contradict the compatibility page; retain only the raw GET/POST, multi-statement, and `CALL` limitations here. ########## 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: This limitation contradicts the compatibility page's verified JSON-POST binding contract and the linked HugeGraph change: `{cypher, parameters}` supports `$name`. Telling users to interpolate values is therefore inaccurate and needlessly unsafe; document JSON POST bindings and restrict the raw-string caveat to GET/legacy raw POST, or qualify this statement by version. ########## 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: `bulkport` is not defined or linked anywhere in this repository, while the linked Loader is the documented bulk-import tool. This sends migration readers to an unavailable or ambiguous option; remove it or replace it with a real documented tool. ########## 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: PR 描述承诺兼容性矩阵的每一行都有明确证据等级（文档示例、转译器 TCK 自报、API 表面或未测试），但这里的表格只有契约说明和测试方法，读者无法区分这些证据来源。请补充证据等级列，或修改 PR 描述以匹配实际内容。 ########## 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` | 暂不支持 —— 在客户端转义/校验后拼接字面量 | Review Comment: This migration advice contradicts the compatibility page's verified JSON-POST binding contract: `{cypher, parameters}` supports `$param` bindings in the current development change. Replace the interpolation instruction with the supported binding form, while noting that GET and legacy raw-body POST do not carry parameters. ########## data/version_routes.json: ########## @@ -1498,6 +1498,48 @@ "1.5": null, "1.3": null, "1.0": null + }, + "cn:language/hugegraph-cypher": { Review Comment: These entries are appended after `en:quickstart/...`, but `generate_version_routes()` builds `pages` from sorted logical IDs (`scripts/versioning.py:2426-2448`). Regenerating the route map will move these keys into the `cn:language/...` and `en:language/...` blocks, leaving this checked-in map non-deterministic/stale. Insert each locale's entries in sorted order instead. -- 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]
