# google/googlesql architecture

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

- Interactive diagram: https://gitdiagram.com/google/googlesql
- Repository: https://github.com/google/googlesql

## Overview

GoogleSQL is a reusable SQL language, parser, and analyzer—not a database or query engine. The main workflow is SQL input → parsing → semantic analysis against an engine-provided catalog → a Resolved AST for the consuming engine. The repository also includes an optional reference execution path and an interactive query tool, plus Java APIs backed by a local RPC service. The graph emphasizes these documented product stages and sampled modules; unsampled subsystem links are omitted where their wiring is not established.

Main entry points: [`googlesql/tools/execute_query/execute_query_tool.cc`](https://github.com/google/googlesql/blob/master/googlesql/tools/execute_query/execute_query_tool.cc) (Query tool), [`googlesql/analyzer/analyzer_impl.cc`](https://github.com/google/googlesql/blob/master/googlesql/analyzer/analyzer_impl.cc) (Analysis coordinator), [`googlesql/resolved_ast/resolved_node.h`](https://github.com/google/googlesql/blob/master/googlesql/resolved_ast/resolved_node.h) (Resolved AST), [`googlesql/parser/parser.cc`](https://github.com/google/googlesql/blob/master/googlesql/parser/parser.cc) (SQL parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["SQL language"]
  node_parser["SQL parser<br/>[parser.cc]"]
  node_parse_tree["Parse tree<br/>[parse_tree.cc]"]
  node_unparser["SQL unparser<br/>[unparser.cc]"]
end

subgraph group_analysis["Semantic analysis"]
  node_public_analyzer["Analyzer API<br/>[analyzer.cc]"]
  node_analyzer_impl["Analysis coordinator<br/>[analyzer_impl.cc]"]
  node_resolver["Statement resolver<br/>[resolver.cc]"]
  node_query_resolver["Query resolution<br/>[resolver_query.cc]"]
  node_graph_resolver["Graph queries"]
  node_resolver_helpers["Query context"]
  node_catalog["Engine catalog<br/>[catalog.h]"]
  node_resolved_ast["Resolved AST<br/>[resolved_node.h]"]
  node_rewriters["AST rewrites"]
end

subgraph group_execution["Reference execution"]
  node_reference_impl["Reference execution<br/>[algebrizer.cc]"]
end

subgraph group_integration["Tools and APIs"]
  node_execute_tool["Query tool"]
  node_web_handler["Web interface"]
  node_local_service["Local RPC service<br/>[local_service.cc]"]
  node_java_client["Java client<br/>[Client.java]"]
  node_prepared_query["Prepared query<br/>[PreparedQuery.java]"]
end

node_client(("SQL consumer"))

node_client -->|"submits SQL"| node_parser
node_parser -->|"builds tree"| node_parse_tree
node_public_analyzer -->|"delegates analysis"| node_analyzer_impl
node_analyzer_impl -.->|"resolves statements"| node_resolver
node_resolver -.->|"resolves queries"| node_query_resolver
node_query_resolver -->|"uses context"| node_resolver_helpers
node_query_resolver -->|"resolves graph SQL"| node_graph_resolver
node_analyzer_impl -.->|"looks up names"| node_catalog
node_analyzer_impl -->|"produces AST"| node_resolved_ast
node_resolved_ast -.->|"rewrites AST"| node_rewriters
node_resolved_ast -.->|"renders SQL"| node_unparser
node_resolved_ast -->|"feeds execution"| node_reference_impl
node_client -->|"runs query"| node_execute_tool
node_execute_tool -->|"parses query"| node_parser
node_execute_tool -->|"analyzes query"| node_public_analyzer
node_execute_tool -->|"runs query"| node_reference_impl
node_web_handler -->|"dispatches query"| node_execute_tool
node_prepared_query -->|"calls service"| node_java_client
node_java_client -->|"uses local RPC"| node_local_service
node_local_service -->|"parses requests"| node_parser
node_local_service -->|"analyzes requests"| node_public_analyzer

click node_parser "https://github.com/google/googlesql/blob/master/googlesql/parser/parser.cc"
click node_parse_tree "https://github.com/google/googlesql/blob/master/googlesql/parser/parse_tree.cc"
click node_unparser "https://github.com/google/googlesql/blob/master/googlesql/parser/unparser.cc"
click node_public_analyzer "https://github.com/google/googlesql/blob/master/googlesql/public/analyzer.cc"
click node_analyzer_impl "https://github.com/google/googlesql/blob/master/googlesql/analyzer/analyzer_impl.cc"
click node_resolver "https://github.com/google/googlesql/blob/master/googlesql/analyzer/resolver.cc"
click node_query_resolver "https://github.com/google/googlesql/blob/master/googlesql/analyzer/resolver_query.cc"
click node_graph_resolver "https://github.com/google/googlesql/blob/master/googlesql/analyzer/graph_query_resolver.cc"
click node_resolver_helpers "https://github.com/google/googlesql/blob/master/googlesql/analyzer/query_resolver_helper.h"
click node_catalog "https://github.com/google/googlesql/blob/master/googlesql/public/catalog.h"
click node_resolved_ast "https://github.com/google/googlesql/blob/master/googlesql/resolved_ast/resolved_node.h"
click node_rewriters "https://github.com/google/googlesql/tree/master/googlesql/analyzer/rewriters"
click node_reference_impl "https://github.com/google/googlesql/blob/master/googlesql/reference_impl/algebrizer.cc"
click node_execute_tool "https://github.com/google/googlesql/blob/master/googlesql/tools/execute_query/execute_query_tool.cc"
click node_web_handler "https://github.com/google/googlesql/blob/master/googlesql/tools/execute_query/execute_query_web_handler.cc"
click node_local_service "https://github.com/google/googlesql/blob/master/googlesql/local_service/local_service.cc"
click node_java_client "https://github.com/google/googlesql/blob/master/java/com/google/googlesql/Client.java"
click node_prepared_query "https://github.com/google/googlesql/blob/master/java/com/google/googlesql/PreparedQuery.java"

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_parser,node_parse_tree,node_unparser toneBlue
class node_public_analyzer,node_analyzer_impl,node_resolver,node_query_resolver,node_graph_resolver,node_resolver_helpers,node_catalog,node_resolved_ast,node_rewriters toneAmber
class node_reference_impl toneMint
class node_execute_tool,node_web_handler,node_local_service,node_java_client,node_prepared_query toneRose
class node_client toneIndigo
```

## Components

### SQL language

- [SQL parser](https://github.com/google/googlesql/blob/master/googlesql/parser/parser.cc): `googlesql/parser/parser.cc`
- [Parse tree](https://github.com/google/googlesql/blob/master/googlesql/parser/parse_tree.cc): `googlesql/parser/parse_tree.cc`
- [SQL unparser](https://github.com/google/googlesql/blob/master/googlesql/parser/unparser.cc): `googlesql/parser/unparser.cc`

### Semantic analysis

- [Analyzer API](https://github.com/google/googlesql/blob/master/googlesql/public/analyzer.cc): `googlesql/public/analyzer.cc`
- [Analysis coordinator](https://github.com/google/googlesql/blob/master/googlesql/analyzer/analyzer_impl.cc): `googlesql/analyzer/analyzer_impl.cc`
- [Statement resolver](https://github.com/google/googlesql/blob/master/googlesql/analyzer/resolver.cc): `googlesql/analyzer/resolver.cc`
- [Query resolution](https://github.com/google/googlesql/blob/master/googlesql/analyzer/resolver_query.cc): `googlesql/analyzer/resolver_query.cc`
- [Graph queries](https://github.com/google/googlesql/blob/master/googlesql/analyzer/graph_query_resolver.cc): `googlesql/analyzer/graph_query_resolver.cc`
- [Query context](https://github.com/google/googlesql/blob/master/googlesql/analyzer/query_resolver_helper.h): `googlesql/analyzer/query_resolver_helper.h`
- [Engine catalog](https://github.com/google/googlesql/blob/master/googlesql/public/catalog.h): `googlesql/public/catalog.h`
- [Resolved AST](https://github.com/google/googlesql/blob/master/googlesql/resolved_ast/resolved_node.h): `googlesql/resolved_ast/resolved_node.h`
- [AST rewrites](https://github.com/google/googlesql/tree/master/googlesql/analyzer/rewriters): `googlesql/analyzer/rewriters`

### Reference execution

- [Reference execution](https://github.com/google/googlesql/blob/master/googlesql/reference_impl/algebrizer.cc): `googlesql/reference_impl/algebrizer.cc`

### Tools and APIs

- [Query tool](https://github.com/google/googlesql/blob/master/googlesql/tools/execute_query/execute_query_tool.cc): `googlesql/tools/execute_query/execute_query_tool.cc`
- [Web interface](https://github.com/google/googlesql/blob/master/googlesql/tools/execute_query/execute_query_web_handler.cc): `googlesql/tools/execute_query/execute_query_web_handler.cc`
- [Local RPC service](https://github.com/google/googlesql/blob/master/googlesql/local_service/local_service.cc): `googlesql/local_service/local_service.cc`
- [Java client](https://github.com/google/googlesql/blob/master/java/com/google/googlesql/Client.java): `java/com/google/googlesql/Client.java`
- [Prepared query](https://github.com/google/googlesql/blob/master/java/com/google/googlesql/PreparedQuery.java): `java/com/google/googlesql/PreparedQuery.java`

### Other components

- **SQL consumer**

## Connections

- SQL consumer → SQL parser: submits SQL (evidence: `README.md`)
- SQL parser → Parse tree: builds tree (evidence: `README.md`)
- Analyzer API → Analysis coordinator: delegates analysis
- Analysis coordinator → Statement resolver: resolves statements
- Statement resolver → Query resolution: resolves queries
- Query resolution → Query context: uses context (evidence: `googlesql/analyzer/query_resolver_helper.h`)
- Query resolution → Graph queries: resolves graph SQL (evidence: `googlesql/analyzer/graph_query_resolver.cc`)
- Analysis coordinator → Engine catalog: looks up names
- Analysis coordinator → Resolved AST: produces AST (evidence: `README.md`)
- Resolved AST → AST rewrites: rewrites AST (evidence: `googlesql/analyzer/rewriters/rewrite_subpipeline.cc`)
- Resolved AST → SQL unparser: renders SQL
- Resolved AST → Reference execution: feeds execution (evidence: `README.md`)
- SQL consumer → Query tool: runs query (evidence: `README.md`)
- Query tool → SQL parser: parses query (evidence: `googlesql/tools/execute_query/execute_query_tool.cc`)
- Query tool → Analyzer API: analyzes query (evidence: `googlesql/tools/execute_query/execute_query_tool.cc`)
- Query tool → Reference execution: runs query (evidence: `README.md`)
- Web interface → Query tool: dispatches query (evidence: `googlesql/tools/execute_query/execute_query_web_handler.cc`)
- Prepared query → Java client: calls service (evidence: `java/com/google/googlesql/PreparedQuery.java`)
- Java client → Local RPC service: uses local RPC (evidence: `README.md`)
- Local RPC service → SQL parser: parses requests (evidence: `googlesql/local_service/local_service.cc`)
- Local RPC service → Analyzer API: analyzes requests (evidence: `googlesql/local_service/local_service.cc`)