You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs: add Cypher language guide, compatibility matrix, and Neo4j migration guide (EN/CN) - #499
Three pages, each with full EN + CN mirrors under content/{en,cn}/docs/language/:
hugegraph-cypher.md — how to use Cypher in HugeGraph: the /cypher REST endpoint, Java client (CypherManager), MATCH/WHERE/RETURN, CREATE/SET/DELETE, aggregation, Gremlin equivalents for unsupported constructs, and an honest Known limitations section (no parameterized queries in released versions — a missing $param evaluates to null —, no CALL procedures, single statement per request).
cypher-compatibility.md — a verification record of the parameter-binding change: request forms, verified behavior per test, the baseline failure and its fix, and the unverified areas.
migrate-from-neo4j.md — what carries over directly, habits that change (strong schema, schema DDL via REST APIs instead of Cypher), and a suggested migration path.
All three new pages are registered in data/docs_nav.json (group tree, section tree, breadcrumb, section children) and data/version_routes.json (latest only — the pages do not exist in 1.0–1.7).
The compatibility page records unverified areas explicitly; running the openCypher TCK against a live server is the natural follow-up.
ASF code PR #3289 was merged into master on 2026-10-08; its organization mirror #238 is closed. The bilingual pages now distinguish merged master support (the 1.8.0 development line) from the latest published 1.7.0 release, retain the verified request/binding boundaries, and explain that the translator's historical TCK percentage is not a HugeGraph end-to-end compatibility rate. The code dependency is merged, so this documentation PR can be reviewed and merged independently.
- Document the Cypher API (REST endpoint, Java client), MATCH/WHERE/RETURN,
CREATE/SET/DELETE, aggregation, and Gremlin equivalents for unsupported
constructs
- State known limitations honestly: no parameterized queries, partial clause
coverage via the cypher-for-gremlin transpiler, no CALL procedures,
single statement per request
- Update language section indexes (EN/CN) to cover both languages
- Register the page in data/docs_nav.json (group tree, section tree,
active_path breadcrumb, section children) and data/version_routes.json
(latest only; page does not exist in 1.0-1.7)
- Closes apache/hugegraph-doc cypher doc gap tracked in apache/hugegraph#2205
- cypher-compatibility.md: feature matrix with explicit evidence tiers
(documented examples / transpiler TCK self-report / API surface /
untested), failure behaviour, and Gremlin workarounds
- migrate-from-neo4j.md: what carries over, habits to change (strong
schema, no Cypher DDL/params/CALL), suggested migration path
- Register both pages in data/docs_nav.json and data/version_routes.json
(latest only; pages do not exist in 1.0-1.7)
- CN anchors verified against Hugo-slugified heading ids
- Companion pages to the Cypher language guide; related to #2205
The reason will be displayed to describe this comment to others. Learn more.
Blocking: yes. Summary: The compatibility matrix and Known limitations list mark MERGE ON CREATE/ON MATCH SET, =~, NOT ... IN and EXPLAIN as not supported, but HugeGraph's transpiler setup handles them. The migration page also has a broken Loader link, and the $param behaviour is described as a failure when the query actually returns no rows. Evidence: I checked the pages against apache/hugegraph master dbb6663a8 (CypherAPI, CypherClient, CypherOpProcessor, conf/gremlin-server.yaml) and hugegraph-toolchain CypherManager/HugeClient.cypher(). I translated 25 statements from the pages with translation-1.0.4.jar and the server's default translator definition. I resolved every internal link against the PR head. The REST endpoints, auth header requirement, Java client call, single-statement rule, CALL failure, DDL failure, date()/datetime() and map projection rows match the source. The EN and CN pages match each other. The only latest-head workflow run, "Build and deploy site", is waiting for maintainer approval (action_required).
Thanks for the detailed translator-level review. I’ve started validating core Cypher reads and writes against TinkerPop 3.8 on Java 17, and am investigating a minimal parameter wrapper while keeping translation-1.0.4. I’ll update this PR with the verified EN/CN documentation changes once the runtime results are available.
The implementation is now available in draft hugegraph/hugegraph#238,
at c3b2f3e3b9ff1de0495260d6eec0b16816d7f095, based on the Java 17 / TinkerPop 3.8.1 branch.
It retains translation:1.0.4 and adds bound JSON requests, parameter validation, and execution-thread rollback.
On the pinned baseline 27a7c9b, failed writes left partial data that became visible after later reads in two
reproductions. The proposed fix passes the regression, including native readback and 32 subsequent query/readback
checks. On Java 17.0.20.1 + TinkerPop 3.8.1 + RocksDB, all 20 Cypher API tests and 11 focused unit tests now pass.
Related Gremlin/Login regression, formatting and compilation also pass (one inapplicable Gremlin backend test skips).
This existing documentation PR has been updated with a test-mapped matrix and links to the fixed source revision.
The results describe this development change; advanced constructs and other backends remain unverified.
- Record the nine-request legacy CRUD sample and tested runtime.
- Describe delayed failed-write residue and the failed atomicity check.
- Link the evidence and limit claims to the observed scope.
Final documentation preview evidence (before/after screenshots use the same viewport).
The final strict scripts/hugo.sh build exited 0 with Go 1.27.0 and Hugo 0.165.0 Extended (darwin-arm64); output: EN 292 pages, CN 290 pages. The compatibility matrix maps 31 passing focused tests (Cypher API 20/20, client 7/7, processor 4/4) to code PR #238 at source commit c3b2f3e3.
- Link measured Java 17, TinkerPop 3.8.1, and RocksDB results to code PR apache#238.
- Document parameter requests and the failed-write regression.
- Limit compatibility claims to tested cases; mark advanced features unverified.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The migration guide overstates when Gremlin is a fallback and carries an outdated draft status for the linked source PR. Evidence: the page's migration table directs schema DDL and procedures to REST APIs; gh -R hugegraph/hugegraph pr view 238 reports the linked PR as open and not draft.
- guide: MERGE ON CREATE/ON MATCH, =~ and NOT ... IN translate but are
unverified end-to-end; only map projections and datetime() fail translation
- guide: $param statement runs with null binding (empty result), not an error;
JSON-bound parameters land via hugegraph/hugegraph#238
- guide: add EXPLAIN tip (translated Gremlin in result.data[0].translation),
PROFILE unsupported
- migration: point Loader links at /docs/quickstart/toolchain/hugegraph-loader/,
drop undefined 'bulkport'; scope the Gremlin-fallback claim to query
constructs (DDL and CALL go through REST APIs)
- migration: qualify parameter binding by version in habits table and limits
- compatibility: drop 'draft' label from PR apache#238 (now open)
- version_routes.json: insert the 6 new page entries in sorted locale order
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The aggregation example groups two separate Cypher statements in one request, contrary to the documented single-statement limit. Evidence: the changed code fence contains two MATCH/RETURN statements; the limitations section permits one statement per request.
The reason will be displayed to describe this comment to others. Learn more.
🧹 Minor: This code fence contains two independent Cypher statements, but the page says each request accepts one statement. Please split them into separate code fences or label them as separate requests, and make the same clarification in the Chinese page.
Reply to @imbajin (2026-09-26, code-fence comment)
@imbajin Thanks for catching this — fixed in 3599a2b. Every example fence in hugegraph-cypher.md now contains exactly one statement, in both EN and CN:
the aggregation fence you flagged → split into two labeled fences (content/en/docs/language/hugegraph-cypher.md:111 and :116; CN mirror at the same lines);
the Read / Create / Delete fences had the same shape (multiple statements grouped in one block), so they were split the same way for consistency with the "single statement per request" rule.
No wording changes elsewhere in the page.
Reply to the 2026-09-26 review threads
1. EXPLAIN tip vs. compatibility record (hugegraph-cypher.md:133, EN + CN) — fixed in 3599a2b.
The tip no longer presents EXPLAIN → result.data[0].translation as a guaranteed response contract. It now says the statement is parsed with the EXPLAIN option and the translated Gremlin is expected in result.data[0].translation — translator-level behavior, not yet verified end-to-end on a server — with a link to the compatibility notes. PROFILE remains unsupported.
2. "apache/hugegraph#238 URL returns 404" (6 threads: cypher-compatibility.md:58, hugegraph-cypher.md:126, migrate-from-neo4j.md:31, plus the CN mirrors) — no change; the cited URL does not exist on this branch.
All #238 links in the three pages point to https://github.com/hugegraph/hugegraph/pull/238 (verified open: "fix(cypher): support bound queries safely"). apache/hugegraph#238 appears nowhere in the changed files, so there is no broken link to fix. If the bot reviewed an intermediate revision where the link was worded differently, the current head supersedes it.
Where we intentionally did NOT change
migrate-from-neo4j.md:45 / CN :43 — the second Loader mention links to the GitHub apache/hugegraph-toolchain/tree/master/hugegraph-loader directory; the link is live (repo active, default branch master), and no review finding targets it. The in-doc Loader link that was flagged earlier (/docs/quickstart/toolchain/hugegraph-loader/) is already in place at line 34/33.
data/*.json — untouched by this round; the 2026-09-25 sort-order fix is already in the tree.
Compatibility/migration page content — the 2026-09-26 threads raise no new factual issue beyond the two items above.
Already-resolved prior wave (context only)
The 16 review threads from 2026-09-24/25 (bitflicker64 ×4: matrix rows for MERGE ... ON CREATE/ON MATCH SET, =~, NOT ... IN, EXPLAIN/PROFILE split, $param null-evaluation caveat, Loader link; Copilot ×10: CN mirrors, PR-description scope, version_routes.json ordering; imbajin ×2: Gremlin-fallback scoping, "draft" label) were all addressed in commit debb318 ("docs: address cypher page review feedback") with per-thread replies posted on 2026-09-25. The PR description was re-scoped to the verification-record format, dropping the per-row evidence-tier promise. This push (3599a2b) only adds the 2026-09-26 fixes above.
Commit / readback
Branch: docs/cypher-language-page-2205 (fast-forward debb31848..3599a2bdf, no force)
This says a Gremlin equivalent always works for anything Cypher cannot express, but the same page documents gaps that fail during translation and CALL features that map to REST APIs rather than a Gremlin query. Please qualify this as applying where a Gremlin equivalent exists, and mention the REST fallback for other unsupported features.
The compatibility page classifies EXPLAIN/PROFILE as not verified, but this sentence makes the stronger claim that PROFILE is unsupported. That can cause users to reject a feature that may work in a different translator/server combination; keep the statement at the documented evidence level.
Link IndexLabel API and clarify unique index mapping
This link lands on the schema overview, which only documents reading the complete schema; the create operation for indexes is documented under the IndexLabel API, and HugeGraph's constraint equivalent is a unique index. Link directly to that API and qualify the constraint mapping so migration users can actually perform this step.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The guide overstates accepted Basic credentials, and the migration page links index creation to a read-only schema overview. The Chinese parameter contract and TCK percentage also need correction. Evidence: CypherAPI decoder/split behavior, the GET-only Schema API page versus POST IndexLabel API, and the 879/958 calculation.
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.
The reason will be displayed to describe this comment to others. Learn more.
⚠️ Important: This says Basic credentials are supported without qualification, but CypherAPI uses Base64.getUrlDecoder() and splits the decoded credential on every colon. Standard Basic values can contain + or / in Base64, and a valid password can contain :, so these credentials are rejected. Please fix the parser or document the accepted credential format.
The reason will be displayed to describe this comment to others. Learn more.
⚠️ Important: This links index and constraint creation to the Schema API overview, which documents GET /schema; index creation is documented under IndexLabel at POST /schema/indexlabels. Please link to the IndexLabel API and clarify which constraint types map to HugeGraph unique indexes.
The reason will be displayed to describe this comment to others. Learn more.
🧹 Minor: 非空字符串 also includes whitespace-only values, while the English contract is nonblank and the API rejects cypher.isBlank(). Please change this to 非空白字符串 to match the API.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: yes. Summary: The compatibility page documents request forms and binding rules from an unmerged change on the hugegraph/hugegraph fork as verified behaviour, with no release qualifier, and contradicts the guide's released-version $param behaviour. Evidence: apache/hugegraph master CypherAPI (@Consumes(APPLICATION_JSON), raw body only), master CypherApiTest methods, git merge-base --is-ancestor 27a7c9b origin/master (not an ancestor), TinkerPop 3.5.1 in master hugegraph-server/pom.xml versus 3.8.1 in 27a7c9b.
The reason will be displayed to describe this comment to others. Learn more.
Important: This table lists POST text/plain and POST application/json with a {"cypher": ..., "parameters": ...} object as verified request forms, and line 34 says a missing binding is an execution error. None of that is in any Apache HugeGraph release or in apache/hugegraph master. Evidence: on apache/hugegraph master (2f827d6e8) CypherAPI.post has @Consumes(APPLICATION_JSON) only and takes the whole body as the Cypher string, so a text/plain request gets 415 and a JSON object body is sent to the translator as Cypher text and fails. CypherApiTest on master has only testGet, testPost, testCreate and testRelationQuery; testPlainTextPost and testParameters exist only on the hugegraph/hugegraph fork (PR #238, open). The tested base 27a7c9b is not an ancestor of apache master and uses TinkerPop 3.8.1, while apache master and 1.7.0 use 3.5.1. The guide on this PR (hugegraph-cypher.md, Known limitations) says the opposite for released versions: a missing binding evaluates to null and the query returns no rows. A reader who follows this page against a released server gets errors, and the two pages disagree on the same $param case. The CN page repeats this at lines 23 to 35. Requested change: mark the request-forms table, the JSON example and the binding rules (EN and CN) as unreleased behaviour from hugegraph/hugegraph PR #238, state that released servers accept only GET ?cypher= and raw-text POST application/json, and say which HugeGraph version the verified results apply to. Alternatively hold this page until the server change is merged into apache/hugegraph.
A maintainer review flagged that the request-forms table presents forms from an
unmerged change as verified released behaviour, with no release qualifier, and
that it contradicts the guide's released-version `$param` statement.
- state up front that no row describes a released HugeGraph version: releases
expose only `GET ?cypher=` and `POST application/json` with a raw body
- add an "In a released version" column; mark `text/plain` and the JSON-object
bound-parameter form as introduced by hugegraph/hugegraph#238
- link the tested commit to apache/hugegraph and record that it has diverged
from `master` (10 ahead, 5 behind) while `master` ships TinkerPop 3.5.1
- record that PR apache#238 is open and unmerged against a task branch
- cross-link both locales to the guide's Known limitations section
Thanks for the second pass — both points are correct and the page has been corrected.
What changed
Release qualifier up front. The scope section now states that no row on the page describes a released HugeGraph version, spells out the two request forms a released build exposes (GET ?cypher= and POST application/json with a raw body), and says that released versions take no bound parameters.
Per-row availability. The request-forms table gained an In a released version column. GET ?cypher= and the raw-body POST are marked available; POST text/plain and the JSON-object bound-parameter form are marked No — introduced by #238, with a note that the JSON object form is not available in any release and that on released versions a $param statement runs with the binding bound to null and returns no rows. That now agrees with the guide's Known limitations bullet instead of contradicting it.
Provenance corrected. The tested commit link points at apache/hugegraph@27a7c9b rather than the contributor fork, and the page records that the commit has diverged from master (10 commits ahead, 5 behind) while master declares tinkerpop.version3.5.1 and its CypherAPI is @Consumes(APPLICATION_JSON) with a raw String cypher body. The hugegraph/hugegraph#238 reference now records that the PR is open and unmerged against the task/tp381-3-upgrade-validation branch.
Both the English and Chinese pages carry the same change; statement lines stay byte-identical between locales.
One question so the wording matches your intent: the tested tree is a TinkerPop 3.8 development line, so if master is the only thing readers should be told about, the alternative is to move all of the request-form and binding detail behind an explicit not in any release heading rather than keeping it in the table with a column. Happy to restructure that way if you prefer it.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: yes. Summary: The write examples in the Cypher guide fail on the schema HugeGraph ships for this exact person/knows graph, and the migration guide's first step sends readers to a page that, by its own scope note, covers no released version and has no construct classification. Two minor accuracy points on the compatibility page. Earlier open points on this head (Basic credential parsing, the Schema API link, 91.7% rounding, 非空字符串) are not repeated here. Evidence: apache/hugegraph master and 1.7.0 example.groovy (person has no nullableKeys, knows has date/weight), GraphTransaction.checkNonnullProperty, HugeVertexProperty.remove, translation-1.0.4 output for the REMOVE and CREATE examples, CypherAPI @path at tags 1.0.0 to 1.7.0, GitHub compare master...27a7c9b. Strict scripts/hugo.sh build at 6f52040 passes (EN 292 / CN 290), anchors resolve, scripts.test_versioning passes 75/75. The latest-head 'Build and deploy site' workflow is waiting for maintainer approval.
The reason will be displayed to describe this comment to others. Learn more.
Important: The write examples fail on the schema HugeGraph ships for this graph. scripts/example.groovy (master and 1.7.0) defines person with properties("name", "age", "city").primaryKeys("name") and no nullableKeys, and knows with properties date and weight. On that schema:
CREATE (a:person {name: 'peter'})-[:knows]->(b:person {name: 'lop'}) (line 83) translates with transpiler 1.0.4 to g.addV('person').property(single, 'name', 'peter')...addE('knows'). GraphTransaction.checkNonnullProperty rejects it with "All non-null property keys [age, city] of vertex label 'person' must be set". The edge without date/weight hits the same check in HugeVertex.
REMOVE n.city (line 91) translates to sideEffect(__.properties('city').drop()). HugeVertexProperty.remove() throws "Can't remove non-null vertex property", so the whole SET/REMOVE statement fails.
The Gremlin table row CREATE (n:person {name:'x'}) / g.addV('person').property('name','x') (line 129) fails the same way.
A reader who loads the bundled example graph and runs these gets errors, and in the example data lop is a software vertex.
Requested change: state the exact schema the examples assume, including nullableKeys("age", "city") on person and a knows label whose properties are nullable, or change the examples to set every non-null property and drop the REMOVE (or show it on a nullable key). Apply the same change to the CN page, lines 49, 83, 91 and 129.
The reason will be displayed to describe this comment to others. Learn more.
Important: Step 1 tells readers to classify their queries into "works as-is / rewrite as Gremlin / switch to a REST API" against the compatibility notes, and line 12 points there for "the verified and unverified areas". After 6f52040 that page opens with "No statement on this page describes a released HugeGraph version" and contains only the test record for the unmerged hugegraph/hugegraph#238 change: request forms, fixture test methods, and a list of unverified constructs. It has no per-construct classification a Neo4j user can apply to a released server, so the first step of the migration path cannot be followed.
Requested change: point step 1 and line 12 at the Known limitations section of hugegraph-cypher.md (which does describe released behaviour), or add a short released-version classification to the guide and link that. Same change in the CN page, lines 12 and 37 to 38.
The reason will be displayed to describe this comment to others. Learn more.
Minor: "10 commits ahead and 5 behind" is already out of date. gh api repos/apache/hugegraph/compare/master...27a7c9b returns diverged ahead=10 behind=6 today, and the count changes with every master merge. The same applies to "master currently declares tinkerpop.version3.5.1", which stops being true when the TinkerPop upgrade lands. Please drop the ahead/behind counts and anchor the master statements to a commit or a release (for example "as of 1.7.0"). CN line 17 has the same counts.
The reason will be displayed to describe this comment to others. Learn more.
Minor: "A released build exposes exactly two request forms on /graphspaces/{graphspace}/graphs/{graph}/cypher" holds only for 1.7.0. CypherAPI at tags 1.0.0, 1.2.0, 1.3.0 and 1.5.0 is @Path("graphs/{graph}/cypher"); the graphspace path first appears in 1.7.0. Please say "1.7.0 exposes..." or mention that earlier releases use /graphs/{graph}/cypher. CN lines 9 to 10 make the same claim.
@n24q02m For Neo4j data migration, please recommend Apache SeaTunnel 3.0.0 as the preferred option in both the EN and CN migration guides, including the “Import data” step and the bulk-import entry in the habits table. Please base all SeaTunnel examples and connector links on 3.0.0.
SeaTunnel's official download page lists 3.0.0 as released on September 29, 2026. Its official versioned connector documentation covers:
Neo4j Source: reads Cypher query results with explicit field schemas; 3.0.0 adds multi-table reads via tables_configs.
HugeGraph Sink: 3.0.0 refactors the sink with multi-mapping support. Use the recommended mappings configuration for vertices/edges and document the applicable schema creation behavior.
HugeGraph Source: newly added in 3.0.0 for reading vertices/edges, with schema auto-discovery and multi-label/parallel reads. This also enables HugeGraph export and migration workflows.
Please explicitly identify these 3.0.0 additions/changes and link the official pages so readers can distinguish them from the older connector behavior.
Please also link HugeGraph's own Import Graph Data with SeaTunnel Sink guide from the migration guide. It targets SeaTunnel 3.0+ and explains environment preparation, the new mappings configuration, and vertex/edge import examples. Use this as the HugeGraph-side setup reference alongside the SeaTunnel 3.0.0 connector documentation above.
For this Neo4j migration, the recommended path is Neo4j Source → HugeGraph Sink, without an intermediate file export. Explain the property, stable vertex ID, and edge endpoint mappings, and load vertices before edges. Loader can remain an alternative for file-based imports.
The connector capabilities above are documented; a complete Neo4j → HugeGraph migration has not been run as part of this check, so validate any example before presenting it as tested.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: yes. Summary: The new navigation entries change the pinned versioned-site metadata, so artifact validation will fail until the expected metrics are regenerated. The exact-head Actions run also fails in its OINK baseline check. Evidence: data/docs_nav.json:220-226 and scripts/versioning.py:130-166,3444-3447.
The reason will be displayed to describe this comment to others. Learn more.
‼️ Blocking: yes. Summary: These new navigation entries change the generated metrics (latest page count and tree hash, plus each historical version's removed count and tree hash), but this PR leaves DOCS_NAV_EXPECTED_STATS unchanged. validate_artifact() compares generated docsNavigation against those pinned values, so the version builds will fail after the earlier OINK check; please regenerate and update the expected stats alongside these routes. Evidence: the new routes are added here and are null for historical versions in data/version_routes.json; exact-head scripts/versioning.py still pins latest pages at 91 and checks metadata at lines 3444-3447.
The reason will be displayed to describe this comment to others. Learn more.
⚠️ Blocking: no. Summary: The disclaimer says no statement on this page describes a released version, but the same paragraph immediately defines released API request forms and the table labels some forms as released. Please limit the disclaimer to the development-tree test results and keep the released behavior explicitly scoped. Evidence: lines 9-13 and the request-form table at lines 29-34.
Habits table (bulk-import entry): both guides now point graph-to-graph data migration at Apache SeaTunnel 3.0.0 (released 2026-09-29), with the HugeGraph Loader kept as the alternative for file-based bulk loads.
"Import data" step rewritten around the recommended direct path Neo4j Source → HugeGraph Sink (no intermediate file export), noting REST for small datasets, plus property → PropertyKey mapping, stable vertex IDs kept stable, edge endpoints mapped to existing vertices, and vertices-before-edges ordering.
3.0.0 additions called out explicitly with official links: Neo4j Source (tables_configs multi-table reads), HugeGraph Sink (mappings refactor + schema-creation behavior), and the new HugeGraph Source for export/migration workflows.
Caveat kept explicit: connector capabilities are documented upstream, but a complete Neo4j → HugeGraph migration has not been run end-to-end here — readers should validate examples on their own data before treating them as tested.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The released-behaviour claims in the guide hold against apache/hugegraph master: the Cypher endpoint rejects requests without a Basic or Bearer header, POST takes a raw application/json string, $param is inlined as null because CypherOpProcessor uses inline_parameters with an empty binding map, EXPLAIN returns translation, failures come back through status.message, and hugeClient.cypher().execute(...) exists in hugegraph-client. EN and CN match, and every internal link target exists at this head. The SeaTunnel step added in f09e8e3 has one gap: it does not tell the reader which vertex ID strategy to create in step 2, and step 3 depends on that choice. Points already raised in open threads (docs_nav expected stats, release-scoped paths, write examples against the example schema, Basic auth parsing, the TCK percentage, the IndexLabel link) are not repeated here. Evidence: git diff a5a9861..f09e8e3 (10 files), apache/hugegraph master d9abcd4 CypherAPI.java, CypherClient.java, CypherModel.java and CypherOpProcessor.java, hugegraph-toolchain master HugeClient.cypher() and CypherManager.execute(String), and the in-repo guides quickstart/toolchain/import/hugegraph-seatunnel-connector.md and export-migration/hugegraph-seatunnel-source.md at this head. The Build and deploy site run for this head is action_required and is waiting for maintainer approval.
The reason will be displayed to describe this comment to others. Learn more.
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.
- link the standalone ASF change and tested source
- document validated request and reserved value boundaries
- refresh the bilingual verification record and regex scope
- preserve the historical baseline failure evidence
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The new commit's claims about apache/hugegraph#3289 match the code at fd8f4a6. Two minor accuracy gaps are new: the missing-binding error is scoped to the JSON-object form, but in #3289 it also applies to GET and raw POST, and the migration table still sends readers to the fork PR #238. The open blocking thread on data/docs_nav.json:220 (DOCS_NAV_EXPECTED_STATS not updated) still applies at this head and is not repeated here. Evidence: git diff f09e8e3 eb4e1aa. At apache/hugegraph fd8f4a6, the head of the open, non-draft #3289, I read CypherAPI, CypherClient and CypherOpProcessor and counted the @test methods: CypherApiTest 23, CypherClientTest 7, CypherOpProcessorTest 8. Every test method named on the page exists. testInvalidRequests covers the 400 bodies and testRejectPlainTextPost covers the 415. e62c961 is an ancestor of master, is the merge base of #3289, and pins TinkerPop 3.8.1 with release 17. I ran versioning.materialize_docs_navigation in worktrees: the base a5a9861 gives latest pages=91 and treeSha256 3314337a..., which matches the pinned values, and the head gives pages=94 and treeSha256 1ac19691..., so validate_artifact will fail for latest. The latest-head 'Build and deploy site' run is action_required, waiting for maintainer approval.
The reason will be displayed to describe this comment to others. Learn more.
Minor: This scopes the missing-binding error to the JSON-object form, and the request table describes GET and raw-body POST as unchanged ("Existing query-string form", "Legacy raw-body form remains available"). In #3289 at fd8f4a6 the error also applies to those two forms. CypherAPI.query and the raw-body path of CypherAPI.post pass Collections.emptyMap(), CypherClient.createRequest always adds that map as ARGS_BINDINGS, and CypherOpProcessor.validateParameters throws Missing Cypher parameter: <name> for every Parameter node in the AST that has no entry in the map. So once #3289 merges, GET ?cypher=MATCH (n:person) WHERE n.name = $name RETURN n changes from the released behaviour that lines 11 to 12 and 35 to 36 describe (null binding, no rows) to an execution error. No test in the table covers $param through GET or raw POST, so this comes from reading the code, not from a test result.
Requested change: say that on the tested tree a missing binding is an execution error for every request form, including GET and raw-body POST, and that this replaces the released null-and-no-rows behaviour. Add the same note to the Known limitations bullet in hugegraph-cypher.md (line 139), and make the same change on the CN pages (compatibility line 47, guide line 139).
| `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) |
The reason will be displayed to describe this comment to others. Learn more.
Minor: The last commit moved the guide and the compatibility page to the Apache change. hugegraph-cypher.md line 139 now says bound parameters "are proposed in the unmerged ASF PR #3289, carried over from PR #238", and the compatibility page names #3289 as the standalone code change. This row still says JSON-bound parameters "land in PR #238". #238 is on the hugegraph/hugegraph organization repository, so no Apache HugeGraph release will ship from it. The CN row (line 30) has the same text.
Requested change: in both languages, point this row at apache/hugegraph#3289, worded the way the guide words it (unmerged, carried over from #238).
- mark the upstream Cypher change as merged
- distinguish master support from the 1.7.0 release
- align bilingual usage and migration notes
- separate translator TCK results from compatibility claims
@n24q02m A quick update on the validation baseline: Server and Toolchain have both landed substantial changes. The supported build/runtime baseline is now Java 17, with Server on TinkerPop 3.8.1; the Toolchain Java 17 build contract is also merged in apache/hugegraph-toolchain#787.
The basic Cypher improvements are now merged in apache/hugegraph#3289, including JSON-bound parameters, request validation, and same-thread rollback/failure cleanup. These are available on current master; please keep that distinct from the published 1.7.0 release in the documentation.
Could you run the documented examples against the latest Server and Toolchain master, confirm the query, parameter-binding and basic read/write behavior, and update the verification record with the actual versions and results? Please keep unverified features clearly separate. Once that confirmation is in place, we can move this documentation PR toward merge promptly.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The new claims in 486f137 and 38db01d about apache/hugegraph#3289 match the merged code: it merged as 5039e5b on 2026-10-08, the 16-binding cap is fixed, and the tested tree sits on af3c686 (1.8.0, TinkerPop 3.8.1). One new minor problem: the SeaTunnel 3.0.0 docs link in the migration guide returns 404. The open blocking thread on data/docs_nav.json:220 (DOCS_NAV_EXPECTED_STATS) still applies after a rebase and is not repeated here. Evidence: read the full exact-head diff, EN and CN. At apache/hugegraph 5039e5b I read CypherAPI, CypherOpProcessor and docs/cypher-compatibility.md. The @test counts are 23/7/8, and every test method named on the page exists. The Cypher sources at the verified commit 8d06ad3 are identical to 5039e5b, and the merge base of 8d06ad3 and master is af3c686. CypherOpProcessor has no init override, so maxParameters stays at the TinkerPop default of 16, and getTranslatorDefinition rejects any other processor config key. HugeClient.cypher() and CypherManager.execute(String) exist on toolchain master. Merged 38db01d into hugegraph-doc master e6389aa locally: strict scripts/hugo.sh build passes (EN 294 / CN 292 pages), and all 62 internal links and anchors on the six new pages resolve. versioning.materialize_docs_navigation gives latest pages=95 and treeSha256 fd869e87..., but master pins pages=92 and 15de4de3..., so validate_artifact will still fail. The latest-head 'Build and deploy site' run failed in prepare because scripts/version_cache.py, which the master workflow calls, is missing at this head (base a5a9861). The branch needs a rebase before CI can say anything about this change.
The reason will be displayed to describe this comment to others. Learn more.
Minor: The "SeaTunnel 3.0.0 connector docs" link goes to https://seatunnel.apache.org/docs/3.0.0/about/, which returns HTTP 404 ("Page Not Found"). SeaTunnel 3.0.0 moved that page to https://seatunnel.apache.org/docs/3.0.0/introduction/about/, which returns 200. The old path still works only for 2.3.x (/docs/2.3.12/about/). The three connector links below this line (Neo4j Source, HugeGraph Sink, HugeGraph Source) all return 200, so only this one is broken. The Hugo build cannot catch it because it is an external link.
Requested change: point the link at https://seatunnel.apache.org/docs/3.0.0/introduction/about/, or at https://seatunnel.apache.org/docs/3.0.0/connectors if the sentence is meant to name the connector index. The CN page has the same link on line 51.
The reason will be displayed to describe this comment to others. Learn more.
Minor: Same broken link as the EN page (line 56). https://seatunnel.apache.org/docs/3.0.0/about/ returns HTTP 404. The 3.0.0 page is at https://seatunnel.apache.org/docs/3.0.0/introduction/about/. Please update it the same way as the EN page.
Addressed the open review threads; pushed as 1481d96 (merge of current master), 2079bd0, and ad1d032.
data/docs_nav.json expected stats (blocking) — regenerated DOCS_NAV_EXPECTED_STATS by running the full versioning.py build pipeline at the merged head for all five versions. latest is now pages: 95, treeSha256: fd869e87… (the 92-page nav from master plus the three new pages). The three new nav entries resolve to nothing on the pinned release content, so each historical version's removed count rises by exactly 3 (1.7: 5→8, 1.5: 13→16, 1.3: 22→25, 1.0: 21→24); the historical treeSha256s are unchanged, matching the mechanism described in the review. validate passes for all five versions locally, and the versioning unit tests pass.
Missing-binding scope — both language versions of the compatibility page and the guide's Known limitations bullet now state that on the tested tree the missing-binding execution error applies to every request form, including GET ?cypher= and raw-body POST, replacing the released null-and-no-rows behaviour, per the #3289 code path.
Released-form scoping — the scope section now attributes the two request forms to 1.7.0 explicitly and notes that releases before 1.7.0 expose the same forms under /graphs/{graph}/cypher.
Migration guide step 1 — classification now points at the Known limitations section (which describe released behaviour); the compatibility notes are described as the development-tree record only. The English page is brought in line with the Chinese page here.
Vertex ID strategy (step 3) — the reader is now told to pick the strategy before importing: idStrategy = "PRIMARY_KEY" with a Neo4j business key in idFields and edge endpoints expressed through those same key fields, or idStrategy = "CUSTOMIZE_STRING" to keep the Neo4j node id; pre-created labels must use the same strategy (automatic creation does not convert PRIMARY_KEY to CUSTOMIZE_STRING), and step 2 is optional when the Sink mappings configuration creates the schema.
Example schema assumption — the examples now state they assume nullableKeys("age", "city") on person and nullable knows properties, and that on the released default schema the create/update examples fail the non-null property check.
The earlier threads (the #238→#3289 provenance row, the stale ahead/behind counts, and the disclaimer scoping) were addressed by the earlier commits on this branch.
Results: both legacy forms, the JSON-object form, aggregation/order/limit, single-vertex CREATE, SET/REMOVE, edge DELETE and DETACH DELETE all behaved as documented, checked with native REST readback. A missing binding is an execution error (status.code 400) on all three request forms; 17 top-level bindings are rejected; one Map with 20 entries works via explicit property references (only the referenced fields are written); text/plain gives 415; non-object JSON bodies give 400. On auth: the cypher endpoint rejects header-less requests with 401, and with server auth disabled any Basic credentials or a Bearer token are accepted.
One addition: the two-vertex shorthand CREATE (a)-[:knows]->(b) fails on a PRIMARY_KEY label ("The primary keys: [name] of vertex label 'person' must be set", status.code 400) but works on an AUTOMATIC label; single-vertex CREATE is fine on both. I documented that caveat and pointed the example at separate CREATE statements in a49a8c3.
The examples this PR documents go through the server REST endpoint, so I did not exercise the toolchain clients separately.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The Cypher guide, compatibility record and Neo4j migration guide match the server code at apache/hugegraph 5039e5b (merged #3289) and 1.7.0 on every behavioural claim I checked, and EN/CN agree. A few accuracy and link problems remain open at a49a8c3: Basic credentials are documented without the parser's limits, the guide's write example fails on the schema the guide itself recommends, the index/constraint row links a read-only page, one SeaTunnel link returns 404, the TCK percentage is mis-rounded, and one CN term is looser than the API contract. None changes released-version behaviour a reader relies on. Evidence: full exact-head diff (11 files) read in a detached worktree; CypherAPI, CypherClient and CypherOpProcessor read at 5039e5b (graphspace @path, emptyMap for GET/raw POST, ARGS_BINDINGS always attached, validateParameters missing-binding error, maxParameters with unknown-config rejection, EXPLAIN translation path, RESERVED_NULL_VALUE); scripts/example.groovy at 5039e5b; HugeClient.cypher() and CypherManager.execute in hugegraph-toolchain master; every internal link and anchor resolved against content/ at this head; curl on the SeaTunnel URLs; all check runs on a49a8c3 are success (publish skipped).
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.
The reason will be displayed to describe this comment to others. Learn more.
Important: Basic credentials are documented as accepted without qualification, but at apache/hugegraph 5039e5b CypherAPI still decodes them with Base64.getUrlDecoder() and then does authorization.split(":") and requires exactly two parts. A standard Basic header whose Base64 contains + or / fails to decode, and a password containing : splits into three parts; both make toUserPass return null and the request fails before reaching Gremlin Server. Requested change: state that Basic credentials must use URL-safe Base64 and that the password must not contain : (or recommend Bearer for such accounts), here and in CN line 32. The same point is open in an earlier thread on this line.
The reason will be displayed to describe this comment to others. Learn more.
Minor: Line 51 tells readers to use the scripts/example.groovy schema with nullable keys added. That schema declares person with .primaryKeys("name") (example.groovy line 39 at 5039e5b), and lines 54-57 say this exact two-vertex shorthand is rejected on a PRIMARY_KEY label. So a reader who follows the recommended setup gets an execution error on this example. Requested change: replace the example with a form that works on the recommended schema, for example two single-vertex CREATE statements followed by MATCH (a:person {name:'peter'}), (b:person {name:'lop'}) CREATE (a)-[:knows]->(b), or recommend an AUTOMATIC id strategy in the setup paragraph. Same change in CN line 90.
The reason will be displayed to describe this comment to others. Learn more.
Minor: The row says to create indexes and constraints through the schema REST APIs and links /docs/clients/restful-api/schema/, which only documents GET .../schema. Index creation is documented in /docs/clients/restful-api/indexlabel/ (POST .../schema/indexlabels). Requested change: link the IndexLabel page, here and in CN line 29.
The reason will be displayed to describe this comment to others. Learn more.
Minor: https://seatunnel.apache.org/docs/3.0.0/about/ returns HTTP 404 (checked with curl on 2026-10-09); https://seatunnel.apache.org/docs/3.0.0/introduction/about/ returns 200. Requested change: update the link here and in CN line 53.
The reason will be displayed to describe this comment to others. Learn more.
Minor: 非空字符串 admits whitespace-only strings, but CypherAPI.queryByCypher rejects cypher.isBlank() and the EN page says nonblank. Requested change: use 非空白字符串 to match the API and the EN text.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The released-version missing-parameter description overstates row behavior: an absent binding becomes null, and whether rows remain depends on the expression. Evidence: apache/hugegraph 1.7.0 CypherOpProcessor uses inline_parameters without missing-binding validation; the merged CypherApiTest confirms that returning null can still produce a row.
The reason will be displayed to describe this comment to others. Learn more.
⚠️ Important: This says every statement referencing $param returns no rows, but released versions inline a missing binding as null; row behavior then depends on the expression. For example, RETURN $value AS value can return a row containing null, while the documented equality predicate returns no rows. Please scope the no-rows claim to the predicate case and align the repeated EN/CN statements. Evidence: CypherOpProcessor at 1.7.0 configures inline_parameters and parses the statement without missing-binding validation; the merged CypherApiTest at 5039e5b verifies that RETURN $value AS value with a null value returns a row.
This branch has not been deployed
No deployments
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
bitflicker64
left a comment
imbajin
left a comment
Purpose of the PR
What is included
Three pages, each with full EN + CN mirrors under
content/{en,cn}/docs/language/:hugegraph-cypher.md— how to use Cypher in HugeGraph: the/cypherREST endpoint, Java client (CypherManager), MATCH/WHERE/RETURN, CREATE/SET/DELETE, aggregation, Gremlin equivalents for unsupported constructs, and an honest Known limitations section (no parameterized queries in released versions — a missing$paramevaluates to null —, noCALLprocedures, single statement per request).cypher-compatibility.md— a verification record of the parameter-binding change: request forms, verified behavior per test, the baseline failure and its fix, and the unverified areas.migrate-from-neo4j.md— what carries over directly, habits that change (strong schema, schema DDL via REST APIs instead of Cypher), and a suggested migration path.All three new pages are registered in
data/docs_nav.json(group tree, section tree, breadcrumb, section children) anddata/version_routes.json(latest only — the pages do not exist in 1.0–1.7).Validation
scripts/hugo.sh build(strict,--panicOnWarning) passes: EN 292 / CN 290 pages.Notes
ASF code PR #3289 was merged into master on 2026-10-08; its organization mirror #238 is closed. The bilingual pages now distinguish merged master support (the 1.8.0 development line) from the latest published 1.7.0 release, retain the verified request/binding boundaries, and explain that the translator's historical TCK percentage is not a HugeGraph end-to-end compatibility rate. The code dependency is merged, so this documentation PR can be reviewed and merged independently.