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
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.
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.
Blocking: no. Summary: 628170c fixes two of the three points from the previous round: the constraint row now maps uniqueness to UNIQUE IndexLabels and says that primary_keys overwrites, and the English index sentence is scoped to WHERE property predicates on the starting vertex again. One new Minor gap is in the constraint row: a UNIQUE index cannot cover the primary keys of a PRIMARY_KEY label, and step 3 suggests exactly that setup. The open Minor on hugegraph-cypher.md:36 ("1.7.0 and earlier" does not hold for 1.0.0) still applies at this head and is not repeated. Evidence: read the full diff against master 2102662 (13 files) and the 1e5df57..628170c delta (3 files); the 628170c..59ae3bc merge touches no file in this PR. At apache/hugegraph 1.0.0, 1.7.0 and master c2ec57043 I read IndexLabelBuilder.checkPrimaryKeyIndex, GraphIndexTransaction.updateIndex (UNIQUE conflict), HugeVertex.constructEdge (edge non-null keys) and GraphTransaction.checkNonnullProperty; CypherAPI at 1.0.0, 1.2.0 and 1.7.0. At this head scripts/test_versioning.py passes, dist/validate-links.sh passes, and the latest navigation stats match DOCS_NAV_EXPECTED_STATS. The only workflow run at this head, 'Build and deploy site' 39133157795, is action_required and waiting for maintainer approval.
State the supported range as 1.2.0 to 1.7.0 and document that a UNIQUE
index cannot cover all primary keys of a PRIMARY_KEY label, with the
CUSTOMIZE_STRING workaround that keeps duplicate rejection.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Khcp1EMFjG59GuGNef1U73
The reason will be displayed to describe this comment to others. Learn more.
Rechecked at 2f0b5ba084de59d9092666778b9e89d06a5ac59b (2026-10-19). The two latest documentation corrections are independently confirmed: the EN/CN migration rows distinguish PRIMARY_KEY identity from UNIQUE duplicate rejection, including the prohibition on indexing all primary keys; all four authentication notes correctly scope the older behavior to 1.2.0–1.7.0.
Evidence: IndexLabelBuilder.checkPrimaryKeyIndex, CypherAPI at the 1.0.0/1.2.0/1.3.0/1.5.0/1.7.0 tags, and current authentication handling. A separate source cross-check confirmed that CUSTOMIZE_STRING retains supplied identity independently of primary-key-derived identity; the guide already explains node_id and edge endpoint mappings.
Current independent documentation/static-review score: 8.5/10. No new blocking finding across the current 13-file patch. This review did not run Hugo, runtime Cypher queries or a live Neo4j migration, and does not reclassify historical verification as current acceptance. The workflow for this head remains action_required; recommend waiting for current-head CI/acceptance.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The guide reflects the verified Cypher behavior, but the current error envelope and parallel-edge migration semantics still need to be documented. Two inline comments identify these gaps. Evidence: Checked the claims against Apache master at fd8d06c, merge #3259, and SeaTunnel 3.0.0 docs and source at 543f2a5.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The Cypher shortcut omits required vertex data under the assumed schema, and the recommended SeaTunnel path can skip failed records by default. Evidence: GraphTransaction.checkNonnullProperty at 5039e5b and the official SeaTunnel 3.0.0 HugeGraph Sink configuration.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The migration guide misstates the released connector's failure-handling defaults. Evidence: SeaTunnel v3.0.0 HugeGraphOptions.java defines both defaults.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: yes. Summary: SeaTunnel auto-created EdgeLabels default to SINGLE, so the migration guide still loses parallel Neo4j relationships, and the compatibility page still says the two-vertex shorthand works with AUTOMATIC despite the non-null check.
The earlier review comments below still apply at da365c9; this head does not fix them.
⚠️ Important: Blocking: no. Summary: This only says translation failures appear in status.message, but current master also returns stable status.attributes.errors entries with code, message and hint after #3259. Please document this machine-readable error shape in the REST API reference, or scope this statement to the pinned pre-#3259 commit. Evidence: Current CypherModel.failOf() populates status.attributes.errors, and CypherClient maps failures through CypherErrorMapper; merge #3259 is a0aae8e7. (#499 (comment))
⚠️ Important: Blocking: no. Summary: Auto-created EdgeLabels default to SINGLE when SeaTunnel 3.0.0 mappings omit frequency, so parallel Neo4j relationships with the same type and endpoints cannot retain distinct edge identities. Please warn about this and specify frequency = "MULTIPLE" with a stable relationship sortKeys in both language guides. Evidence: SeaTunnel 3.0.0 SchemaManager defaults a missing frequency to SINGLE and requires sort keys for MULTIPLE (commit 543f2a5); HugeGraph edge IDs include sort keys. (#499 (comment))
The reason will be displayed to describe this comment to others. Learn more.
Blocking: no. Summary: The endpoints, auth rules, binding contract, error envelope, cited test methods, links and navigation stats match apache/hugegraph master, 1.7.0 and the nav generator. One problem remains: the migration table gives the wrong HTTP status for a missing-index error.
The reason will be displayed to describe this comment to others. Learn more.
Blocking: yes. Summary: The 1.0 entry in DOCS_NAV_EXPECTED_STATS expects one removed page too many, so the versioned site build fails at this head. The new section index cards also describe content that the Cypher compatibility and Neo4j migration pages do not contain.
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.