# google/zetasql architecture

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

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

## Overview

##### Project Type and Purpose
- ZetaSQL is a C++-based SQL language component (library + tools), not a full database.
- It provides:
- A parser for GoogleSQL
- A semantic analyzer that produces a Resolved AST
- A reference execution engine (reference_impl)
- A compliance test suite
- A CLI/tool (`execute_query`) and a Java API (over gRPC)

a. Client Interfaces
- CLI / `execute_query` tool (in zetasql/tools/execute_query)
- Java client library (`java/com/google/zetasql`) via a local gRPC service (in zetasql/local_service)
- (Potential) Other engines embedding ZetaSQL public API
b. Public API Layer (`zetasql/public`)
- Exposes Analyzer, Parser, Catalog, Evaluator, Formatter, etc.
- Depends on protobuf definitions under `zetasql/public/proto`
c. Parser (`zetasql/parser`)
- Flex/Bison + TextMapper-generated code
- Produces a Parse Tree (semi-public)
d. Analyzer (`zetasql/analyzer`)
- Takes Parse Tree + Catalog + LanguageOptions
- Performs name-resolution, type-checking, semantic rewriters
- Emits a Resolved AST
e. Resolved AST (`zetasql/resolved_ast`)
- Intermediate representation with its own generated definitions
- Consumed by reference_impl, external engines, and the SQL builder
f. Reference Implementation (`zetasql/reference_impl`)
- Executes the Resolved AST (interprets query plans, functions, DML)
- Used by `execute_query` for “running” queries
g. Compliance Test Suite (`zetasql/compliance`)
- Drives Parser + Analyzer + Reference_impl to validate language conformance
h. Supporting Libraries (`zetasql/common`, `zetasql/base`)
- Utility code shared across parser, analyzer, public API, etc.
i. Build & Deployment
- Bazel WORKSPACE/BUILD files
- Dockerfile for consistent build env

1. SQL Text (from CLI or Java client)
→ Parser
2. Parser
→ Parse Tree AST
3. Parse Tree AST + Catalog + Options
→ Analyzer
4. Analyzer
→ Resolved AST
5. Resolved AST
→ Reference Implementation (executor)
6. Reference Implementation
→ Tabular results (back to CLI or via gRPC to Java)
7. Compliance Suite
→ Orchestrates steps 1–6 with known SQL tests

##### Architectural Patterns & Principles
- Layered architecture: clearly separate Parsing, Analysis, Execution, Public API.
- Reusable libraries: `public`, `common`, and `base` modules with stable interfaces.
- Pluggable catalogs: engines supply a Catalog interface to hook in their metadata/storage.
- Generated code: TextMapper for parser, Python scripts for Resolved AST definitions.
- RPC boundary: Java → gRPC → C++ local_service → Public API → Pipeline

##### Technologies & Frameworks
- C++17 (core logic)
- Bazel (build system)
- Flex/Bison, TextMapper (parser generation)
- Protocol Buffers + gRPC (local_service, public API protos)
- Java JNI + gRPC stub (Java bindings)
- Docker (build/dev environment)

##### Essential Elements to Capture
- Clear component labels (module name + path)
- External interfaces (CLI flags, gRPC endpoints)
- Build/test infra (Bazel, Docker)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Interfaces
    subgraph "Client Interfaces"
        direction TB
        CLI["CLI: execute_query"]:::client
        Java["Java API"]:::client
        Other["Other Engines"]:::client
    end

    CLI -->|"SQL Text"| Parser
    Java -->|"SQL Text via gRPC"| GRPC
    Other -->|"SQL Text"| PublicAPI

    %% gRPC boundary
    GRPC["gRPC Interface\n(local_service)"]:::client
    GRPC -->|"Calls"| PublicAPI

    click CLI "https://github.com/google/zetasql/tree/master/zetasql/tools/execute_query"
    click Java "https://github.com/google/zetasql/tree/master/java/com/google/zetasql"
    click GRPC "https://github.com/google/zetasql/tree/master/zetasql/local_service"

    %% Public API layer
    subgraph "Public API Layer"
        direction TB
        PublicAPI["zetasql/public\n(proto)"]:::client
    end
    click PublicAPI "https://github.com/google/zetasql/tree/master/zetasql/public"

    %% Parsing layer
    subgraph "Parsing Layer"
        direction TB
        Parser["zetasql/parser\n(Flex/Bison)"]:::parsing
    end
    click Parser "https://github.com/google/zetasql/tree/master/zetasql/parser"

    Parser -->|"Parse Tree"| Analyzer

    %% Analysis & AST
    subgraph "Analysis & AST"
        direction TB
        Analyzer["zetasql/analyzer"]:::analysis
        Resolved["zetasql/resolved_ast"]:::analysis
    end
    click Analyzer "https://github.com/google/zetasql/tree/master/zetasql/analyzer"
    click Resolved "https://github.com/google/zetasql/tree/master/zetasql/resolved_ast"

    Analyzer -->|"Resolved AST"| Resolved

    %% Execution
    subgraph "Execution Layer"
        direction TB
        Executor["zetasql/reference_impl"]:::execution
    end
    click Executor "https://github.com/google/zetasql/tree/master/zetasql/reference_impl"

    Resolved -->|"Interprets AST"| Executor

    Executor -->|"Results"| CLI
    Executor -->|"Results via gRPC"| Java

    %% Compliance Suite
    subgraph "Compliance Test Suite"
        direction TB
        Compliance["zetasql/compliance"]:::test
    end
    click Compliance "https://github.com/google/zetasql/tree/master/zetasql/compliance"

    Compliance --> Parser
    Compliance --> Analyzer
    Compliance --> Executor

    %% Infrastructure
    subgraph "Build & Deployment"
        direction TB
        Bazel["Bazel\n(WORKSPACE/BUILD)"]:::infra
        Docker["Dockerfile"]:::infra
    end
    click Bazel "https://github.com/google/zetasql/tree/master/WORKSPACE"
    click Bazel "https://github.com/google/zetasql/tree/master/BUILD"
    click Bazel "https://github.com/google/zetasql/tree/master/bazel/"
    click Docker "https://github.com/google/zetasql/tree/master/Dockerfile"

    Bazel --> PublicAPI
    Bazel --> Parser
    Bazel --> Analyzer
    Bazel --> Executor
    Docker --> Bazel

    %% Styles
    classDef client fill:#FDE9D9,stroke:#333
    classDef parsing fill:#D0E4FE,stroke:#333
    classDef analysis fill:#DFF2BF,stroke:#333
    classDef execution fill:#FFF2CC,stroke:#333
    classDef infra fill:#E4E4E4,stroke:#333
    classDef test fill:#F2DCDB,stroke:#333
```
