0
# Neomodel
1
2
An Object Graph Mapper (OGM) for the Neo4j graph database, built on the neo4j-python-driver. Neomodel provides familiar class-based model definitions with proper inheritance, a powerful query API, schema enforcement through cardinality restrictions, full transaction support, and both synchronous and asynchronous programming patterns.
3
4
## Package Information
5
6
- **Package Name**: neomodel
7
- **Language**: Python
8
- **Installation**: `pip install neomodel`
9
10
## Core Imports
11
12
```python
13
import neomodel
14
```
15
16
Common patterns for working with neomodel:
17
18
```python
19
from neomodel import (
20
StructuredNode, StringProperty, IntegerProperty,
21
RelationshipTo, config
22
)
23
```
24
25
For async operations:
26
27
```python
28
from neomodel import (
29
AsyncStructuredNode, AsyncRelationshipTo, adb
30
)
31
```
32
33
## Basic Usage
34
35
```python
36
from neomodel import (
37
StructuredNode, StringProperty, IntegerProperty,
38
RelationshipTo, config
39
)
40
41
# Configure database connection
42
config.DATABASE_URL = 'bolt://neo4j:password@localhost:7687'
43
44
# Define node models
45
class Person(StructuredNode):
46
name = StringProperty(unique_index=True, required=True)
47
age = IntegerProperty()
48
49
# Define relationships
50
friends = RelationshipTo('Person', 'FRIENDS_WITH')
51
52
class Movie(StructuredNode):
53
title = StringProperty(required=True)
54
year = IntegerProperty()
55
56
# Create and connect nodes
57
person = Person(name="Alice", age=30).save()
58
movie = Movie(title="The Matrix", year=1999).save()
59
60
# Query nodes
61
alice = Person.nodes.get(name="Alice")
62
matrix_movies = Movie.nodes.filter(title__contains="Matrix")
63
64
# Traverse relationships
65
alice_friends = alice.friends.all()
66
```
67
68
## Architecture
69
70
Neomodel uses a dual-architecture approach:
71
72
- **Synchronous API**: Traditional blocking operations using `StructuredNode`, `db`, and sync-specific classes
73
- **Asynchronous API**: Non-blocking operations using async/await with `AsyncStructuredNode`, `adb`, and async-specific classes
74
75
Key components:
76
77
- **Node Models**: StructuredNode base classes for defining graph entities
78
- **Property Types**: Typed properties with validation and index support
79
- **Relationship Management**: Cardinality-aware relationship definitions and traversal
80
- **Query System**: NodeSet and Traversal classes for complex graph queries
81
- **Database Interface**: Connection management and transaction support
82
83
## Capabilities
84
85
### Node Management
86
87
Core functionality for defining and working with graph nodes, including model definitions, CRUD operations, and property management for both synchronous and asynchronous contexts.
88
89
```python { .api }
90
class StructuredNode:
91
def save(self): ...
92
def delete(self): ...
93
def refresh(self): ...
94
@classmethod
95
def create(cls, **kwargs): ...
96
@classmethod
97
def get_or_create(cls, **kwargs): ...
98
99
class AsyncStructuredNode:
100
async def save(self): ...
101
async def delete(self): ...
102
async def refresh(self): ...
103
@classmethod
104
async def create(cls, **kwargs): ...
105
@classmethod
106
async def get_or_create(cls, **kwargs): ...
107
```
108
109
[Node Management](./nodes.md)
110
111
### Property Types
112
113
Comprehensive set of typed properties for node and relationship attributes, including basic types, specialized validation, date/time handling, and indexing support.
114
115
```python { .api }
116
class StringProperty:
117
def __init__(self, max_length=None, choices=None, **kwargs): ...
118
119
class IntegerProperty:
120
def __init__(self, **kwargs): ...
121
122
class DateTimeProperty:
123
def __init__(self, default_now=False, **kwargs): ...
124
125
class JSONProperty:
126
def __init__(self, **kwargs): ...
127
128
class UniqueIdProperty:
129
def __init__(self, **kwargs): ...
130
```
131
132
[Property Types](./properties.md)
133
134
### Relationship Management
135
136
Powerful relationship definition and traversal system with cardinality constraints, supporting both simple connections and complex relationship models with properties.
137
138
```python { .api }
139
class RelationshipTo:
140
def __init__(self, cls_name, relation_type, **kwargs): ...
141
142
class RelationshipFrom:
143
def __init__(self, cls_name, relation_type, **kwargs): ...
144
145
class StructuredRel:
146
def save(self): ...
147
def delete(self): ...
148
149
# Cardinality classes
150
class One: ...
151
class ZeroOrOne: ...
152
class OneOrMore: ...
153
class ZeroOrMore: ...
154
```
155
156
[Relationship Management](./relationships.md)
157
158
### Query and Traversal
159
160
Advanced querying capabilities including filtering, ordering, aggregation, and graph traversal operations with support for complex WHERE clauses and relationship navigation.
161
162
```python { .api }
163
class NodeSet:
164
def filter(self, **kwargs): ...
165
def get(self, **kwargs): ...
166
def all(self): ...
167
def order_by(self, *props): ...
168
def limit(self, count): ...
169
170
class Q:
171
def __init__(self, **kwargs): ...
172
def __and__(self, other): ...
173
def __or__(self, other): ...
174
175
class Traversal:
176
def traverse(self, *relationships): ...
177
```
178
179
[Query and Traversal](./queries.md)
180
181
### Database Operations
182
183
Database connection management, schema operations, transaction support, and administrative functions for maintaining Neo4j database state.
184
185
```python { .api }
186
# Database instances
187
db: Database # Sync database interface
188
adb: AsyncDatabase # Async database interface
189
190
# Utility functions
191
def clear_neo4j_database(): ...
192
def install_all_labels(): ...
193
def change_neo4j_password(new_password): ...
194
def drop_constraints(): ...
195
def drop_indexes(): ...
196
```
197
198
[Database Operations](./database.md)
199
200
### Exception Handling
201
202
Comprehensive exception classes for error handling in neomodel operations, providing detailed information about various error conditions during database operations, model definitions, and data validation.
203
204
```python { .api }
205
# Base exceptions
206
class NeomodelException(Exception): ...
207
class DoesNotExist(NeomodelException): ...
208
class MultipleNodesReturned(ValueError, NeomodelException): ...
209
210
# Property exceptions
211
class RequiredProperty(NeomodelException): ...
212
class UniqueProperty(ConstraintValidationFailed): ...
213
class InflateError(ValueError, NeomodelException): ...
214
class DeflateError(ValueError, NeomodelException): ...
215
216
# Cardinality exceptions
217
class CardinalityViolation(NeomodelException): ...
218
class AttemptedCardinalityViolation(NeomodelException): ...
219
220
# Model definition exceptions
221
class NodeClassNotDefined(ModelDefinitionException): ...
222
class RelationshipClassNotDefined(ModelDefinitionException): ...
223
```
224
225
[Exception Handling](./exceptions.md)
226
227
## Configuration
228
229
```python { .api }
230
# Core configuration variables
231
DATABASE_URL: str # Neo4j connection URL (default: "bolt://neo4j:foobarbaz@localhost:7687")
232
DATABASE_NAME: str # Specific database name for multi-database instances
233
DRIVER: object # Custom Neo4j driver instance
234
FORCE_TIMEZONE: bool # Force timezone handling (default: False)
235
236
# Connection configuration options
237
CONNECTION_ACQUISITION_TIMEOUT: float # Timeout for acquiring connections (default: 60.0)
238
CONNECTION_TIMEOUT: float # Connection timeout in seconds (default: 30.0)
239
ENCRYPTED: bool # Enable encrypted connection (default: False)
240
KEEP_ALIVE: bool # Enable connection keep-alive (default: True)
241
MAX_CONNECTION_LIFETIME: int # Maximum connection lifetime in seconds (default: 3600)
242
MAX_CONNECTION_POOL_SIZE: int # Maximum connection pool size (default: 100)
243
MAX_TRANSACTION_RETRY_TIME: float # Maximum transaction retry time (default: 30.0)
244
RESOLVER: object # Custom address resolver (default: None)
245
TRUSTED_CERTIFICATES: object # Certificate trust configuration
246
USER_AGENT: str # User agent string for driver connections
247
```
248
249
Configuration is handled through the `neomodel.config` module, allowing connection URL specification, custom driver instances, and comprehensive connection tuning options. All connection parameters correspond to Neo4j Python driver configuration options.
250
251
## Command-Line Tools
252
253
Neomodel provides several CLI scripts for database management, schema operations, and development utilities.
254
255
```bash
256
# Install database indexes and constraints for model schemas
257
neomodel_install_labels someapp.models
258
259
# Remove all indexes and constraints from database
260
neomodel_remove_labels
261
262
# Inspect existing database and generate Python model definitions
263
neomodel_inspect_database --write-to models.py
264
265
# Generate database diagram in PlantUML or Arrows.app format
266
neomodel_generate_diagram --file-type puml --write-to-dir diagrams/
267
```
268
269
**Available Scripts:**
270
- `neomodel_install_labels` - Setup indexes and constraints for neomodel schemas
271
- `neomodel_remove_labels` - Drop all indexes and constraints from database
272
- `neomodel_inspect_database` - Inspect database schema and generate model definitions
273
- `neomodel_generate_diagram` - Generate database visualization diagrams
274
275
All scripts support `--db` parameter for custom Neo4j connection URLs and will use `NEO4J_BOLT_URL` environment variable as fallback.
276
277
## Data Integration
278
279
Neomodel provides integration utilities for converting query results to popular data science libraries.
280
281
```python { .api }
282
# NumPy integration (requires numpy package)
283
from neomodel.integration.numpy import to_ndarray
284
285
def to_ndarray(query_results: tuple, dtype=None, order="K"):
286
"""
287
Convert cypher query results to numpy ndarray.
288
289
Args:
290
query_results (tuple): Results from db.cypher_query()
291
dtype: Optional numpy data type
292
order (str): Array ordering ('K', 'C', 'F', 'A')
293
294
Returns:
295
numpy.ndarray: Query results as numpy array
296
"""
297
298
# Pandas integration (requires pandas package)
299
from neomodel.integration.pandas import to_dataframe, to_series
300
301
def to_dataframe(query_results: tuple, index=None, dtype=None):
302
"""
303
Convert cypher query results to pandas DataFrame.
304
305
Args:
306
query_results (tuple): Results from db.cypher_query()
307
index: Optional row index for DataFrame
308
dtype: Optional pandas data type
309
310
Returns:
311
pandas.DataFrame: Query results as DataFrame
312
"""
313
314
def to_series(query_results: tuple, field=0, index=None, dtype=None):
315
"""
316
Convert cypher query results to pandas Series.
317
318
Args:
319
query_results (tuple): Results from db.cypher_query()
320
field (int): Column index to extract (default: 0)
321
index: Optional row index for Series
322
dtype: Optional pandas data type
323
324
Returns:
325
pandas.Series: Single column as Series
326
"""
327
```
328
329
### Integration Usage Example
330
331
```python
332
from neomodel import db
333
from neomodel.integration.pandas import to_dataframe
334
from neomodel.integration.numpy import to_ndarray
335
336
# Execute cypher query
337
results = db.cypher_query("MATCH (u:User) RETURN u.name AS name, u.age AS age")
338
339
# Convert to pandas DataFrame
340
df = to_dataframe(results)
341
print(df)
342
# name age
343
# 0 Alice 30
344
# 1 Bob 25
345
346
# Convert to numpy array
347
arr = to_ndarray(results)
348
print(arr)
349
# [['Alice' 30]
350
# ['Bob' 25]]
351
```
352
353
## Types
354
355
```python { .api }
356
# Direction constants
357
OUTGOING: int # Value: 1
358
INCOMING: int # Value: -1
359
EITHER: int # Value: 0
360
361
# Base classes
362
class NeomodelException(Exception): ...
363
class DoesNotExist(NeomodelException): ...
364
class RequiredProperty(ValueError): ...
365
class UniqueProperty(ValueError): ...
366
```