š Neo4j Local Setup Guide¶
Complete guide to using grai.build with a local Neo4j instance.
š Prerequisites¶
- Python 3.11+ installed
- Docker Desktop (recommended) OR Neo4j Desktop
- Terminal/Command line access
- grai.build project already installed
š³ Option 1: Neo4j with Docker (Recommended)¶
Step 1: Install Docker Desktop¶
Download and install Docker Desktop:
- macOS: https://www.docker.com/products/docker-desktop/
- Follow installation instructions and start Docker Desktop
Step 2: Run Neo4j Container¶
Open your terminal and run:
docker run \
--name neo4j-grai \
-p 7474:7474 \
-p 7687:7687 \
-e NEO4J_AUTH=neo4j/graipassword \
-v $HOME/neo4j/data:/data \
-v $HOME/neo4j/logs:/logs \
-d \
neo4j:latest
What this does:
- Creates a container named
neo4j-grai
- Exposes port
7474
for browser interface - Exposes port
7687
for Bolt protocol (what grai uses) - Sets password to
graipassword
(change this if needed) - Persists data to
~/neo4j/data
on your Mac - Runs in detached mode (background)
Step 3: Verify Neo4j is Running¶
You should see logs indicating Neo4j started successfully.
Step 4: Access Neo4j Browser¶
Open your browser and go to:
Login credentials:
- Username:
neo4j
- Password:
graipassword
You should see the Neo4j Browser interface. Try running:
Step 5: Useful Docker Commands¶
# Stop Neo4j
docker stop neo4j-grai
# Start Neo4j (after stopping)
docker start neo4j-grai
# Restart Neo4j
docker restart neo4j-grai
# View logs
docker logs -f neo4j-grai
# Remove container (keeps data)
docker rm neo4j-grai
# Remove container AND data
docker rm -v neo4j-grai
rm -rf ~/neo4j
š„ļø Option 2: Neo4j Desktop¶
Step 1: Download Neo4j Desktop¶
Download from: https://neo4j.com/download/
Step 2: Install and Launch¶
- Install Neo4j Desktop
- Launch the application
- Create a new Project (e.g., "grai-project")
- Create a new Database (e.g., "grai-db")
Step 3: Configure Database¶
- Click on your database
- Go to Settings
- Note the connection details:
- Bolt URL:
bolt://localhost:7687
- Username:
neo4j
- Password: Set during database creation
Step 4: Start Database¶
Click the "Start" button on your database.
š§ Configure grai.build¶
Step 1: Install Neo4j Python Driver¶
The neo4j
driver should already be installed if you have grai-build installed. Verify:
If not installed:
Step 2: Create Your Project Directory¶
Important: For real-world use, create your project in a separate directory (not in the grai.build source repo).
# Create a new project directory anywhere you want
mkdir -p ~/my-projects/my-graph-project
cd ~/my-projects/my-graph-project
# Initialize a new grai project
grai init
# Or copy the example template (replace with your actual path)
cp -r /path/to/grai.build/templates/* .
Your project structure should look like:
~/my-projects/my-graph-project/
āāā grai.yml # Project manifest
āāā entities/
ā āāā customer.yml
ā āāā product.yml
āāā relations/
ā āāā purchased.yml
āāā target/ # Will be created by grai build
Step 3: Update Project Configuration¶
Edit your grai.yml
file:
# grai.yml
name: my-graph-project
version: 1.0.0
config:
neo4j:
uri: bolt://localhost:7687
database: neo4j
user: neo4j
password: graipassword # Change to your password
compiler:
backend: neo4j
output_dir: target/neo4j
validator:
strict_mode: true
Step 3: Test Connection¶
Create a test script to verify connection:
cat > test_connection.py << 'EOF'
"""Test Neo4j connection."""
from grai.core.loader.neo4j_loader import (
connect_neo4j,
verify_connection,
get_database_info,
close_connection,
)
# Connection details
URI = "bolt://localhost:7687"
USER = "neo4j"
PASSWORD = "graipassword" # Change to your password
DATABASE = "neo4j"
def main():
print("š Testing Neo4j connection...")
try:
# Connect
print(f"Connecting to {URI}...")
driver = connect_neo4j(
uri=URI,
user=USER,
password=PASSWORD,
)
print("ā
Connected successfully!")
# Verify
print(f"\nš Verifying connection to database '{DATABASE}'...")
if verify_connection(driver, database=DATABASE):
print("ā
Connection verified!")
else:
print("ā Connection verification failed")
return
# Get database info
print(f"\nš Database information:")
info = get_database_info(driver, database=DATABASE)
print(f" - Nodes: {info['node_count']}")
print(f" - Relationships: {info['relationship_count']}")
print(f" - Labels: {info['labels']}")
print(f" - Relationship types: {info['relationship_types']}")
# Close
close_connection(driver)
print("\nā
Connection test complete!")
except Exception as e:
print(f"ā Error: {e}")
import traceback
traceback.print_exc()
if __name__ == "__main__":
main()
EOF
python test_connection.py
Expected output:
š Testing Neo4j connection...
Connecting to bolt://localhost:7687...
ā
Connected successfully!
š Verifying connection to database 'neo4j'...
ā
Connection verified!
š Database information:
- Nodes: 0
- Relationships: 0
- Labels: []
- Relationship types: []
ā
Connection test complete!
š Use grai.build with Neo4j¶
Step 1: Navigate to Your Project¶
# Go to your project directory (wherever you created it)
cd ~/my-projects/my-graph-project
# Or if you want to test with the templates first:
cd /path/to/grai.build/templates
Step 2: Build and Validate¶
# Validate the project
grai validate
# Build (compile to Cypher without executing)
grai build
# View the compiled Cypher
cat target/neo4j/compiled.cypher
Step 3: Execute Against Neo4j¶
# Execute with explicit connection details
grai run \
--uri bolt://localhost:7687 \
--user neo4j \
--password graipassword
Expected output:
ā
Project validated successfully
š¦ Compiling project...
ā
Compiled 2 entities and 1 relation
š Output written to: target/neo4j/compiled.cypher
š Connecting to Neo4j at bolt://localhost:7687...
ā
Connected successfully
ā” Executing Cypher statements...
ā
Executed 3 statements successfully
š Records affected: 0 (no data loaded yet)
ā±ļø Execution time: 0.42s
Step 4: Verify in Neo4j Browser¶
Open http://localhost:7474 and run:
You should see:
The schema is loaded, but no data yet (since we're using MERGE without actual data).
Step 5: Load Sample Data¶
Create a test data file:
cat > load_sample_data.py << 'EOF'
"""Load sample data into Neo4j."""
from grai.core.loader.neo4j_loader import connect_neo4j, execute_cypher, close_connection
URI = "bolt://localhost:7687"
USER = "neo4j"
PASSWORD = "graipassword"
SAMPLE_DATA = """
// Create sample customers
CREATE (c1:customer {customer_id: 'C001', name: 'Alice Smith', region: 'US-West'});
CREATE (c2:customer {customer_id: 'C002', name: 'Bob Jones', region: 'US-East'});
CREATE (c3:customer {customer_id: 'C003', name: 'Charlie Brown', region: 'EU'});
// Create sample products
CREATE (p1:product {product_id: 'P001', name: 'Laptop', price: 999.99});
CREATE (p2:product {product_id: 'P002', name: 'Mouse', price: 29.99});
CREATE (p3:product {product_id: 'P003', name: 'Keyboard', price: 79.99});
// Create purchases
MATCH (c:customer {customer_id: 'C001'})
MATCH (p:product {product_id: 'P001'})
CREATE (c)-[:PURCHASED {order_id: 'O001', order_date: datetime('2024-01-15')}]->(p);
MATCH (c:customer {customer_id: 'C001'})
MATCH (p:product {product_id: 'P002'})
CREATE (c)-[:PURCHASED {order_id: 'O002', order_date: datetime('2024-01-15')}]->(p);
MATCH (c:customer {customer_id: 'C002'})
MATCH (p:product {product_id: 'P003'})
CREATE (c)-[:PURCHASED {order_id: 'O003', order_date: datetime('2024-01-20')}]->(p);
MATCH (c:customer {customer_id: 'C003'})
MATCH (p:product {product_id: 'P001'})
CREATE (c)-[:PURCHASED {order_id: 'O004', order_date: datetime('2024-02-01')}]->(p);
"""
def main():
print("š¦ Loading sample data into Neo4j...")
driver = connect_neo4j(uri=URI, user=USER, password=PASSWORD)
result = execute_cypher(driver, SAMPLE_DATA)
if result.success:
print(f"ā
Loaded successfully!")
print(f" Statements executed: {result.statements_executed}")
print(f" Records affected: {result.records_affected}")
print(f" Execution time: {result.execution_time:.2f}s")
else:
print(f"ā Failed to load data")
for error in result.errors:
print(f" {error}")
close_connection(driver)
if __name__ == "__main__":
main()
EOF
python load_sample_data.py
Step 6: Query Your Data¶
In Neo4j Browser (http://localhost:7474):
// See all nodes and relationships
MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 25
// Find customers who bought laptops
MATCH (c:customer)-[p:PURCHASED]->(prod:product {name: 'Laptop'})
RETURN c.name, c.region, p.order_date, prod.name, prod.price
// Count purchases per customer
MATCH (c:customer)-[p:PURCHASED]->()
RETURN c.name, count(p) AS purchase_count
ORDER BY purchase_count DESC
šØ Visualize Your Graph¶
Use grai's built-in visualization:
# Generate interactive visualization
grai visualize --format d3 --open
# Or Cytoscape format
grai visualize --format cytoscape --open
This will open an interactive HTML visualization in your browser showing your graph schema.
š Common Workflows¶
Workflow 1: Iterative Development¶
# 1. Edit YAML files
vim entities/customer.yml
# 2. Validate changes
grai validate
# 3. Build and review compiled Cypher
grai build
cat target/neo4j/compiled.cypher
# 4. Execute when ready
grai run --uri bolt://localhost:7687 --user neo4j --password graipassword
# 5. Verify in browser
open http://localhost:7474
Workflow 2: Fresh Start¶
# Clear the database and reload
python << 'EOF'
from grai.core.loader.neo4j_loader import connect_neo4j, clear_database, close_connection
driver = connect_neo4j(
uri="bolt://localhost:7687",
user="neo4j",
password="graipassword"
)
# WARNING: This deletes ALL data!
result = clear_database(driver, confirm=True)
print(f"ā
Cleared {result.records_affected} records")
close_connection(driver)
EOF
# Rebuild from scratch
grai run --uri bolt://localhost:7687 --user neo4j --password graipassword
python load_sample_data.py
Workflow 3: Check Database State¶
# Get detailed info
python << 'EOF'
from grai.core.loader.neo4j_loader import connect_neo4j, get_database_info, close_connection
driver = connect_neo4j(
uri="bolt://localhost:7687",
user="neo4j",
password="graipassword"
)
info = get_database_info(driver)
print(f"š Database Statistics:")
print(f" Nodes: {info['node_count']}")
print(f" Relationships: {info['relationship_count']}")
print(f" Labels: {', '.join(info['labels']) or 'None'}")
print(f" Relationship types: {', '.join(info['relationship_types']) or 'None'}")
close_connection(driver)
EOF
š Troubleshooting¶
Issue: "Cannot connect to Neo4j"¶
Check if Neo4j is running:
Check logs:
Test connection manually:
Issue: "Authentication failed"¶
Make sure your password matches:
# Docker: password set with NEO4J_AUTH
docker run -e NEO4J_AUTH=neo4j/YOUR_PASSWORD ...
# In grai commands
grai run --password YOUR_PASSWORD
Issue: "neo4j driver not installed"¶
Install the Python driver:
Issue: Port already in use¶
Check what's using the ports:
Stop conflicting services or change Neo4j ports:
Issue: Permission denied on data directory¶
Fix directory permissions:
š Next Steps¶
- Explore the CLI:
- Try other commands:
-
Create your own entities:
-
Copy
templates/entities/customer.yml
as a starting point - Define your own properties and relationships
-
Run
grai validate
andgrai build
-
Read the documentation:
docs/PARSER.md
- YAML structuredocs/VALIDATOR.md
- Validation rulesdocs/COMPILER.md
- Cypher generationdocs/VISUALIZER.md
- Visualization options
šÆ Quick Reference¶
Essential Commands¶
# Validate project
grai validate
# Build (compile only)
grai build
# Build and execute
grai run --uri bolt://localhost:7687 --user neo4j --password graipassword
# Visualize schema
grai visualize --format d3 --open
# View lineage
grai lineage --format mermaid
# Export IR
grai export --format json --output schema.json
Connection Details (Docker)¶
URI: bolt://localhost:7687
User: neo4j
Password: graipassword (or what you set)
Browser: http://localhost:7474
Database: neo4j
Docker Commands¶
# Start
docker start neo4j-grai
# Stop
docker stop neo4j-grai
# Logs
docker logs -f neo4j-grai
# Remove
docker rm neo4j-grai
ā Success Checklist¶
- Neo4j running (Docker or Desktop)
- Can access http://localhost:7474
- Can login with credentials
- Python neo4j driver installed (
pip install neo4j
) -
test_connection.py
runs successfully -
grai validate
passes -
grai build
generates Cypher -
grai run
loads schema - Can query data in Neo4j Browser
-
grai visualize --open
shows graph
š You're ready to build knowledge graphs with grai.build and Neo4j!