A Python library to automatically import JSON to FalkorDB as a Graph.
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.
- 🔄 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
uv pip install -e .pip install .Or install dependencies directly:
pip install falkordbfrom 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)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
# Simple object
data = {
"product": "Laptop",
"price": 999.99,
"in_stock": True
}
importer.convert(data, clear_db=True, root_label="Product")# Load and convert JSON file
importer.load_from_file("data.json", clear_db=True)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 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)-
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
-
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
-
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")
-
Duplicate Prevention:
- Content hashing (SHA256) identifies duplicate nodes
- Identical content creates only one node in the graph
- Cache prevents redundant database queries
-
Cypher Execution:
- All operations use FalkorDB's GRAPH.QUERY command
- Cypher queries are generated automatically
- Transactions ensure data consistency
Initialize the JSON Importer.
Parameters:
db(FalkorDB, optional): Pre-initialized FalkorDB connection. If provided,hostandportare ignored.host(str): FalkorDB host address (used only ifdbis not provided, default: "localhost")port(int): FalkorDB port number (used only ifdbis not provided, default: 6379)graph_name(str): Name of the graph database (default: "json_graph")
Convert JSON data into a graph structure.
Parameters:
data(Union[Dict, List, Any]): JSON data as dict, list, or primitive valueclear_db(bool): If True, clear the database before importingroot_label(str): Label for the root node
Load JSON data from a file and import it into the graph.
Parameters:
filepath(str): Path to the JSON fileclear_db(bool): If True, clear the database before importing
Raises:
FileNotFoundError: If the file doesn't existValueError: If the file contains invalid JSON
Clear all data from the current graph database.
See the examples/ directory for more detailed examples:
basic_usage.py: Simple usage examples with various JSON structures
Run the test suite:
python -m pytest tests/Or using unittest:
python -m unittest discover tests- Python >= 3.8
- falkordb >= 4.0.0
- FalkorDB server running and accessible
MIT License - see LICENSE file for details
Contributions are welcome! Please feel free to submit a Pull Request.
For issues and questions, please open an issue on the GitHub repository.