bitflicker64 commented on code in PR #499: URL: https://github.com/apache/hugegraph-doc/pull/499#discussion_r4203852254
########## content/en/docs/language/migrate-from-neo4j.md: ########## @@ -0,0 +1,83 @@ +--- +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 notes](/docs/language/cypher-compatibility/) for the +verified and unverified areas 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` | Released versions send the raw statement only — a missing binding evaluates to `null` (empty result), so validate values client-side; JSON-bound parameters land in [PR #238](https://github.com/hugegraph/hugegraph/pull/238) | +| `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; graph-to-graph data migration uses [Apache SeaTunnel 3.0.0](https://seatunnel.apache.org/download/) (preferred — see below), file-based bulk loads use the [HugeGraph Loader](/docs/quickstart/toolchain/hugegraph-loader/) | + +### Suggested migration path + +1. **Inventory your queries**: classify the Cypher in your application against + the [compatibility notes](/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**: the preferred path is + [Apache SeaTunnel 3.0.0](https://seatunnel.apache.org/download/) (released + 2026-09-29) running **Neo4j Source → HugeGraph Sink** directly — no + intermediate file export. REST remains fine for small datasets; the + [HugeGraph Loader](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader) + stays an alternative for file-based imports. HugeGraph-side setup + (environment, `mappings`, vertex/edge import examples) is covered in the + [Import Graph Data with SeaTunnel Sink guide](/docs/quickstart/toolchain/import/hugegraph-seatunnel-connector/). + + The [SeaTunnel 3.0.0 connector docs](https://seatunnel.apache.org/docs/3.0.0/about/) document + what to rely on: + - [Neo4j Source](https://seatunnel.apache.org/docs/3.0.0/connectors/source/Neo4j/) reads Cypher + query results with explicit field schemas; 3.0.0 adds multi-table reads via `tables_configs`. + - [HugeGraph Sink](https://seatunnel.apache.org/docs/3.0.0/connectors/sink/HugeGraph/) is + refactored in 3.0.0 with multi-mapping support — use the recommended `mappings` configuration + for vertices/edges and follow its schema-creation behavior. + - [HugeGraph Source](https://seatunnel.apache.org/docs/3.0.0/connectors/source/HugeGraph/) is + new in 3.0.0 (schema auto-discovery, multi-label/parallel reads), enabling HugeGraph export + and migration workflows. + + Map Neo4j properties to HugeGraph PropertyKeys, keep stable vertex IDs stable, map edge Review Comment: Minor: "keep stable vertex IDs stable" does not tell the reader what to do, and step 2 can lock them into a choice that step 3 cannot undo. Step 2 says to create VertexLabels through the schema API first, without naming an ID strategy. The repo's own SeaTunnel guides describe two cases: - With `idStrategy = "PRIMARY_KEY"` plus `idFields`, the ID is derived from the label and the key values, so edge endpoints have to be expressed through those same key fields (`import/hugegraph-seatunnel-connector.md`, sections 3.1 and 3.2). - Keeping an external ID such as the Neo4j node id needs `CUSTOMIZE_STRING`. The import guide's troubleshooting list also says "Automatic creation does not change an existing `PRIMARY_KEY` label into `CUSTOMIZE_STRING`" (`export-migration/hugegraph-seatunnel-source.md` lines 15 and 139, `import/hugegraph-seatunnel-connector.md` line 304). A reader who creates `PRIMARY_KEY` labels in step 2 and then tries to carry Neo4j ids in step 3 gets a schema incompatibility. Step 2 also says HugeGraph needs the schema before any write, while the Sink's `mappings` creates missing schema by default (same guide, line 65). Requested change: in step 2 or step 3, tell the reader to pick the ID strategy first. Either use `PRIMARY_KEY` with a Neo4j business key in `idFields` and the same key fields for edge endpoints, or use `CUSTOMIZE_STRING` to keep the Neo4j id. Say that pre-created labels must use that same strategy, and that step 2 is optional when `mappings` creates the schema. Make the same change in CN `migrate-from-neo4j.md` lines 40-41 and 57-58. -- 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]
