cypher4sql

Neo4j-enhanced context engineering for SQL generation.

Overview

cypher4sql uses Neo4j schema graphs to provide rich context for text-to-SQL models:

• Semantic table retrieval via vector embeddings
• FK statistics (fanout, cardinality, risk tags)
• Join path finding for multi-hop queries
• Planner hints for complex joins

Architecture

User Question
     ↓
┌─────────────────────────────────────┐
│  Neo4j Schema Graph (cypher4sql)    │
│  - Vector search → relevant tables  │
│  - FK stats → join risk/hints       │
│  - Path finding → join options      │
└─────────────────────────────────────┘
     ↓
Enhanced Context + FK Stats
     ↓
SQL Model → Query

Usage

Training

• FK stats for reward shaping
• Mutation validation (Phase 3.5)
• Context engineering for training data

Production

• Live schema retrieval
• Semantic table ranking
• FK stats for query planning

FK Stats Format (v4)

Join Options:
  1. orders.customer_id -> customers.id [1:N, fk_u=0.85, n=50000, fanout=3.2, risk=MED]
  2. order_items.order_id -> orders.id [1:N, fk_u=1.00, n=150000, fanout=2.8, risk=LOW]

Safe (no-dup) joins: order_items->orders

License

MIT