A hands-on workshop for building a semantic layer on top of a relational data warehouse using Neo4j — enabling accurate natural language to SQL with an AI agent.
A graph-based semantic layer that sits between an AI agent and BigQuery. The agent uses Neo4j to find the right tables and columns for any natural language question, then generates and executes the SQL.
By the end of the workshop, you'll be able to ask questions like "Which customers have an active subscription and an open critical support ticket?" and get back a correct SQL query and formatted results — without writing a single line of SQL yourself.
Natural language question
↓
Neo4j (semantic search + graph traversal)
→ returns relevant tables, columns, FK paths
↓
LLM (SQL generation)
↓
BigQuery (execution)
↓
Answer
| Module | Description |
|---|---|
| Setup | Accounts, API keys, and environment configuration |
| Module 1: Introduction | Why semantic layers, why graph, how the architecture works |
| Module 2: Build the Semantic Layer | ETL pipeline: BigQuery → Neo4j graph + vector embeddings |
| Module 3: Run an Agent | Run a CLI agent over MCP and explore the ACME dataset (Claude Desktop optional) |
| Module 4: Bring Your Own Data | Load any schema into Neo4j using CSV files |
Large-schema stress test over BigQuery public Census ACS data — 278 near-identical tables, Neocarta WITH vs WITHOUT comparison, and a compact-retrieval variant (~45–81% token savings).
→ Census quickstart · Findings
1. Complete setup (accounts, API keys, and environment):
2. Start with Module 1 — module-1/README.md
- Python 3.12+, uv
- Google Cloud project with BigQuery enabled
- Neo4j instance (AuraDB Free or Desktop)
- OpenAI API key