# wahid989/sqlglot architecture

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

- Interactive diagram: https://gitdiagram.com/wahid989/sqlglot
- Repository: https://github.com/wahid989/sqlglot

## Overview

SQLGlot is a Python SQL parser, transpiler, optimizer, and lightweight execution engine. The principal workflow accepts SQL plus an optional source dialect, tokenizes and parses it into an expression tree, then generates SQL in a target dialect. Separate capabilities include query analysis, planning and execution, AST comparison, lineage, and JSONPath. Edges are limited to relationships visible in excerpts, SOURCE INDEX references, or README statements; several feature implementations are unsampled, so their internal connections are not asserted.

Main entry points: [`sqlglot/__init__.py`](https://github.com/wahid989/sqlglot/blob/main/sqlglot/__init__.py) (Public API), [`sqlglot/dialects/dialect.py`](https://github.com/wahid989/sqlglot/blob/main/sqlglot/dialects/dialect.py) (Dialect registry), [`sqlglot/parser.py`](https://github.com/wahid989/sqlglot/blob/main/sqlglot/parser.py) (SQL parser), [`sqlglot/optimizer/optimizer.py`](https://github.com/wahid989/sqlglot/blob/main/sqlglot/optimizer/optimizer.py) (Query optimizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_parse["SQL Parsing"]
  node_api["Public API<br/>[__init__.py]"]
  node_tokens["Tokenizer<br/>[tokens.py]"]
  node_dialects["Dialect registry<br/>[dialect.py]"]
  node_parser["SQL parser<br/>[parser.py]"]
  node_dialectimpl["Dialect grammars"]
end

subgraph group_ast["Expression Model"]
  node_expressions["Expression tree<br/>[core.py]"]
  node_queryexpr["Query expressions<br/>[query.py]"]
end

subgraph group_transform["SQL Analysis &amp; Output"]
  node_optimizer["Query optimizer<br/>[optimizer.py]"]
  node_scope["Scope analysis<br/>[scope.py]"]
  node_types["Type annotation<br/>[annotate_types.py]"]
  node_schema["Schema metadata<br/>[schema.py]"]
  node_generator["SQL generator<br/>[generator.py]"]
end

subgraph group_extras["Additional Capabilities"]
  node_planner["Query planner<br/>[planner.py]"]
  node_executor["Python executor<br/>[python.py]"]
  node_lineage["Query lineage<br/>[lineage.py]"]
  node_diff["AST diff<br/>[diff.py]"]
  node_jsonpath["JSONPath<br/>[jsonpath.py]"]
end

node_user(("SQL caller"))
node_engine(("External SQL engine"))

node_user -->|"submits SQL"| node_api
node_api -->|"selects dialect"| node_dialects
node_api -->|"tokenizes"| node_tokens
node_api -->|"parses SQL"| node_parser
node_dialects -->|"configures tokenizer"| node_tokens
node_dialects -->|"configures parser"| node_parser
node_dialects -->|"configures generator"| node_generator
node_parser -->|"builds nodes"| node_expressions
node_expressions -->|"extends query model"| node_queryexpr
node_api -->|"generates SQL"| node_generator
node_api -->|"optimizes queries"| node_optimizer
node_optimizer -->|"analyzes scopes"| node_scope
node_optimizer -->|"annotates types"| node_types
node_types -->|"reads scopes"| node_scope
node_types -->|"reads schema"| node_schema
node_api -.->|"plans SQL"| node_planner
node_planner -->|"feeds plan"| node_executor
node_executor -.->|"executes locally"| node_engine
node_api -.->|"analyzes lineage"| node_lineage
node_api -.->|"compares trees"| node_diff
node_api -.->|"queries JSONPath"| node_jsonpath
node_dialectimpl -.->|"extends dialect parsing"| node_parser
node_dialectimpl -.->|"extends dialect output"| node_generator

click node_api "https://github.com/wahid989/sqlglot/blob/main/sqlglot/__init__.py"
click node_tokens "https://github.com/wahid989/sqlglot/blob/main/sqlglot/tokens.py"
click node_dialects "https://github.com/wahid989/sqlglot/blob/main/sqlglot/dialects/dialect.py"
click node_parser "https://github.com/wahid989/sqlglot/blob/main/sqlglot/parser.py"
click node_expressions "https://github.com/wahid989/sqlglot/blob/main/sqlglot/expressions/core.py"
click node_queryexpr "https://github.com/wahid989/sqlglot/blob/main/sqlglot/expressions/query.py"
click node_optimizer "https://github.com/wahid989/sqlglot/blob/main/sqlglot/optimizer/optimizer.py"
click node_scope "https://github.com/wahid989/sqlglot/blob/main/sqlglot/optimizer/scope.py"
click node_types "https://github.com/wahid989/sqlglot/blob/main/sqlglot/optimizer/annotate_types.py"
click node_schema "https://github.com/wahid989/sqlglot/blob/main/sqlglot/schema.py"
click node_generator "https://github.com/wahid989/sqlglot/blob/main/sqlglot/generator.py"
click node_dialectimpl "https://github.com/wahid989/sqlglot/tree/main/sqlglot/parsers"
click node_planner "https://github.com/wahid989/sqlglot/blob/main/sqlglot/planner.py"
click node_executor "https://github.com/wahid989/sqlglot/blob/main/sqlglot/executor/python.py"
click node_lineage "https://github.com/wahid989/sqlglot/blob/main/sqlglot/lineage.py"
click node_diff "https://github.com/wahid989/sqlglot/blob/main/sqlglot/diff.py"
click node_jsonpath "https://github.com/wahid989/sqlglot/blob/main/sqlglot/jsonpath.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_api,node_tokens,node_dialects,node_parser,node_dialectimpl toneBlue
class node_expressions,node_queryexpr toneAmber
class node_optimizer,node_scope,node_types,node_schema,node_generator toneMint
class node_planner,node_executor,node_lineage,node_diff,node_jsonpath toneRose
class node_user,node_engine toneIndigo
```

## Components

### SQL Parsing

- [Public API](https://github.com/wahid989/sqlglot/blob/main/sqlglot/__init__.py): `sqlglot/__init__.py`
- [Tokenizer](https://github.com/wahid989/sqlglot/blob/main/sqlglot/tokens.py): `sqlglot/tokens.py`
- [Dialect registry](https://github.com/wahid989/sqlglot/blob/main/sqlglot/dialects/dialect.py): `sqlglot/dialects/dialect.py`
- [SQL parser](https://github.com/wahid989/sqlglot/blob/main/sqlglot/parser.py): `sqlglot/parser.py`
- [Dialect grammars](https://github.com/wahid989/sqlglot/tree/main/sqlglot/parsers): `sqlglot/parsers`

### Expression Model

- [Expression tree](https://github.com/wahid989/sqlglot/blob/main/sqlglot/expressions/core.py): `sqlglot/expressions/core.py`
- [Query expressions](https://github.com/wahid989/sqlglot/blob/main/sqlglot/expressions/query.py): `sqlglot/expressions/query.py`

### SQL Analysis & Output

- [Query optimizer](https://github.com/wahid989/sqlglot/blob/main/sqlglot/optimizer/optimizer.py): `sqlglot/optimizer/optimizer.py`
- [Scope analysis](https://github.com/wahid989/sqlglot/blob/main/sqlglot/optimizer/scope.py): `sqlglot/optimizer/scope.py`
- [Type annotation](https://github.com/wahid989/sqlglot/blob/main/sqlglot/optimizer/annotate_types.py): `sqlglot/optimizer/annotate_types.py`
- [Schema metadata](https://github.com/wahid989/sqlglot/blob/main/sqlglot/schema.py): `sqlglot/schema.py`
- [SQL generator](https://github.com/wahid989/sqlglot/blob/main/sqlglot/generator.py): `sqlglot/generator.py`

### Additional Capabilities

- [Query planner](https://github.com/wahid989/sqlglot/blob/main/sqlglot/planner.py): `sqlglot/planner.py`
- [Python executor](https://github.com/wahid989/sqlglot/blob/main/sqlglot/executor/python.py): `sqlglot/executor/python.py`
- [Query lineage](https://github.com/wahid989/sqlglot/blob/main/sqlglot/lineage.py): `sqlglot/lineage.py`
- [AST diff](https://github.com/wahid989/sqlglot/blob/main/sqlglot/diff.py): `sqlglot/diff.py`
- [JSONPath](https://github.com/wahid989/sqlglot/blob/main/sqlglot/jsonpath.py): `sqlglot/jsonpath.py`

### Other components

- **SQL caller**
- **External SQL engine**

## Connections

- SQL caller → Public API: submits SQL (evidence: `README.md`)
- Public API → Dialect registry: selects dialect (evidence: `sqlglot/__init__.py`)
- Public API → Tokenizer: tokenizes (evidence: `sqlglot/__init__.py`)
- Public API → SQL parser: parses SQL (evidence: `sqlglot/__init__.py`)
- Dialect registry → Tokenizer: configures tokenizer (evidence: `sqlglot/dialects/dialect.py`)
- Dialect registry → SQL parser: configures parser (evidence: `sqlglot/dialects/dialect.py`)
- Dialect registry → SQL generator: configures generator (evidence: `sqlglot/dialects/dialect.py`)
- SQL parser → Expression tree: builds nodes (evidence: `sqlglot/parser.py`)
- Expression tree → Query expressions: extends query model (evidence: `sqlglot/expressions/query.py`)
- Public API → SQL generator: generates SQL (evidence: `README.md`)
- Public API → Query optimizer: optimizes queries (evidence: `README.md`)
- Query optimizer → Scope analysis: analyzes scopes
- Query optimizer → Type annotation: annotates types
- Type annotation → Scope analysis: reads scopes (evidence: `sqlglot/optimizer/annotate_types.py`)
- Type annotation → Schema metadata: reads schema (evidence: `sqlglot/optimizer/annotate_types.py`)
- Public API → Query planner: plans SQL (evidence: `README.md`)
- Query planner → Python executor: feeds plan (evidence: `sqlglot/executor/python.py`)
- Python executor → External SQL engine: executes locally (evidence: `README.md`)
- Public API → Query lineage: analyzes lineage (evidence: `README.md`)
- Public API → AST diff: compares trees (evidence: `README.md`)
- Public API → JSONPath: queries JSONPath (evidence: `sqlglot/dialects/dialect.py`)
- Dialect grammars → SQL parser: extends dialect parsing (evidence: `sqlglot/parsers/bigquery.py`)
- Dialect grammars → SQL generator: extends dialect output