json2graph

A Python library to automatically import JSON to FalkorDB as a Graph.

Overview

json2graph converts JSON data (from files or dictionaries) into a graph structure in FalkorDB. It automatically creates nodes from objects and arrays with smart labeling based on keys, extracts primitive values as properties, and creates relationships based on the JSON structure. The library handles nested data recursively and prevents duplicate nodes using content hashing.

Features

• 🔄 Automatic Graph Creation: Converts JSON objects and arrays into graph nodes
• 🏷️ Smart Labeling: Uses JSON keys to label nodes intelligently
• 🔗 Relationship Mapping: Creates relationships based on JSON structure
• 📦 Property Extraction: Extracts primitive values (strings, numbers, booleans) as node properties
• 🔁 Recursive Processing: Handles deeply nested JSON structures
• 🔒 Duplicate Prevention: Uses content hashing to prevent duplicate nodes
• 🗂️ File & Dict Support: Import from JSON files or Python dictionaries
• 🧹 Database Management: Optional database clearing before import
• 🔌 FalkorDB Integration: Uses FalkorDB Python client with Cypher queries via GRAPH.QUERY

Installation

Using uv (recommended)

uv pip install -e .

Using pip

pip install .

Or install dependencies directly:

pip install falkordb

Quick Start

from json2graph import JSONImporter

# Initialize the importer (Option 1: let it create the connection)
importer = JSONImporter(
    host="localhost",
    port=6379,
    graph_name="my_graph"
)

# Or initialize with your own FalkorDB connection (Option 2)
# from falkordb import FalkorDB
# db = FalkorDB(host="localhost", port=6379)
# importer = JSONImporter(db=db, graph_name="my_graph")

# Import from a dictionary
data = {
    "name": "John Doe",
    "age": 30,
    "skills": ["Python", "JavaScript"]
}
importer.convert(data, clear_db=True)

# Import from a JSON file
importer.load_from_file("data.json", clear_db=True)

Usage

Initialize the Importer

Option 1: Let JSONImporter create the connection (default)

from json2graph import JSONImporter

importer = JSONImporter(
    host="localhost",      # FalkorDB host (default: "localhost")
    port=6379,            # FalkorDB port (default: 6379)
    graph_name="my_graph" # Graph database name (default: "json_graph")
)

Option 2: Pass a pre-initialized FalkorDB connection

from falkordb import FalkorDB
from json2graph import JSONImporter

# Create your own FalkorDB connection
db = FalkorDB(host="localhost", port=6379)

# Pass it to JSONImporter
importer = JSONImporter(
    db=db,                # Pre-initialized FalkorDB connection
    graph_name="my_graph" # Graph database name
)

This is useful when you want to:

• Reuse the same connection across multiple components
• Configure the connection with custom settings (e.g., password, SSL)
• Manage the connection lifecycle yourself

Convert JSON Dictionary

# Simple object
data = {
    "product": "Laptop",
    "price": 999.99,
    "in_stock": True
}
importer.convert(data, clear_db=True, root_label="Product")

Load from JSON File

# Load and convert JSON file
importer.load_from_file("data.json", clear_db=True)

Nested Structures

The library handles nested objects and arrays automatically:

data = {
    "company": "TechCorp",
    "employees": [
        {
            "name": "Alice",
            "role": "Developer",
            "skills": ["Python", "Go"]
        },
        {
            "name": "Bob",
            "role": "Designer",
            "skills": ["Photoshop"]
        }
    ],
    "location": {
        "city": "San Francisco",
        "country": "USA"
    }
}
importer.convert(data, root_label="Company")

Clear Database

# Clear all nodes and relationships
importer.clear_db()

# Or clear during import
importer.convert(data, clear_db=True)
importer.load_from_file("data.json", clear_db=True)

How It Works

1. Node Creation:

   • JSON objects become nodes with labels derived from their keys
   • JSON arrays become container nodes with element relationships
   • Primitive values become node properties

2. Smart Labeling:

   • Object nodes are labeled based on their parent key
   • Array nodes get "Array" suffix (e.g., "employeesArray")
   • Labels are sanitized for Cypher compatibility

3. Relationships:

   • Parent-child relationships are created based on JSON structure
   • Relationship types are derived from JSON keys
   • Array elements get indexed relationships (e.g., "ELEMENT_0", "ELEMENT_1")

4. Duplicate Prevention:

   • Content hashing (SHA256) identifies duplicate nodes
   • Identical content creates only one node in the graph
   • Cache prevents redundant database queries

5. Cypher Execution:

   • All operations use FalkorDB's GRAPH.QUERY command
   • Cypher queries are generated automatically
   • Transactions ensure data consistency

API Reference

JSONImporter

__init__(db=None, host="localhost", port=6379, graph_name="json_graph")

Initialize the JSON Importer.

Parameters:

• db (FalkorDB, optional): Pre-initialized FalkorDB connection. If provided, host and port are ignored.
• host (str): FalkorDB host address (used only if db is not provided, default: "localhost")
• port (int): FalkorDB port number (used only if db is not provided, default: 6379)
• graph_name (str): Name of the graph database (default: "json_graph")

convert(data, clear_db=False, root_label="Root")

Convert JSON data into a graph structure.

Parameters:

• data (Union[Dict, List, Any]): JSON data as dict, list, or primitive value
• clear_db (bool): If True, clear the database before importing
• root_label (str): Label for the root node

load_from_file(filepath, clear_db=False)

Load JSON data from a file and import it into the graph.

Parameters:

• filepath (str): Path to the JSON file
• clear_db (bool): If True, clear the database before importing

Raises:

• FileNotFoundError: If the file doesn't exist
• ValueError: If the file contains invalid JSON

clear_db()

Clear all data from the current graph database.

Examples

See the examples/ directory for more detailed examples:

• basic_usage.py: Simple usage examples with various JSON structures

Testing

Run the test suite:

python -m pytest tests/

Or using unittest:

python -m unittest discover tests

Requirements

• Python >= 3.8
• falkordb >= 4.0.0
• FalkorDB server running and accessible

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on the GitHub repository.