nl2sql

ExecutorNode

Overview

• Delegates SQL execution to an executor service based on datasource capabilities.
• Persists results via the artifact store and returns ExecutorResponse.
• Sits after GeneratorNode in the SQL agent subgraph.
• Class: ExecutorNode
• Source: packages/nl2sql/src/nl2sql/pipeline/nodes/executor/node.py

---

Responsibilities

• Validate required execution inputs (SQL and datasource ID).
• Gate execution on the datasource declaring supports_sql.
• Build and submit ExecutorRequest.
• Return executor response and propagate errors.

---

Position in Execution Graph

Upstream:

• GeneratorNode

Downstream:

• Subgraph end (artifacts returned to control graph).

Trigger conditions:

• Executed when SQL generation succeeds.

flowchart LR
    Generator[GeneratorNode] --> Executor[ExecutorNode] --> EndNode[SubgraphEnd]

---

Inputs

From SubgraphExecutionState:

• generator_response.sql_draft (required)
• sub_query.datasource_id (required)
• sub_query.schema_version (optional)
• trace_id, subgraph_name, user_context

From NL2SQLContext:

• ds_registry
• tenant_id

Validation performed:

• Missing SQL → MISSING_SQL
• Missing datasource ID → MISSING_DATASOURCE_ID
• No executor for datasource → INVALID_STATE

---

Outputs

Mutations to SubgraphExecutionState:

• executor_response (ExecutorResponse)
• errors and reasoning

Side effects:

• Executes SQL against datasource via executor service.
• Persists results to artifact store.

---

Internal Flow (Step-by-Step)

1. Validate SQL and datasource ID.
2. Check the adapter declares supports_sql; otherwise return INVALID_STATE.
3. Build ExecutorRequest with trace/subgraph identifiers and schema version.
4. Execute request and return ExecutorResponse.
5. On exception, emit EXECUTOR_CRASH.

---

Contracts & Interfaces

Implements a LangGraph node callable:

def __call__(self, state: SubgraphExecutionState) -> Dict[str, Any]

Key contracts:

• ExecutorRequest
• ExecutorResponse

---

Determinism Guarantees

• Deterministic request construction.
• Execution results depend on external datasource state and are not deterministic.

---

Error Handling

Emits PipelineError with:

• MISSING_SQL
• MISSING_DATASOURCE_ID
• INVALID_STATE
• EXECUTOR_CRASH

---

Retry + Idempotency

• No internal retry logic.
• Idempotency depends on datasource and query semantics.

---

Performance Characteristics

• External I/O dominates (database execution).
• Artifact persistence writes Parquet results.

---

Observability

• Logger: executor
• Propagates executor response reasoning and errors.

---

Configuration

• tenant_id from settings.
• Executor selection based on adapter capabilities.

---

Extension Points

• Extend SqlExecutorService to alter execution behavior.
• Replace node in build_sql_agent_graph() to alter execution behavior.

---

Known Limitations

• Executes in‑process on the pipeline thread pool; there is no process sandbox (see ../../execution/isolation.md).
• No built‑in retries on transient execution failures.

---

Related Code

• packages/nl2sql/src/nl2sql/pipeline/nodes/executor/node.py
• packages/nl2sql/src/nl2sql/execution/executor/sql_executor.py

This site is open source. Improve this page.