Repository navigation
Conversation
- Add comprehensive bilingual migration guides for TinkerPop 3.8.1 upgrade - Highlight top 6 high-frequency syntax changes with code examples - Categorize edge cases and protocol references into quick-access tables - Update Gremlin language reference step and feature tables - Align Server quickstart and introduction with 1.8.0 release scopes - Draft 1.8.0 release notes with Gremlin breaking changes summary
183acfe to
7748d24
Compare
- Add comprehensive bilingual migration guides for TinkerPop 3.8.1 upgrade - Highlight top 6 high-frequency syntax changes with code examples - Categorize edge cases and protocol references into quick-access tables - Update Gremlin language reference step and feature tables - Align Server quickstart and introduction with 1.8.0 release scopes - Draft 1.8.0 release notes with Gremlin breaking changes summary
7748d24 to
76fa08e
Compare
bitflicker64
left a comment
bitflicker64
left a comment
There was a problem hiding this comment.
Blocking: yes. Summary: Most of the Gremlin behaviour this guide describes checks out on TinkerPop 3.8.1, but three points would mislead users upgrading from 1.7.0. The date steps are listed as breaking changes, but they do not exist in 3.5.1. The serializer table leaves out HugeGraph's GraphBinary builder and registries. The release notes say the word analyzer is removed, but only its jar is no longer bundled. Five smaller accuracy points are attached. Evidence: I checked versions in apache/hugegraph: tag 1.7.0 uses TinkerPop 3.5.1 and Java 11; master fd8d06c51 uses TinkerPop 3.8.1, Groovy 4.0.25 and Java 17. I ran the guide's queries on TinkerGraph through GremlinGroovyScriptEngine 3.5.1 (JDK 11) and 3.8.1 (JDK 17). These confirmed: has(key, traversal) silently returns [] on 3.8.1; store() and aggregate(Scope) are gone; none() is replaced by discard(); by() drops elements with missing properties; choose() runs only the first match and passes unmatched elements through; local() unrolls bulk; range(local) wraps single items; sum() returns Integer. I also confirmed that datetime, dateDiff, mergeV, mergeE, split and asString are all missing on 3.5.1. Source checks: master gremlin-server.yaml, docs/server-runtime.md, HugeGraphIoRegistry, HugeGraphTypeSerializerRegistryBuilder, HugeFeatures, HugeVertex and HugeVertexProperty, PathFilter, docs/BUILDING.md and #3295. I confirmed the GraphBinary missing-serializer error with gremlin-util 3.8.1, and the GraphSON maxNumberLength default of 10000 in GraphSONMapper 3.8.1. At this head, dist/validate-links.sh passes and scripts/test_versioning.py passes 85/85. I could not run a strict Hugo build because the site needs Hugo 0.168.0 with Dart Sass. There were no earlier review comments, and the PR has no CI checks at this head.
bitflicker64
left a comment
bitflicker64
left a comment
There was a problem hiding this comment.
Blocking: yes. Summary: At 0cc3ffb all eight threads from 76fa08e are addressed: the date steps are now listed as new, the serializer section points to the bundled yaml with the builder and registries, the word analyzer note is correct, and the five Minor points are fixed in both languages. Two new problems block the guide. First, on HugeGraph 1.8 the headline has(key, traversal) case fails with an error; it does not return an empty result. Second, the new serializer rows map typed GraphSON V2/V3 to the untyped classes. Three Minor points are inline. Evidence: read the full diff df23ce2..0cc3ffb (10 files, +544/-10) and the incremental change from 76fa08e. I ran every query in the guide through GremlinGroovyScriptEngine on TinkerGraph 3.5.1 (JDK 11) and 3.8.1 (JDK 17). I also ran the guide's has, none/discard, order().by, choose and dateDiff lines on an in-process HugeGraph 1.8.0 build (TinkerPop 3.8.1, Groovy 4.0.25, memory backend). I printed mimeTypesSupported() for the GraphSON serializers in gremlin-driver 3.5.1 and gremlin-util 3.8.1. Source checks at apache/hugegraph master 86c05ef: gremlin-server.yaml, docs/server-runtime.md, TraversalUtil.validPropertyValue(), PropertyKey/DataType.valueToNumber() in hugegraph-struct, HugeFeatures, PathFilter and the pom versions; also 1.7.0 gremlin-server.yaml. dist/validate-links.sh passes at this head, and the datetime() output types, dateDiff() in milliseconds, the by() and choose() behaviour, B07/B09/B11/B14/B15 and the GraphSON limit default of 10000 match TinkerPop 3.8.1. The Hugo build was not run: Hugo 0.166 is installed and the site needs 0.168 with Dart Sass. The PR has no CI checks at this head.
|
|
||
| * **Impact**: | ||
| In TinkerPop 3.8.0, the `has(String, Traversal)` and `has(T, Traversal)` overloads were removed. | ||
| In the Groovy script engine, legacy code will not throw a compilation error; instead, it **silently falls back to `has(String, Object)`**, comparing the anonymous traversal object itself against vertex/edge properties. In practice, this **silently yields 0 results / empty sets**! |
There was a problem hiding this comment.
Important: On HugeGraph 1.8 this query does not return an empty result; it fails. HugeGraph pushes has() into its own query, and TraversalUtil.validPropertyValue() rejects a traversal as the value. I ran the guide's two legacy lines on an in-process 1.8.0 build (TinkerPop 3.8.1, memory backend, age as an INT key with a range index). g.V().has('age', __.is(gt(30))) fails with IllegalArgumentException: Invalid data type of query value '[IsStep(gt(30))]', expect INT for 'age', actual got class org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.DefaultGraphTraversal. g.V().has(T.label, __.is('person')) fails with HugeException: The label type must be number or string, but got 'class org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.DefaultGraphTraversal'. The same error appears when the has() sits inside where() or filter(), or follows in(). The silent [] happens on TinkerGraph, not on HugeGraph. Users who follow this text will look for queries that return nothing, while their logs show an error that the guide never mentions. Please describe the 1.8 symptom as this error and quote its text, and keep the TinkerGraph silent case as a side note at most. Line 29 of this page and line 17 of both release notes make the same claim. The CN guide needs the same change at lines 22, 26 and 29.
| |---|---|---|---| | ||
| | `GraphBinaryMessageSerializerV1` | `org.apache.tinkerpop.gremlin.util.ser.GraphBinaryMessageSerializerV1` | `builder: org.apache.hugegraph.io.HugeGraphTypeSerializerRegistryBuilder`<br>`ioRegistries: [org.apache.hugegraph.io.HugeGraphIoRegistry]` | Recommended default binary serializer | | ||
| | `GraphSONMessageSerializerV1d0` | `org.apache.tinkerpop.gremlin.util.ser.GraphSONUntypedMessageSerializerV1` | `ioRegistries: [org.apache.hugegraph.io.HugeGraphIoRegistry, org.apache.hugegraph.io.HugeGraphSONV1MessageIoRegistry]` | Untyped GraphSON V1 | | ||
| | `GraphSONMessageSerializerV2d0` | `org.apache.tinkerpop.gremlin.util.ser.GraphSONUntypedMessageSerializerV2` | `ioRegistries: [org.apache.hugegraph.io.HugeGraphIoRegistry]` | Untyped GraphSON V2 | |
There was a problem hiding this comment.
Important: These two rows map typed serializers to untyped ones. In TinkerPop 3.5.1, GraphSONMessageSerializerV2d0 serves application/vnd.gremlin-v2.0+json and GraphSONMessageSerializerV3d0 serves application/vnd.gremlin-v3.0+json, and both are typed. Their 3.8.1 names are GraphSONMessageSerializerV2 and GraphSONMessageSerializerV3, which serve the same MIME types. GraphSONUntypedMessageSerializerV2 and GraphSONUntypedMessageSerializerV3 serve application/vnd.gremlin-v2.0+json;types=false and application/vnd.gremlin-v3.0+json;types=false instead. I printed these lists from mimeTypesSupported() in gremlin-driver 3.5.1 and gremlin-util 3.8.1. If a user edits a 1.7.0 yaml row by row with this table, a client that asks for typed GraphSON v2 or v3 finds no matching serializer, and its requests fail. The gremlin-server.yaml on master has both forms: untyped V1/V2/V3, then typed GraphSONMessageSerializerV2 and GraphSONMessageSerializerV3, the order docs/server-runtime.md describes. Please map V2d0 to GraphSONMessageSerializerV2 and V3d0 to GraphSONMessageSerializerV3, and list the untyped V2/V3 entries as additions that the 1.8.0 file brings. The CN table (lines 172-173) needs the same change. Its V3 row also labels the untyped class "标准 Typed GraphSON V3".
| g.V().hasLabel('person').discard() | ||
|
|
||
| // Discarding unhandled inputs in choose() branches: | ||
| g.V().choose(__.values('age')).option(gt(30), __.values('name')).option(Pick.none, __.discard()) |
There was a problem hiding this comment.
Minor: On a vertex without age, this example does not discard the input. Pick.none only covers values that match no option; when the choice traversal returns nothing, 3.8.1 passes the element through. On TinkerGraph 3.8.1 this exact line returns [v[3], josh, v[5], peter]. On the HugeGraph 1.8.0 build, a person vertex without age comes back as v[1:noage]. Section 5 already adds .option(Pick.unproductive, __.discard()) for this case. Please add it here as well, or change the comment so it says only unmatched values are dropped. CN lines 86-87 need the same change.
| --- | ||
| title: "HugeGraph 1.8.0 Release Notes" | ||
| linkTitle: "Release-1.8.0" | ||
| weight: 1 |
There was a problem hiding this comment.
Minor: The 1.7.0 release notes also use weight: 1. The changelog pages step by 2 (1.5.0 is 3, 1.3.0 is 5) so the newest release comes first. When weights are equal, Hugo orders pages by date and then by link title. These pages have no date, so Release-1.7.0 sorts above Release-1.8.0 in the sidebar. weight: 0 does not work either, because Hugo treats 0 as unweighted and puts the page last. Please give 1.7.0 a larger weight (for example 2) in both languages, or use a negative weight here. The CN page has the same front matter.
|
|
||
| > [!NOTE] | ||
| > **Version & Migration Note**: HugeGraph 1.8.0 upgrades its underlying TinkerPop engine to **3.8.1** (along with Java 17 and Groovy 4.0.25). | ||
| > Certain legacy syntax patterns (e.g., `store()`, `has(key, traversal)`, and scoped `aggregate()`) have been deprecated or modified. See the [1.8 Gremlin & TinkerPop Migration Guide](../guides/gremlin-migration-3.8) for details. |
There was a problem hiding this comment.
Minor: store() and aggregate(Scope, ...) are removed, not deprecated. On 3.8.1, g.V().store('x') fails with MissingMethodException: No signature of method: ...DefaultGraphTraversal.store(), and aggregate(local, 'x') fails the same way. On HugeGraph 1.8, has(key, traversal) fails with Invalid data type of query value. "Deprecated" suggests old scripts still run with a warning. Please say these forms were removed and now fail. CN line 15 (已被废弃) needs the same change.
imbajin
left a comment
imbajin
left a comment
There was a problem hiding this comment.
Blocking: no. Summary: The migration guide overstates Client 1.5 compatibility and misstates mergeV/mergeE validation and introduction. Evidence: apache/hugegraph master 86c05ef PathFilter/UserAPI; TinkerPop 3.8.1 upgrade notes.
|
|
||
| ### 2. Can HugeGraph Client 1.5.0 Continue to Work? | ||
| * **Verdict**: **Yes**. | ||
| * HugeGraph Server 1.8.0 provides backward-compatible adapters (graph alias mapping and legacy auth path redirection). Applications using `hugegraph-client:1.5.0` can continue standard CRUD, schema management, and REST operations without forced SDK upgrades. |
There was a problem hiding this comment.
graphs/{graph}/auth/... while the server PathFilter only prefixes the default graphspace and UserAPI is mounted at graphspaces/{graphspace}/auth/users; the rewritten request still has no matching route. Please narrow the claim to verified operations or document/provide the legacy auth adapter, and mirror the correction in Chinese.
| ## Full Compatibility Reference | ||
|
|
||
| ### Appendix 1: Writes & Upsert (`mergeV` / `mergeE`) | ||
| `mergeV()` and `mergeE()` are new steps in TinkerPop 3.8 (absent in 3.5.1) for graph upserts: |
There was a problem hiding this comment.
🧹 Minor: TinkerPop introduced mergeV() and mergeE() in 3.6.0, with further semantics changes in 3.6.2; they are not new in TinkerPop 3.8. Since this guide compares HugeGraph's 3.5.1 and 3.8.1 stacks, please describe them as newly available in HugeGraph 1.8.0 or in this upgrade, and mirror that wording in Chinese.
| `mergeV()` and `mergeE()` are new steps in TinkerPop 3.8 (absent in 3.5.1) for graph upserts: | ||
| - **M01**: `onCreate` property maps strictly inherit the search match map. Conflicting keys cannot overwrite matched properties. | ||
| - **M02**: `mergeE` no longer implicitly binds incoming/outgoing vertices from upstream traversers; specify `Direction.OUT` and `Direction.IN` in the map or use explicit options. | ||
| - **M03**: Conflicting `onCreate` / `onMatch` maps are validated during construction rather than deferred to runtime execution. |
There was a problem hiding this comment.
onCreate map that overrides the merge search criteria; it does not validate conflicts between onCreate and onMatch maps. Please narrow M03 to the onCreate versus search-criteria case and mirror the correction in Chinese.
This branch has not been deployed
3 participants
What does this PR do?
This PR focuses on the Gremlin query compatibility and TinkerPop 3.5.1 → 3.8.1 upgrade migration documentation for the upcoming HugeGraph 1.8.0 release.
Scope & Boundaries of this PR
gremlin.util.ser.*) and client query script adaptation guidance.Modified & Created Pages List / 修改页面清单
content/cn/docs/guides/gremlin-migration-3.8.mdcontent/en/docs/guides/gremlin-migration-3.8.mdcontent/cn/docs/language/hugegraph-gremlin.mdUniformListValues=false)、更新步骤表（增discard/datetime/mergeV/mergeE，删store），新增迁移指南提示块content/en/docs/language/hugegraph-gremlin.mdcontent/cn/docs/quickstart/hugegraph/hugegraph-server.mdcontent/en/docs/quickstart/hugegraph/hugegraph-server.mdcontent/cn/docs/introduction/_index.mdcontent/en/docs/introduction/_index.mdcontent/cn/docs/changelog/hugegraph-1.8.0-release-notes.mdcontent/en/docs/changelog/hugegraph-1.8.0-release-notes.mdDetailed Changes Breakdown
has(key, traversal)overload (prevents silent empty results in Groovy).store()and scopedaggregate()steps.none()renamed todiscard().by()behavior on missing properties (order,project,pathdrops) andcoalescepatterns.choose()branch semantics alignment.OffsetDateTime) anddateDiff()unit change (seconds to milliseconds).gremlin.util.ser.*) and HugeGraph Client 1.5.0 backward-compatibility support.hugegraph-gremlin.md(CN & EN) features table and step tables.