From df9c00689df36cca3929145fb39d85a032e1f9bb Mon Sep 17 00:00:00 2001 From: Gregory Woods Date: Wed, 2 Feb 2022 09:17:59 +0000 Subject: [PATCH 1/2] Add Transaction Configuration section and Access Mode header --- modules/ROOT/pages/actions/index.adoc | 1 + modules/ROOT/pages/actions/routing.adoc | 8 ++++---- .../pages/actions/transaction-configuration.adoc | 15 +++++++++++++++ 3 files changed, 20 insertions(+), 4 deletions(-) create mode 100644 modules/ROOT/pages/actions/transaction-configuration.adoc diff --git a/modules/ROOT/pages/actions/index.adoc b/modules/ROOT/pages/actions/index.adoc index da3d316..f900fff 100644 --- a/modules/ROOT/pages/actions/index.adoc +++ b/modules/ROOT/pages/actions/index.adoc @@ -11,6 +11,7 @@ There are several _actions_ that can be performed using the Cypher transaction H * xref:actions/query-format.adoc[] * xref:actions/result-format.adoc[] * xref:actions/routing.adoc[] +* xref:actions/transaction-configuration.adoc[] *Using the API:* diff --git a/modules/ROOT/pages/actions/routing.adoc b/modules/ROOT/pages/actions/routing.adoc index 1201236..0b5a489 100644 --- a/modules/ROOT/pages/actions/routing.adoc +++ b/modules/ROOT/pages/actions/routing.adoc @@ -19,7 +19,7 @@ The level of support depends on whether link:https://neo4j.com/docs/operations-m |Clusters support routing for queries that involve a xref::/actions/begin-and-commit-a-transaction-in-one-request.adoc[single request] (i.e. via the `tx/commit` endpoint). This is because the cluster does not currently support transaction identifiers across the cluster. -In this context, all queries are considered `WRITE` queries, even if they contain no cypher with write operations. -Since the HTTP API did not previously support marking queries as `READ` or `WRITE`, the server assumes all queries are `WRITE` queries to support all cases. -The effect of this is that all queries are ultimately executed on the leader. -|=== +By default, all transactions are considered `WRITE` transactions, even if they contain no Cypher with write operations. This can be overridden by setting a value of `READ` in the `access-mode` header of the request (see xref::/actions/transaction-configuration.adoc[Transaction Configuration - Access Mode]). + +This default has the effect that all queries are ultimately executed on the leader. To ensure efficient load balancing of `READ` transactions, you must label them as such in the request. +|=== \ No newline at end of file diff --git a/modules/ROOT/pages/actions/transaction-configuration.adoc b/modules/ROOT/pages/actions/transaction-configuration.adoc new file mode 100644 index 0000000..9e8a350 --- /dev/null +++ b/modules/ROOT/pages/actions/transaction-configuration.adoc @@ -0,0 +1,15 @@ +[[http-api-actions-transaction-configuration]] + +:description: Configuring HTTP Transactions. + + += Transaction Configuration + +For any transaction initiating request (i.e. `/tx` or `tx/commit` ) you can provide configuration options that apply for the duration of the whole transaction. + +== Access Mode +To ensure that efficient load balancing across a cluster, it is important to label transactions that only contain `READ` statements with a `READ` access mode. + +This can be done by adding an `access-mode` header to the request with a value of `READ`. + +The default value if an `access-mode` configuration has not been provided is `WRITE` (expect for clusters where Server-side routing has been disabled where it is `READ`). \ No newline at end of file From 74c0ea5f5331aef63d662951e55254d44379de40 Mon Sep 17 00:00:00 2001 From: David Oliver Date: Wed, 9 Feb 2022 17:02:47 +0000 Subject: [PATCH 2/2] Editorial update --- modules/ROOT/content-nav.adoc | 2 ++ modules/ROOT/pages/actions/routing.adoc | 8 +++++--- .../pages/actions/transaction-configuration.adoc | 15 +++++++++------ 3 files changed, 16 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 7412894..c95f212 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -5,6 +5,8 @@ ** xref:actions/transaction-flow.adoc[] ** xref:actions/query-format.adoc[] ** xref:actions/result-format.adoc[] +** xref:actions/routing.adoc[] +** xref:actions/transaction-configuration.adoc[] ** xref:actions/begin-a-transaction.adoc[] ** xref:actions/execute-statements-in-an-open-transaction.adoc[] ** xref:actions/reset-transaction-timeout-of-an-open-transaction.adoc[] diff --git a/modules/ROOT/pages/actions/routing.adoc b/modules/ROOT/pages/actions/routing.adoc index 0b5a489..0150dc1 100644 --- a/modules/ROOT/pages/actions/routing.adoc +++ b/modules/ROOT/pages/actions/routing.adoc @@ -19,7 +19,9 @@ The level of support depends on whether link:https://neo4j.com/docs/operations-m |Clusters support routing for queries that involve a xref::/actions/begin-and-commit-a-transaction-in-one-request.adoc[single request] (i.e. via the `tx/commit` endpoint). This is because the cluster does not currently support transaction identifiers across the cluster. -By default, all transactions are considered `WRITE` transactions, even if they contain no Cypher with write operations. This can be overridden by setting a value of `READ` in the `access-mode` header of the request (see xref::/actions/transaction-configuration.adoc[Transaction Configuration - Access Mode]). +By default, all transactions are considered `WRITE` transactions, even if they contain no Cypher with write operations. +This can be overridden by setting a value of `READ` in the `access-mode` header of the request (For more information, see xref::/actions/transaction-configuration.adoc[Transaction Configuration - Access Mode]). -This default has the effect that all queries are ultimately executed on the leader. To ensure efficient load balancing of `READ` transactions, you must label them as such in the request. -|=== \ No newline at end of file +This default value ensures that all queries are ultimately run on the leader. +To ensure efficient load balancing of `READ` transactions, you should label them as such in the request. +|=== diff --git a/modules/ROOT/pages/actions/transaction-configuration.adoc b/modules/ROOT/pages/actions/transaction-configuration.adoc index 9e8a350..61c090a 100644 --- a/modules/ROOT/pages/actions/transaction-configuration.adoc +++ b/modules/ROOT/pages/actions/transaction-configuration.adoc @@ -1,15 +1,18 @@ -[[http-api-actions-transaction-configuration]] - :description: Configuring HTTP Transactions. - +[[http-api-actions-transaction-configuration]] = Transaction Configuration -For any transaction initiating request (i.e. `/tx` or `tx/commit` ) you can provide configuration options that apply for the duration of the whole transaction. +For any transaction-initiating request (such as `/tx` or `tx/commit`), you can provide configuration options that apply for the duration of the whole transaction. == Access Mode To ensure that efficient load balancing across a cluster, it is important to label transactions that only contain `READ` statements with a `READ` access mode. -This can be done by adding an `access-mode` header to the request with a value of `READ`. +This can be done by adding an `access-mode` header to the request, with a value of `READ`. + +[WARNING] +==== +If an `access-mode` configuration has *not* been provided, the default value is `WRITE`. -The default value if an `access-mode` configuration has not been provided is `WRITE` (expect for clusters where Server-side routing has been disabled where it is `READ`). \ No newline at end of file +However, if you have clusters with link:https://neo4j.com/docs/operations-manual/current/clustering/internals/#clustering-routing[Server-side routing] disabled, the default value is `READ`. +====