This is an automated email from the ASF dual-hosted git repository. xiazcy pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 5ad09cb8425cd7f9d6bc839a68dfb3e9aab9bab2 Merge: 3c1aea1a5d e679b6c315 Author: Yang Xia <[email protected]> AuthorDate: Tue Mar 31 14:55:07 2026 -0700 Merge branch '3.8-dev' # Conflicts: # docs/src/dev/provider/index.asciidoc # docs/src/reference/gremlin-applications.asciidoc docs/src/reference/gremlin-applications.asciidoc | 8 +- docs/src/reference/gremlin-variants.asciidoc | 16 ++- docs/src/upgrade/release-3.7.x.asciidoc | 127 ++++++++++++++++++++++- docs/src/upgrade/release-3.8.1.asciidoc | 126 ++-------------------- 4 files changed, 143 insertions(+), 134 deletions(-) diff --cc docs/src/reference/gremlin-applications.asciidoc index 5096cf5e6a,c54359bc74..1d124c1e22 --- a/docs/src/reference/gremlin-applications.asciidoc +++ b/docs/src/reference/gremlin-applications.asciidoc @@@ -2380,10 -3056,9 +2380,10 @@@ The Gremlin MCP server exposes these to properties may be surfaced as enums to encourage valid values in queries. * `run_gremlin_query` — Executes an arbitrary Gremlin traversal and returns JSON results. * `refresh_schema_cache` — Forces schema discovery to run again when the graph has changed. +* `translate_gremlin_query` — Translates a Gremlin query to a target language variant with optional normalization. * `format_gremlin_query` — Formats a Gremlin query using gremlint. - ==== Schema discovery + === Schema discovery Schema discovery is the foundation that lets humans and AI assistants reason about a graph without prior tribal knowledge. By automatically mapping the graph’s structure and commonly observed patterns, it produces a concise, diff --cc docs/src/reference/gremlin-variants.asciidoc index 2871361464,338f6fac97..89cd8d63d4 --- a/docs/src/reference/gremlin-variants.asciidoc +++ b/docs/src/reference/gremlin-variants.asciidoc @@@ -2878,34 -3047,17 +2878,32 @@@ therefore cardinality functions that ta [[gremlin-python-limitations]] === Limitations - * Traversals that return a `Set` *might* be coerced to a `List` in Python. In the case of Python, number equality - is different from JVM languages which produces different `Set` results when those types are in use. When this case - is detected during deserialization, the `Set` is coerced to a `List` so that traversals return consistent - results within a collection across different languages. If a `Set` is needed then convert `List` results - to `Set` manually. - * Traversals that return a `Set` containing non-hashable items, such as `Dictionary`, `Set` and `List`, will be coerced - into a `List` during deserialization. Python requires set elements to be hashable, for which Gremlin does not. If a - `Set` is needed, convert elements to hashable equivalents manually (e.g. `dict` to `HashableDict`, `list` to `tuple`, - `set` to `frozenset`). + * Traversals that return a `Set` may be coerced to a `List` in Python in two cases. First, when the `Set` contains + mixed numeric types (e.g. `int` and `float`), because Python number equality differs from the JVM — a Java `Set` of + `[1, 1.0d]` has two elements, but Python considers `1 == 1.0` and would collapse them to one, so the `Set` is coerced to + a `List` to preserve all elements consistently across languages. Second, when the `Set` contains non-hashable items such + as `Dictionary`, `Set`, or `List`, because Python requires set elements to be hashable while Gremlin does not, the `Set` + is also coerced to a `List`. For this case, if a `Set` is needed, convert elements to hashable equivalents manually + (e.g. `dict` to `HashableDict`, `list` to `tuple`, `set` to `frozenset`). * Gremlin is capable of returning `Dictionary` results that use non-hashable keys (e.g. Dictionary as a key) and Python does not support that at a language level. Using GraphSON 3.0 or GraphBinary (after 3.5.0) makes it possible to return -such results. In all other cases, Gremlin that returns such results will need to be re-written to avoid that sort of -key. +such results. However, it may not be possible to serialize these maps so they can't be re-inserted (or round tripped). +In all other cases, Gremlin that returns such results will need to be re-written to avoid that sort of key. +* The `float` type in Python is a double precision floating point number which is commonly referred to in other +languages as a `double`. This means that single precision floating point values will be deserialized into a double, so +there will be a precision difference. +* Gremlin supports multiple fixed-width integers such as byte (1-byte), short (2-byte), and long (8-byte). These are +deserialized into Python's variable size `int` type. These numbers can't be exactly round tripped because the original +type information is lost during deserialization. During serialization, these numbers will try to be converted into a +4-byte integer which may throw exceptions if the value is too large or waste space if the value is very small. +* The Gremlin Char type is deserialized as a string and therefore can't be round tripped as it will it will attempt to +be serialized as a string. +* Date and Duration types in Gremlin are deserialized as `datetime.datetime` and `datetime.timedelta` respectively in +`gremlin-python`. This can lead to errors for large values because they exceed the maximum size allowed for `datetime` +and `timedelta`. +* In Gremlin, 1 isn't equal to the boolean true value and 0 isn't equal to the boolean false value, but they are equal +in Python. This means that in `gremlin-python` if these values are in a `Set`, you will get a different behavior than +what is intended by Gremlin, since it follows Python's behavior. * The `subgraph()`-step is not supported by any variant that is not running on the Java Virtual Machine as there is no `Graph` instance to deserialize a result into on the client-side. A workaround is to replace the step with `aggregate(local)` and then convert those results to something the client can use locally.
