Struct CompiledSchema 

pub struct CompiledSchema {

    pub types: Vec<TypeDefinition>,
    pub enums: Vec<EnumDefinition>,
    pub input_types: Vec<InputObjectDefinition>,
    pub interfaces: Vec<InterfaceDefinition>,
    pub unions: Vec<UnionDefinition>,
    pub queries: Vec<QueryDefinition>,
    pub mutations: Vec<MutationDefinition>,
    pub subscriptions: Vec<SubscriptionDefinition>,
    pub directives: Vec<DirectiveDefinition>,
    pub fact_tables: HashMap<String, FactTableMetadata>,
    pub observers: Vec<ObserverDefinition>,
    pub subscribable: Vec<SubscribableEntity>,
    pub operation_cost_weights: HashMap<String, usize>,
    pub federation: Option<FederationConfig>,
    pub security: Option<SecurityConfig>,
    pub observers_config: Option<ObserversConfig>,
    pub subscriptions_config: Option<SubscriptionsConfig>,
    pub validation_config: Option<ValidationConfig>,
    pub debug_config: Option<DebugConfig>,
    pub mcp_config: Option<McpConfig>,
    pub rest_config: Option<RestConfig>,
    pub grpc_config: Option<GrpcConfig>,
    pub changelog: Option<ChangelogConfig>,
    pub session_variables: SessionVariablesConfig,
    pub hierarchies_config: Option<HierarchiesConfig>,
    pub naming_convention: NamingConvention,
    pub naming_acronyms: Vec<String>,
    pub schema_format_version: Option<u32>,
    pub schema_sdl: Option<String>,
    pub custom_scalars: CustomTypeRegistry,
    pub query_index: HashMap<String, usize>,
    pub mutation_index: HashMap<String, usize>,
    pub subscription_index: HashMap<String, usize>,
}

Complete compiled schema - all type information for serving.

This is the central type that holds the entire GraphQL schema after compilation from any supported authoring language.

Example

use fraiseql_core::schema::CompiledSchema;

let json = r#"{
    "types": [],
    "queries": [],
    "mutations": [],
    "subscriptions": []
}"#;

let schema = CompiledSchema::from_json(json, false).unwrap();
assert_eq!(schema.types.len(), 0);

Fields

types: Vec<TypeDefinition>

GraphQL object type definitions.

enums: Vec<EnumDefinition>

GraphQL enum type definitions.

input_types: Vec<InputObjectDefinition>

GraphQL input object type definitions.

interfaces: Vec<InterfaceDefinition>

GraphQL interface type definitions.

unions: Vec<UnionDefinition>

GraphQL union type definitions.

queries: Vec<QueryDefinition>

GraphQL query definitions.

mutations: Vec<MutationDefinition>

GraphQL mutation definitions.

subscriptions: Vec<SubscriptionDefinition>

GraphQL subscription definitions.

directives: Vec<DirectiveDefinition>

Custom directive definitions. These are user-defined directives beyond the built-in @skip, @include, @deprecated.

fact_tables: HashMap<String, FactTableMetadata>

Fact table metadata (for analytics queries). Key: table name (e.g., tf_sales)

observers: Vec<ObserverDefinition>

Observer definitions (database change event listeners).

subscribable: Vec<SubscribableEntity>

@subscribable declarations (#366): GraphQL types whose underlying table(s) get the shipped external-write capture trigger.

Aggregated by the compiler from each type’s @subscribable(tables=[...]) annotation; consumed by generate_capture_trigger_ddl to emit per-table capture triggers. Empty (and omitted from the compiled JSON) when no type is subscribable — so a schema that predates this field deserializes and re-serializes byte-for-byte unchanged.

operation_cost_weights: HashMap<String, usize>

Per-operation @cost(weight: N) overrides (#379): root query/mutation name → manual cost weight, consulted by the runtime per-tenant cost-budget check (estimate_query_cost) so a top-level operation counts as exactly N instead of its walked subtree complexity. Aggregated by the compiler from each operation’s @cost annotation. Empty (and omitted from the compiled JSON) when no operation carries @cost — so a schema that predates this field deserializes and re-serializes byte-for-byte unchanged.

federation: Option<FederationConfig>

Federation metadata for Apollo Federation v2 support.

security: Option<SecurityConfig>

Security configuration (from fraiseql.toml).

observers_config: Option<ObserversConfig>

Observers/event system configuration (from fraiseql.toml).

Contains backend connection settings (redis_url, nats_url, etc.) and event handler definitions compiled from the [observers] TOML section.

subscriptions_config: Option<SubscriptionsConfig>

WebSocket subscription configuration (hooks, limits). Compiled from the [subscriptions] TOML section.

validation_config: Option<ValidationConfig>

Query validation config (depth/complexity limits). Compiled from the [validation] TOML section.

debug_config: Option<DebugConfig>

Debug/development configuration. Compiled from the [debug] TOML section.

mcp_config: Option<McpConfig>

MCP (Model Context Protocol) server configuration. Compiled from the [mcp] TOML section.

rest_config: Option<RestConfig>

REST transport configuration. Compiled from the [rest] TOML section.

grpc_config: Option<GrpcConfig>

gRPC transport configuration. Compiled from the [grpc] TOML section.

changelog: Option<ChangelogConfig>

Changelog GraphQL-exposure configuration.

Compiled from the [changelog] TOML section. When present with expose = true, the compiler injects the EntityChangeLog / TransportCheckpoint types plus their cursor query, point-lookup query, and checkpoint upsert mutation. None when the block is absent (the default).

session_variables: SessionVariablesConfig

Session variable injection configuration.

When populated, the executor calls PostgreSQL set_config() before each mutation, injecting per-request values (JWT claims, HTTP headers, literals) as transaction-scoped settings. SQL functions read these via current_setting('app.tenant_id', true).

Compiled from the [session_variables] TOML section.

hierarchies_config: Option<HierarchiesConfig>

Hierarchy definitions for ID-based ltree operators.

Maps hierarchy names to table/path_column pairs. Compiled from the [hierarchies] TOML section. Used at runtime to resolve HierarchyContext for descendantOfId / ancestorOfId WHERE clause generation.

naming_convention: NamingConvention

Naming convention for GraphQL operation names.

When set to CamelCase, operation names are converted from snake_case (e.g., create_dns_server → createDnsServer) in the introspection schema and lookup indexes. Compiled from [fraiseql] in fraiseql.toml.

naming_acronyms: Vec<String>

Acronyms whose internal digit stays attached when resolving a GraphQL field name back to its snake_case JSONB key (e.g. s3, ipv4, oauth2). Added to the built-in defaults at boot via fraiseql_db::utils::set_runtime_acronyms. Skipped when empty so a schema with no project acronyms serializes byte-for-byte as before this field existed (no schema-hash churn; back-compat on load).

schema_format_version: Option<u32>

Schema format version emitted by the compiler.

Used to detect runtime/compiler skew. If present and ≠ CURRENT_SCHEMA_FORMAT_VERSION, validate_format_version() returns an error.

schema_sdl: Option<String>

Raw GraphQL schema as string (for SDL generation).

custom_scalars: CustomTypeRegistry

Custom scalar type registry.

Contains definitions for custom scalar types defined in the schema. Built during code generation from IRScalar definitions. Not serialized - populated at runtime from ir.scalars.

query_index: HashMap<String, usize>

O(1) lookup index: query name → index into self.queries. Built at construction time by build_indexes(); not serialized. Populated automatically by from_json(); call build_indexes() after direct mutation of self.queries.

mutation_index: HashMap<String, usize>

O(1) lookup index: mutation name → index into self.mutations. Built at construction time by build_indexes(); not serialized. Populated automatically by from_json(); call build_indexes() after direct mutation of self.mutations.

subscription_index: HashMap<String, usize>

O(1) lookup index: subscription name → index into self.subscriptions. Built at construction time by build_indexes(); not serialized. Populated automatically by from_json(); call build_indexes() after direct mutation of self.subscriptions.

Implementations

impl CompiledSchema

pub fn new() -> Self

Create empty schema.

impl CompiledSchema

pub fn validate_format_version(&self) -> Result<(), String>

Verify that the compiled schema was produced by a compatible compiler version.

Schemas without a schema_format_version field (produced before v2.1) are accepted with a warning. Schemas with a mismatched version are rejected to prevent silent data corruption from structural changes.

Errors

Returns an error string if the version is present and incompatible.

pub fn add_fact_table( &mut self, table_name: String, metadata: FactTableMetadata, )

Register fact table metadata.

Arguments

• table_name - Fact table name (e.g., tf_sales)
• metadata - Typed FactTableMetadata

pub fn get_fact_table(&self, name: &str) -> Option<&FactTableMetadata>

Get fact table metadata by name.

Arguments

• name - Fact table name

Returns

Fact table metadata if found

pub fn list_fact_tables(&self) -> Vec<&str>

List all fact table names.

Returns

Vector of fact table names

pub fn has_fact_tables(&self) -> bool

Check if schema contains any fact tables.

pub fn find_observer(&self, name: &str) -> Option<&ObserverDefinition>

Find an observer definition by name.

pub fn find_observers_for_entity( &self, entity: &str, ) -> Vec<&ObserverDefinition>

Get all observers for a specific entity type.

pub fn find_observers_for_event(&self, event: &str) -> Vec<&ObserverDefinition>

Get all observers for a specific event type (INSERT, UPDATE, DELETE).

pub const fn has_observers(&self) -> bool

Check if schema contains any observers.

pub const fn observer_count(&self) -> usize

Get total number of observers.

pub const fn federation_metadata(&self) -> Option<()>

Stub federation metadata when federation feature is disabled.

pub const fn security_config(&self) -> Option<&SecurityConfig>

Get security configuration from schema.

Returns

Security configuration if present (includes role definitions)

pub fn is_multi_tenant(&self) -> bool

Returns true if this schema declares a multi-tenant deployment.

Multi-tenant schemas require Row-Level Security (RLS) to be active whenever query result caching is enabled. Without RLS, all tenants sharing the same query parameters would receive the same cached response.

Detection is based on security.multi_tenant in the compiled schema JSON.

pub fn tenancy_mode(&self) -> TenancyMode

Returns the tenancy isolation mode configured for this schema.

Defaults to TenancyMode::None when no security or tenancy configuration is present, meaning single-tenant operation with no isolation machinery.

pub fn tenancy_config(&self) -> Option<&TenancyConfig>

Returns the tenancy configuration, if present.

Returns None when no security configuration exists. Returns the default TenancyConfig (mode=none) when security exists but tenancy is not explicitly configured.

pub fn find_role(&self, role_name: &str) -> Option<RoleDefinition>

Find a role definition by name.

Arguments

• role_name - Name of the role to find

Returns

Role definition if found

pub fn get_role_scopes(&self, role_name: &str) -> Vec<String>

Get scopes for a role.

Arguments

• role_name - Name of the role

Returns

Vector of scopes granted to the role

pub fn role_has_scope(&self, role_name: &str, scope: &str) -> bool

Check if a role has a specific scope.

Arguments

• role_name - Name of the role
• scope - Scope to check for

Returns

true if role has the scope, false otherwise

pub fn has_rls_configured(&self) -> bool

Returns true if Row-Level Security policies are declared in this schema.

Used at server startup to validate that caching is safe for multi-tenant deployments. When caching is enabled and no RLS policies are configured, the server emits a startup warning about potential data leakage.

Example

use fraiseql_core::schema::CompiledSchema;

let schema = CompiledSchema::default();
assert!(!schema.has_rls_configured());

pub fn raw_schema(&self) -> String

Get raw GraphQL schema SDL.

Returns

Raw schema string if available, otherwise generates from type definitions

pub fn validate(&self) -> Result<(), Vec<String>>

Validate the schema for internal consistency.

Checks:

• All type references resolve to defined types
• No duplicate type/operation names
• Required fields have valid types

Errors

Returns list of validation errors if schema is invalid.

impl CompiledSchema

pub fn build_indexes(&mut self)

Build O(1) lookup indexes for queries, mutations, and subscriptions.

Called automatically by from_json(). Must be called manually after any direct mutation of self.queries, self.mutations, or self.subscriptions.

pub fn display_name(&self, name: &str) -> String

Return the display name for an operation, applying the naming convention.

When naming_convention is CamelCase, converts snake_case names to camelCase (e.g., create_dns_server → createDnsServer). When Preserve, returns the name unchanged.

pub fn find_type(&self, name: &str) -> Option<&TypeDefinition>

Find a type definition by name.

pub fn type_has_gated_field(&self, type_name: &str) -> bool

Whether the named type has any policy-gated field (FieldDefinition::authorize).

Used by projection paths that do not (yet) run the dynamic field authorizer to fail closed conservatively when a gated type could be projected (#423).

pub fn has_any_authorize_field(&self) -> bool

Whether any object type in the schema declares a policy-gated field (#423).

Used by projection paths with a dynamic/unknown result type (Relay node, federation _entities) to fail closed when field-level authorization is in use but cannot yet be enforced on that path.

pub fn find_enum(&self, name: &str) -> Option<&EnumDefinition>

Find an enum definition by name.

pub fn find_input_type(&self, name: &str) -> Option<&InputObjectDefinition>

Find an input object definition by name.

pub fn find_interface(&self, name: &str) -> Option<&InterfaceDefinition>

Find an interface definition by name.

pub fn find_implementors(&self, interface_name: &str) -> Vec<&TypeDefinition>

Find all types that implement a given interface.

pub fn find_union(&self, name: &str) -> Option<&UnionDefinition>

Find a union definition by name.

pub fn find_query(&self, name: &str) -> Option<&QueryDefinition>

Find a query definition by name.

Uses the O(1) pre-built index when available; falls back to O(n) linear scan for schemas built directly in tests without calling build_indexes().

If the exact name is not found, retries with to_snake_case(name) to handle camelCase → snake_case normalization (e.g. dnsServers → dns_servers). This supports schemas compiled before the SDK camelCase migration.

pub fn find_mutation(&self, name: &str) -> Option<&MutationDefinition>

Find a mutation definition by name.

Uses the O(1) pre-built index when available; falls back to O(n) linear scan for schemas built directly in tests without calling build_indexes().

If the exact name is not found, retries with to_snake_case(name) to handle camelCase → snake_case normalization. This supports schemas compiled before the SDK camelCase migration.

pub fn find_subscription(&self, name: &str) -> Option<&SubscriptionDefinition>

Find a subscription definition by name.

Uses the O(1) pre-built index when available; falls back to O(n) linear scan for schemas built directly in tests without calling build_indexes().

If the exact name is not found, retries with to_snake_case(name) to handle camelCase → snake_case normalization. This supports schemas compiled before the SDK camelCase migration.

pub fn find_directive(&self, name: &str) -> Option<&DirectiveDefinition>

Find a custom directive definition by name.

pub const fn operation_count(&self) -> usize

Get total number of operations (queries + mutations + subscriptions).

impl CompiledSchema

pub fn from_json( json: &str, strict_integrity: bool, ) -> Result<Self, FraiseQLError>

Deserialize from JSON string.

This is the primary way to create a schema from any authoring language. The authoring language emits schema.json; fraiseql-cli compile produces schema.compiled.json; Rust deserializes and owns the result.

Integrity Checking

fraiseql-cli compile embeds a _content_hash field (SHA-256 of the compiled JSON body, first 16 bytes as lowercase hex) in the compiled output. This function extracts that field, recomputes the hash over the remaining JSON, and compares.

• strict_integrity = true: missing or mismatched hash returns Err.
• strict_integrity = false: missing hash logs a warning; mismatch logs a warning but proceeds (backwards compatibility for schemas compiled without _content_hash).

Errors

Returns error if JSON is malformed or doesn’t match schema structure.

Example

use fraiseql_core::schema::CompiledSchema;

let json = r#"{"types": [], "queries": [], "mutations": [], "subscriptions": []}"#;
let schema = CompiledSchema::from_json(json, false).unwrap();

pub fn to_json(&self) -> Result<String, Error>

Serialize to JSON string.

Errors

Returns error if serialization fails (should not happen for valid schema).

pub fn to_json_pretty(&self) -> Result<String, Error>

Serialize to pretty JSON string (for debugging/config files).

Errors

Returns error if serialization fails.

pub fn content_hash(&self) -> String

Returns a 32-character hex SHA-256 content hash of this schema’s canonical JSON.

Use as schema_version when constructing CachedDatabaseAdapter to guarantee cache invalidation on any schema change, regardless of whether the package version was bumped.

Two schemas that differ by even one field will produce different hashes. The same schema serialised twice always produces the same hash (stable).

Panics

Does not panic — CompiledSchema always serialises to valid JSON.

Example

use fraiseql_core::schema::CompiledSchema;

let schema = CompiledSchema::default();
let hash = schema.content_hash();
assert_eq!(hash.len(), 32); // 16 bytes → 32 hex chars

Trait Implementations

impl Clone for CompiledSchema

fn clone(&self) -> CompiledSchema

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CompiledSchema

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CompiledSchema

fn default() -> CompiledSchema

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for CompiledSchema

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for CompiledSchema

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for CompiledSchema

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.