grai.build Documentation¶

Welcome to the grai.build documentation! This guide will help you understand and use grai.build to manage your graph database schemas.

📚 Documentation Structure¶

Getting Started¶

Getting Started - Quick start guide and installation
Philosophy - Design principles and project vision
Neo4j Setup - Setting up Neo4j locally for development

Core Features¶

CLI Reference - Complete command-line interface documentation
Source Configuration - How to configure data sources (BigQuery, Snowflake, etc.)
Data Loading - Loading data from warehouses into your graph
Schema Migrations - Version-controlled schema evolution and migrations
Build Cache - Incremental builds for faster iteration
Profiles - Multi-environment configuration (dev, staging, prod)

Advanced Features¶

Lineage Tracking - Track dependencies and impact analysis
Visualization - Interactive graph visualizations

🚀 Quick Links¶

New to grai.build?¶

Start here:

Getting Started Guide - Install and create your first project
Philosophy - Understand the "why" behind grai.build
CLI Reference - Learn the command-line tools

Common Tasks¶

Initialize a project: grai init
Validate your schema: grai validate
Build Cypher output: grai build
Create a migration: grai migrate "description"
Apply migrations: grai migrate upgrade
Deploy to Neo4j: grai run --password <password>
View lineage: grai lineage
Create visualization: grai visualize

Need Help?¶

GitHub Issues - Report bugs or request features
GitHub Discussions - Ask questions and share ideas
Support Guide - Where to get help

📖 Documentation by Topic¶

Schema Definition¶

Learn how to define your graph schema:

Source Configuration - Configure different data source types
Getting Started - Entity and relation basics

Development Workflow¶

Build Cache - Speed up development with incremental builds
Schema Migrations - Track and deploy schema changes safely
CLI Reference - All available commands and options

Data Operations¶

Data Loading - Load data from various sources
Neo4j Setup - Configure your Neo4j instance

Analysis & Visualization¶

Lineage Tracking - Understand data flow and dependencies
Visualization - Generate interactive graph visualizations

🎯 Use Cases¶

dbt Users¶

If you're familiar with dbt, you'll feel at home with grai.build:

YAML-based definitions - Like dbt models
Build command - Similar to dbt build
Data loading - Like dbt run but for graphs (from BigQuery, Postgres, Snowflake)
Documentation generation - Like dbt docs generate
Incremental builds - Skip unchanged files (via build cache)
Profiles - Multi-environment configs like dbt
APOC optimization - Automatic 2-3x speedup for bulk loading

See: Philosophy

Data Engineers¶

Managing graph schemas and loading data in production:

CI/CD integration - Validate schemas and load data in your pipeline
Version control - Track schema changes in git
Multiple environments - Dev, staging, production configs
Data source connectors - BigQuery, Snowflake, PostgreSQL (future)
Orchestration-ready - Integrates with Airflow, Prefect, etc.

See: Data Loading, Profiles

Data Analysts¶

Exploring and documenting graph structures:

Lineage visualization - See upstream/downstream dependencies
Impact analysis - Understand change implications
Interactive docs - Browse your graph schema

See: Lineage Tracking, Visualization

🏗️ Architecture¶

grai.build follows a clear pipeline:

YAML Definitions → Parser → Validator → Compiler → Cypher Scripts → Neo4j
                                                   ↓
                                            Lineage Tracker
                                                   ↓
                                            Visualizations

Data Sources (BigQuery, etc.) → Data Loader → Batching → Neo4j
                                     ↓
                                Verbose Logging

Each component is independent and testable, making the tool reliable and extensible.

🤝 Contributing¶

Want to contribute to grai.build?

🐛 Report bugs
💡 Suggest features
📖 Improve documentation
🧪 Write tests
🔧 Submit pull requests

See our Contributing Guide and Code of Conduct.

📄 License¶

grai.build is open source under the MIT License.

Ready to get started? Head to the Getting Started Guide!