Graph Database Clients: For Technical Decision Makers#

Purpose: Help CTOs, architects, and product managers understand Python graph database client libraries without deep graph theory expertise.

Audience: Technical leaders evaluating graph database adoption, teams planning migrations, developers choosing between query languages.

What This Solves#

Graph database client libraries solve the connection and interaction problem between your Python application and graph database systems.

The Core Problem: You have relationship-heavy data (social networks, fraud rings, supply chains, knowledge graphs) that traditional SQL databases handle poorly. Graph databases excel at traversing multi-hop relationships, but you need a way for your Python code to:

• Send queries to the graph database
• Receive and process results efficiently
• Manage connections, transactions, and errors
• Abstract away database-specific protocols

Who Encounters This:

• Startups building social features, recommendation engines, or knowledge bases
• Enterprise teams implementing fraud detection, network analysis, or supply chain optimization
• Data scientists constructing knowledge graphs for LLM-powered applications (GraphRAG)
• SaaS developers adding relationship-driven features to existing products

Why It Matters: Choosing the wrong client library locks you into a specific database vendor, query language, and ecosystem. Migration costs can reach hundreds of thousands of dollars in engineering time. The choice made today determines your flexibility, operational costs, and feature velocity for years.

Accessible Analogies#

The Translator Analogy#

Think of your graph database as a foreign city, and the client library as your tour guide/translator:

• Neo4j driver (Cypher): A local expert who speaks the native language fluently, knows all the shortcuts, and has deep cultural knowledge. Fastest and most natural, but only works in this one city.

• gremlinpython (Gremlin): A professional translator who works across multiple cities in the same region (TinkerPop family). Slightly less fluent in each individual dialect, but you can move between cities (Neptune, Cosmos DB, JanusGraph) without finding a new guide.

• TigerGraph (GSQL): A hyper-specialized guide for a unique city with its own invented language. Incredibly effective for that specific place, but you can’t take this guide anywhere else—total lock-in.

The Filing System Analogy#

Imagine organizing a library:

• Relational databases (SQL): Books organized in strict categories with catalog cards. Finding related books means walking to different sections, checking multiple cards (JOINs). Slow for “show me all mystery novels written by authors who also wrote sci-fi and were influenced by Author X.”

• Graph databases: Every book has strings connecting it to related books, authors, and genres. Following those strings (traversals) is instant. The client library is the tool that lets you pull strings and read the labels.

The Protocol Translator#

Your Python code speaks Python. Your graph database speaks a specialized protocol (Bolt, WebSocket, gRPC, HTTP). The client library is the interpreter that:

• Translates your session.run("MATCH (n:User) RETURN n") into Bolt binary protocol
• Manages the TCP connection pool
• Deserializes results back into Python objects

Without it, you’d be manually crafting binary packets—impractical and error-prone.

When You Need This#

✅ You Need Graph Database Clients If:#

Relationship depth matters (3+ hops):

• “Find friends-of-friends-of-friends who like this product” (social networks)
• “Trace transaction chains 5 levels deep” (fraud detection)
• “Show supply chain impact 4 tiers upstream” (risk analysis)

Pattern matching drives value:

• Detecting rings, cycles, or suspicious subgraph structures
• Knowledge graph reasoning (entity → relationship → entity chains)
• Network influence propagation

Data model is naturally a graph:

• Org charts with complex reporting structures
• Infrastructure dependency maps
• Recommendation engines with collaborative filtering

❌ You DON’T Need This If:#

Simple CRUD operations:

• User profiles with basic lookups (use PostgreSQL)
• Document storage without complex relationships (use MongoDB)
• Time-series data (use InfluxDB, TimescaleDB)

All relationships are 1-2 hops:

• Basic “user has many orders” (SQL foreign keys suffice)
• Simple hierarchies (category → subcategory → product)

You’re already solving it well:

• PostgreSQL with recursive CTEs handling your traversals adequately
• Current solution meets performance SLAs and you’re not hitting scaling issues

Decision Criteria: When to Upgrade to Graph#

Trade-offs#

Query Language Lock-in Spectrum#

Most Portable ←----------------------------------→ Most Locked-In
   Gremlin          Cypher/GQL          GSQL         Proprietary
   (multi-DB)       (converging)      (TigerGraph)    (single vendor)

Gremlin (gremlinpython) - Portability Choice:

• ✅ Pros: Works across Neptune, Cosmos DB, JanusGraph, DataStax
• ✅ Pros: Apache governance, multi-vendor PMC
• ❌ Cons: Imperative style is harder to read than declarative Cypher
• ❌ Cons: Doesn’t work with Neo4j (market leader)

Cypher (neo4j) - Developer Experience Choice:

• ✅ Pros: Most readable query language, largest community (44% market share)
• ✅ Pros: Converging to ISO GQL standard (future-proofing)
• ✅ Pros: Best GraphRAG and LLM integration (2025+)
• ❌ Cons: Neo4j dominance means de facto lock-in
• ❌ Cons: GQL standardization timeline uncertain (2026-2028 expected)

GSQL (pyTigerGraph) - Performance Choice:

• ✅ Pros: Best performance for deep analytics (10+ hop traversals)
• ✅ Pros: Turing-complete query language (complex algorithms)
• ❌ Cons: Complete vendor lock-in (portability score: 2/10)
• ❌ Cons: Smaller ecosystem and hiring pool

OGM (Object-Graph Mapper) vs Raw Driver#

OGM (neomodel) - Productivity:

• ✅ Django-style models, faster CRUD development (30-50% time savings)
• ❌ Hides query details, can obscure performance issues
• ❌ Adds abstraction overhead

Raw Driver (neo4j, gremlinpython) - Control:

• ✅ Full query optimization control
• ✅ No abstraction overhead
• ❌ More boilerplate code for simple CRUD

Recommendation: Start with raw driver, add OGM if CRUD patterns dominate.

Build vs Buy (Self-Hosted vs Managed)#

Self-Hosted (Community Edition):

• ✅ Free for Neo4j Community, no usage limits
• ✅ Full control over infrastructure
• ❌ Operational burden (backups, scaling, monitoring)
• ❌ No enterprise support or high availability (Community)

Managed Services (AuraDB, Neptune, Cosmos):

• ✅ Zero operational overhead
• ✅ Built-in backups, scaling, monitoring
• ❌ $65-2,000+/month (can reach $10K+ at scale)
• ❌ Cloud vendor lock-in (migration complexity)

Cost Considerations#

Direct Costs#

Hidden Costs#

Learning Curve:

• Cypher/Gremlin training: 1-2 weeks per developer
• Graph modeling: 2-4 weeks for team to shift thinking
• Query optimization: Ongoing (graph queries need different tuning than SQL)

Migration Lock-in Cost:

• Cypher to Gremlin: 3-6 months for medium codebase (all queries rewritten)
• GSQL to anything: 6-12 months (proprietary language, no migration tools)
• Data export/import: 1-4 weeks depending on volume and schema complexity

Opportunity Cost Examples:

• Choosing TigerGraph for a small project: If you outgrow GSQL lock-in, migration cost = $200K-500K in engineering time
• Skipping GraphRAG opportunity: Companies report 300-320% ROI on knowledge graph implementations (LinkedIn: 63% ticket resolution improvement)

ROI Break-Even Analysis#

When graph DB pays for itself:

• Query performance gains: 10-100x faster for 3+ hop traversals
• Developer productivity: 40% faster feature delivery for relationship-heavy features (anecdotal, industry reports)
• Fraud detection improvements: 50% better detection rates (finance industry data)

Typical payback period: 6-18 months for teams with clear relationship-heavy use cases.

Implementation Reality#

First 90 Days: What to Expect#

Weeks 1-2: Learning & Proof of Concept

• Install local Neo4j or use AuraDB free tier
• Team learns Cypher/Gremlin basics (online tutorials: 5-10 hours per developer)
• Model one core use case (e.g., user → friend → product recommendation)
• Build simple prototype showing multi-hop traversal

Weeks 3-6: Production Architecture

• Choose managed vs self-hosted (decision driven by team expertise)
• Set up connection pooling, error handling, retry logic
• Migrate subset of production data
• Benchmark queries against existing SQL approach (expect 10-50x improvement for graph queries)

Weeks 7-12: Integration & Optimization

• Integrate with existing Python services
• Tune indexes (graph indexes work differently than SQL—expect learning curve)
• Handle schema evolution (graph schemas are more flexible, but migrations still needed)
• Monitor performance under load

Team Skill Requirements#

Essential:

• Comfortable with Python async/await patterns (if using async clients)
• Willingness to learn declarative query language (Cypher is SQL-like, Gremlin is more programmatic)
• Graph modeling mindset (thinking in nodes/edges vs tables/rows)

Nice to Have:

• Prior experience with NoSQL databases (helps with schema flexibility concepts)
• Understanding of graph algorithms (PageRank, community detection—libraries often provide these)

Hiring Impact:

• Cypher developers: Moderate pool (Neo4j dominance means growing talent base)
• Gremlin developers: Smaller pool (more specialized)
• GSQL developers: Very small pool (lock-in includes talent availability)

Common Pitfalls#

1. “All graph databases are the same”

• Reality: Neo4j (Cypher), Neptune (Gremlin), TigerGraph (GSQL) are fundamentally different query languages and data models.
• Avoidance: Evaluate client library portability upfront.

2. “We can switch databases later”

• Reality: Query language lock-in is real. Cypher → Gremlin migration = months of rewriting.
• Avoidance: Choose based on 5-year horizon, not 6-month prototype needs.

3. “Graph databases are slow for everything”

• Reality: 10-100x faster for multi-hop traversals, but slower for simple key-value lookups than Redis.
• Avoidance: Use graph DBs for graph queries, not as a general-purpose database.

4. “OGMs always improve productivity”

• Reality: OGMs excel for CRUD, but complex traversals often need raw Cypher/Gremlin for control.
• Avoidance: Start with raw driver, add OGM selectively for CRUD-heavy patterns.

5. “Gremlin works everywhere”

• Reality: Gremlin is TinkerPop-family only (Neptune, Cosmos, JanusGraph). Neo4j and TigerGraph do NOT support Gremlin.
• Avoidance: Verify database compatibility before committing to Gremlin.

Success Metrics (Realistic Expectations)#

Performance:

• 3-hop queries: 50-100ms (vs 500-2000ms in SQL with JOINs)
• 5-hop queries: 200-500ms (vs timeouts in SQL)

Development Velocity:

• Feature delivery for relationship-heavy features: 30-50% faster (once team is trained)
• Query writing: Initially slower (learning curve), then faster (more expressive language)

Operational:

• Managed service uptime: 99.9%+ (AuraDB, Neptune SLAs)
• Self-hosted: Depends on team expertise (expect 2-4 weeks to stabilize production setup)

Common Misconceptions#

“Graph databases replace all databases”#

Reality: Graph DBs are specialized tools. Use them for relationship-heavy queries, not for simple CRUD, time-series, or full-text search. Most production systems use graph DBs alongside PostgreSQL, Redis, and Elasticsearch.

“GQL will solve all portability issues”#

Reality: ISO GQL standard (2024) is a major step forward, but:

• Full vendor adoption: 2026-2028 expected
• Gremlin is a separate family (no GQL convergence planned)
• Legacy codebases won’t auto-migrate

“Self-hosting is always cheaper”#

Reality: Managed services ($65-2K/month) often cheaper than:

• DevOps salary ($120K+/year)
• Downtime costs (hours of engineer time debugging crashes)
• Backup/DR infrastructure

Calculate total cost of ownership, not just license fees.

Decision Framework for Stakeholders#

Primary Recommendation: Neo4j + Cypher#

Choose neo4j (official driver) when:

• Starting a new graph database project
• Developer experience and time-to-market matter
• GraphRAG or knowledge graph use case (best LLM integration)
• Betting on GQL standardization (Cypher converging to ISO GQL)

Risk: Medium lock-in (acceptable for velocity gains, GQL migration path exists)

Alternative: TinkerPop + Gremlin#

Choose gremlinpython when:

• Multi-cloud or multi-database strategy required (Neptune + Cosmos DB flexibility)
• Vendor-neutral governance important (Apache Foundation)
• Portability outweighs developer convenience

Risk: Low lock-in, higher learning curve

Niche: TigerGraph + GSQL#

Choose pyTigerGraph when:

• Deep graph analytics (10+ hop traversals, complex algorithms) required
• Existing TigerGraph investment
• Performance justifies severe lock-in (portability: 2/10)

Risk: High lock-in, small hiring pool

Questions to Ask Before Committing#

1. What’s our relationship depth? (1-2 hops → maybe Postgres, 3+ hops → graph DB)
2. Do we need multi-database portability? (Yes → Gremlin, No → Cypher)
3. What’s our scale projection? (<10M edges → any, >1B edges → TigerGraph/Neptune)
4. Is semantic reasoning required? (Yes → RDF/rdflib, No → property graph)
5. What’s our cloud commitment? (AWS → Neptune, Azure → Cosmos, Multi-cloud → self-hosted or Neo4j)

Emerging Trends to Monitor (2025-2030)#

GQL Standardization (ISO/IEC 39075:2024)#

• Published April 2024, Cypher converging to compliance
• By 2028, expect broad vendor adoption (reduced lock-in)
• Migration path: Cypher users have smooth transition, Gremlin separate family

GraphRAG (Graph + LLMs)#

• Microsoft open-sourced GraphRAG (July 2024)
• Knowledge graphs as LLM context (retrieval-augmented generation)
• Neo4j leading integration (vector + graph hybrid)
• Implication: Graph DB clients need vector embedding support (table stakes by 2026)

PostgreSQL AGE (Apache Graph Extension)#

• Cypher queries in PostgreSQL (Apache incubator project)
• “Good enough” graph for many use cases
• Implication: Lowers barrier to entry, may slow pure graph DB adoption for simple use cases

Multi-Model Convergence#

• ArangoDB (graph + document + key-value in one database)
• DuckDB adding graph capabilities
• Implication: Graph becomes a feature, not a separate database (reduces operational complexity)

Date compiled: February 5, 2026 Research ID: 1.011

S1 Rapid Discovery: Graph Database Python Clients#

Research Methodology#

Scope Definition#

This discovery focuses on client libraries for interacting with graph databases from Python, NOT the graph databases themselves. The goal is to evaluate developer experience, community health, and production readiness of each library.

Discovery Process#

1. Initial Library Identification

   • Categorize by database: Neo4j, ArangoDB, TigerGraph, Amazon Neptune, Dgraph
   • Identify multi-database solutions: Apache TinkerPop (Gremlin), RDFLib
   • Note official vs community-maintained libraries

2. Metrics Collection For each library, we gather:

   • GitHub metrics: stars, forks, contributors, open issues, last commit date
   • PyPI metrics: weekly downloads, latest version, Python version support
   • Maintenance signals: release frequency, issue response time
   • Documentation quality: quick scan of docs completeness

3. First Impression Evaluation

   • Installation simplicity: pip install <package> should work cleanly
   • Quickstart availability: can a developer be productive in 10 minutes?
   • API design: does it feel Pythonic?

Libraries Evaluated#

Evaluation Criteria#

Tier 1 - Production Ready

• 500k+ weekly downloads
• Active maintenance (commits within 30 days)
• Official/vendor support
• Comprehensive documentation

Tier 2 - Mature Community

• 50k-500k weekly downloads
• Regular releases (quarterly or better)
• Good documentation
• Active issue resolution

Tier 3 - Emerging/Niche

• <50k weekly downloads
• May have gaps in documentation
• Smaller community
• Specialized use cases

Tier 4 - Caution Advised

• Stale/EOL projects
• No recent releases
• Deprecated in favor of alternatives

Data Sources#

• PyPI: https://pypi.org/ (version, dependencies, downloads)
• PyPI Stats: https://pypistats.org/ (download statistics)
• GitHub: Repository metrics and activity
• Snyk Advisor: Package health analysis
• Official documentation sites

Key Findings Summary#

See individual library files and recommendation.md for detailed analysis. The most widely adopted libraries are gremlinpython (5.7M weekly downloads), rdflib (1.4M), neo4j driver (520K), and python-arango (350K-1.2M).

gremlinpython - Apache TinkerPop Gremlin for Python#

Quick Facts#

Installation#

pip install gremlinpython

First Impression#

Strengths:

• Universal graph query language (Gremlin)
• Works with multiple databases: Neptune, JanusGraph, CosmosDB, etc.
• Most downloaded graph Python library
• Apache Foundation backing
• Stable, mature codebase

Considerations:

• Gremlin syntax differs from Cypher
• Generic API may lack database-specific optimizations
• TinkerPop 4.0 brings breaking changes (HTTP replacing WebSockets)

Compatible Databases#

• Amazon Neptune
• JanusGraph
• Azure Cosmos DB (Gremlin API)
• DataStax Enterprise Graph
• IBM Compose for JanusGraph
• OrientDB
• TigerGraph (limited)

Quick Example#

from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
from gremlin_python.structure.graph import Graph

# Connect to Gremlin server
graph = Graph()
conn = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g')
g = graph.traversal().withRemote(conn)

# Traverse the graph
people = g.V().hasLabel('person').values('name').toList()
print(people)

# Find friends of Alice
friends = g.V().has('person', 'name', 'Alice').out('knows').values('name').toList()
print(friends)

conn.close()

Amazon Neptune Usage#

from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection

# With neptune-python-utils for IAM auth
from neptune_python_utils.gremlin_utils import GremlinUtils

gremlin_utils = GremlinUtils()
conn = gremlin_utils.remote_connection()
g = gremlin_utils.traversal_source(connection=conn)

Assessment#

Tier: 1 - Production Ready

gremlinpython is the standard for Gremlin-based graph traversal. Its massive adoption (5.7M downloads/week) reflects use in AWS Neptune and other cloud graph services. Essential for multi-database portability or when using Gremlin-compatible databases.

Links#

• PyPI: https://pypi.org/project/gremlinpython/
• GitHub: https://github.com/apache/tinkerpop/tree/master/gremlin-python
• Docs: https://tinkerpop.apache.org/docs/current/reference/#gremlin-python
• Neptune Utils: https://github.com/awslabs/amazon-neptune-tools

neo4j - Official Neo4j Python Driver#

Quick Facts#

Installation#

pip install neo4j

# With optional Rust extension for 10x performance
pip install neo4j-rust-ext

# With pandas/numpy integration
pip install neo4j[numpy,pandas,pyarrow]

First Impression#

Strengths:

• Official vendor support with dedicated team
• Production-stable with semantic versioning
• Async support built-in
• Rust extensions available for performance-critical workloads
• Excellent documentation and examples
• Type hints throughout

Considerations:

• Python 3.10+ required (no legacy support)
• Deprecated neo4j-driver package still in PyPI (causes confusion)

Quick Example#

from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))

with driver.session() as session:
    result = session.run("MATCH (n:Person) RETURN n.name LIMIT 10")
    for record in result:
        print(record["n.name"])

driver.close()

Assessment#

Tier: 1 - Production Ready

The official Neo4j driver is the clear choice for Neo4j integration. It has strong community adoption, official support, excellent documentation, and modern Python features. The Rust extension option makes it suitable for high-throughput workloads.

Links#

• PyPI: https://pypi.org/project/neo4j/
• GitHub: https://github.com/neo4j/neo4j-python-driver
• Docs: https://neo4j.com/docs/python-manual/current/

neomodel - Python OGM for Neo4j#

Quick Facts#

Installation#

pip install neomodel

# With Rust driver extension for performance
pip install neomodel[rust-driver-ext]

# With optional dependencies (Shapely, pandas, numpy)
pip install neomodel[extras,rust-driver-ext]

First Impression#

Strengths:

• Django-style model definitions (familiar pattern)
• Schema enforcement with cardinality restrictions
• Full transaction and async support
• Neo4j Labs project (good maintenance quality)
• Django integration via django-neomodel plugin
• Vector and full-text search support (v6.0+)

Considerations:

• Abstracts away Cypher (less control for complex queries)
• Learning curve for graph-specific concepts
• Performance overhead vs raw driver

Quick Example#

from neomodel import StructuredNode, StringProperty, RelationshipTo

class Person(StructuredNode):
    name = StringProperty(required=True)
    friends = RelationshipTo('Person', 'FRIEND')

# Create and relate nodes
alice = Person(name="Alice").save()
bob = Person(name="Bob").save()
alice.friends.connect(bob)

# Query
for friend in alice.friends.all():
    print(friend.name)

Assessment#

Tier: 2 - Mature Community

neomodel is the recommended OGM for Neo4j, especially for developers coming from Django/SQLAlchemy backgrounds. It provides a Pythonic abstraction over the graph while still allowing raw Cypher when needed. Good choice for rapid development.

Links#

• PyPI: https://pypi.org/project/neomodel/
• GitHub: https://github.com/neo4j-contrib/neomodel
• Docs: https://neomodel.readthedocs.io/
• Neo4j Labs: https://neo4j.com/labs/neomodel/

py2neo - End of Life (EOL)#

Quick Facts#

Status Warning#

py2neo has been officially declared End of Life as of April 2025.

The project is no longer maintained and will receive no further updates. The GitHub repository has moved to neo4j-contrib/py2neo but is effectively archived.

Migration Path#

Neo4j recommends migrating to:

1. neo4j - Official Python driver for direct Cypher queries
2. neomodel - For ORM-style object-graph mapping

Why py2neo Was Popular#

Historically, py2neo offered:

• Higher-level API than the raw driver
• Built-in OGM (Object-Graph Mapper)
• HTTP and Bolt protocol support
• Cypher lexer for Pygments
• Command-line tools

Migration Example#

Old (py2neo):

from py2neo import Graph
graph = Graph("bolt://localhost:7687", auth=("neo4j", "password"))
graph.run("MATCH (n) RETURN n LIMIT 10")

New (neo4j driver):

from neo4j import GraphDatabase
driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))
with driver.session() as session:
    session.run("MATCH (n) RETURN n LIMIT 10")

Assessment#

Tier: 4 - Do Not Use

Do not start new projects with py2neo. For existing codebases, plan migration to the official neo4j driver or neomodel. Historical releases remain available on PyPI for legacy compatibility.

Links#

• PyPI (historical): https://pypi.org/project/py2neo/
• GitHub (archived): https://github.com/neo4j-contrib/py2neo
• Migration Guide: https://neo4j.com/blog/developer/py2neo-end-migration-guide/

pydgraph - Official Dgraph Python Client#

Quick Facts#

Installation#

pip install pydgraph

First Impression#

Strengths:

• Official client with gRPC protocol
• Good Python version support (3.7+)
• Clean, simple API
• Connection string support for clusters
• ACL (Access Control List) authentication

Considerations:

• Smaller ecosystem compared to Neo4j
• Dgraph uses GraphQL-like DQL, learning curve
• gRPC dependency can cause build issues on older systems

Quick Example#

import pydgraph

# Create client
client_stub = pydgraph.DgraphClientStub('localhost:9080')
client = pydgraph.DgraphClient(client_stub)

# Set schema
schema = """
name: string @index(exact) .
friends: [uid] .
type Person {
    name
    friends
}
"""
op = pydgraph.Operation(schema=schema)
client.alter(op)

# Create data
txn = client.txn()
try:
    mutation = pydgraph.Mutation(set_nquads='_:alice <name> "Alice" .')
    txn.mutate(mutation)
    txn.commit()
finally:
    txn.discard()

# Query
query = """
{
  people(func: has(name)) {
    name
    friends { name }
  }
}
"""
res = client.txn(read_only=True).query(query)
print(res.json)

client_stub.close()

Connection String Format#

# Standard connection
client_stub = pydgraph.DgraphClientStub("localhost:9080")

# With authentication
client_stub = pydgraph.DgraphClientStub("dgraph://username:password@host:9080")

Assessment#

Tier: 3 - Emerging/Niche

pydgraph is the correct choice for Dgraph integration. While the community is smaller than Neo4j, the library is well-maintained with zero open issues. Suitable for applications needing Dgraph’s distributed graph capabilities and native GraphQL-like query language.

Links#

• PyPI: https://pypi.org/project/pydgraph/
• GitHub: https://github.com/dgraph-io/pydgraph
• Dgraph Docs: https://dgraph.io/docs/

python-arango - Official ArangoDB Python Driver#

Quick Facts#

Installation#

pip install python-arango

# For async support
pip install python-arango-async

First Impression#

Strengths:

• Official vendor support
• Excellent maintenance (zero open issues)
• Clean, Pythonic API
• Comprehensive AQL query support
• Graph traversal, document, and key-value operations
• Async alternative available

Considerations:

• ArangoDB-specific (multi-model but single vendor)
• Smaller community than Neo4j ecosystem

Quick Example#

from arango import ArangoClient

client = ArangoClient(hosts="http://localhost:8529")
db = client.db("mydb", username="root", password="password")

# Create a graph
graph = db.create_graph("social")
people = graph.create_vertex_collection("people")
friends = graph.create_edge_definition(
    edge_collection="friends",
    from_vertex_collections=["people"],
    to_vertex_collections=["people"]
)

# Insert vertices and edges
alice = people.insert({"_key": "alice", "name": "Alice"})
bob = people.insert({"_key": "bob", "name": "Bob"})
friends.insert({"_from": "people/alice", "_to": "people/bob"})

# AQL query
cursor = db.aql.execute("FOR p IN people RETURN p.name")
print([doc for doc in cursor])

Assessment#

Tier: 1 - Production Ready

python-arango is an excellent choice for ArangoDB integration. The library is well-maintained with official support, zero open issues, and comprehensive coverage of ArangoDB features. Particularly strong for applications needing multi-model (document + graph + key-value) capabilities.

Links#

• PyPI: https://pypi.org/project/python-arango/
• GitHub: https://github.com/arangodb/python-arango
• Docs: https://docs.python-arango.com/
• Async: https://github.com/arangodb/python-arango-async

pyTigerGraph - TigerGraph Python Client#

Quick Facts#

Installation#

# Core functionality
pip install pyTigerGraph

# With Graph Data Science / ML capabilities
pip install pyTigerGraph[gds]

First Impression#

Strengths:

• Official vendor support
• Graph machine learning integration
• Async support (v1.8+)
• DataFrame loading from Pandas
• Good for analytics and ML workloads

Considerations:

• Smaller community (niche database)
• Less documentation compared to Neo4j/ArangoDB
• TigerGraph-specific GSQL language

Quick Example#

import pyTigerGraph as tg

conn = tg.TigerGraphConnection(
    host="https://your-instance.i.tgcloud.io",
    graphname="MyGraph",
    username="tigergraph",
    password="password"
)

# Get auth token
conn.getToken(conn.createSecret())

# Run a query
results = conn.runInstalledQuery("find_friends", params={"person": "Alice"})

# Upsert vertices
conn.upsertVertices("Person", [
    {"id": "alice", "name": "Alice"},
    {"id": "bob", "name": "Bob"}
])

Graph Data Science Features#

# With pyTigerGraph[gds]
from pyTigerGraph.gds import featurizer

# Create graph features for ML
feat = conn.gds.featurizer()
feat.installAlgorithm("pagerank")
feat.runAlgorithm("pagerank", params={"v_type": "Person"})

Assessment#

Tier: 3 - Emerging/Niche

pyTigerGraph is the right choice when using TigerGraph, especially for graph analytics and machine learning use cases. The library has official support but a smaller community. Best suited for enterprise analytics workloads where TigerGraph’s performance advantages justify the ecosystem trade-offs.

Links#

• PyPI: https://pypi.org/project/pyTigerGraph/
• GitHub: https://github.com/tigergraph/pyTigerGraph
• Docs: https://docs.tigergraph.com/pytigergraph/current/intro/

rdflib - Python Library for RDF#

Quick Facts#

Installation#

pip install rdflib

First Impression#

Strengths:

• Dominant library for RDF/semantic web in Python
• Comprehensive format support (RDF/XML, Turtle, JSON-LD, N-Quads, etc.)
• Full SPARQL 1.1 implementation
• Mature, well-documented
• Large ecosystem of extensions

Considerations:

• Focus on RDF graphs (different paradigm from property graphs)
• Not designed for high-performance graph traversal
• Steeper learning curve for developers new to semantic web

Quick Example#

from rdflib import Graph, Literal, RDF, URIRef, Namespace

# Create a graph
g = Graph()

# Define namespace
FOAF = Namespace("http://xmlns.com/foaf/0.1/")
g.bind("foaf", FOAF)

# Add triples
alice = URIRef("http://example.org/alice")
g.add((alice, RDF.type, FOAF.Person))
g.add((alice, FOAF.name, Literal("Alice")))
g.add((alice, FOAF.knows, URIRef("http://example.org/bob")))

# SPARQL query
results = g.query("""
    SELECT ?name WHERE {
        ?person foaf:name ?name .
    }
""")
for row in results:
    print(row.name)

# Serialize
print(g.serialize(format="turtle"))

RDF vs Property Graphs#

Assessment#

Tier: 1 - Production Ready

rdflib is the standard for RDF processing in Python. Essential for semantic web applications, knowledge graphs with linked data, and SPARQL-based querying. Different use case than property graph databases but equally mature.

Links#

• PyPI: https://pypi.org/project/rdflib/
• GitHub: https://github.com/RDFLib/rdflib
• Docs: https://rdflib.readthedocs.io/
• Website: https://rdflib.dev/

Graph Database Python Clients: Recommendations#

Quick Assessment Summary#

Tier Rankings#

Top Picks by Use Case#

For Neo4j Integration#

Primary: neo4j (official driver)

• Best for: Direct Cypher queries, maximum control, performance
• Install: pip install neo4j

Alternative: neomodel (OGM)

• Best for: Django-style model definitions, rapid development
• Install: pip install neomodel

For Multi-Database Portability#

Primary: gremlinpython

• Best for: Neptune, JanusGraph, CosmosDB, any Gremlin-compatible DB
• Install: pip install gremlinpython

For ArangoDB#

Primary: python-arango

• Best for: Multi-model (document + graph + key-value) applications
• Install: pip install python-arango

For Semantic Web / Knowledge Graphs#

Primary: rdflib

• Best for: RDF processing, SPARQL queries, linked data
• Install: pip install rdflib

For Graph Analytics / ML#

Primary: pyTigerGraph[gds]

• Best for: Large-scale graph analytics, ML on graphs
• Install: pip install pyTigerGraph[gds]

Decision Matrix#

Libraries to Avoid#

1. py2neo - Officially EOL (April 2025), migrate to neo4j/neomodel
2. pyorient - Last release 2017, OrientDB has limited Python support
3. neo4j-driver - Deprecated package name, use neo4j instead

Key Insights#

1. gremlinpython dominates downloads due to AWS Neptune and cloud adoption
2. Neo4j ecosystem is strongest with official driver + OGM options
3. ArangoDB has excellent official support with zero open issues
4. RDFLib serves a distinct use case (semantic web vs property graphs)
5. TigerGraph and Dgraph are niche but officially supported

Next Steps for Deeper Evaluation#

1. Test connection setup with actual database instances
2. Benchmark query performance for representative workloads
3. Evaluate async support for concurrent applications
4. Review error handling and retry mechanisms
5. Assess integration with web frameworks (FastAPI, Django)

Data Sources#

• PyPI: Package metadata and downloads
• PyPI Stats: https://pypistats.org/
• GitHub: Repository metrics
• Snyk Advisor: Package health analysis
• Official documentation for each library

Research conducted: December 2025

S2 Comprehensive Discovery: Graph Database Python Client Libraries#

Overview#

This document outlines the methodology for evaluating Python client libraries for graph databases. The analysis covers official drivers, community libraries, and Object-Graph Mappers (OGMs) across multiple graph database platforms.

Scope#

Libraries Evaluated#

Evaluation Criteria#

1. API Design and Ergonomics#

• Pythonic Design: Adherence to Python idioms (PEP 8, context managers, generators)
• Type Hints: MyPy compatibility and IDE support
• Documentation Quality: Official docs, examples, and community resources
• Learning Curve: Time to productivity for developers

2. Performance Characteristics#

• Connection Pooling: Configuration options and efficiency
• Bulk Operations: Batch insert/update capabilities
• Serialization: Data format handling (JSON, Binary, custom)
• Rust Extensions: Native code acceleration options

3. Async Support#

• Native asyncio: Built-in async/await support
• Framework Integration: FastAPI, aiohttp, Starlette compatibility
• Concurrent Transactions: Parallel query execution

4. Transaction and Consistency#

• ACID Support: Transaction isolation levels
• Retry Logic: Automatic retry on transient failures
• Causal Consistency: Bookmark/session management
• Read/Write Splitting: Routing to appropriate cluster nodes

5. Query Language Support#

6. Schema and Migration#

• Schema Definition: Programmatic vs. declarative
• Constraint Management: Unique, existence, type constraints
• Index Management: Creation, deletion, optimization
• Migration Tooling: Version control for schema changes

7. Testing and Development#

• Mocking Support: Test doubles and fixtures
• Embedded Mode: In-process database for testing
• CI/CD Integration: Docker, testcontainers compatibility

Data Sources#

Primary Sources#

1. Official Documentation: Driver manuals and API references
2. GitHub Repositories: Source code, issues, release notes
3. PyPI: Package metadata, version history, dependencies

Secondary Sources#

1. Community Forums: Stack Overflow, database-specific communities
2. Performance Benchmarks: Published comparisons and metrics
3. Migration Guides: Version upgrade documentation

Analysis Deliverables#

1. Per-Library Deep Dives: 100-200 lines covering features, patterns, and limitations
2. Feature Matrix: Side-by-side comparison across all criteria
3. Recommendations: Use-case based guidance with justifications

Versioning Context#

All analysis conducted against library versions current as of December 2024:

• neo4j-driver: 6.0.x
• neomodel: 6.0.x
• python-arango: 8.2.x
• pyTigerGraph: 1.6.x
• gremlinpython: 3.7.x
• pydgraph: 24.x / 25.x
• rdflib: 7.2.x

Graph Database Python Client Libraries: Feature Matrix#

Overview#

This matrix compares Python client libraries for graph databases across key functional and technical criteria. Libraries are evaluated as of December 2024.

Quick Reference#

Async Support#

Connection Management#

Transaction Support#

Query Language Features#

OGM/ORM Capabilities#

Type System#

Performance Features#

Error Handling#

Testing Support#

Documentation and Community#

Python Version Support#

Database Version Support#

Installation Size#

Summary Scores (1-5)#

Scores based on: API ergonomics, Python idiom adherence, documentation quality, maintenance activity, and production readiness.

gremlinpython - Apache TinkerPop Gremlin Client#

Overview#

gremlinpython is the official Python language variant (GLV) for Apache TinkerPop’s Gremlin graph traversal language. It provides a consistent API for interacting with any TinkerPop-enabled graph database, offering database portability through a standardized query language.

Key Information#

Supported Databases#

gremlinpython works with any TinkerPop-compliant database:

• Amazon Neptune
• Azure Cosmos DB (Gremlin API)
• JanusGraph
• OrientDB
• Neo4j (with TinkerPop plugin)
• TigerGraph (with TinkerPop connector)
• DataStax Graph

Installation#

pip install gremlinpython

Connection Management#

Basic Connection#

from gremlin_python.process.anonymous_traversal import traversal
from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection

# Create traversal source
g = traversal().with_remote(
    DriverRemoteConnection('ws://localhost:8182/gremlin', 'g')
)

# With authentication
g = traversal().with_remote(
    DriverRemoteConnection(
        'wss://your-endpoint:8182/gremlin',
        'g',
        username='user',
        password='password'
    )
)

Connection Options#

from gremlin_python.driver.client import Client

# Lower-level client access
client = Client(
    'ws://localhost:8182/gremlin',
    'g',
    pool_size=8,           # Connection pool size
    max_workers=4,         # Thread pool workers
    message_serializer=None # Custom serializer
)

# Submit raw Gremlin
result = client.submit("g.V().count()")
for r in result:
    print(r)

Traversal Basics#

Creating Vertices#

# Add vertex
g.addV('person').property('name', 'Alice').property('age', 30).next()

# Add with ID
g.addV('person').property(T.id, 'alice').property('name', 'Alice').next()

Creating Edges#

# Add edge between vertices
g.V().has('person', 'name', 'Alice').as_('a') \
     .V().has('person', 'name', 'Bob').as_('b') \
     .addE('knows').from_('a').to('b').property('since', 2020).next()

Reading Data#

# Get all vertices of type
people = g.V().hasLabel('person').toList()

# Get specific vertex
alice = g.V().has('person', 'name', 'Alice').next()

# Get vertex properties
props = g.V().has('person', 'name', 'Alice').valueMap().next()

Updating Data#

# Update property
g.V().has('person', 'name', 'Alice') \
     .property('age', 31).next()

# Add multiple properties
g.V().has('person', 'name', 'Alice') \
     .property('email', '[email protected]') \
     .property('city', 'NYC').next()

Deleting Data#

# Delete vertex (and connected edges)
g.V().has('person', 'name', 'Alice').drop().iterate()

# Delete edge
g.E().hasLabel('knows').drop().iterate()

Traversal Patterns#

Filtering#

# Has filters
g.V().has('person', 'age', P.gt(25)).toList()
g.V().has('person', 'name', P.within('Alice', 'Bob')).toList()

# Multiple conditions
g.V().hasLabel('person') \
     .has('age', P.gte(18)) \
     .has('age', P.lt(65)).toList()

# Not filter
g.V().hasLabel('person').not_(__.has('retired', True)).toList()

Traversing Relationships#

# Outgoing edges
friends = g.V().has('person', 'name', 'Alice').out('knows').toList()

# Incoming edges
followers = g.V().has('person', 'name', 'Alice').in_('follows').toList()

# Both directions
connections = g.V().has('person', 'name', 'Alice').both('knows').toList()

# Multiple hops
friends_of_friends = g.V().has('person', 'name', 'Alice') \
                          .out('knows').out('knows') \
                          .dedup().toList()

Path Queries#

# Get paths
paths = g.V().has('person', 'name', 'Alice') \
             .repeat(__.out('knows')).times(2) \
             .path().by('name').toList()

# Shortest path
path = g.V().has('person', 'name', 'Alice') \
            .repeat(__.out().simplePath()) \
            .until(__.has('person', 'name', 'Charlie')) \
            .path().limit(1).next()

Aggregation#

# Count
count = g.V().hasLabel('person').count().next()

# Group by
by_age = g.V().hasLabel('person') \
              .group().by('age').by(__.count()).next()

# Statistics
stats = g.V().hasLabel('person') \
             .values('age').fold() \
             .project('min', 'max', 'avg', 'count') \
             .by(__.min()) \
             .by(__.max()) \
             .by(__.mean()) \
             .by(__.count()).next()

Serialization#

GraphBinary (Recommended)#

from gremlin_python.driver.serializer import GraphBinarySerializersV1

g = traversal().with_remote(
    DriverRemoteConnection(
        'ws://localhost:8182/gremlin',
        'g',
        message_serializer=GraphBinarySerializersV1()
    )
)

GraphSON#

from gremlin_python.driver.serializer import GraphSONSerializersV3d0

g = traversal().with_remote(
    DriverRemoteConnection(
        'ws://localhost:8182/gremlin',
        'g',
        message_serializer=GraphSONSerializersV3d0()
    )
)

Transaction Support#

# Begin transaction
tx = g.tx()

# Get transaction-bound traversal
gtx = tx.begin()

try:
    gtx.addV('person').property('name', 'Alice').next()
    gtx.addV('person').property('name', 'Bob').next()
    tx.commit()
except:
    tx.rollback()
    raise

Async Alternatives#

gremlinpython itself is synchronous. For async support, consider:

aiogremlin#

from aiogremlin import Cluster, Graph

cluster = await Cluster.open(hosts=['localhost'])
client = await cluster.connect()
g = Graph().traversal().withRemote(client)

# Async operations
result = await g.V().toList()

Goblin OGM#

from goblin import Goblin, Vertex, String

class Person(Vertex):
    name = String()

app = await Goblin.open(hosts=['localhost'])
session = await app.session()

person = Person(name='Alice')
session.add(person)
await session.flush()

gremlinpy (FastAPI compatible)#

from gremlinpy import Graph

g = Graph().traversal()
# Compatible with existing event loops

Traversal Strategies#

from gremlin_python.process.strategies import *

# Read-only strategy
g = g.withStrategies(ReadOnlyStrategy())

# Subgraph strategy (filter)
g = g.withStrategies(SubgraphStrategy(
    vertices=__.hasLabel('person'),
    edges=__.hasLabel('knows')
))

# Partition strategy
g = g.withStrategies(PartitionStrategy(
    partitionKey='region',
    writePartition='us-west'
))

Error Handling#

from gremlin_python.driver.protocol import GremlinServerError

try:
    result = g.V().has('invalid').next()
except GremlinServerError as e:
    print(f"Server error: {e}")
except StopIteration:
    print("No results found")

Connection Pooling Issues#

Known limitation (TINKERPOP-3114):

“Once a connection error occurred, pooled connections are broken and will not be recovered.”

Workaround:

# Implement connection health checks
def get_connection():
    try:
        g.V().limit(1).next()
        return g
    except:
        # Reconnect
        return create_new_connection()

Limitations#

• No native Python asyncio (use aiogremlin/goblin)
• Connection pool recovery issues
• WebSocket-only protocol
• Remote execution only (no embedded mode)
• Reference-only objects from server (no full properties)
• Significant memory overhead for large result sets

When to Use#

Choose gremlinpython when:

• Database portability is important
• Working with TinkerPop-compatible databases
• Standard graph query language preferred
• Amazon Neptune or Azure Cosmos DB target

Consider alternatives when:

• Native async required (use aiogremlin/goblin)
• Database-specific features needed
• Maximum performance critical
• OGM patterns preferred (use goblin)

Resources#

• TinkerPop Documentation
• Practical Gremlin Book
• PyPI Package
• Apache TinkerPop
• Goblin OGM
• aiogremlin

Neo4j Python Driver (neo4j)#

Overview#

The official Neo4j Python driver provides low-level, high-performance access to Neo4j databases using the Bolt protocol. Maintained by Neo4j Inc., it serves as the foundation for higher-level libraries like neomodel.

Key Information#

Installation#

pip install neo4j

# With optional Rust extensions for performance
pip install neo4j-rust-ext

Core Features#

Connection Management#

from neo4j import GraphDatabase

# Basic connection
driver = GraphDatabase.driver(
    "neo4j://localhost:7687",
    auth=("neo4j", "password")
)

# With context manager (recommended)
with GraphDatabase.driver(uri, auth=auth) as driver:
    driver.verify_connectivity()
    # Use driver...

Query Execution#

# Simple query execution (v5.0+)
records, summary, keys = driver.execute_query(
    "MATCH (p:Person {name: $name}) RETURN p",
    name="Alice",
    database_="neo4j"
)

# With routing control
from neo4j import RoutingControl

records, summary, keys = driver.execute_query(
    "MATCH (p:Person) RETURN p",
    routing_=RoutingControl.READ
)

Session-Based Transactions#

with driver.session(database="neo4j") as session:
    # Managed transaction (recommended - auto-retry)
    result = session.execute_read(
        lambda tx: tx.run("MATCH (p:Person) RETURN p").data()
    )

    # Write transaction
    session.execute_write(
        lambda tx: tx.run(
            "CREATE (p:Person {name: $name})",
            name="Bob"
        )
    )

Async Support#

Full async/await support mirrors the synchronous API:

from neo4j import AsyncGraphDatabase

async def main():
    async with AsyncGraphDatabase.driver(uri, auth=auth) as driver:
        async with driver.session() as session:
            result = await session.execute_read(
                lambda tx: tx.run("MATCH (n) RETURN n").data()
            )

Async Features#

• AsyncDriver, AsyncSession, AsyncTransaction
• AsyncResult with async iteration
• Compatible with asyncio, FastAPI, aiohttp
• Shares non-I/O components with sync implementation

Connection Pooling#

Configuration Options#

driver = GraphDatabase.driver(
    uri, auth=auth,
    max_connection_pool_size=100,        # Max connections per host
    connection_acquisition_timeout=60,    # Seconds to wait for connection
    connection_timeout=30,                # TCP connection timeout
    max_connection_lifetime=3600,         # Max age of pooled connection
    liveness_check_timeout=60             # Idle check threshold
)

Best Practices#

• Create one driver instance per application
• Driver objects are expensive to create (connection pool setup)
• Sessions are lightweight - create/close as needed
• Use context managers for automatic resource cleanup

Transaction Support#

Transaction Types#

1. Auto-commit: Single statement, no retry

   session.run("CREATE (n:Node)")

2. Managed Transactions: Recommended - includes retry logic

   session.execute_read(work_function)
   session.execute_write(work_function)

3. Explicit Transactions: Manual control

   tx = session.begin_transaction()
   try:
       tx.run(query)
       tx.commit()
   except:
       tx.rollback()

Causal Consistency#

# Bookmark management for causal chains
with driver.session(bookmarks=[bookmark]) as session:
    session.execute_write(work)
    new_bookmark = session.last_bookmark()

Error Handling#

from neo4j.exceptions import (
    ServiceUnavailable,
    TransientError,
    ClientError,
    DatabaseError
)

try:
    driver.execute_query(query)
except ServiceUnavailable:
    # Connection/cluster issues
except TransientError:
    # Retryable errors (deadlock, etc.)
except ClientError:
    # Query syntax, constraint violations

Type System#

Neo4j to Python Type Mapping#

Performance Optimization#

Rust Extensions#

pip install neo4j-rust-ext

• Drop-in replacement for default transport
• Significant performance improvement for I/O-heavy workloads
• No code changes required

Bulk Operations#

# Batch create with UNWIND
session.execute_write(lambda tx: tx.run(
    "UNWIND $batch AS row CREATE (n:Node {id: row.id, name: row.name})",
    batch=[{"id": 1, "name": "A"}, {"id": 2, "name": "B"}]
))

Testing#

# Use testcontainers for integration tests
from testcontainers.neo4j import Neo4jContainer

with Neo4jContainer() as neo4j:
    driver = GraphDatabase.driver(
        neo4j.get_connection_url(),
        auth=("neo4j", neo4j.NEO4J_ADMIN_PASSWORD)
    )

Limitations#

• No built-in ORM/OGM (use neomodel for that)
• Cypher-only (no Gremlin support)
• Manual schema management required
• No migration tooling included

When to Use#

Choose neo4j-driver when:

• Direct control over queries and transactions is needed
• Performance is critical (with Rust extensions)
• Building custom abstractions on top
• Async support is required

Consider alternatives when:

• OGM patterns would simplify development (use neomodel)
• Multi-database portability is needed (use gremlinpython)

Resources#

• Python Driver Manual
• API Documentation
• GitHub Repository

neomodel - Neo4j Object Graph Mapper#

Overview#

neomodel is a Python Object Graph Mapper (OGM) for Neo4j that provides Django-style model definitions for graph data. It allows developers to work with graph data using Pythonic patterns without writing raw Cypher queries.

Key Information#

Installation#

pip install neomodel

# With extras (includes Shapely for spatial data)
pip install neomodel[extras]

# With Rust driver extensions for performance
pip install neomodel[rust-driver-ext]

Configuration#

from neomodel import config

# Connection string
config.DATABASE_URL = 'bolt://neo4j:password@localhost:7687'

# Or using dataclass configuration (v6.0+)
from neomodel import NeomodelConfig

config = NeomodelConfig(
    driver_options={"max_connection_pool_size": 50},
    database="neo4j",
    auto_install_labels=True
)

Environment Variables#

NEO4J_BOLT_URL=bolt://neo4j:password@localhost:7687
NEO4J_DATABASE=neo4j

Model Definition#

Basic Node Definition#

from neomodel import (
    StructuredNode, StringProperty, IntegerProperty,
    UniqueIdProperty, RelationshipTo, RelationshipFrom
)

class Person(StructuredNode):
    uid = UniqueIdProperty()
    name = StringProperty(required=True)
    age = IntegerProperty(index=True)

    # Relationships
    friends = RelationshipTo('Person', 'FRIENDS_WITH')
    employer = RelationshipTo('Company', 'WORKS_AT')

Property Types#

from neomodel import (
    StringProperty,      # String values
    IntegerProperty,     # Integer values
    FloatProperty,       # Floating point
    BooleanProperty,     # Boolean
    DateProperty,        # datetime.date
    DateTimeProperty,    # datetime.datetime
    UniqueIdProperty,    # Auto-generated UUID
    ArrayProperty,       # Lists
    JSONProperty,        # JSON-serializable dicts
    PointProperty,       # Spatial data
)

Relationship Properties#

from neomodel import StructuredRel, DateTimeProperty

class WorkedAt(StructuredRel):
    start_date = DateTimeProperty()
    end_date = DateTimeProperty()
    role = StringProperty()

class Person(StructuredNode):
    name = StringProperty()
    employers = RelationshipTo('Company', 'WORKED_AT', model=WorkedAt)

CRUD Operations#

Create#

# Create single node
person = Person(name="Alice", age=30).save()

# Create with relationships
company = Company(name="Acme").save()
person.employer.connect(company)

Read#

# Get by property
alice = Person.nodes.get(name="Alice")

# Filter nodes
adults = Person.nodes.filter(age__gte=18)

# All nodes
all_people = Person.nodes.all()

# First match
first_person = Person.nodes.first()

Update#

person = Person.nodes.get(name="Alice")
person.age = 31
person.save()

Delete#

person = Person.nodes.get(name="Alice")
person.delete()

Query API#

Filtering#

# Comparison operators
Person.nodes.filter(age__gt=25)      # Greater than
Person.nodes.filter(age__gte=25)     # Greater or equal
Person.nodes.filter(age__lt=25)      # Less than
Person.nodes.filter(age__lte=25)     # Less or equal
Person.nodes.filter(name__ne="Bob")  # Not equal

# String operators
Person.nodes.filter(name__contains="ali")
Person.nodes.filter(name__startswith="A")
Person.nodes.filter(name__endswith="ce")
Person.nodes.filter(name__icontains="ALI")  # Case insensitive

# List operations
Person.nodes.filter(name__in=["Alice", "Bob"])

Traversal (v6.0+)#

# Advanced traversal with filtering and ordering
results = Person.nodes.filter(name="Alice").traverse(
    relation_type="FRIENDS_WITH",
    filter_expr={"age__gte": 18},
    order_by="age"
)

Raw Cypher#

from neomodel import db

results, meta = db.cypher_query(
    "MATCH (p:Person) WHERE p.age > $age RETURN p",
    {"age": 25}
)

Async Support#

from neomodel import adb, AsyncStructuredNode

class Person(AsyncStructuredNode):
    name = StringProperty()

async def main():
    # Async operations
    person = await Person(name="Alice").save()
    alice = await Person.nodes.get(name="Alice")
    await person.delete()

    # Async traversal
    friends = await alice.friends.all()

Async Configuration#

from neomodel import adb

await adb.set_connection("bolt://localhost:7687")

Schema Management#

Constraints and Indexes#

from neomodel import install_all_labels, install_labels

# Install all constraints and indexes
install_all_labels()

# Install for specific models
install_labels(Person)

Schema Definition#

class Person(StructuredNode):
    # Unique constraint
    email = StringProperty(unique_index=True)

    # Index only
    name = StringProperty(index=True)

    # Required (not null)
    created = DateTimeProperty(required=True)

Hooks#

class Person(StructuredNode):
    name = StringProperty()

    def pre_save(self):
        # Called before saving
        self.name = self.name.strip()

    def post_save(self):
        # Called after saving
        log.info(f"Saved {self.name}")

    def pre_delete(self):
        # Called before deletion
        pass

    def post_delete(self):
        # Called after deletion
        pass

Transaction Support#

from neomodel import db

# Context manager
with db.transaction:
    person = Person(name="Alice").save()
    company = Company(name="Acme").save()
    person.employer.connect(company)

# Explicit control
db.begin()
try:
    person = Person(name="Alice").save()
    db.commit()
except:
    db.rollback()
    raise

Django Integration#

# settings.py
NEOMODEL_NEO4J_BOLT_URL = 'bolt://neo4j:password@localhost:7687'

# models.py
from django_neomodel import DjangoNode
from neomodel import StringProperty

class Person(DjangoNode):
    name = StringProperty()

    class Meta:
        app_label = 'myapp'

Vector and Full-Text Search (v6.0+)#

from neomodel import VectorIndex, FullTextIndex

class Document(StructuredNode):
    content = StringProperty()
    embedding = ArrayProperty()

    # Vector index for semantic search
    __vector_index__ = VectorIndex(
        property_name='embedding',
        dimensions=384
    )

    # Full-text index
    __fulltext_index__ = FullTextIndex(
        property_names=['content']
    )

Performance Considerations#

Batch Operations#

# Use batch_save for bulk inserts
from neomodel import db

with db.transaction:
    for data in large_dataset:
        Person(name=data['name']).save()

Connection Pooling#

Inherited from neo4j-driver configuration - set via driver_options in config.

Limitations#

• Neo4j-specific (no multi-database portability)
• No automatic migration tooling (schema drift possible)
• OGM overhead vs. raw Cypher
• Complex traversals may require raw Cypher

When to Use#

Choose neomodel when:

• Django-like model patterns preferred
• Type safety and validation important
• Schema enforcement needed
• Working primarily with Neo4j

Consider alternatives when:

• Maximum performance required (use neo4j-driver)
• Multi-database support needed (use gremlinpython)
• Complex graph algorithms (use raw Cypher)

Resources#

• Documentation
• Neo4j Labs Page
• GitHub Repository
• Django Integration

py2neo (End of Life)#

Status: Archived#

IMPORTANT: py2neo is End of Life (EOL) as of 2023. No further updates will be released. Users should migrate to the official Neo4j Python driver.

The project has been transferred to Neo4j Inc. for archival purposes at neo4j-contrib/py2neo.

Overview#

py2neo was a comprehensive Neo4j client library and toolkit providing a high-level API, OGM capabilities, admin tools, and a Cypher lexer for Pygments. It supported both Bolt and HTTP protocols.

Key Information#

Historical Features#

Graph Object API#

from py2neo import Graph, Node, Relationship

# Connect to database
graph = Graph("bolt://localhost:7687", auth=("neo4j", "password"))

# Create nodes and relationships
alice = Node("Person", name="Alice")
bob = Node("Person", name="Bob")
knows = Relationship(alice, "KNOWS", bob)

# Merge to database
graph.merge(alice, "Person", "name")

OGM Capabilities#

from py2neo.ogm import GraphObject, Property, RelatedTo

class Person(GraphObject):
    __primarykey__ = "name"

    name = Property()
    born = Property()
    friends = RelatedTo("Person", "KNOWS")

# Usage
person = Person()
person.name = "Alice"
graph.push(person)

Cypher Execution#

# Direct Cypher queries
results = graph.run(
    "MATCH (p:Person {name: $name}) RETURN p",
    name="Alice"
)

for record in results:
    print(record["p"])

Batch Operations#

from py2neo import Graph

tx = graph.begin()
for i in range(1000):
    tx.create(Node("Item", id=i))
    if i % 100 == 0:
        tx.commit()
        tx = graph.begin()
tx.commit()

Migration Path#

Recommended Migration: neo4j-driver#

For low-level access, migrate to the official Neo4j Python driver:

# py2neo (old)
from py2neo import Graph
graph = Graph("bolt://localhost:7687", auth=("neo4j", "password"))
result = graph.run("MATCH (n) RETURN n")

# neo4j-driver (new)
from neo4j import GraphDatabase
driver = GraphDatabase.driver("neo4j://localhost:7687", auth=("neo4j", "password"))
with driver.session() as session:
    result = session.run("MATCH (n) RETURN n")

Recommended Migration: neomodel#

For OGM functionality, migrate to neomodel:

# py2neo OGM (old)
from py2neo.ogm import GraphObject, Property

class Person(GraphObject):
    name = Property()

# neomodel (new)
from neomodel import StructuredNode, StringProperty

class Person(StructuredNode):
    name = StringProperty()

Why py2neo Was Deprecated#

1. Maintenance Burden: Single maintainer model not sustainable
2. Official Driver Improvements: Neo4j’s official driver matured significantly
3. Community Fragmentation: Multiple overlapping libraries caused confusion
4. Compatibility Challenges: Keeping up with Neo4j versions became difficult

Historical Strengths#

• Clean, Pythonic API
• Built-in OGM functionality
• Cypher lexer for syntax highlighting
• HTTP fallback when Bolt unavailable
• Comprehensive documentation

Historical Limitations#

• Single maintainer created bus factor risk
• Calendar versioning led to breaking changes
• No async support
• Performance overhead vs. official driver
• Infrequent updates in later years

Lessons for Library Selection#

The py2neo deprecation offers lessons for evaluating graph database libraries:

1. Prefer Official Drivers: Better long-term support guarantees
2. Check Maintainer Count: Multiple maintainers reduce abandonment risk
3. Evaluate Release Frequency: Regular releases indicate active maintenance
4. Consider Corporate Backing: Libraries backed by database vendors more stable

Current Alternatives#

Resources (Archival)#

• Archived Handbook
• GitHub Archive
• PyPI (frozen)
• Migration Guide

pydgraph - Dgraph Python Client#

Overview#

pydgraph is the official Python client for Dgraph, a distributed, horizontally scalable graph database. It uses gRPC for high-performance communication and supports Dgraph’s GraphQL-like query language (DQL, formerly GraphQL+-).

Key Information#

Version Compatibility#

Installation#

pip install pydgraph

Connection Management#

Basic Connection#

import pydgraph

# Create client stub
stub = pydgraph.DgraphClientStub('localhost:9080')

# Create client
client = pydgraph.DgraphClient(stub)

# Close when done
stub.close()

Multiple Stubs (Cluster)#

# Connect to multiple cluster nodes
stub1 = pydgraph.DgraphClientStub('node1:9080')
stub2 = pydgraph.DgraphClientStub('node2:9080')
stub3 = pydgraph.DgraphClientStub('node3:9080')

client = pydgraph.DgraphClient(stub1, stub2, stub3)

Connection Strings#

# Using connection string
client = pydgraph.DgraphClient.from_cloud(
    "dgraph://user:pass@host:9080?tls=true"
)

# Dgraph Cloud
client = pydgraph.DgraphClient.from_cloud(
    "https://your-instance.cloud.dgraph.io/graphql",
    api_key="your-api-key"
)

TLS Configuration#

import grpc

# Load credentials
with open('ca.crt', 'rb') as f:
    ca_cert = f.read()

credentials = grpc.ssl_channel_credentials(ca_cert)

stub = pydgraph.DgraphClientStub(
    'localhost:9080',
    credentials=credentials
)

Schema Management#

Alter Schema#

schema = """
    name: string @index(exact) .
    age: int @index(int) .
    email: string @index(hash) @upsert .

    type Person {
        name
        age
        email
        friends
    }
"""

client.alter(pydgraph.Operation(schema=schema))

Drop Operations#

# Drop all data and schema
client.alter(pydgraph.Operation(drop_all=True))

# Drop specific predicate
client.alter(pydgraph.Operation(drop_attr='name'))

# Drop specific type
client.alter(pydgraph.Operation(drop_op=pydgraph.Operation.TYPE, drop_value='Person'))

Transaction Types#

Read-Write Transaction#

txn = client.txn()
try:
    # Mutations and queries
    response = txn.mutate(set_nquads='_:alice <name> "Alice" .')
    txn.commit()
finally:
    txn.discard()

Read-Only Transaction#

txn = client.txn(read_only=True)
try:
    response = txn.query(query_string)
finally:
    txn.discard()

Best-Effort Transaction#

# For stale reads (better performance)
txn = client.txn(read_only=True, best_effort=True)

Mutations#

JSON Mutations#

import json

txn = client.txn()
try:
    data = {
        'uid': '_:alice',
        'dgraph.type': 'Person',
        'name': 'Alice',
        'age': 30,
        'friends': [
            {'uid': '_:bob', 'dgraph.type': 'Person', 'name': 'Bob'}
        ]
    }

    response = txn.mutate(set_obj=data)

    # Get assigned UIDs
    alice_uid = response.uids['alice']
    bob_uid = response.uids['bob']

    txn.commit()
finally:
    txn.discard()

N-Quads Mutations#

txn = client.txn()
try:
    nquads = """
        _:alice <dgraph.type> "Person" .
        _:alice <name> "Alice" .
        _:alice <age> "30"^^<xs:int> .
    """
    response = txn.mutate(set_nquads=nquads)
    txn.commit()
finally:
    txn.discard()

Delete Mutations#

txn = client.txn()
try:
    # Delete specific predicate
    txn.mutate(del_nquads=f'<{uid}> <name> * .')

    # Delete node completely
    txn.mutate(del_obj={'uid': uid})

    txn.commit()
finally:
    txn.discard()

Queries (DQL)#

Basic Query#

query = """
    {
        people(func: type(Person)) {
            uid
            name
            age
            friends {
                name
            }
        }
    }
"""

response = client.txn(read_only=True).query(query)
result = json.loads(response.json)
people = result['people']

Parameterized Query#

query = """
    query findPerson($name: string) {
        person(func: eq(name, $name)) {
            uid
            name
            age
        }
    }
"""

variables = {'$name': 'Alice'}
response = client.txn(read_only=True).query(query, variables=variables)

Aggregation Queries#

query = """
    {
        stats(func: type(Person)) {
            count: count(uid)
            avgAge: avg(age)
            minAge: min(age)
            maxAge: max(age)
        }
    }
"""

Upsert Operations#

Basic Upsert#

query = """
    query {
        user as var(func: eq(email, "[email protected]"))
    }
"""

mutation = """
    uid(user) <name> "Alice" .
    uid(user) <email> "[email protected]" .
"""

txn = client.txn()
try:
    request = txn.create_request(
        query=query,
        mutations=[pydgraph.Mutation(set_nquads=mutation)]
    )
    response = txn.do_request(request)
    txn.commit()
finally:
    txn.discard()

Conditional Upsert#

query = """
    query {
        user as var(func: eq(email, "[email protected]"))
    }
"""

# Only mutate if user doesn't exist
mutation = pydgraph.Mutation(
    set_nquads='uid(user) <name> "Alice" .',
    cond='@if(eq(len(user), 0))'
)

Async Operations#

pydgraph provides async variants using gRPC futures:

async_alter#

future = client.async_alter(pydgraph.Operation(schema=schema))

# Handle result
try:
    result = pydgraph.DgraphClient.handle_alter_future(future)
except Exception as e:
    if pydgraph.util.is_jwt_expired(e):
        # Refresh token and retry
        pass

async_query and async_mutation#

txn = client.txn()

# Async query
query_future = txn.async_query(query_string)
result = pydgraph.Txn.handle_query_future(query_future)

# Async mutation
mutation_future = txn.async_mutation(set_obj=data)
result = pydgraph.Txn.handle_mutate_future(mutation_future)

Note: Async methods use gRPC futures, not native Python asyncio. They cannot retry on JWT expiration.

ACL and Authentication#

Login#

# Login with credentials
client.login("groot", "password")

# Login with namespace (multi-tenancy)
client.login_into_namespace("user", "password", namespace=1)

Refresh Token#

# Tokens expire - refresh periodically
client.retry_login()

Error Handling#

import grpc

try:
    response = txn.mutate(set_obj=data)
    txn.commit()
except grpc.RpcError as e:
    if e.code() == grpc.StatusCode.ABORTED:
        # Transaction conflict - retry
        pass
    elif e.code() == grpc.StatusCode.UNAUTHENTICATED:
        # JWT expired
        client.retry_login()
except pydgraph.errors.TransactionError as e:
    # Transaction-specific error
    pass
finally:
    txn.discard()

Performance Considerations#

Batch Mutations#

# Accumulate mutations, commit in batches
txn = client.txn()
batch = []

for item in large_dataset:
    batch.append(item)
    if len(batch) >= 1000:
        txn.mutate(set_obj=batch)
        batch = []

if batch:
    txn.mutate(set_obj=batch)

txn.commit()

Connection Reuse#

# Reuse client and stubs across requests
# Create once at application startup

Limitations#

• gRPC futures not native asyncio
• No connection pooling (manage stubs manually)
• No OGM layer included
• DQL learning curve (different from Cypher/Gremlin)
• Limited IDE support for DQL
• No built-in migration tooling

When to Use#

Choose pydgraph when:

• Distributed, horizontally scalable graph needed
• GraphQL-native development preferred
• Multi-tenancy (namespaces) required
• Integration with Dgraph Cloud
• High-write throughput scenarios

Consider alternatives when:

• Native asyncio critical
• OGM patterns preferred
• Cypher or Gremlin expertise exists
• Smaller scale deployments

Resources#

• Dgraph Documentation
• GitHub Repository
• DQL Query Language
• PyPI Package
• Dgraph Cloud

python-arango - ArangoDB Python Driver#

Overview#

python-arango is the official Python driver for ArangoDB, providing comprehensive access to ArangoDB’s multi-model capabilities including document, graph, and key-value operations. It offers a Pythonic interface to ArangoDB’s REST API.

Key Information#

Installation#

pip install python-arango

# For async support (separate package)
pip install python-arango-async

Connection Management#

Basic Connection#

from arango import ArangoClient

# Initialize client
client = ArangoClient(hosts="http://localhost:8529")

# Connect to database
db = client.db("mydb", username="root", password="password")

# System database for admin operations
sys_db = client.db("_system", username="root", password="password")

Connection Options#

client = ArangoClient(
    hosts="http://localhost:8529",
    http_client=None,          # Custom HTTP client
    serializer=None,           # Custom JSON serializer
    deserializer=None          # Custom JSON deserializer
)

Document Operations#

Basic CRUD#

# Get collection
collection = db.collection("users")

# Insert
metadata = collection.insert({"name": "Alice", "age": 30})
# Returns: {'_id': 'users/12345', '_key': '12345', '_rev': '_abc123'}

# Get by key
doc = collection.get("12345")

# Update
collection.update({"_key": "12345", "age": 31})

# Replace
collection.replace({"_key": "12345", "name": "Alice", "age": 31})

# Delete
collection.delete("12345")

Batch Operations#

# Batch insert
docs = [{"name": f"User{i}"} for i in range(1000)]
results = collection.insert_many(docs)

# Batch update
updates = [{"_key": key, "status": "active"} for key in keys]
collection.update_many(updates)

# Batch delete
collection.delete_many([{"_key": k} for k in keys])

AQL Queries#

Query Execution#

# Simple query
cursor = db.aql.execute(
    "FOR doc IN users FILTER doc.age > @min_age RETURN doc",
    bind_vars={"min_age": 25}
)

# Iterate results
for doc in cursor:
    print(doc)

# Get all results as list
results = cursor.batch()

Query Options#

cursor = db.aql.execute(
    query,
    bind_vars={"param": value},
    count=True,           # Include count
    batch_size=100,       # Results per batch
    ttl=3600,             # Cursor TTL in seconds
    max_runtime=30.0,     # Max execution time
    profile=True          # Include query profile
)

# Access statistics
print(cursor.statistics())
print(cursor.profile())

Graph Operations#

Graph Management#

# Create graph
graph = db.create_graph(
    "social",
    edge_definitions=[{
        "edge_collection": "knows",
        "from_vertex_collections": ["users"],
        "to_vertex_collections": ["users"]
    }]
)

# Get existing graph
graph = db.graph("social")

Vertex Operations#

# Get vertex collection
users = graph.vertex_collection("users")

# Insert vertex
users.insert({"_key": "alice", "name": "Alice"})

# Get vertex
alice = users.get("alice")

# Update vertex
users.update({"_key": "alice", "age": 30})

Edge Operations#

# Get edge collection
knows = graph.edge_collection("knows")

# Insert edge
knows.insert({
    "_from": "users/alice",
    "_to": "users/bob",
    "since": 2020
})

# Traverse graph
result = graph.traverse(
    start_vertex="users/alice",
    direction="outbound",
    max_depth=2
)

Async Support#

python-arango-async (Separate Package)#

from arangoasync import ArangoClient
from arangoasync.auth import Auth

async with ArangoClient(hosts="http://localhost:8529") as client:
    auth = Auth(username="root", password="password")
    db = await client.db("mydb", auth=auth)

    # Async operations
    collection = db.collection("users")
    await collection.insert({"name": "Alice"})

    cursor = await db.aql.execute("FOR doc IN users RETURN doc")
    async for doc in cursor:
        print(doc)

Fire-and-Forget Async (python-arango)#

# Create async execution context
async_db = db.begin_async_execution(return_result=True)

# Queue operations
job1 = async_db.collection("users").insert({"name": "Alice"})
job2 = async_db.collection("users").insert({"name": "Bob"})

# Check job status
print(job1.status())  # 'pending', 'done', or 'error'

# Get results when ready
result1 = job1.result()

Transaction Support#

Single Request Transactions#

# Stream transaction
txn = db.begin_transaction(
    read=["users"],
    write=["orders"]
)

try:
    txn.collection("users").insert({"name": "Alice"})
    txn.collection("orders").insert({"item": "Book"})
    txn.commit()
except:
    txn.abort()
    raise

JavaScript Transactions#

# Server-side transaction with JavaScript
result = db.transaction(
    read=["users"],
    write=["orders"],
    action="""
        function(params) {
            const db = require('@arangodb').db;
            const user = db.users.insert({name: params.name});
            return user;
        }
    """,
    params={"name": "Alice"}
)

Index Management#

# Create persistent index
collection.add_persistent_index(
    fields=["name", "email"],
    unique=True,
    sparse=False
)

# Create geo index
collection.add_geo_index(
    fields=["location"],
    geo_json=True
)

# Create fulltext index (deprecated, use ArangoSearch)
collection.add_fulltext_index(
    fields=["description"],
    min_length=3
)

# List indexes
for index in collection.indexes():
    print(index)