Skip to content

Architecture Overview

NL2SQL is a multi-stage orchestration pipeline built on LangGraph. A single request flows through control-plane nodes (resolution, decomposition, planning), capability-driven subgraphs (SQL agents), and an aggregation layer. The system is wired by Runtime, which instantiates registries, stores, and policy enforcement.

Key runtime components

  • Runtime initializes registries, stores, and policy enforcement.
  • build_graph() compiles the LangGraph control-plane pipeline.
  • run_with_graph() executes the pipeline with cancellation and timeout.
  • GraphState is the shared mutable state across pipeline nodes (see graph_state.md).

System topology

flowchart TD
    UserQuery[User Query] --> Runtime[run_with_graph()]
    Runtime --> Graph[build_graph()]
    Graph --> Resolver[DatasourceResolverNode]
    Resolver --> Decomposer[DecomposerNode]
    Decomposer --> Router[Scan Layer Router]
    Router --> Subgraph[SQL Agent Subgraph]
    Subgraph --> Router
    Router --> Aggregator[EngineAggregatorNode]
    Aggregator --> Synthesizer[AnswerSynthesizerNode]

    subgraph Context[Runtime]
        DS[DatasourceRegistry]
        LLM[LLMRegistry]
        VS[IndexStore and Retriever]
        SS[SchemaStore]
        RBAC[RBAC]
        AS[ArtifactStore]
    end

Subsystem architecture

flowchart LR
    User[User Query]
    Planner[Planner/Decomposer]
    Schema[Schema Store]
    Retrieval[Chunking + Retrieval]
    Validator[Validation Layer]
    Execution[Execution Layer]
    Adapter[Adapter/Plugin Backend]
    Artifacts[Artifact Store]
    Obs[Observability]

    User --> Planner
    Planner --> Retrieval
    Retrieval --> Schema
    Planner --> Validator
    Validator --> Execution
    Execution --> Adapter
    Execution --> Artifacts
    Planner --> Obs
    Execution --> Obs

Major subsystems (and responsibilities)

  • Planner / Decomposer: DecomposerNode produces stable, semantically-scoped sub-queries and, from them, a deterministic ExecutionDAG.
  • Schema Store: SchemaStore persists versioned schema snapshots with fingerprints.
  • Chunking + Retrieval: SchemaChunkBuilder produces typed chunks; the Retriever provides staged retrieval for routing and planning context, over the index store's live builds.
  • Validation layer: LogicalValidatorNode enforces schema correctness and RBAC.
  • Execution layer: ExecutorNode routes to capability-driven executor services (e.g., SQL executor).
  • Adapter / Plugin backend: adapters implement DatasourceAdapter and are discovered via entry points.
  • Artifact store: executor results are persisted as Parquet artifacts and referenced by ArtifactRef.
  • Observability: structured logs, and events that observers turn into a log, an audit log and OpenTelemetry metrics and traces.

End-to-end flow

sequenceDiagram
    participant User as User
    participant Runtime as run_with_graph
    participant Resolver as DatasourceResolverNode
    participant Decomposer as DecomposerNode
    participant Router as Scan Layer Router
    participant Subgraph as SQL Agent Subgraph
    participant Agg as EngineAggregatorNode
    participant Synth as AnswerSynthesizerNode

    User->>Runtime: user_query
    Runtime->>Resolver: GraphState
    Resolver->>Decomposer: resolved datasources
    Decomposer->>Router: ExecutionDAG over the sub-queries
    Router->>Subgraph: Send(sub_query)
    Subgraph-->>Router: ArtifactRef + diagnostics
    Router->>Agg: all scan artifacts
    Agg->>Synth: aggregated rows
    Synth-->>Runtime: final_answer + errors

Determinism

Determinism guarantees and non-determinism sources are documented in determinism.md.

Source references

  • Graph construction: packages/nl2sql/src/nl2sql/pipeline/graph.py
  • Runtime execution: packages/nl2sql/src/nl2sql/pipeline/runtime.py
  • Shared state: packages/nl2sql/src/nl2sql/pipeline/state.py
  • Context initialization: packages/nl2sql/src/nl2sql/runtime.py