Document ON ERROR RETRY
#1203
Document ON ERROR RETRY
#1203
Conversation
|
Thanks for the documentation updates. The preview documentation has now been torn down - reopening this PR will republish it. |
henriknyman
left a comment
henriknyman
left a comment
There was a problem hiding this comment.
Nice work!
Comments are mostly related to that the default error fallback behaviour is actually ON ERROR RETRY THEN FAIL.
| === `ON ERROR RETRY` | ||
|
|
||
| `ON ERROR RETRY` uses an exponential delay between retry attempts for transaction batches that fail due to transient errors (i.e. errors where retrying a transaction can be expected to give a different result), with an optional xref:subqueries/subqueries-in-transactions.adoc#specify-retry-duration[maximum retry duration]. | ||
| If the transaction still fails after the maximum duration, the failure is handled according to an optionally specified xref:subqueries/subqueries-in-transactions.adoc#fallback-error-handling[fallback error handling mode] (`THEN CONTINUE` (default), `THEN BREAK`, `THEN FAIL`). |
There was a problem hiding this comment.
The default is THEN FAIL.
| If the transaction still fails after the maximum duration, the failure is handled according to an optionally specified xref:subqueries/subqueries-in-transactions.adoc#fallback-error-handling[fallback error handling mode] (`THEN CONTINUE` (default), `THEN BREAK`, `THEN FAIL`). | ||
|
|
||
| `ON ERROR RETRY` increases query robustness by handling transient errors without manual intervention. | ||
| It is particularly suitable for xref:subqueries/subqueries-in-transactions.adoc#concurrent-transactions[concurrent transactions], reducing the likelihood of xref:subqueries/subqueries-in-transactions.adoc#deadlocks[deadlocks]. |
There was a problem hiding this comment.
To be precise, it doesn't reduce the likelihood of deadlocks, but makes the query not fail because of deadlocks.
| The below example demonstrates a basic retry scenario. | ||
| If a transient error occurs during the creation of a `User` node, the transaction will be retried for the default maximum retry duration (`30` seconds). | ||
| If the retry succeeds, the query continues. If the retry fails after the default duration, it behaves like xref:subqueries/subqueries-in-transactions#on-error-continue[`ON ERROR CONTINUE`] (the default fallback). |
There was a problem hiding this comment.
..., the query fails because it behaves like ON ERROR FAIL (the default fallback)
| See xref:subqueries/subqueries-in-transactions.adoc#on-error-continue[`ON ERROR CONTINUE`] for more information about this behavior. | ||
|
|
||
| [NOTE] | ||
| Because `THEN CONTINUE` is the default fallback option it does not have to be specified. |
There was a problem hiding this comment.
THEN FAIL is the default fallback option
| Because `THEN CONTINUE` is the default fallback option it does not have to be specified. | ||
|
|
||
| * `ON ERROR RETRY ... THEN BREAK`: the query will ignore recoverable errors and stop the execution of subsequent inner transactions. | ||
| The out transaction succeeds, and `null` will be returned for the failed inner transaction and all subsequent ones. |
There was a problem hiding this comment.
Is "The out transaction succeeds" an incomplete sentence or meant to be "The outer transaction succeeds"?
There was a problem hiding this comment.
The outer transactions succeeds, and ....
| See xref:subqueries/subqueries-in-transactions.adoc#on-error-break[`ON ERROR BREAK`] for more information about this behavior. | ||
|
|
||
| * `ON ERROR RETRY ... THEN FAIL`: the query will acknowledge a recoverable error and stop the execution of subsequent inner transactions, causing the outer transaction to fail. | ||
| all subsequent ones. |
There was a problem hiding this comment.
"all subsequent ones."
Incomplete sentence or leftover?
There was a problem hiding this comment.
leftover :/
| It returns the `transactionID`, `commitStatus` and `errorMessage` of the failed transactions. | ||
| .Query using `ON ERROR CONTINUE` to ignore deadlocks and complete outer transaction | ||
| .Query using `ON ERROR RETRY` to ignore deadlocks and complete outer transaction |
There was a problem hiding this comment.
"to ignore deadlocks" -> "to retry deadlocked inner transactions"
There was a problem hiding this comment.
But this query does not use ON ERROR RETRY - the following one does.
| To retry the any failed inner transactions, use the error option `ON ERROR RETRY`, which retries any failing transactions until the maximum retry duration has been reached. | ||
| The following query uses `ON ERROR RETRY` to retry the above query for a maximum of `3` seconds. | ||
| Note that `ON ERROR RETRY` by default falls back to the error option `THEN CONTINUE`, which ensures that any deadlocks are bypassed and that subsequent inner transactions are executed. |
There was a problem hiding this comment.
The default fallback is ON ERROR FAIL.
To be precise, deadlocks are not bypassed, but among the the conflicting transactions, (e.g. if there are 2 of them) one of them (A) is selected to fail with a deadlock detected exception, and the other (B) (typically the one holding the most locks) is allowed to continue and may now acquire the locks held by the failed transaction (A) so that it can eventually commit. When the failed transaction (A) is retried after (B) has committed it might also succeed to commit.
Here it may be useful to provide a note or a warning that deadlock detection and retries are time consuming, and if the import data contains a significant amount of relationships to be merged between the same nodes but occurring in different batches, increasing the concurrency is not necessarily beneficial but could instead slow down the overall performance of the import.
There was a problem hiding this comment.
Have added a note just before the example box
| MERGE (m:Movie {movieId: row.movieId}) | ||
| MERGE (y:Year {year: row.year}) | ||
| MERGE (m)-[r:RELEASED_IN]->(y) | ||
| } IN 2 CONCURRENT TRANSACTIONS OF 10 ROWS ON ERROR RETRY FOR 3 SECONDS REPORT STATUS AS status |
There was a problem hiding this comment.
You need to explicitly write ON ERROR RETRY THEN CONTINUE or otherwise REPORT STATUS will fail with a syntax error as the default is ON ERROR FAIL.
| ---- | ||
|
|
||
| | New error handling option for `CALL { ... } IN TRANSACTIONS`: `ON ERROR RETRY`. | ||
| This option applies an exponential delay between retries for transaction batches failing due to transient errors, with an optional maximum retry duration, and handles failure based on a specified fallback error mode if the transaction does not succeed within the given time. |
There was a problem hiding this comment.
The retry logic is currently exponential backoff with some random jitter, but I am not sure if we need to go into that level of detail anywhere (maybe compare with driver docs?)
There was a problem hiding this comment.
I think we can skip this. The driver docs doesn't go into details either.
|
This PR includes documentation updates Updated pages: |
Note: This feature is no longer earmarked for Cypher 25, but will be part of Cypher 5 in the 2025.03 release.
4 participants
Note: This feature is no longer earmarked for Cypher 25, but will be part of Cypher 5 in the 2025.03 release.