How devprajwalv/text-to-sql works
Query Studio lets an analyst ask questions about Olist marketplace data, inspect generated SQL, and explore results. The main path runs from the Angular query workspace through FastAPI to retrieval, SQL generation, guarded SQLite execution, and a logged response; review-required queries pause for approval before execution. Separate user-facing capabilities include schema browsing, health status, and paginated results. The README documents indexing and data seeding, but their runtime details are not fully excerpted; edges reflect only shown calls or documented relationships.
Main entry points: sql_chain.py Query orchestration · main.py FastAPI app · api.ts API client · chat-window.ts Query workspace
Components 25
Analyst workspace
- Workspace
frontend/src/app/app.ts - Query workspace
frontend/src/app/chat-window.ts - Approval dialog
frontend/src/app/approval-modal.ts - SQL display
frontend/src/app/sql-display.ts - Results table
frontend/src/app/results-table.ts - Schema explorer
frontend/src/app/schema-explorer.ts - API client
frontend/src/app/api.ts
HTTP API
- FastAPI app
api/main.py - Query routes
api/routes/query.py - Health route
api/routes/health.py - Schema route
api/routes/schema.py
Query workflow
- Query orchestration
agent/sql_chain.py - Table retrieval
agent/retriever.py - Semantic catalog
agent/semantic_layer.py - SQL guard
agent/hitl_guard.py - Worked examples
agent/few_shot_examples.yaml - Index builder
agent/build_index.py
Data and metadata
- Data importer
data/seed.py - Table metadata
model/schema.py - SQLite connections
model/database.py - Analytics database
model/database.py - Request log
model/schema.py
Other components
- Analyst
- OpenAI models
- Chroma index
Connections 39
- Analyst → Workspace: uses
README.md - Workspace → API client: loads health and schema
frontend/src/app/app.ts - Workspace → Query workspace: shows query workspace
frontend/src/app/app.ts - Workspace → Schema explorer: shows schema explorer
frontend/src/app/app.ts - Query workspace → API client: submits and decides
frontend/src/app/chat-window.ts - Query workspace → Approval dialog: opens review
frontend/src/app/chat-window.ts - Query workspace → SQL display: displays SQL
frontend/src/app/chat-window.ts - Query workspace → Results table: displays results
frontend/src/app/chat-window.ts - Schema explorer → API client: fetches schema
frontend/src/app/schema-explorer.ts - Results table → API client: uses API types
frontend/src/app/results-table.ts - Approval dialog → API client: submits decision
frontend/src/app/approval-modal.ts - API client → FastAPI app: calls API
README.md - FastAPI app → Health route: registers route
api/main.py - FastAPI app → Schema route: registers route
api/main.py - FastAPI app → Query routes: registers route
api/main.py - Query routes → Query orchestration: calls ask and decide
api/routes/query.py - Schema route → Semantic catalog: serves catalog
api/routes/schema.py - Health route → Table retrieval: checks retrieval mode
api/routes/health.py - Health route → SQLite connections: checks database
api/routes/health.py - Query orchestration → Table retrieval: retrieves tables
agent/sql_chain.py - Query orchestration → Semantic catalog: formats schema context
agent/sql_chain.py - Query orchestration → OpenAI models: generates SQL
README.md - Query orchestration → Worked examples: loads examples
agent/sql_chain.py - Query orchestration → SQL guard: previews and executes SQL
agent/sql_chain.py - Query orchestration → SQLite connections: logs requests
agent/sql_chain.py - Query orchestration → Analytics database: queries data
agent/sql_chain.py - Table retrieval → Semantic catalog: builds table documents
agent/retriever.py - Table retrieval → Chroma index: queries index
README.md - Table retrieval → OpenAI models: embeds questions
README.md - Semantic catalog → Table metadata: reads metadata
agent/semantic_layer.py - SQL guard → Table metadata: restricts catalog
agent/hitl_guard.py - Data importer → Analytics database: seeds tables
README.md - Data importer → Table metadata: uses metadata
data/seed.py - SQLite connections → Analytics database: connects
model/database.py - FastAPI app → SQLite connections: initializes log schema
api/main.py - FastAPI app → Table metadata: creates application tables
api/main.py - Query orchestration → Request log: stores request records
agent/sql_chain.py - Index builder → Semantic catalog: builds schema documents
agent/build_index.py - Index builder → Chroma index: persists collection
README.md