Skip to content

grai.build

Schema-as-code for graph databases — Define schemas in YAML, generate docs like dbt, manage migrations like Alembic.

CI codecov PyPI Python 3.11+ License: MIT

What is grai.build?

grai.build manages your graph schema, not your data. Define entities and relations in YAML, and grai.build:

  • Validates schema for consistency before deployment
  • Compiles to Cypher constraints and indexes
  • Generates interactive documentation (like dbt docs)
  • Tracks lineage with visualizations
  • Manages migrations with version control

What it's not: An ETL tool. Use Airflow, Prefect, or dbt for data loading — grai.build handles the schema layer.

Quick Start

pip install grai-build

grai init my-graph-project
cd my-graph-project

grai build
grai docs --serve
grai run --uri bolt://localhost:7687 --user neo4j --password secret

Schema Definition

Entity (entities/customer.yml): 

entity: customer
source: analytics.customers
keys: [customer_id]
properties:
  - name: customer_id
    type: string
  - name: name
    type: string

Relation (relations/purchased.yml): 

relation: PURCHASED
from: customer
to: product
source: analytics.orders
mappings:
  from_key: customer_id
  to_key: product_id
properties:
  - name: order_date
    type: datetime

Documentation

Section Description
Getting Started Installation and first project
CLI Reference Complete command reference
Schema Migrations Version-controlled schema changes
Neo4j Setup Database configuration
Philosophy Design principles

Features

Feature Description
Schema validation Catch reference errors and type mismatches
Cypher compilation Generate constraints, indexes, and merge statements
Documentation Interactive HTML docs with graph visualization
Lineage tracking Dependency graphs and impact analysis
Migrations Version-controlled schema changes with up/down scripts
Build caching Incremental builds for faster iteration

Contributing

Contributions welcome. See the GitHub repository for details.

License

MIT License