You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by "spmallette (via GitHub)" <gi...@apache.org> on 2026/09/25 16:06:13 UTC
[PR] Clarify Gremlin.Net type limitations with reproductions [tinkerpop]
spmallette opened a new pull request, #3683:
URL: https://github.com/apache/tinkerpop/pull/3683
Sharpen the Gremlin.Net Limitations section so each type-range limitation states its true trigger and can be reproduced. The DateTimeOffset entry now notes that the +/-14:00 offset bound is the common trigger, not just the year range. The null Map key entry explains that group()/groupCount() over a missing property drops the element rather than producing a null key, so a null key must be injected explicitly. The Duration and non-BMP char entries clarify that only out-of-range values are affected. A short csharp example reproduces the offset, high-precision decimal, and null-key cases against a modern-graph server.
<!--
Thanks for contributing! Reminders:
+ TARGET the earliest branch where you want the change
3.7-dev -> 3.7.7 (non-breaking only)
3.8-dev -> 3.8.2 (non-breaking only)
master -> 4.0.0
+ Committers will MERGE the PR forward to newer versions
+ ADD entry to the CHANGELOG.asciidoc for the targeted version
Do not reference a JIRA number there
+ ADD JIRA number to title and link in description
+ PRs requires 3 +1s from committers OR
1 +1 and 7 day wait to merge.
+ MORE details: https://s.apache.org/rtnal
-->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Clarify Gremlin.Net type limitations with reproductions [tinkerpop]
Posted by "Cole-Greer (via GitHub)" <gi...@apache.org>.
Cole-Greer commented on PR #3683:
URL: https://github.com/apache/tinkerpop/pull/3683#issuecomment-5837887868
VOTE +1 pending comment resolution
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Clarify Gremlin.Net type limitations with reproductions [tinkerpop]
Posted by "Cole-Greer (via GitHub)" <gi...@apache.org>.
Cole-Greer commented on code in PR #3683:
URL: https://github.com/apache/tinkerpop/pull/3683#discussion_r4106641516
##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -3183,21 +3183,50 @@ anchor:gremlin-net-limitations[]
[[gremlin-dotnet-limitations]]
=== Limitations
+Several Gremlin types have a wider domain than their closest C# counterparts, so a value produced by the server
+that falls outside the C# range fails to deserialize when Gremlin.Net reads the result.
+
* The `subgraph()`-step returns a detached `Graph` data container exposing
`Vertices: IDictionary<object, Vertex>` and `Edges: IDictionary<object, Edge>`. The result is not a live `Graph`
instance: mutating the collections has no effect on the source graph, and it cannot be passed to
`traversal().with(...)`. To re-query subgraph elements against the original graph, extract their `Id` and use
`g.V(id)` / `g.E(id)` on the original `GraphTraversalSource`.
-* `DateTimeOffset` cannot represent the extreme values of Gremlin's `OffsetDateTime` maximum and minimum,
-so offset date-time values at those boundaries will fail to deserialize.
-* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so extreme duration values (such as
-`Duration.FOREVER`) that exceed `TimeSpan.MaxValue` or `TimeSpan.MinValue` will fail to deserialize.
+* C#'s `DateTimeOffset` accepts offsets only in the range `-14:00` to `+14:00` and years from 1 to 9999, while
+Gremlin's `OffsetDateTime` permits offsets up to `+18:00`/`-18:00` and a much wider year range. An offset
+date-time whose offset or year lies outside the C# range fails to deserialize. The offset bound is the more
+common trigger, since a value such as `datetime('2018-03-22T00:35:44.741+18:00')` is a valid `OffsetDateTime`
+but cannot be represented as a `DateTimeOffset`.
+* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so a duration whose magnitude exceeds
+`TimeSpan.MaxValue` or `TimeSpan.MinValue` fails to deserialize. This affects only extreme values such as
+`Duration.FOREVER`. Durations within the `TimeSpan` range are unaffected.
* Gremlin's `BigDecimal` supports up to 33 digits of precision while C#'s `decimal` type is limited to 28-29
-significant digits, so high-precision values may lose accuracy or fail to deserialize.
-* C# `char` values do not support values outside the Basic Multilingual Plane, which are mainly 4-byte UTF-8
-characters. Those GraphBinary `Char` values are not supported.
-* C# `Dictionary` does not allow `null` keys, so `Map` results with `null` keys (e.g. from `group()` or
-`groupCount()` on a missing property) will fail during deserialization.
+significant digits, so a value that exceeds the `decimal` range fails to deserialize.
+* C#'s `char` holds a single UTF-16 code unit and cannot represent a code point outside the Basic Multilingual
+Plane, which GraphBinary encodes as a four-byte `Char`. Such a value is not reconstructed correctly on
+deserialization. Characters within the Basic Multilingual Plane are unaffected.
+* C#'s `Dictionary` does not allow `null` keys, so a `Map` result that contains a `null` key fails to
+deserialize. A `null` key does not arise from `group()` or `groupCount()` over a missing property, because an
+element whose key-defining traversal produces nothing is dropped from the result rather than counted under a
+`null` key. A `null` key must be introduced explicitly, for example with
+`by(coalesce(values('lang'), constant(null)))`.
+
+The following examples reproduce these limitations against a <<gremlin-server,Gremlin Server>> loaded with the
Review Comment:
I'm not sure that synthetic examples add much value here, however I don't think they take anything away either. I'm -0 on their inclusion.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Clarify Gremlin.Net type limitations with reproductions [tinkerpop]
Posted by "Cole-Greer (via GitHub)" <gi...@apache.org>.
Cole-Greer commented on code in PR #3683:
URL: https://github.com/apache/tinkerpop/pull/3683#discussion_r4106592131
##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -3183,21 +3183,50 @@ anchor:gremlin-net-limitations[]
[[gremlin-dotnet-limitations]]
=== Limitations
+Several Gremlin types have a wider domain than their closest C# counterparts, so a value produced by the server
+that falls outside the C# range fails to deserialize when Gremlin.Net reads the result.
+
* The `subgraph()`-step returns a detached `Graph` data container exposing
`Vertices: IDictionary<object, Vertex>` and `Edges: IDictionary<object, Edge>`. The result is not a live `Graph`
instance: mutating the collections has no effect on the source graph, and it cannot be passed to
`traversal().with(...)`. To re-query subgraph elements against the original graph, extract their `Id` and use
`g.V(id)` / `g.E(id)` on the original `GraphTraversalSource`.
-* `DateTimeOffset` cannot represent the extreme values of Gremlin's `OffsetDateTime` maximum and minimum,
-so offset date-time values at those boundaries will fail to deserialize.
-* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so extreme duration values (such as
-`Duration.FOREVER`) that exceed `TimeSpan.MaxValue` or `TimeSpan.MinValue` will fail to deserialize.
+* C#'s `DateTimeOffset` accepts offsets only in the range `-14:00` to `+14:00` and years from 1 to 9999, while
+Gremlin's `OffsetDateTime` permits offsets up to `+18:00`/`-18:00` and a much wider year range. An offset
+date-time whose offset or year lies outside the C# range fails to deserialize. The offset bound is the more
+common trigger, since a value such as `datetime('2018-03-22T00:35:44.741+18:00')` is a valid `OffsetDateTime`
+but cannot be represented as a `DateTimeOffset`.
+* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so a duration whose magnitude exceeds
+`TimeSpan.MaxValue` or `TimeSpan.MinValue` fails to deserialize. This affects only extreme values such as
+`Duration.FOREVER`. Durations within the `TimeSpan` range are unaffected.
* Gremlin's `BigDecimal` supports up to 33 digits of precision while C#'s `decimal` type is limited to 28-29
-significant digits, so high-precision values may lose accuracy or fail to deserialize.
-* C# `char` values do not support values outside the Basic Multilingual Plane, which are mainly 4-byte UTF-8
-characters. Those GraphBinary `Char` values are not supported.
-* C# `Dictionary` does not allow `null` keys, so `Map` results with `null` keys (e.g. from `group()` or
-`groupCount()` on a missing property) will fail during deserialization.
+significant digits, so a value that exceeds the `decimal` range fails to deserialize.
+* C#'s `char` holds a single UTF-16 code unit and cannot represent a code point outside the Basic Multilingual
+Plane, which GraphBinary encodes as a four-byte `Char`. Such a value is not reconstructed correctly on
Review Comment:
I think if we are going to make a statement such as "Such a value is not reconstructed correctly on deserialization", then we need to state what happens to values outside the range. Do users get a serialization exception? Corrupted data?...
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Clarify Gremlin.Net type limitations with reproductions [tinkerpop]
Posted by "Cole-Greer (via GitHub)" <gi...@apache.org>.
Cole-Greer commented on code in PR #3683:
URL: https://github.com/apache/tinkerpop/pull/3683#discussion_r4106631578
##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -3183,21 +3183,50 @@ anchor:gremlin-net-limitations[]
[[gremlin-dotnet-limitations]]
=== Limitations
+Several Gremlin types have a wider domain than their closest C# counterparts, so a value produced by the server
+that falls outside the C# range fails to deserialize when Gremlin.Net reads the result.
+
* The `subgraph()`-step returns a detached `Graph` data container exposing
`Vertices: IDictionary<object, Vertex>` and `Edges: IDictionary<object, Edge>`. The result is not a live `Graph`
instance: mutating the collections has no effect on the source graph, and it cannot be passed to
`traversal().with(...)`. To re-query subgraph elements against the original graph, extract their `Id` and use
`g.V(id)` / `g.E(id)` on the original `GraphTraversalSource`.
-* `DateTimeOffset` cannot represent the extreme values of Gremlin's `OffsetDateTime` maximum and minimum,
-so offset date-time values at those boundaries will fail to deserialize.
-* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so extreme duration values (such as
-`Duration.FOREVER`) that exceed `TimeSpan.MaxValue` or `TimeSpan.MinValue` will fail to deserialize.
+* C#'s `DateTimeOffset` accepts offsets only in the range `-14:00` to `+14:00` and years from 1 to 9999, while
+Gremlin's `OffsetDateTime` permits offsets up to `+18:00`/`-18:00` and a much wider year range. An offset
+date-time whose offset or year lies outside the C# range fails to deserialize. The offset bound is the more
+common trigger, since a value such as `datetime('2018-03-22T00:35:44.741+18:00')` is a valid `OffsetDateTime`
+but cannot be represented as a `DateTimeOffset`.
+* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so a duration whose magnitude exceeds
+`TimeSpan.MaxValue` or `TimeSpan.MinValue` fails to deserialize. This affects only extreme values such as
+`Duration.FOREVER`. Durations within the `TimeSpan` range are unaffected.
* Gremlin's `BigDecimal` supports up to 33 digits of precision while C#'s `decimal` type is limited to 28-29
-significant digits, so high-precision values may lose accuracy or fail to deserialize.
-* C# `char` values do not support values outside the Basic Multilingual Plane, which are mainly 4-byte UTF-8
-characters. Those GraphBinary `Char` values are not supported.
-* C# `Dictionary` does not allow `null` keys, so `Map` results with `null` keys (e.g. from `group()` or
-`groupCount()` on a missing property) will fail during deserialization.
+significant digits, so a value that exceeds the `decimal` range fails to deserialize.
+* C#'s `char` holds a single UTF-16 code unit and cannot represent a code point outside the Basic Multilingual
+Plane, which GraphBinary encodes as a four-byte `Char`. Such a value is not reconstructed correctly on
+deserialization. Characters within the Basic Multilingual Plane are unaffected.
+* C#'s `Dictionary` does not allow `null` keys, so a `Map` result that contains a `null` key fails to
+deserialize. A `null` key does not arise from `group()` or `groupCount()` over a missing property, because an
Review Comment:
> A `null` key does not arise from `group()` or `groupCount()` over a missing property, because an element whose key-defining traversal produces nothing is dropped from the result rather than counted under a `null` key. A `null` key must be introduced explicitly, for example with `by(coalesce(values('lang'), constant(null)))`.
In my opinion this is unnecessary flourish, people know what a null map key is, I don't think we need to tell them what does and doesn't produce them.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Clarify Gremlin.Net type limitations with reproductions [tinkerpop]
Posted by "Cole-Greer (via GitHub)" <gi...@apache.org>.
Cole-Greer commented on code in PR #3683:
URL: https://github.com/apache/tinkerpop/pull/3683#discussion_r4107673015
##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -3183,21 +3183,36 @@ anchor:gremlin-net-limitations[]
[[gremlin-dotnet-limitations]]
=== Limitations
+Several Gremlin types have a wider domain than their closest C# counterparts. When the server returns a value
+that falls outside the C# range, the outcome depends on the type. In most cases Gremlin.Net raises an exception
+as it deserializes the response, so the error surfaces on the client at the point the result is read. The one
+exception is a character outside the Basic Multilingual Plane, which is reconstructed incorrectly without any
+error.
+
* The `subgraph()`-step returns a detached `Graph` data container exposing
`Vertices: IDictionary<object, Vertex>` and `Edges: IDictionary<object, Edge>`. The result is not a live `Graph`
instance: mutating the collections has no effect on the source graph, and it cannot be passed to
`traversal().with(...)`. To re-query subgraph elements against the original graph, extract their `Id` and use
`g.V(id)` / `g.E(id)` on the original `GraphTraversalSource`.
-* `DateTimeOffset` cannot represent the extreme values of Gremlin's `OffsetDateTime` maximum and minimum,
-so offset date-time values at those boundaries will fail to deserialize.
-* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so extreme duration values (such as
-`Duration.FOREVER`) that exceed `TimeSpan.MaxValue` or `TimeSpan.MinValue` will fail to deserialize.
+* C#'s `DateTimeOffset` accepts offsets only in the range `-14:00` to `+14:00` and years from 1 to 9999, while
Review Comment:
There is one other weird case with `DateTimeOffset` in .Net, the offset is specified in whole minutes, while Java and GraphBinary specify the offset as a number of seconds. It appears that datetimes with a sub-minute precision offset currently throw an `ArgumentException` when attempting to deserialize in .Net. We should document this for now, it's probably worth a JIRA to intercept this and truncate the seconds portion of the offset.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Clarify Gremlin.Net type limitations with reproductions [tinkerpop]
Posted by "Cole-Greer (via GitHub)" <gi...@apache.org>.
Cole-Greer commented on code in PR #3683:
URL: https://github.com/apache/tinkerpop/pull/3683#discussion_r4107571174
##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -3183,21 +3183,36 @@ anchor:gremlin-net-limitations[]
[[gremlin-dotnet-limitations]]
=== Limitations
+Several Gremlin types have a wider domain than their closest C# counterparts. When the server returns a value
+that falls outside the C# range, the outcome depends on the type. In most cases Gremlin.Net raises an exception
+as it deserializes the response, so the error surfaces on the client at the point the result is read. The one
+exception is a character outside the Basic Multilingual Plane, which is reconstructed incorrectly without any
+error.
+
* The `subgraph()`-step returns a detached `Graph` data container exposing
`Vertices: IDictionary<object, Vertex>` and `Edges: IDictionary<object, Edge>`. The result is not a live `Graph`
instance: mutating the collections has no effect on the source graph, and it cannot be passed to
`traversal().with(...)`. To re-query subgraph elements against the original graph, extract their `Id` and use
`g.V(id)` / `g.E(id)` on the original `GraphTraversalSource`.
-* `DateTimeOffset` cannot represent the extreme values of Gremlin's `OffsetDateTime` maximum and minimum,
-so offset date-time values at those boundaries will fail to deserialize.
-* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so extreme duration values (such as
-`Duration.FOREVER`) that exceed `TimeSpan.MaxValue` or `TimeSpan.MinValue` will fail to deserialize.
+* C#'s `DateTimeOffset` accepts offsets only in the range `-14:00` to `+14:00` and years from 1 to 9999, while
Review Comment:
Both the DateTime and Duration entries here cover the range limitation accurately, but there is also a precision limitation when converting from gremlin types to dotnet. Gremlin uses nanosecond precision for both types, while dotnet is limited to 100ns "ticks". These types are truncated upon deserialization (`00.123456789s` -> `00.1234567s`)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Clarify Gremlin.Net type limitations with reproductions [tinkerpop]
Posted by "codecov-commenter (via GitHub)" <gi...@apache.org>.
codecov-commenter commented on PR #3683:
URL: https://github.com/apache/tinkerpop/pull/3683#issuecomment-5835756320
## [Codecov](https://app.codecov.io/gh/apache/tinkerpop/pull/3683?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
:white_check_mark: All modified and coverable lines are covered by tests.
:white_check_mark: Project coverage is 80.05%. Comparing base ([`a28cd1f`](https://app.codecov.io/gh/apache/tinkerpop/commit/a28cd1f2f1f10c140030a56de44c5c6c045af5f0?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)) to head ([`7cde46e`](https://app.codecov.io/gh/apache/tinkerpop/commit/7cde46e83456325fd7a6587f4342256d430e4668?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)).
:warning: Report is 649 commits behind head on master.
<details><summary>Additional details and impacted files</summary>
```diff
@@ Coverage Diff @@
## master #3683 +/- ##
============================================
+ Coverage 76.35% 80.05% +3.69%
============================================
Files 1012 32 -980
Lines 60341 6913 -53428
Branches 7075 0 -7075
============================================
- Hits 46076 5534 -40542
+ Misses 11548 1053 -10495
+ Partials 2717 326 -2391
```
</details>
[:umbrella: View full report in Codecov by Harness](https://app.codecov.io/gh/apache/tinkerpop/pull/3683?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
<details><summary> :rocket: New features to boost your workflow: </summary>
- :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
- :package: [JS Bundle Analysis](https://docs.codecov.com/docs/javascript-bundle-analysis): Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
</details>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Clarify Gremlin.Net type limitations with reproductions [tinkerpop]
Posted by "spmallette (via GitHub)" <gi...@apache.org>.
spmallette commented on code in PR #3683:
URL: https://github.com/apache/tinkerpop/pull/3683#discussion_r4390386457
##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -3183,21 +3183,36 @@ anchor:gremlin-net-limitations[]
[[gremlin-dotnet-limitations]]
=== Limitations
+Several Gremlin types have a wider domain than their closest C# counterparts. When the server returns a value
+that falls outside the C# range, the outcome depends on the type. In most cases Gremlin.Net raises an exception
+as it deserializes the response, so the error surfaces on the client at the point the result is read. The one
+exception is a character outside the Basic Multilingual Plane, which is reconstructed incorrectly without any
+error.
+
* The `subgraph()`-step returns a detached `Graph` data container exposing
`Vertices: IDictionary<object, Vertex>` and `Edges: IDictionary<object, Edge>`. The result is not a live `Graph`
instance: mutating the collections has no effect on the source graph, and it cannot be passed to
`traversal().with(...)`. To re-query subgraph elements against the original graph, extract their `Id` and use
`g.V(id)` / `g.E(id)` on the original `GraphTraversalSource`.
-* `DateTimeOffset` cannot represent the extreme values of Gremlin's `OffsetDateTime` maximum and minimum,
-so offset date-time values at those boundaries will fail to deserialize.
-* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so extreme duration values (such as
-`Duration.FOREVER`) that exceed `TimeSpan.MaxValue` or `TimeSpan.MinValue` will fail to deserialize.
+* C#'s `DateTimeOffset` accepts offsets only in the range `-14:00` to `+14:00` and years from 1 to 9999, while
Review Comment:
https://issues.apache.org/jira/browse/TINKERPOP-3301
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Clarify Gremlin.Net type limitations with reproductions [tinkerpop]
Posted by "spmallette (via GitHub)" <gi...@apache.org>.
spmallette merged PR #3683:
URL: https://github.com/apache/tinkerpop/pull/3683
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org