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, false)?;

// 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 after_mutation::AfterMutationObserver;

pub use after_mutation::CommittedMutation;

pub use after_mutation::current_dispatch_depth;

pub use after_mutation::dispatched_at;

pub use aggregation::AggregationSqlGenerator;

pub use aggregation::ParameterizedAggregationSql;

pub use field_filter::FieldAccessResult;

pub use field_filter::can_access_field;

pub use field_filter::can_reference_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 mutation_result::MutationErrorShapeCheck;

pub use mutation_result::mutation_error_shape_violations;

pub use query_function::QueryFunctionRequest;

pub use query_function::QueryFunctionResolver;

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

after_mutation

The engine’s notice that a mutation committed (#1340, #1440).

aggregation

Runtime Aggregation SQL Generation Module

cascade

Cascade-spec error classification.

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.

partial_period

Partial-period awareness for pre-aggregated time-series views.

query_function

Resolution of a function-backed root query field (#1329).

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).

CascadeLimits

Response-size limits for the typed cascade surface, per the graphql-cascade spec’s security requirements (specification/16_security.md).

CountSelection

A relationship whose related rows are counted, for each row of the level above it.

EmbedSelection

A relationship to embed into each row of the level above it.

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.

MutationExecution

Core mutation execution logic.

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.

RowRead

A row-shaped read and the projection it was actually read with (#1351).

RuntimeConfig

Runtime configuration for the FraiseQL query executor.

StampContract

What a mutation’s function may stamp in its entity_type column (rulings AA 1, AG 2).

StreamedRowRead

The streamed twin of RowRead, carrying its projection for the same reason.

SubscriptionPlan

A subscription planned for one subscriber: what each event is served as.

WindowProjector

Window function result projector.

WindowQueryParser

Window query parser

WriteSelections

A write’s result selection set, guaranteed non-empty.

Functions

coerce_pagination_arg

One definition of “is this argument a row count”, re-exported so every transport that reads limit/offset/first/last fails closed the same way (#1197). A second, lenient reading of the same argument is how the bound got dropped in the first place. One definition of “is this argument a row count”, re-exported so every transport that reads limit/offset/first/last fails closed the same way (#1197). A second, lenient reading of the same argument is how the bound got dropped in the first place. One definition of “is this argument a row count”, re-exported so every transport that reads limit/offset/first/last fails closed the same way (#1197). A second, lenient reading of the same argument is how the bound got dropped in the first place. Reject a pagination argument that exceeds the configured maximum page size.

collect_variable_references

Every variable referenced by the executed operation, in document order, without duplicates.

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.

mutation_contract_errors

How many writes this process refused as a mutation contract error — an off-contract or ambiguous entity_type stamp, on either outcome (rulings AA 1, AG 3) — each rolled back.

mutation_return_selections

The selection set a transport with no selection set of its own projects a write through: every scalar field the mutation’s declared return type names.

page_size_precedence

Resolve the top-level page-size ceiling (#421) by precedence.

project_entity

Project an entity-shaped JSONB value into a GraphQL response object, mirroring the query path’s SQL projection exactly.

project_nested_lists

#489 — recase + project nested LIST-of-object fields left raw by the SQL projection.

resolve_session_variables

Resolve session variable mappings against the current security context.

stamp_nested_typenames

Stamp __typename on the nested single objects whose selection asked for it.

suggest_similar

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

suppressed_subscription_events

How many events subscription plans have suppressed since the process started.

validate_argument_names

Check that every argument in provided is one of accepted.

validate_argument_values

Check the value written at each of provided against the type declared gives that argument (§ 5.6.1), and the declared type of each variable used there against the same (§ 5.8.5).

validate_enum_argument_literals

Adjudicate enum membership for the literals a document writes at a field’s arguments (#1362).

validate_enum_argument_values

Adjudicate enum membership for the values written at a field’s arguments, from a resolved argument map (#1362).

validate_enum_variable_values

Adjudicate enum membership for supplied variable values against their own declarations — § 6.1.2, for enums (#1362).

validate_variable_types

Check that every variable definition names a type the schema publishes as an input type (GraphQL § 5.8.2).

validate_variable_uses

Check that every variable referenced by the operation is defined by it.

validate_variable_values

Check each supplied variable against the type its operation declares, and refuse a non-null variable that carries no value at all (§ 6.1.2).

validate_variables_used

Check that every variable the operation defines is also used by it (GraphQL § 5.8.4).

Type Aliases

JsonRowStream

Projected response rows delivered as the database produces them (#958).

RootErrorRenderer

Renders an engine error as a GraphQL errors entry, without its path (see RuntimeConfig::root_error_renderer).