wip

Author: andrejtonev

pages/client-libraries/python.mdx

@@ -545,6 +545,9 @@ With sessions, you can run:
 ##### Managed transactions
 
 To create a managed transaction, use `Session.execute_read()` procedure for read queries and `Session.execute_write()` procedure for write queries.
+As of Memgraph version 3.2, queries are categorized as read or write and the corresponding storage access is taken. This allows for better query parallelization and higher throughput.
+An exception will be thrown if the user tries to execute a write query inside a read transaction. See [transaction accessor misalignment](/fundamentals/transactions#transaction-accessor-misalignment) for more details.
+
 
 ```python
 def match_user(tx, name):
@@ -581,6 +584,10 @@ To maintain multiple concurrent transactions, use [multiple concurrent sessions]
 With explicit transactions, you can get **complete control over transactions**. To begin a transaction, run `Session.begin_transaction()` procedure and to run a transaction, use `Transaction.run()` procedure.
 Explicit transactions offer the possibility of explicitly controlling the end of a transaction with `Transaction.commit()`, `Transaction.rollback()` or `Transaction.close()` methods.
 
+As of Memgraph version 3.2, queries are categorized as read or write and the corresponding storage access is taken. This allows for better query parallelization and higher throughput.
+Explicit transactions can cover a number of individual queries, but storage access is given at the start. For best performance, the user needs to declare whether the transaction should use read or write access.
+This can be done by setting the session's `default_access_mode` to `"r"` or `"w"`. This will in turn set the access mode of a transaction created via the `begin_transaction` function. Note that `execute_read` and `execute_write` will override the session's default access.
+
 Use explicit transaction if you need to **distribute Cypher execution across multiple functions for the same transaction** or if you need to **run multiple queries within a single transactions without automatic retries**.
 
 The following example shows how to explicitly control the transaction of changing account balances based on a token transfer:
@@ -610,7 +617,7 @@ def create_users(client, sender, receiver):
 
 
 def transfer_tokens(client, sender_id, receiver_id, num_of_tokens):
-    with client.session(database="memgraph") as session:
+    with client.session(database="memgraph", default_access_mode="w") as session:
         tx = session.begin_transaction()
 
         try:
@@ -675,6 +682,8 @@ In the above example, if John's account balance is changed to a number less than
 
 Implicit or auto-commit transactions are the simplest way to run a Cypher query since they won't be automatically retried as with `execute_query()` procedure or managed transactions.
 With implicit transactions, you don't have the same control of transaction as with explicit transactions, so they are mostly used for quick prototyping.
+As of Memgraph version 3.2, queries are categorized as read or write and the corresponding storage access is taken. This allows for better query parallelization and higher throughput.
+Access mode is automatically determined when executing single queries through implicit transactions.
 
 To run an implicit transaction, use the `Session.run()` method:
 

pages/help-center/errors/transactions.mdx

@@ -99,6 +99,25 @@ While some client drivers may handle serialization errors by retrying transactio
 developers should not rely solely on this mechanism. Always include comprehensive error handling 
 in your application to address cases where the error persists beyond the retry logic. 
 
+## Transaction accessor misalignment
+
+### Error message
+
+1. **Accessor type {} and query type {} are misaligned!**
+
+### Handling transaction timeout
+
+Transactions in Memgraph must acquire the appropriate type of storage access at the start of their execution. This access can be one of the following types:
+
+- **Shared access**: Allows multiple queries to run in parallel, marked as either read or write.
+- **Read-only access**: Permits multiple read queries to run in parallel but forbids any write operations or queries requiring unique access.
+- **Unique access**: Grants exclusive access to a single query, preventing any other type of access during its execution.
+
+While single queries can be parsed and the correct type of storage access can be determined automatically by Memgraph, this is not the case for explicit (managed) transactions.
+In managed transactions, the database cannot infer the required access type in advance because the transaction's operations are not know at the beginning.
+This can lead to storage access misalignment if the requested access type does not match the operations being performed.
+
+See appropriate driver's documentation for more information on how to define transaction's type.
 
 ## Transaction timeout
 
@@ -119,15 +138,17 @@ Here are the [instructions](/configuration/configuration-settings#using-flags-an
 
 Here are the storage access error messages you might encounter:
 
-1. **Cannot access storage, unique access query is running. Try again later.**
+1. **Cannot get shared access storage. Try stopping other queries that are running in parallel.**
 2. **Cannot get unique access to the storage. Try stopping other queries that are running in parallel.**
+3. **Cannot get read only access to the storage. Try stopping other queries that are running in parallel.**
 
 ### Understanding storage access timeout
 
-Storage access timeouts occur during query preparation when the query execution engine cannot get the required type of access to the storage. There are two types of storage access:
+Storage access timeouts occur during query preparation when the query execution engine cannot get the required type of access to the storage. There are three types of storage access:
 
-- **Shared access**: Multiple queries can have shared access at the same time, but shared access cannot be granted while a query with unique access is running.
-- **Unique access**: Only one query can have unique access at a time, and no other query can have any type of access during that period.
+- **Shared access**: Multiple queries can have shared access at the same time. These queries are marked with a read or write type, allowing Memgraph to efficiently execute multiple operations in parallel without conflicts.
+- **Unique access**: Only one query can have unique access at a time, and no other access type can be granted during that period.
+- **Read-only access**: Queries with read-only access allow other read queries to run in parallel but forbid any write operations or unique access queries.
 
 These timeouts prevent worker starvation and database blocking that could occur if queries were to wait indefinitely for storage access.