README.md

OntoBricks 0.6.2

Knowledge Graph Builder for Databricks

Project Description

OntoBricks is a web application that transforms Databricks tables into a materialized graph viewer. It lets you design ontologies (OWL), map them to Unity Catalog tables via R2RML, materialize triples into a Delta-backed triple store and a Lakebase Postgres graph engine, reason over the graph (OWL 2 RL, SWRL, SHACL), and query it through an auto-generated GraphQL API. The entire pipeline — from metadata import to a queryable graph viewer — can run in four clicks using LLM-powered automation.

Project Support

Please note that all projects in the /databrickslabs github account are provided for your exploration only, and are not formally supported by Databricks with Service Level Agreements (SLAs). They are provided AS-IS and we do not make any guarantees of any kind. Please do not submit a support ticket relating to any issues arising from the use of these projects.

Any issues discovered through the use of this project should be filed as GitHub Issues on the Repo. They will be reviewed as time permits, but there are no formal SLAs for support.

Building the Project

OntoBricks uses uv for dependency management. All dependencies are declared in pyproject.toml.

# Clone the repository
git clone <repository-url>
cd OntoBricks

# Install dependencies (uv resolves them from pyproject.toml)
uv sync

# Or use the setup script
scripts/setup.sh

Prerequisites

Python 3.10 or higher
Databricks workspace access (Databricks Apps must be enabled). Local development uses a Personal Access Token; production uses the App's service principal.
A SQL Warehouse (you'll need its ID for local dev).
Databricks Lakebase Autoscaling project + branch + Postgres database — required since v0.4.0 for the domain registry (domains, versions, permissions, schedules, global config) and the Graph DB triple store. Provisioned Lakebase instances are not supported. The Postgres driver (psycopg[binary] + psycopg-pool) is declared as an optional dependency so volume-only forks can opt out — install with uv sync --extra lakebase for any normal deployment.
Unity Catalog Volume in the catalog/schema that hosts the triplestore VIEWs (triplestore_<domain>_v<n>). The volume is reserved for binary artefacts (documents/ uploads — domain-scoped attachments imported by the ontology designer).
psql (libpq client) on PATH for the Lakebase permission bootstrap scripts (brew install libpq && brew link --force libpq on macOS).

Deploying / Installing the Project

Local Development

# Configure credentials
cp .env.example .env
# Edit .env with your Databricks host, token, and warehouse ID

# Start the application
scripts/start.sh
# Open http://localhost:8000

Deploy to Databricks Apps

# Install and authenticate the Databricks CLI (>= 0.250.0)
brew install databricks            # or curl -fsSL https://databricks.com/install.sh | sh
databricks auth login --host https://<workspace>

# Edit scripts/deploy.config.sh (CLI profile, warehouse, registry catalog/schema,
# Lakebase project/branch/database — see the file header) and then:
make deploy
# Or directly: scripts/deploy.sh

scripts/deploy.sh generates app.yaml from app.yaml.template + scripts/deploy.config.sh, validates and deploys the DAB bundle on target dev-lakebase, runs scripts/bootstrap-app-permissions.sh (app SP CAN_MANAGE on itself), then runs scripts/bootstrap-lakebase-perms.sh on the regis

ontobricks