Module runtime 

Runtime query executor - executes compiled queries.

Architecture

The runtime loads a CompiledSchema and executes incoming GraphQL queries by:

1. Parsing the GraphQL query
2. Matching it to a compiled query template
3. Binding variables
4. Executing the pre-compiled SQL
5. Projecting JSONB results to GraphQL response

Key Concepts

• Zero runtime compilation: All SQL is pre-compiled
• Pattern matching: Match incoming query structure to templates
• Variable binding: Safe parameter substitution
• Result projection: JSONB → GraphQL JSON transformation

Example

// Requires: a compiled schema file and a live PostgreSQL database.
// See: tests/integration/ for runnable examples.
use fraiseql_core::runtime::Executor;
use fraiseql_core::schema::CompiledSchema;
use fraiseql_core::db::postgres::PostgresAdapter;
use std::sync::Arc;

// Load compiled schema
let schema = CompiledSchema::from_json(schema_json)?;

// Create executor with a concrete adapter implementation
let adapter = Arc::new(PostgresAdapter::new("postgresql://localhost/mydb").await?);
let executor = Executor::new(schema, adapter);

// Execute GraphQL query
let query = r#"query { users { id name } }"#;
let result = executor.execute(query, None).await?;

println!("{}", result);

Re-exports

pub use aggregation::AggregationSqlGenerator;

pub use aggregation::ParameterizedAggregationSql;

pub use executor_adapter::ExecutorAdapter;

pub use field_filter::FieldAccessResult;

pub use field_filter::can_access_field;

pub use field_filter::classify_field_access;

pub use field_filter::filter_fields;

pub use jsonb_strategy::JsonbOptimizationOptions;

pub use jsonb_strategy::JsonbStrategy;

pub use query_tracing::QueryExecutionTrace;

pub use query_tracing::QueryPhaseSpan;

pub use query_tracing::QueryTraceBuilder;

pub use query_tracing::create_phase_span;

pub use query_tracing::create_query_span;

pub use sql_logger::SqlOperation;

pub use sql_logger::SqlQueryLog;

pub use sql_logger::SqlQueryLogBuilder;

pub use sql_logger::create_sql_span;

pub use subscription::ActiveSubscription;

pub use subscription::DeliveryResult;

pub use subscription::KafkaAdapter;

pub use subscription::KafkaConfig;

pub use subscription::KafkaMessage;

pub use subscription::SubscriptionError;

pub use subscription::SubscriptionEvent;

pub use subscription::SubscriptionId;

pub use subscription::SubscriptionManager;

pub use subscription::SubscriptionOperation;

pub use subscription::SubscriptionPayload;

pub use subscription::TransportAdapter;

pub use subscription::TransportManager;

pub use subscription::WebhookAdapter;

pub use subscription::WebhookConfig;

pub use subscription::WebhookPayload;

pub use subscription::extract_rls_conditions;

pub use subscription::protocol;

pub use tenant_enforcer::TenantEnforcer;

pub use window::WindowSql;

pub use window::WindowSqlGenerator;

Modules

aggregation

Runtime Aggregation SQL Generation Module

executor_adapter

Type-erased executor interface.

field_filter

Field-level RBAC filtering for runtime field projection.

input_validator

Input validation for GraphQL mutations and queries.

jsonb_strategy

JSONB field handling strategy selection

mutation_result

Mutation response parser for app.mutation_response composite rows.

query_tracing

Query execution tracing and observability instrumentation.

relay

Relay cursor encoding and decoding.

sql_logger

Structured SQL query logging and tracing.

subscription

Subscription runtime for event-driven GraphQL subscriptions.

tenant_enforcer

Multi-tenancy enforcement layer.

window

Window Function SQL Generation

Structs

AggregateQueryParser

Aggregate query parser

AggregationProjector

Aggregation result projector

BulkResult

Result of a bulk REST operation (collection-level PATCH/DELETE).

ExecutionContext

Execution context for query cancellation support.

ExecutionPlan

Execution plan for a query.

Executor

Query executor - executes compiled GraphQL queries.

ExplainPlan

Explanation of a query’s execution plan, returned by the explain endpoint.

ExplainResult

Result of EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) run against a view with real parameter values.

FieldMapping

Field mapping for projection with alias support.

ProjectionMapper

Projection mapper - maps JSONB fields to GraphQL selection set.

QueryMatch

A matched query with extracted information.

QueryMatcher

Query pattern matcher.

QueryPlanner

Query planner - selects optimal execution strategy.

ResultProjector

Result projector - high-level result transformation.

RuntimeConfig

Runtime configuration for the FraiseQL query executor.

WindowProjector

Window function result projector.

WindowQueryParser

Window query parser

Functions

extract_root_field_names

Returns the response key (alias or field name) for every root-level selection.

is_multi_root

Returns true when the query has more than one root field selection.

multi_root_queries_total

Total multi-root GraphQL queries dispatched via the parallel execution path.

suggest_similar

Return candidates from haystack whose edit distance to needle is ≤ 2.