You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Raised when a database server or service is not available.
12
+
This may be due to incorrect configuration or could indicate a runtime failure of a database service that the driver is unable to route around.
13
+
14
+
.. class:: neo4j.exceptions.SecurityError
15
+
16
+
Raised when a security issue occurs, generally around TLS or authentication.
17
+
18
+
19
+
Cypher execution errors
20
+
=======================
21
+
22
+
.. class:: neo4j.exceptions.CypherError
23
+
24
+
Raised when the Cypher engine returns an error to the client.
25
+
There are many possible types of Cypher error, each identified by a unique `status code <https://neo4j.com/docs/developer-manual/current/reference/status-codes/>`_.
26
+
27
+
The three classifications of status code are supported by the three subclasses of :class:`.CypherError`, listed below:
16
28
17
29
.. autoclass:: neo4j.exceptions.ClientError
18
-
:show-inheritance:
19
-
:members:
20
30
21
31
.. autoclass:: neo4j.exceptions.DatabaseError
22
-
:show-inheritance:
23
-
:members:
24
32
25
33
.. autoclass:: neo4j.exceptions.TransientError
26
-
:show-inheritance:
27
-
:members:
34
+
35
+
36
+
Low-level errors
37
+
================
38
+
39
+
.. class:: neo4j.exceptions.ProtocolError
40
+
41
+
Raised when an unexpected or unsupported protocol event occurs.
42
+
This error generally indicates a fault with the driver or server software.
43
+
If you receive this error, please raise a GitHub issue or a support ticket.
All database activity is co-ordinated through two mechanisms: the :class:`.Session` and the :class:`.Transaction`.
5
6
A :class:`.Transaction` is a unit of work that is either committed in its entirety or is rolled back on failure.
6
-
A :class:`.Session` is a logical container for one or more transactional units of work.
7
-
Sessions automatically provide guarantees of causal consistency within a clustered environment.
7
+
A :class:`.Session` is a logical container for any number of causally-related transactional units of work.
8
+
Sessions automatically provide guarantees of causal consistency within a clustered environment but multiple sessions can also be causally chained if required.
8
9
9
-
A session can be given a default `access mode` on construction.
10
-
This applies only in clustered environments and determines whether transactions carried out within that session should be routed to a `read` or `write` server.
11
-
Transaction functions within that session can override this access mode.
12
10
13
-
.. note::
14
-
The driver does not parse Cypher statements and cannot determine whether a statement tagged as `read` or `write` is tagged correctly.
15
-
Since the access mode is not passed to the server, this can allow a `write` statement to be executed in a `read` call on a single instance.
16
-
Clustered environments are not susceptible to this loophole as cluster roles prevent it.
11
+
Sessions
12
+
========
13
+
14
+
Sessions provide the top-level of containment for database activity.
15
+
Session creation is a lightweight operation and sessions are `not` thread safe.
16
+
17
+
Connections are drawn from the :class:`.Driver` connection pool as required; an idle session will not hold onto a connection.
18
+
19
+
Sessions will often be created and destroyed using a `with` block context.
20
+
For example::
21
+
22
+
with driver.session() as session:
23
+
result = session.run("MATCH (a:Person) RETURN a.name")
24
+
# do something with the result...
25
+
26
+
To construct a :class:`.Session` use the :meth:`.Driver.session` method.
27
+
28
+
.. class:: neo4j.Session
29
+
30
+
.. automethod:: close
31
+
32
+
.. automethod:: closed
33
+
34
+
.. automethod:: run
35
+
36
+
.. automethod:: sync
37
+
38
+
.. automethod:: detach
39
+
40
+
.. automethod:: next_bookmarks
41
+
42
+
.. automethod:: last_bookmark
43
+
44
+
.. automethod:: has_transaction
45
+
46
+
.. automethod:: begin_transaction
47
+
48
+
.. automethod:: read_transaction
49
+
50
+
.. automethod:: write_transaction
51
+
52
+
53
+
Transactions
54
+
============
17
55
18
56
Neo4j supports three kinds of transaction: `auto-commit transactions`, `explicit transactions` and `transaction functions`.
19
57
Each has pros and cons but if in doubt, use a transaction function.
20
58
21
59
Auto-commit Transactions
22
-
========================
23
-
Auto-commit transactions are the simplest form, available via :meth:`.Session.run`.
24
-
These are fast and easy to use but support only one statement per transaction and are not automatically retried on failure.
25
-
Auto-commit transactions are also the only way to run ``USING PERIODIC COMMIT`` statements.
60
+
------------------------
61
+
Auto-commit transactions are the simplest form of transaction, available via :meth:`.Session.run`.
62
+
These are easy to use but support only one statement per transaction and are not automatically retried on failure.
63
+
Auto-commit transactions are also the only way to run ``PERIODIC COMMIT`` statements, since this Cypher clause manages its own transactions internally.
26
64
27
65
.. code-block:: python
28
66
@@ -32,8 +70,43 @@ Auto-commit transactions are also the only way to run ``USING PERIODIC COMMIT``
32
70
"RETURN id(a)", name=name).single().value()
33
71
34
72
Explicit Transactions
35
-
=====================
73
+
---------------------
36
74
Explicit transactions support multiple statements and must be created with an explicit :meth:`.Session.begin_transaction` call.
75
+
This creates a new :class:`.Transaction` object that can be used to run Cypher.
76
+
It also gives applications the ability to directly control `commit` and `rollback` activity.
77
+
78
+
.. class:: neo4j.Transaction
79
+
80
+
.. automethod:: run
81
+
82
+
.. automethod:: sync
83
+
84
+
.. attribute:: success
85
+
86
+
This attribute can be used to determine the outcome of a transaction on closure.
87
+
Specifically, this will be either a COMMIT or a ROLLBACK.
88
+
A value can be set for this attribute multiple times in user code before a transaction completes, with only the final value taking effect.
89
+
90
+
On closure, the outcome is evaluated according to the following rules:
.. [1] While a COMMIT will be attempted in this scenario, it will likely fail if the exception originated from Cypher execution within that transaction.
101
+
102
+
.. automethod:: close
103
+
104
+
.. automethod:: closed
105
+
106
+
.. automethod:: commit
107
+
108
+
.. automethod:: rollback
109
+
37
110
Closing an explicit transaction can either happen automatically at the end of a ``with`` block, using the :attr:`.Transaction.success` attribute to determine success,
38
111
or can be explicitly controlled through the :meth:`.Transaction.commit` and :meth:`.Transaction.rollback` methods.
39
112
Explicit transactions are most useful for applications that need to distribute Cypher execution across multiple functions for the same transaction.
@@ -56,7 +129,7 @@ Explicit transactions are most useful for applications that need to distribute C
56
129
"SET a.name = $name", id=node_id, name=name)
57
130
58
131
Transaction Functions
59
-
=====================
132
+
---------------------
60
133
Transaction functions are the most powerful form of transaction, providing access mode override and retry capabilities.
61
134
These allow a function object representing the transactional unit of work to be passed as a parameter.
62
135
This function is called one or more times, within a configurable time limit, until it succeeds.
@@ -72,11 +145,22 @@ Returning a live result object would prevent the driver from correctly managing
To exert more control over how a transaction function is carried out, the :func:`.unit_of_work` decorator can be used.
149
+
150
+
.. autofunction:: neo4j.unit_of_work
75
151
76
-
API
77
-
===
78
-
.. autoclass:: neo4j.Session
79
-
:members:
80
152
81
-
.. autoclass:: neo4j.Transaction
82
-
:members:
153
+
Access modes
154
+
============
155
+
156
+
A session can be given a default `access mode` on construction.
157
+
This applies only in clustered environments and determines whether transactions carried out within that session should be routed to a `read` or `write` server by default.
158
+
159
+
Note that this mode is simply a default and not a constraint.
160
+
This means that transaction functions within a session can override the access mode passed to that session on construction.
161
+
162
+
.. note::
163
+
The driver does not parse Cypher statements and cannot determine whether a statement tagged as `read` or `write` is tagged correctly.
164
+
Since the access mode is not passed to the server, this can allow a `write` statement to be executed in a `read` call on a single instance.
165
+
Clustered environments are not susceptible to this loophole as cluster roles prevent it.
166
+
This behaviour should not be relied upon as the loophole may be closed in a future release.
0 commit comments