# googlecloudplatform/nl2sql architecture

> Architecture diagram of the GitHub repository googlecloudplatform/nl2sql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/nl2sql
- Repository: https://github.com/googlecloudplatform/nl2sql

## Overview

NL2SQL is a composable Python framework that turns a natural-language question into SQL through selectable task modules. Its linear executor fetches a database, optionally narrows tables and columns, generates SQL, and can invoke evaluation-and-repair before returning a result. Datasets support connected databases and Excel-derived custom data; task prompts and LLM integrations are configurable, and optional analytics persist execution artefacts. The map preserves modular join selection and ReAct generation as separate capabilities. Several source excerpts are partial, so uncertain runtime links are omitted or marked unverified.

Main entry points: [`nl2sql/executors/linear_executor/core.py`](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/executors/linear_executor/core.py) (Linear Executor), [`nl2sql/datasets/base.py`](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/datasets/base.py) (Dataset), [`nl2sql/assets/prompts`](https://github.com/googlecloudplatform/nl2sql/tree/main/nl2sql/assets/prompts) (Prompt Assets), [`nl2sql/tasks/table_selection/core.py`](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/table_selection/core.py) (Table Selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow"]
  node_linear["Linear Executor<br/>[core.py]"]
  node_answer["SQL Result<br/>[core.py]"]
end

subgraph group_tasks["NL2SQL Tasks"]
  node_tables["Table Selection<br/>[core.py]"]
  node_columns["Column Selection<br/>[core.py]"]
  node_joins["Join Selection<br/>[core.py]"]
  node_generation["SQL Generation<br/>[core.py]"]
  node_react["ReAct Generation<br/>[react.py]"]
  node_repair["SQL Eval Repair<br/>[core.py]"]
  node_prompts["Prompt Assets"]
  node_classifier["Yes-No Classifier<br/>[classifiers.py]"]
end

subgraph group_data["Data Access"]
  node_dataset["Dataset<br/>[base.py]"]
  node_standard["Standard Dataset<br/>[standard.py]"]
  node_custom["Excel Dataset<br/>[custom.py]"]
  node_database[("SQL Database")]
end

subgraph group_integrations["LLM Integrations"]
  node_llm["LLM Provider"]
  node_vertex["Vertex AI Client<br/>[vertexai.py]"]
  node_palm["Google PaLM Client<br/>[google_palm.py]"]
end

subgraph group_analytics["Analytics"]
  node_analytics["Analytics Handler<br/>[persist.py]"]
  node_fingerprint["System Fingerprint<br/>[fingerprint.py]"]
end

node_questioner(("Questioner"))

node_questioner -->|"submits question"| node_linear
node_linear -->|"gets database"| node_dataset
node_linear -->|"runs selection"| node_tables
node_linear -->|"runs selection"| node_columns
node_linear -->|"filters schema"| node_dataset
node_linear -->|"generates SQL"| node_generation
node_linear -->|"repairs query"| node_repair
node_linear -->|"returns result"| node_answer
node_generation -->|"calls model"| node_llm
node_repair -->|"calls model"| node_llm
node_tables -->|"uses prompts"| node_prompts
node_columns -->|"uses prompts"| node_prompts
node_generation -->|"uses prompts"| node_prompts
node_repair -->|"uses prompts"| node_prompts
node_tables -->|"classifies output"| node_classifier
node_standard -.->|"implements dataset"| node_dataset
node_custom -->|"builds dataset"| node_dataset
node_dataset -.->|"connects schema"| node_database
node_vertex -.->|"provides client"| node_llm
node_palm -.->|"provides client"| node_llm
node_joins -.->|"uses database"| node_dataset
node_react -.->|"uses model"| node_llm
node_analytics -->|"uses fingerprint"| node_fingerprint

click node_linear "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/executors/linear_executor/core.py"
click node_answer "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/executors/linear_executor/core.py"
click node_tables "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/table_selection/core.py"
click node_columns "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/column_selection/core.py"
click node_joins "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/join_selection/core.py"
click node_generation "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/sql_generation/core.py"
click node_react "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/sql_generation/react.py"
click node_repair "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/eval_fix/core.py"
click node_prompts "https://github.com/googlecloudplatform/nl2sql/tree/main/nl2sql/assets/prompts"
click node_dataset "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/datasets/base.py"
click node_standard "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/datasets/standard.py"
click node_custom "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/datasets/custom.py"
click node_vertex "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/llms/vertexai.py"
click node_palm "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/llms/google_palm.py"
click node_analytics "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/commons/reporting/persist.py"
click node_fingerprint "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/commons/reporting/fingerprint.py"
click node_classifier "https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/commons/utils/classifiers.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_linear,node_answer toneBlue
class node_tables,node_columns,node_joins,node_generation,node_react,node_repair,node_prompts,node_classifier toneAmber
class node_dataset,node_standard,node_custom,node_database toneMint
class node_llm,node_vertex,node_palm toneRose
class node_analytics,node_fingerprint,node_questioner toneIndigo
```

## Components

### Workflow

- [Linear Executor](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/executors/linear_executor/core.py): `nl2sql/executors/linear_executor/core.py`
- [SQL Result](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/executors/linear_executor/core.py): `nl2sql/executors/linear_executor/core.py`

### NL2SQL Tasks

- [Table Selection](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/table_selection/core.py): `nl2sql/tasks/table_selection/core.py`
- [Column Selection](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/column_selection/core.py): `nl2sql/tasks/column_selection/core.py`
- [Join Selection](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/join_selection/core.py): `nl2sql/tasks/join_selection/core.py`
- [SQL Generation](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/sql_generation/core.py): `nl2sql/tasks/sql_generation/core.py`
- [ReAct Generation](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/sql_generation/react.py): `nl2sql/tasks/sql_generation/react.py`
- [SQL Eval Repair](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/tasks/eval_fix/core.py): `nl2sql/tasks/eval_fix/core.py`
- [Prompt Assets](https://github.com/googlecloudplatform/nl2sql/tree/main/nl2sql/assets/prompts): `nl2sql/assets/prompts`
- [Yes-No Classifier](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/commons/utils/classifiers.py): `nl2sql/commons/utils/classifiers.py`

### Data Access

- [Dataset](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/datasets/base.py): `nl2sql/datasets/base.py`
- [Standard Dataset](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/datasets/standard.py): `nl2sql/datasets/standard.py`
- [Excel Dataset](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/datasets/custom.py): `nl2sql/datasets/custom.py`
- **SQL Database**

### LLM Integrations

- **LLM Provider**
- [Vertex AI Client](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/llms/vertexai.py): `nl2sql/llms/vertexai.py`
- [Google PaLM Client](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/llms/google_palm.py): `nl2sql/llms/google_palm.py`

### Analytics

- [Analytics Handler](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/commons/reporting/persist.py): `nl2sql/commons/reporting/persist.py`
- [System Fingerprint](https://github.com/googlecloudplatform/nl2sql/blob/main/nl2sql/commons/reporting/fingerprint.py): `nl2sql/commons/reporting/fingerprint.py`

### Other components

- **Questioner**

## Connections

- Questioner → Linear Executor: submits question (evidence: `README.md`)
- Linear Executor → Dataset: gets database (evidence: `nl2sql/executors/linear_executor/core.py`)
- Linear Executor → Table Selection: runs selection (evidence: `nl2sql/executors/linear_executor/core.py`)
- Linear Executor → Column Selection: runs selection (evidence: `nl2sql/executors/linear_executor/core.py`)
- Linear Executor → Dataset: filters schema (evidence: `nl2sql/executors/linear_executor/core.py`)
- Linear Executor → SQL Generation: generates SQL (evidence: `nl2sql/executors/linear_executor/core.py`)
- Linear Executor → SQL Eval Repair: repairs query (evidence: `nl2sql/executors/linear_executor/core.py`)
- Linear Executor → SQL Result: returns result (evidence: `nl2sql/executors/linear_executor/core.py`)
- SQL Generation → LLM Provider: calls model (evidence: `nl2sql/tasks/sql_generation/core.py`)
- SQL Eval Repair → LLM Provider: calls model (evidence: `nl2sql/tasks/eval_fix/core.py`)
- Table Selection → Prompt Assets: uses prompts (evidence: `nl2sql/tasks/table_selection/core.py`)
- Column Selection → Prompt Assets: uses prompts (evidence: `nl2sql/tasks/column_selection/core.py`)
- SQL Generation → Prompt Assets: uses prompts (evidence: `nl2sql/tasks/sql_generation/core.py`)
- SQL Eval Repair → Prompt Assets: uses prompts (evidence: `nl2sql/tasks/eval_fix/core.py`)
- Table Selection → Yes-No Classifier: classifies output (evidence: `nl2sql/tasks/table_selection/core.py`)
- Standard Dataset → Dataset: implements dataset (evidence: `nl2sql/datasets/standard.py`)
- Excel Dataset → Dataset: builds dataset (evidence: `nl2sql/datasets/custom.py`)
- Dataset → SQL Database: connects schema
- Vertex AI Client → LLM Provider: provides client
- Google PaLM Client → LLM Provider: provides client
- Join Selection → Dataset: uses database (evidence: `nl2sql/tasks/join_selection/core.py`)
- ReAct Generation → LLM Provider: uses model
- Analytics Handler → System Fingerprint: uses fingerprint (evidence: `nl2sql/commons/reporting/persist.py`)
