You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by "kenhuuu (via GitHub)" <gi...@apache.org> on 2026/06/17 01:33:00 UTC

[PR] TINKERPOP-3253 Add transaction closure methods to GLVs [tinkerpop]

kenhuuu opened a new pull request, #3464:
URL: https://github.com/apache/tinkerpop/pull/3464

   https://issues.apache.org/jira/browse/TINKERPOP-3253
   
   Adds executeInTx/evaluateInTx to GraphTraversalSource across all GLVs to wrap the begin/commit/rollback lifecycle, so a lambda receives the transaction-bound g and is auto-committed on success or rolled back on error.
   
   The methods live on GraphTraversalSource rather than on the Transaction returned by g.tx() because the closure is a Traversal-API convenience; hosting it on the Transaction would hand Driver-API users (who submit strings) a traversal source and mix the two APIs. Keeping it on g also lets Java's existing g.tx() routing cover both embedded and remote with no interface changes. The value-returning form is named evaluateInTx rather than call because call already exists on GraphTraversalSource as the service step, and the InTx suffix keeps the transactional intent clear now that the methods no longer sit under tx().
   
   The surface follows each language's idiom rather than forcing uniformity: dynamic languages expose a single method, while statically typed languages get a void/value pair. Go returns interface{} instead of using generics, to match the driver's existing untyped result API.
   
   Behavior is single-shot with no retry, since Gremlin Server has no standardized retriable-error signal across providers. On commit failure a rollback is still attempted for server-side resource hygiene, but the original error stays primary and secondary cleanup failures are only logged. gtx.tx() still returns the same transaction so the commit path keeps working; only opening a second transaction errors.
   
   VOTE +1
   
   <!--
   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] TINKERPOP-3253 Add transaction closure methods to GLVs [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.
spmallette commented on code in PR #3464:
URL: https://github.com/apache/tinkerpop/pull/3464#discussion_r3436916205


##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -354,6 +354,34 @@ err = tx.Commit()
 if err != nil { log.Fatal(err) }
 ----
 
+==== Transaction Closures

Review Comment:
   ngl, even though I knew what this PR was for, i still read this title as "closing a transaction". 
   
   Maybe, "Transaction Blocks" as a language independent way to describe things? At least with "blocks" it's hard to make an assumption about what that is and you click? Or maybe, "Transaction Batching" or "Batches"?



-- 
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] TINKERPOP-3253 Add transaction closure methods to GLVs [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.
kenhuuu merged PR #3464:
URL: https://github.com/apache/tinkerpop/pull/3464


-- 
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] TINKERPOP-3253 Add transaction closure methods to GLVs [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.
spmallette commented on code in PR #3464:
URL: https://github.com/apache/tinkerpop/pull/3464#discussion_r3436916205


##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -354,6 +354,34 @@ err = tx.Commit()
 if err != nil { log.Fatal(err) }
 ----
 
+==== Transaction Closures

Review Comment:
   ngl, even though I knew what this PR was for, i still read this title as "closing a transaction". 
   
   Maybe, "Transaction Blocks" as a language independent way to describe things? At least with "blocks" it's hard to make an assumption about what that is and you click?



-- 
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] TINKERPOP-3253 Add transaction closure methods to GLVs [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.
spmallette commented on code in PR #3464:
URL: https://github.com/apache/tinkerpop/pull/3464#discussion_r3436968769


##########
docs/src/reference/the-traversal.asciidoc:
##########
@@ -60,8 +60,57 @@ traversal strategies may not function properly.
 image:gremlin-coins.png[width=100,float=right] A link:http://en.wikipedia.org/wiki/Database_transaction[database transaction]
 represents a unit of work to execute against the database. A traversals unit of work is affected by usage convention
 (i.e. the method of <<connecting-gremlin, connecting>>) and the graph provider's transaction model. Without diving
-deeply into different conventions and models the most general and recommended approach to working with transactions is
-demonstrated as follows:
+deeply into different conventions and models, the recommended way to work with transactions is to wrap the unit of
+work in a closure passed to `executeInTx` (or `evaluateInTx` when a value must be returned), which manages the
+transaction lifecycle for you:
+
+[source,java]
+----
+GraphTraversalSource g = traversal().with(graph);
+// or
+GraphTraversalSource g = traversal().with(conn);
+
+// the closure receives the transaction-bound gtx; the transaction is begun
+// automatically, committed when the closure completes normally, and rolled
+// back if it throws
+g.executeInTx(gtx -> {
+    gtx.addV('person').iterate();
+    gtx.addV('software').iterate();
+});
+
+// use evaluateInTx when the unit of work needs to return a value
+long count = g.evaluateInTx(gtx -> gtx.V().count().next());
+----
+
+This closure form is preferred for several reasons:
+
+* *Correctness by default.* The transaction is always committed on success and rolled back on any error (or other
+abnormal exit), so partial work is never left dangling and there is no way to forget a `commit()` or a `rollback()` in
+an error path.
+* *Less boilerplate.* The common begin/do-work/commit cycle becomes a single call, removing the repetitive
+try/catch lifecycle management that is easy to get subtly wrong.
+* *Steers you toward the transaction-bound source.* The closure receives `gtx` as its argument, so the transactional
+source is the one already in hand for the unit of work. This makes it natural to run traversals against `gtx` rather
+than accidentally against the non-transactional `g` (which would execute as a separate implicit transaction).
+* *It papers over the remote/embedded paradigm difference (Java).* In Java a `GraphTraversalSource` can be backed by
+either a remote connection or an embedded graph, and the two model transactions differently. In the *remote* case
+`g.tx()` returns a distinct transaction object each time, keyed by a server-side transaction ID, and the `gtx` spawned
+from it is a genuinely separate `GraphTraversalSource` from `g` — issuing a traversal against `g` instead of `gtx`
+silently runs as its own implicit transaction. In the *embedded* case `g.tx()` returns a thread-bound transaction (the
+traditional Java model in which the transaction is associated with the current thread), so `g` and `gtx` actually
+share the same transaction scope. Because the closure hands you the correct transaction-bound `gtx` and owns the
+lifecycle, the exact same code is correct under both paradigms; you do not have to reason about whether `g` and `gtx`
+refer to the same underlying transaction. (The non-Java GLVs are always remote, so this distinction does not arise
+there.)
+
+The closure runs the unit of work exactly once (there is no automatic retry). If the closure throws, the original

Review Comment:
   please change the transition to drop the semicolon in this paragraph. 



-- 
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] TINKERPOP-3253 Add transaction closure methods to GLVs [tinkerpop]

Posted by "kenhuuu (via GitHub)" <gi...@apache.org>.
kenhuuu commented on code in PR #3464:
URL: https://github.com/apache/tinkerpop/pull/3464#discussion_r3483971959


##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -354,6 +354,34 @@ err = tx.Commit()
 if err != nil { log.Fatal(err) }
 ----
 
+==== Transaction Closures

Review Comment:
   updated to "Managed Transaction Blocks"



##########
docs/src/reference/the-traversal.asciidoc:
##########
@@ -60,8 +60,57 @@ traversal strategies may not function properly.
 image:gremlin-coins.png[width=100,float=right] A link:http://en.wikipedia.org/wiki/Database_transaction[database transaction]
 represents a unit of work to execute against the database. A traversals unit of work is affected by usage convention
 (i.e. the method of <<connecting-gremlin, connecting>>) and the graph provider's transaction model. Without diving
-deeply into different conventions and models the most general and recommended approach to working with transactions is
-demonstrated as follows:
+deeply into different conventions and models, the recommended way to work with transactions is to wrap the unit of
+work in a closure passed to `executeInTx` (or `evaluateInTx` when a value must be returned), which manages the
+transaction lifecycle for you:
+
+[source,java]
+----
+GraphTraversalSource g = traversal().with(graph);
+// or
+GraphTraversalSource g = traversal().with(conn);
+
+// the closure receives the transaction-bound gtx; the transaction is begun
+// automatically, committed when the closure completes normally, and rolled
+// back if it throws
+g.executeInTx(gtx -> {
+    gtx.addV('person').iterate();
+    gtx.addV('software').iterate();
+});
+
+// use evaluateInTx when the unit of work needs to return a value
+long count = g.evaluateInTx(gtx -> gtx.V().count().next());
+----
+
+This closure form is preferred for several reasons:

Review Comment:
   turned into paragraph



-- 
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] TINKERPOP-3253 Add transaction closure methods to GLVs [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.
spmallette commented on code in PR #3464:
URL: https://github.com/apache/tinkerpop/pull/3464#discussion_r3436975492


##########
docs/src/reference/the-traversal.asciidoc:
##########
@@ -60,8 +60,57 @@ traversal strategies may not function properly.
 image:gremlin-coins.png[width=100,float=right] A link:http://en.wikipedia.org/wiki/Database_transaction[database transaction]
 represents a unit of work to execute against the database. A traversals unit of work is affected by usage convention
 (i.e. the method of <<connecting-gremlin, connecting>>) and the graph provider's transaction model. Without diving
-deeply into different conventions and models the most general and recommended approach to working with transactions is
-demonstrated as follows:
+deeply into different conventions and models, the recommended way to work with transactions is to wrap the unit of
+work in a closure passed to `executeInTx` (or `evaluateInTx` when a value must be returned), which manages the
+transaction lifecycle for you:
+
+[source,java]
+----
+GraphTraversalSource g = traversal().with(graph);
+// or
+GraphTraversalSource g = traversal().with(conn);
+
+// the closure receives the transaction-bound gtx; the transaction is begun
+// automatically, committed when the closure completes normally, and rolled
+// back if it throws
+g.executeInTx(gtx -> {
+    gtx.addV('person').iterate();
+    gtx.addV('software').iterate();
+});
+
+// use evaluateInTx when the unit of work needs to return a value
+long count = g.evaluateInTx(gtx -> gtx.V().count().next());
+----
+
+This closure form is preferred for several reasons:
+
+* *Correctness by default.* The transaction is always committed on success and rolled back on any error (or other
+abnormal exit), so partial work is never left dangling and there is no way to forget a `commit()` or a `rollback()` in
+an error path.
+* *Less boilerplate.* The common begin/do-work/commit cycle becomes a single call, removing the repetitive
+try/catch lifecycle management that is easy to get subtly wrong.
+* *Steers you toward the transaction-bound source.* The closure receives `gtx` as its argument, so the transactional
+source is the one already in hand for the unit of work. This makes it natural to run traversals against `gtx` rather
+than accidentally against the non-transactional `g` (which would execute as a separate implicit transaction).
+* *It papers over the remote/embedded paradigm difference (Java).* In Java a `GraphTraversalSource` can be backed by
+either a remote connection or an embedded graph, and the two model transactions differently. In the *remote* case
+`g.tx()` returns a distinct transaction object each time, keyed by a server-side transaction ID, and the `gtx` spawned
+from it is a genuinely separate `GraphTraversalSource` from `g` — issuing a traversal against `g` instead of `gtx`
+silently runs as its own implicit transaction. In the *embedded* case `g.tx()` returns a thread-bound transaction (the
+traditional Java model in which the transaction is associated with the current thread), so `g` and `gtx` actually
+share the same transaction scope. Because the closure hands you the correct transaction-bound `gtx` and owns the
+lifecycle, the exact same code is correct under both paradigms; you do not have to reason about whether `g` and `gtx`
+refer to the same underlying transaction. (The non-Java GLVs are always remote, so this distinction does not arise
+there.)
+
+The closure runs the unit of work exactly once (there is no automatic retry). If the closure throws, the original
+error is re-raised after the rollback; if the `commit()` itself fails, the commit error is raised and a rollback is
+still attempted to release server-side resources.
+
+Manual transaction control (calling `begin()`, `commit()`, and `rollback()` yourself, shown below) remains fully

Review Comment:
   "fit the use case — for example, when the" - just make it two sentences.



-- 
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] TINKERPOP-3253 Add transaction closure methods to GLVs [tinkerpop]

Posted by "spmallette (via GitHub)" <gi...@apache.org>.
spmallette commented on code in PR #3464:
URL: https://github.com/apache/tinkerpop/pull/3464#discussion_r3436959482


##########
docs/src/reference/the-traversal.asciidoc:
##########
@@ -60,8 +60,57 @@ traversal strategies may not function properly.
 image:gremlin-coins.png[width=100,float=right] A link:http://en.wikipedia.org/wiki/Database_transaction[database transaction]
 represents a unit of work to execute against the database. A traversals unit of work is affected by usage convention
 (i.e. the method of <<connecting-gremlin, connecting>>) and the graph provider's transaction model. Without diving
-deeply into different conventions and models the most general and recommended approach to working with transactions is
-demonstrated as follows:
+deeply into different conventions and models, the recommended way to work with transactions is to wrap the unit of
+work in a closure passed to `executeInTx` (or `evaluateInTx` when a value must be returned), which manages the
+transaction lifecycle for you:
+
+[source,java]
+----
+GraphTraversalSource g = traversal().with(graph);
+// or
+GraphTraversalSource g = traversal().with(conn);
+
+// the closure receives the transaction-bound gtx; the transaction is begun
+// automatically, committed when the closure completes normally, and rolled
+// back if it throws
+g.executeInTx(gtx -> {
+    gtx.addV('person').iterate();
+    gtx.addV('software').iterate();
+});
+
+// use evaluateInTx when the unit of work needs to return a value
+long count = g.evaluateInTx(gtx -> gtx.V().count().next());
+----
+
+This closure form is preferred for several reasons:

Review Comment:
   I personally would like docs to steer clear of heavy reliance on bullets. A smoothly written paragraph is the form we should try to stick to for "reasons". The entire readable internet is leaning into bullets like this now and I think TinkerPop is better for breaking from that. Not saying they can't ever be used, but this just doesn't seem like content to do it with.



-- 
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] TINKERPOP-3253 Add transaction closure methods to GLVs [tinkerpop]

Posted by "xiazcy (via GitHub)" <gi...@apache.org>.
xiazcy commented on PR #3464:
URL: https://github.com/apache/tinkerpop/pull/3464#issuecomment-4737242660

   VOTE +1


-- 
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