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.
Conceptual overview
Conceptual documentation overview of Cypher translation, version boundaries and staged Neo4j data migration. This diagram does not establish migration or release acceptance.
- 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.
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.
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.
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.
- 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.
- 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.
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).
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.
- Basic auth: note that credentials must be URL-safe Base64 and the password cannot contain ':'
- Narrow the "$param returns no rows" claim: 1.7.0 inlines a missing binding as null, so predicates match nothing but RETURN $value still returns a row
- Rewrite the edge CREATE example to create the vertices first and then MATCH them, since PRIMARY_KEY labels reject the multi-vertex shorthand
- Point the index/constraint link at the IndexLabel REST API page
- Fix the SeaTunnel 3.0.0 docs link
- Correct the TCK pass rate to ~91.8% (879/958)
- CN: use 非空白字符串
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Blocking: yes. Summary: The request contract, test mapping, links and navigation data check out against apache/hugegraph 5039e5b and a strict build of this head, but the guide's range-predicate example fails on the schema the page names because person.age has no range index, and the released-version note says a write with a missing $param stores null when 1.7.0 removes the property or stores the translator's marker string. Evidence: read the full diff at 4290c2b (11 files) and the earlier review threads; compared CypherAPI, CypherOpProcessor, CypherClient and the three Cypher test classes at 5039e5b with the pages (23/7/8 tests, all 26 cited method names, the fixed 16-binding limit, the null marker); translated the guide examples with translation-1.0.4; ran the guide examples and the missing-parameter cases against a 1.7.0 server loaded with scripts/example.groovy; versioning.py build and validate for latest pass at this head, dist/validate-links.sh passes, internal links and anchors of the six new pages resolve in the built site, and the nine external links return 200. The only workflow run at this head is waiting for maintainer approval, so there is no CI result yet.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: yes. Summary: The sample CREATE sequence can replace a seeded primary-key vertex; the migration guide also omits required index and ID-field setup. Evidence: HugeGraph 1.7.0 example.groovy seeds the conflicting IDs, and SeaTunnel 3.0.0 requires explicit ID fields and only auto-creates label/property schema.
- Add a RANGE index on person.age to the assumed schema and state that
property predicates need a covering index (mirrored in the habits table
of the migration page and the compatibility notes).
- Use names absent from scripts/example.groovy (alice/bob/carol) in the
create/update/delete examples so PRIMARY_KEY ids do not replace seed vertices.
- Document that a missing $param in a write removes the property on SET and
stores a marker string or fails on CREATE (reviewer-measured on 1.7.0).
- Rewrite the SeaTunnel step: idFields are required for every non-AUTOMATIC
strategy, edges need sourceConfig/targetConfig.idFields, the query must
return the ID column, and mappings do not create IndexLabels.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LHLbjw9SjXQc47Zj7eFuAd
Thanks, all three points are addressed on the new head.
Range predicate without a RANGE index: the schema section now requires a RANGE index on person.age (the page gives the personByAgeindexLabel statement to add to the scripts/example.groovy schema), says that a WHERE property predicate needs a covering index, and migrate-from-neo4j.md has a new row for it. cypher-compatibility.md names the fixture schema used for the 5039e5b run. EN and CN (21083db).
Missing $param on writes: the wording no longer says a write stores null. It now says SET removes the property (or fails on a non-null key) and CREATE stores the " cypher.null" marker string or fails the type check. EN and CN (21083db).
160-character wrap: the five files are rewrapped in 70a1278. The only lines still over 160 characters are single-line links to the test sources, which cannot be split. Wording is unchanged; dist/validate-links.sh passes and a Hugo build of the head succeeds.
Thanks, all three points are addressed in 21083db (EN and CN).
CREATE replacing the seeded peter vertex: the create/match/update/delete examples now use alice, bob and carol, which are not in example.groovy.
CUSTOMIZE_STRING without idFields: the migration page now says the query must return the Neo4j ID, declares it in schema.fields, sets the vertex idFields to it, and maps the edge source and target ID fields.
mappings and IndexLabels: step 2 now says mappings can replace pre-creating PropertyKeys, VertexLabels and EdgeLabels, while the IndexLabels still have to be created separately.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The fixes in 21083db and 70a1278 for the open threads hold at this head: the range example now names its RANGE index, the missing-$param write behaviour matches 1.7.0, the create, update and delete examples avoid the seeded names, the SeaTunnel idFields and IndexLabel notes are in place, and EN and CN agree. One new Minor note: the index rule added in this round says every WHERE property predicate needs an index, which is wrong for primary-key equality lookups and for conditions on adjacent vertices. Evidence: read the full diff e6389aa..70a1278 (11 files) and the delta 4290c2b..70a1278 in a detached worktree. At apache/hugegraph 1.7.0 and master 06f90a9f0 I checked scripts/example.groovy (seeded names, personByCity and personByAgeAndCity SECONDARY only), GraphTransaction.optimizeQuery (label plus all primary keys becomes an id query), IndexLabelBuilder.checkPrimaryKeyIndex and checkRepeatRangeIndex (the suggested personByAge range index is accepted), and HugeVertexStep.queryAdjacentVertices. All 26 cited test methods exist at 5039e5b. A strict scripts/hugo.sh build passes (EN 294 / CN 292), dist/validate-links.sh passes, the CN and EN anchors resolve in the built site, every external link returns 200, and the new prose stays within 160 characters except the three test-source links and the edited one-line _index.md paragraph. scripts/test_versioning passes 80/80. materialize_docs_navigation gives latest pages=95 and treeSha256 fd869e87..., which matches DOCS_NAV_EXPECTED_STATS, both at this head and on a clean merge with master f0107c6. The only workflow run at this head, 'Build and deploy site', is action_required and waiting for maintainer approval.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The migration table maps all Neo4j CREATE CONSTRAINT forms to the IndexLabel API, although HugeGraph stores primary-key and required-property rules on VertexLabels. Evidence: exact-head migration text and the linked IndexLabel and VertexLabel API definitions.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: yes. Summary: The 2026-10-17 merge leaves the navigation and route data correct, and EN and CN agree, but the guide's authentication paragraph is wrong for master: since apache/hugegraph#3290 and #3366, URL-safe Basic credentials that contain - or _ fail there, and no header is needed when authentication is disabled. Evidence: of the PR's own files, merge 0782770 changes only data/docs_nav.json, data/version_routes.json and scripts/versioning.py. In a detached worktree at 0782770, materialize_docs_navigation for latest gives pages=98, removed=4, treeSha256 8491850c..., which matches DOCS_NAV_EXPECTED_STATS. For 1.7 and 1.5 against the release-1.7.0 and release-1.5.0 content, it also matches (85/11 and 77/19, same tree hashes). scripts/test_versioning.py passes 80/80, dist/validate-links.sh passes, and strict scripts/hugo.sh build passes (EN 323 / CN 321). I read CypherAPI at apache/hugegraph 1.7.0 and master f5d9885, the diffs of #3290 (62faab73d), #3366 (8fe10180d) and #3259 (a0aae8e7e), and master docs/cypher-api.md. I also ran Base64.getDecoder() on a URL-safe credential locally. The only workflow run at this head, 'Build and deploy site' 39038694697, is action_required and waiting for maintainer approval. The open threads on the index rule (hugegraph-cypher.md:60) and CREATE CONSTRAINT (migrate-from-neo4j.md:31) still apply and are not repeated.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: yes. Summary: The fixes in 1e5df57 hold for the auth paragraph on master and 1.7.0, the dated compatibility pin, and the primary-key exception to the index rule. The new constraint row in the migration guide still has a gap: it leaves out HugeGraph's UNIQUE IndexLabel and sends key-style constraints to primary_keys, which overwrites a duplicate instead of rejecting it. Two minor wording points remain: the English index sentence no longer limits itself to WHERE property predicates, and "1.7.0 and earlier" does not hold for 1.0.0. Evidence: read the full diff against base 278fdcb (13 files) and the 0935438..1e5df57 delta (8 files). Read CypherAPI at apache/hugegraph 1.0.0, 1.2.0, 1.3.0, 1.5.0, 1.7.0 and master 90790e86 (the anonymous client from #3366, Base64.getDecoder() and split(":", 2) from #3290), GraphTransaction.optimizeQuery (label plus all primary keys becomes an IdQuery), and IndexType.UNIQUE with GraphIndexTransaction.updateIndex ("Unique constraint ... conflict"), which is in every release from 1.0.0 on. At this head, materialize_docs_navigation for latest gives pages=98, removed=4, treeSha256 8491850c..., the same as DOCS_NAV_EXPECTED_STATS. scripts/test_versioning.py passes 85/85 and dist/validate-links.sh passes. The new VertexLabel link targets exist in both locales. I could not run a strict Hugo build locally: the module needs Hugo 0.168.0 and 0.166.0 is installed. The only workflow run at this head, 'Build and deploy site' 39127283628, is action_required and waiting for maintainer approval.
The reason will be displayed to describe this comment to others. Learn more.
Minor: "On 1.7.0 and earlier" does not hold for 1.0.0. In 1.0.0 the endpoint is hugegraph-api/.../api/gremlin/CypherAPI.java. It never throws NotAuthorizedException and never decodes Basic credentials. It forwards whatever Authorization header it gets, including none, to Gremlin Server with doPostRequest(auth, request). A request without the header therefore works when auth is disabled, and Basic credentials are not limited to URL-safe Base64. The header requirement, Base64.getUrlDecoder() and split(":") first appear in the api/cypher/CypherAPI rewrite and are the same in 1.2.0, 1.3.0, 1.5.0 and 1.7.0.
Requested change: write "On 1.2.0 to 1.7.0" here, in CN hugegraph-cypher.md line 34, and in both clients/restful-api/cypher.md notes (line 10).
This 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.
Conceptual overview
Conceptual documentation overview of Cypher translation, version boundaries and staged Neo4j data migration. This diagram does not establish migration or release acceptance.