How google/zetasql works
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)