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.
The compatibility record now follows the standalone ASF code PR #3289, rebased onto current Apache master, with refreshed live RocksDB validation and request/binding boundaries. The original organization PR #238 remains linked. Coordinate the documentation merge with the code change.
- 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
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
The compatibility record now follows the standalone ASF code PR #3289, rebased onto current Apache master, with refreshed live RocksDB validation and request/binding boundaries. The original organization PR #238 remains linked. Coordinate the documentation merge with the code change.