JSON to Neo4j Cypher Converter

Generating Neo4j Cypher from JSON: Graph Data Ingestion

Neo4j is the world's leading graph database, using relationships as first-class citizens. When migrating data from a document store or a REST API, you need to convert JSON objects into Cypher CREATE or MERGE statements. This conversion process transforms flat or nested JSON into a rich network of nodes and relationships, enabling complex pathfinding and pattern matching queries.

Live Example

A JSON representing a social interaction:

{
  "actor": {"id": "u1", "name": "Alice"},
  "action": "FOLLOWS",
  "target": {"id": "u2", "name": "Bob"},
  "timestamp": "2023-10-27"
}

The resulting Cypher statement:

MERGE (a:User {id: 'u1'}) SET a.name = 'Alice'
MERGE (b:User {id: 'u2'}) SET b.name = 'Bob'
MERGE (a)-[r:FOLLOWS]->(b)
SET r.since = '2023-10-27'

Implementation Guide

1. Identify Nodes and Labels: Determine which JSON objects represent entities (e.g., User, Product) and assign them labels.
2. Extract Properties: Map JSON keys to node or relationship properties. Ensure data types (strings, integers, floats) match Neo4j's expectations.
3. Define Relationships: Use JSON keys or structure to identify connections. Map them to Cypher's -[REL_TYPE]-> syntax.
4. Use MERGE instead of CREATE: To avoid duplicate data, use MERGE on a unique identifier (like an ID) to ensure nodes are only created once.
5. Batch Processing: For large JSON files, use the apoc.load.json procedure or pass the JSON as a parameter to a Cypher query using UNWIND.

Technical Deep Dive

The challenge of JSON-to-Graph conversion is "normalization." In JSON, a user object might be duplicated across many records. In a graph, that user should be a single node with many incoming and outgoing relationships. When writing your conversion logic, you must decide which JSON fields are properties of the node and which should be extracted into their own nodes (e.g., a "City" field could be a property string or a separate (:City) node). Using the UNWIND clause in Cypher allows you to pass a massive JSON array and process it in a single transaction, which is significantly faster than executing thousands of individual CREATE statements.

Comparison

Best Practices

• Constraints: Before importing, create unique constraints in Neo4j (e.g., CREATE CONSTRAINT FOR (u:User) REQUIRE u.id IS UNIQUE) to speed up MERGE operations.
• Indexing: Index properties that you frequently use for lookups in your JSON.
• Relationship Direction: Always define a direction for relationships in your Cypher, even if the underlying data is logically bi-directional.

FAQ

Q: Can Neo4j import JSON directly?
A: Yes, using the APOC library's apoc.load.json, you can query a JSON URL or file directly and map it to nodes using Cypher.

Q: How do I handle arrays in JSON?
A: You can store them as property arrays in Neo4j or, better yet, UNWIND the array and create a separate node for each element connected by a relationship.