Module compiler 

Schema compiler for FraiseQL v2.

Overview

The compiler transforms GraphQL schema definitions (from Python/TypeScript decorators) into optimized, executable CompiledSchema with pre-generated SQL templates.

Compilation Pipeline

JSON Schema (from decorators)
        ↓
   Parser (parse.rs)
        ↓ [Syntax validation]

Authoring IR (ir.rs)
        ↓
  Validator (validator.rs)
        ↓ [Type checking, name validation]

Lowering (lowering.rs)
        ↓ [Build optimized IR for code generation]

  SQL Templates
        ↓ [Database-specific artifact]

   Codegen (codegen.rs)
        ↓ [Generate runtime schema metadata]

CompiledSchema JSON
        ↓
Ready for Runtime Execution

Design Principles

1. Separation of Concerns

Schema definition (what queries exist?) is kept separate from execution artifacts (how to execute them?). This allows:

• Different SQL generation strategies (optimize for OLTP vs OLAP)
• Database-specific optimizations without changing schema
• Reuse of schemas across backends
• Testing schema independently from SQL generation

2. Staged Compilation

Each phase has a specific responsibility:

• Parsing: Convert JSON → AST, syntax validation
• Validation: Type checking, semantic validation, circular reference detection
• Lowering: Optimize IR, prepare for code generation
• Codegen: Generate runtime metadata and schema introspection data

This separation makes the compiler maintainable, testable, and allows reuse of phases for different purposes.

3. Immutable Intermediate State

Each phase produces immutable data structures (AuthoringIR, CompiledSchema, etc.) This ensures:

• Reproducible builds (same input = same output)
• Thread-safe processing
• Clear data flow and dependencies
• Easy debugging and verification

Phases

1. Parse (parser.rs): JSON schema → Authoring IR

   • Syntax validation
   • AST construction

2. Validate (validator.rs): Type checking and semantic validation

   • Field type binding
   • Circular reference detection
   • Auth rule validation

3. Lower (lowering.rs): IR optimization for execution

   • Fact table extraction
   • Query optimization
   • Template preparation

4. Codegen (codegen.rs): Generate CompiledSchema

   • Runtime metadata
   • Schema introspection data
   • Field mappings

Example

use fraiseql_core::compiler::Compiler;

// Create compiler
let compiler = Compiler::new();

// Compile schema from JSON
let schema_json = r#"{
    "types": [...],
    "queries": [...]
}"#;

let compiled = compiler.compile(schema_json)?;

// Output CompiledSchema JSON
let output = compiled.to_json()?;

Re-exports

pub use aggregate_types::AggregateType;

pub use aggregate_types::AggregateTypeGenerator;

pub use aggregate_types::GroupByInput;

pub use aggregate_types::HavingInput;

pub use aggregation::AggregationPlan;

pub use aggregation::AggregationPlanner;

pub use aggregation::AggregationRequest;

pub use compilation_cache::CompilationCache;

pub use compilation_cache::CompilationCacheConfig;

pub use compilation_cache::CompilationCacheMetrics;

pub use enum_validator::EnumValidator;

pub use ir::AuthoringIR;

pub use ir::AutoParams;

pub use ir::IRArgument;

pub use ir::IRField;

pub use ir::IRMutation;

pub use ir::IRQuery;

pub use ir::IRSubscription;

pub use ir::IRType;

pub use ir::MutationOperation;

pub use parser::SchemaParser;

pub use validator::SchemaValidator;

pub use validator::ValidationError;

pub use window_functions::WindowExecutionPlan;

pub use window_functions::WindowFunction;

pub use window_functions::WindowFunctionPlanner;

Modules

aggregate_types

Aggregate Type Generation Module

aggregation

Aggregation Execution Plan Module

compilation_cache

Query compilation result caching with LRU eviction.

enum_validator

Enum type validation and parsing for GraphQL schemas.

fact_table

Fact Table Introspection Module

ir

Intermediate Representation (IR) for schema compilation.

parser

Schema parser - JSON → Authoring IR.

validator

Schema validator - validates IR for correctness.

window_functions

Window Function Planning Module

Structs

CodeGenerator

Code generator.

Compiler

Schema compiler.

CompilerConfig

Compiler configuration.

SqlTemplateGenerator

SQL template generator.

Enums

DatabaseTarget

Database target for SQL generation.