0
# Neo4j Python Driver
1

2
The Neo4j Python driver provides connectivity to Neo4j graph databases using the efficient Bolt protocol. It supports both synchronous and asynchronous programming models, offering comprehensive database operations including transactions, sessions, and advanced features like query routing, connection pooling, and causal consistency through bookmarks.
3

4
## Package Information
5

6
- **Package Name**: neo4j
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install neo4j`
10
- **Requires Python**: >=3.7
11

12
## Core Imports
13

14
```python
15
import neo4j
16
```
17

18
Most commonly used imports:
19

20
```python
21
from neo4j import GraphDatabase, Driver, Session, Result
22
from neo4j import basic_auth, Auth
23
from neo4j import Record, Query, Bookmark
24
```
25

26
For graph and temporal data types:
27

28
```python
29
from neo4j.graph import Node, Relationship, Path
30
from neo4j.time import Date, DateTime, Time, Duration
31
from neo4j.spatial import Point, CartesianPoint, WGS84Point
32
```
33

34
For exception handling:
35

36
```python
37
from neo4j.exceptions import (
38
    Neo4jError, ClientError, TransientError, DriverError,
39
    ServiceUnavailable, AuthError, CypherSyntaxError,
40
    ResultNotSingleError, SessionExpired
41
)
42
```
43

44
For async operations:
45

46
```python
47
from neo4j import AsyncGraphDatabase, AsyncDriver, AsyncSession, AsyncResult
48
from neo4j import AsyncManagedTransaction, AsyncTransaction
49
```
50

51
## Basic Usage
52

53
```python
54
from neo4j import GraphDatabase, basic_auth
55

56
# Create a driver instance
57
driver = GraphDatabase.driver(
58
    "bolt://localhost:7687", 
59
    auth=basic_auth("neo4j", "password")
60
)
61

62
# Execute a simple query using execute_query (recommended)
63
records, summary, keys = driver.execute_query(
64
    "CREATE (n:Person {name: $name}) RETURN n",
65
    name="Alice"
66
)
67

68
# Alternative: Use session for more complex operations
69
with driver.session() as session:
70
    result = session.run("MATCH (n:Person) RETURN n.name AS name")
71
    for record in result:
72
        print(record["name"])
73

74
# Always close the driver when done
75
driver.close()
76
```
77

78
Async usage:
79

80
```python
81
import asyncio
82
from neo4j import AsyncGraphDatabase, basic_auth
83

84
async def main():
85
    driver = AsyncGraphDatabase.driver(
86
        "bolt://localhost:7687", 
87
        auth=basic_auth("neo4j", "password")
88
    )
89
    
90
    # Execute query asynchronously
91
    records, summary, keys = await driver.execute_query(
92
        "MATCH (n:Person) RETURN n.name AS name"
93
    )
94
    
95
    await driver.close()
96

97
asyncio.run(main())
98
```
99

100
## Architecture
101

102
The Neo4j Python driver follows a hierarchical architecture designed for scalability and flexibility:
103

104
- **Driver**: Top-level connection manager handling connection pooling, routing, and authentication. Supports both direct connections (BoltDriver) and cluster routing (Neo4jDriver).
105
- **Session**: Logical container for executing work, providing transaction management and causal consistency through bookmarks.
106
- **Transaction**: Unit of work that can be either auto-commit (via `run()`) or explicit (via `begin_transaction()`). Supports both read and write operations with automatic retry logic.
107
- **Result**: Iterator-like object for consuming query results, offering both streaming and eager consumption patterns.
108

109
This design enables efficient connection reuse, automatic failover in clustered environments, and provides both simple and advanced usage patterns through execute_query shortcuts and explicit transaction management.
110

111
## Capabilities
112

113
### Drivers & Connection
114

115
Core connection management through GraphDatabase factory methods and Driver classes, supporting both direct server connections and cluster routing with comprehensive configuration options.
116

117
```python { .api }
118
class GraphDatabase:
119
    @staticmethod
120
    def driver(uri: str, *, auth: Auth = None, **config) -> Driver: ...
121
    
122
    @staticmethod
123
    def bolt_driver(target: str, **config) -> BoltDriver: ...
124
    
125
    @staticmethod
126
    def neo4j_driver(*targets: str, routing_context: dict = None, **config) -> Neo4jDriver: ...
127

128
class Driver:
129
    def session(**config) -> Session: ...
130
    def execute_query(query: str, parameters: dict = None, **kwargs) -> tuple[list[Record], ResultSummary, list[str]]: ...
131
    def close() -> None: ...
132
```
133

134
[Drivers & Connection](./drivers.md)
135

136
### Sessions
137

138
Session management providing contexts for executing work with transaction control, bookmark handling for causal consistency, and support for both read and write operations.
139

140
```python { .api }
141
class Session:
142
    def run(query: str, parameters: dict = None, **kwargs) -> Result: ...
143
    def execute_read(work: Callable, *args, **kwargs): ...
144
    def execute_write(work: Callable, *args, **kwargs): ...
145
    def begin_transaction(**config) -> Transaction: ...
146
    def close() -> None: ...
147
```
148

149
[Sessions](./sessions.md)
150

151
### Transactions & Results
152

153
Transaction management and result handling supporting auto-commit transactions, explicit transactions with full ACID properties, and flexible result consumption patterns.
154

155
```python { .api }
156
class Transaction:
157
    def run(query: str, parameters: dict = None, **kwparameters) -> Result: ...
158
    def commit() -> None: ...
159
    def rollback() -> None: ...
160

161
class Result:
162
    def consume() -> ResultSummary: ...
163
    def single(strict: bool = True) -> Record | None: ...
164
    def data(*args) -> list[dict]: ...
165
    def to_df() -> pandas.DataFrame: ...
166
```
167

168
[Transactions & Results](./transactions-results.md)
169

170
### Authentication
171

172
Authentication system supporting multiple authentication schemes including basic, Kerberos, bearer tokens, and custom authentication mechanisms.
173

174
```python { .api }
175
def basic_auth(user: str, password: str, realm: str = None) -> Auth: ...
176
def kerberos_auth(base64_encoded_ticket: str) -> Auth: ...
177
def bearer_auth(base64_encoded_token: str) -> Auth: ...
178
def custom_auth(principal: str, credentials: str, realm: str, scheme: str, **parameters) -> Auth: ...
179

180
class Auth:
181
    scheme: str | None
182
    principal: str | None
183
    credentials: str | None
184
    realm: str | None
185
```
186

187
[Authentication](./authentication.md)
188

189
### Data Types
190

191
Rich data type system including records, queries with metadata, bookmarks for causal consistency, graph data types (Node, Relationship, Path), temporal types (Date, DateTime, Time, Duration), spatial types (Point variants), and exception hierarchy for error handling.
192

193
```python { .api }
194
class Record:
195
    def keys() -> tuple[str, ...]: ...
196
    def values() -> tuple: ...
197
    def get(key: str, default=None): ...
198
    def data(*keys) -> dict: ...
199

200
class Query:
201
    def __init__(text: str, metadata: dict = None, timeout: float = None): ...
202
    text: str
203
    metadata: dict | None
204
    timeout: float | None
205

206
class Node:
207
    element_id: str
208
    labels: frozenset[str]
209
    def get(name: str, default=None): ...
210

211
# Neo4j temporal types
212
class DateTime:
213
    def __init__(year: int, month: int, day: int, hour: int = 0, ...): ...
214
    year: int
215
    month: int
216
    nanosecond: int
217

218
# Spatial types
219
class Point:
220
    srid: int | None
221
    x: float
222
    y: float
223

224
# Exception hierarchy  
225
class Neo4jError(Exception):
226
    code: str
227
    message: str
228
```
229

230
[Data Types](./data-types.md)
231

232
### Configuration
233

234
Configuration management including SSL/TLS trust settings, connection pooling, timeout configuration, and cluster routing options.
235

236
```python { .api }
237
class TrustSystemCAs: ...
238
class TrustAll: ...
239
class TrustCustomCAs:
240
    def __init__(*certs): ...
241

242
# Configuration constants
243
TRUST_SYSTEM_CA_SIGNED_CERTIFICATES: str
244
TRUST_ALL_CERTIFICATES: str
245
READ_ACCESS: str
246
WRITE_ACCESS: str
247
```
248

249
[Configuration](./configuration.md)