Neo4j
Neo4j is a native graph database: data is stored as nodes and typed relationships with properties, and queried with the Cypher pattern language over the Bolt protocol. Community Edition is GPLv3 and free, runs as one instance with one user database, and has no online backup; Enterprise adds clustering, online backup and role-based access control. It fits data where the relationships carry the questions: people, projects, ideas and how they connect.
Neo4j is a graph database. It stores entities as nodes and the links between them as typed, directed relationships, and it answers questions by matching patterns across those links. It suits data where "how is this connected to that" is the main query, which a relational schema answers only with long chains of joins. The official docs at neo4j.com/docs own the Cypher and operations reference.
What it is
A native graph database written in Java. Data is stored as nodes with labels (types) and properties, connected by relationships that have a type, a direction and their own properties. Queries are written in Cypher, a declarative pattern-matching language. Clients connect over Bolt, a binary protocol on port 7687; the HTTP API and the Browser UI use port 7474.
Two editions ship from the same code base. Community Edition is open source under GPLv3 and is fully functional for a single instance: ACID transactions, Cypher, indexes and constraints. It allows exactly one standard database (neo4j) next to the built-in system database, which holds users, roles and DBMS metadata. Enterprise Edition is commercial and adds clustering, failover, online backup, multiple databases, role-based access control and LDAP.
Versioning changed after 5.x. Since 2025.01 the server uses calendar versions (YYYY.MM.patch); the current line is 2026.09 (2026.09.0 shipped 2026-09-21). 5.26 is the long-term support release: it gets only critical fixes and security patches, the latest being 5.26.32 (2026-10-09), and it is supported until June 2028. 5.26 is the last line that runs on Java 17; the calendar-versioned releases need Java 21. Online upgrades go from 5.26 LTS to the 2025.x and later releases.
How it works
A Neo4j server keeps its graph in store files on disk and caches the hot part in a page cache sized by server.memory.pagecache.size. Transactions go through a write-ahead transaction log before they reach the store, so a crash replays the log on restart. Each node record points to its first relationship, and each relationship points to the next one for both of its nodes. A traversal therefore follows pointers from node to node; it does not look up a join index. That is the property that keeps multi-hop queries fast as the graph grows.
A Cypher query is parsed, planned by a cost-based planner that uses index and label statistics, and run as a pipeline of operators. EXPLAIN shows the plan; PROFILE runs the query and shows rows and database hits per operator.
Backup depends on the edition. Enterprise runs neo4j-admin database backup against a live server. Community has only the offline path: stop the DBMS, run neo4j-admin database dump per database, start it again. The docs state that the dump "can be run only on an offline Neo4j DBMS" on Community, and that users and roles live in the system database, so system must be dumped too.
Step 1 of 4. The driver opens a Bolt session and sends a Cypher query with parameters inside a transaction.
Community Edition. Enterprise replaces the stop-dump-start cycle with an online backup against the running server.
The dump is a consistent copy because nothing writes while the server is down. The cost is a short window of downtime per backup, and that window grows with the size of the store.
When to use it
Reach for it when:
- The data is graph-shaped: people, projects, ideas, tools and goals with many cross-links, where most questions follow those links.
- Queries are variable-depth: "everything within three hops of this node", shortest paths, or "which projects share a person".
- The schema must grow without migrations: new labels and relationship types can be added at any time.
- Several processes need one shared store of connected facts with transactions and uniqueness constraints.
Skip it when:
- The data is tabular and the queries are aggregates and filters. Postgres does that with less operational cost.
- Retrieval is similarity-first, such as document search for RAG. A vector index on a document store fits better; Neo4j's own vector index helps only when the graph is already the primary store.
- High availability is required and Enterprise is not an option. Community runs one instance with no failover.
- The relationships are few and shallow. A foreign key and one join are simpler than a second database.
At a glance
Core concepts
- Node: an entity with zero or more labels, such as
:Personor:Project. - Relationship: a typed, directed edge, such as
(:Person)-[:WORKS_ON]->(:Project). It always has a start and an end node. - Property: a key/value pair on a node or relationship. Values are scalars or lists of scalars, not nested maps.
- Cypher: pattern matching in ASCII-art form:
MATCH (p:Person)-[:WORKS_ON]->(x:Project) RETURN x.name. - Constraint: uniqueness, existence or type rules on a label and property. A uniqueness constraint also creates a backing index.
- Index: range, text, point, full-text and vector indexes speed up finding start nodes.
- MERGE: match a pattern or create it if it is missing. Without a uniqueness constraint on the key, concurrent MERGEs can create duplicates.
Key facts
| Item | Value |
|---|---|
| Licence | GPLv3 (Community); commercial (Enterprise) |
| Current line | 2026.09 (calendar versioning since 2025.01) |
| LTS line | 5.26, latest 5.26.32, supported until June 2028 |
| Java | 17 or 21 for 5.26; 21 for calendar versions |
| Ports | 7687 Bolt, 7474 HTTP, 7473 HTTPS |
| Databases (Community) | One standard database plus system |
| Backup (Community) | Offline neo4j-admin database dump only |
| Minimum memory | 2 GB for development, 8 GB for on-premises servers |
Community compared with Enterprise
| Feature | Community | Enterprise |
|---|---|---|
| Standard databases | One | Many |
| Clustering and failover | No | Yes |
| Online backup | No, offline dump only | Yes, full and differential |
| Role-based access control | No | Yes |
| Dump or load on a running DBMS | No | Yes |
How to integrate
Helm install, Community, standalone
helm repo add neo4j https://helm.neo4j.com/neo4j
helm repo update
helm install graph neo4j/neo4j -n graph --create-namespace -f values.yaml
neo4j:
name: graph # mandatory
password: "change-me" # optional; the chart generates one if omitted
resources:
cpu: "1"
memory: "2Gi"
# edition defaults to community
volumes:
data:
mode: defaultStorageClass
defaultStorageClass:
requests:
storage: 10Gi
Python driver
from neo4j import GraphDatabase
driver = GraphDatabase.driver("neo4j://graph.graph.svc:7687", auth=("neo4j", "change-me"))
with driver.session(database="neo4j") as session:
session.run("CREATE CONSTRAINT person_name IF NOT EXISTS "
"FOR (p:Person) REQUIRE p.name IS UNIQUE")
session.run("MERGE (p:Person {name: $name})", name="Ada")
rows = session.run("MATCH (p:Person) RETURN count(p) AS n").single()
driver.close()
Offline dump and load (Community)
# with the DBMS stopped
neo4j-admin database dump system --to-path=/backups --overwrite-destination=true
neo4j-admin database dump neo4j --to-path=/backups --overwrite-destination=true
# restore, DBMS stopped
neo4j-admin database load system --from-path=/backups --overwrite-destination=true
neo4j-admin database load neo4j --from-path=/backups --overwrite-destination=true
--to-path names a directory that must already exist; the tool writes <database>.dump inside it. neo4j-admin database load --info prints an archive's metadata without loading it, which is a cheap check that a dump is readable.
In the GL stack
Neo4j 5.26 Community runs on the production cluster. Because Community allows only one standard database per DBMS, each graph is its own Neo4j instance: the agents' knowledge graph, a content graph and a graph of readings. Each one has its own credentials and storage. Staying on the 5.26 LTS line keeps the stack on a release that gets security fixes without a feature upgrade every month.
Community Edition has no online backup, so each graph has a nightly CronJob. The job stops the graph for 20 to 60 seconds, dumps the system and neo4j databases, starts the graph again and uploads both archives to the backup store. Dumps are kept for 14 days. The system dump is part of the job because users and roles live there, not in the neo4j dump.
Gotchas
- Community dumps need downtime. The DBMS must be offline for
dumpandload. Schedule the backup in a quiet hour and size the window from the store size. - Dump
systemas well.database dump neo4jdoes not include users and roles. A restore without thesystemdump loses every user and role created since install. - The dump target directory must exist and must not be world-readable or world-executable, or the command fails.
- MERGE without a constraint duplicates. Two transactions that MERGE the same key at the same time can each create a node. Add a uniqueness constraint for every key that MERGE uses.
- Case and whitespace make new nodes.
{name:'Smith'}and{name:'smith'}are different nodes. Normalize keys before writing. - Bolt is not HTTP.
curlagainst 7687 does nothing useful. Use a driver orcypher-shell; the Browser on 7474 is for exploration. - Memory needs explicit settings. Set the heap and
server.memory.pagecache.sizeto match the container limit, or the JVM and the page cache compete for the same memory and the pod is OOM-killed. - The 5.26 to calendar-version jump needs Java 21. Images handle this, but custom builds or bare-metal installs on Java 17 stop at 5.26.
Risks
- Open-core vendor. Neo4j, Inc. controls the roadmap. Clustering, online backup and access control are Enterprise-only, so needs that grow past one instance mean a licence or a migration.
- GPLv3. Running Community as a server is fine; shipping it embedded in distributed software brings copyleft obligations.
- Single point of failure. One Community instance per graph means no failover. A node loss means a restore from the last dump, and anything written since then is gone.
- Query-language lock-in. Cypher shaped the ISO GQL standard, but many applications use Neo4j-specific procedures and functions. Moving to another engine is a rewrite of those parts.
- Security. The default
neo4juser is an admin, and Community has no role-based access control. Keep Bolt off public networks and treat the password as a full-access credential.
Alternatives
- Memgraph: pick it for an in-memory engine that speaks Cypher and Bolt, when the graph fits in RAM and latency matters most.
- Postgres with recursive CTEs (or Apache AGE): pick it when Postgres is already there and traversals are shallow.
- ArangoDB: pick it when one engine must serve documents, key/value and graph queries with one query language (AQL).
- Amazon Neptune: pick it for a managed graph service on AWS with openCypher and Gremlin support.
Related
- Postgres and CloudNativePG — the relational store for tabular data next to the graphs.
- Redis — the in-memory store for caches and queues.
- SeaweedFS and MinIO — S3-compatible object storage, where dump archives land.
- Velero — cluster backup, which leaves databases to their own dump tooling.
- Data layer overview and Backup layer overview.
- Official: Operations Manual, Offline backup (5.x), Database release notes, Cypher Manual.
