Engine configuration reference

Reference for the YAML configuration file that configures a Firebolt engine.

These parameter descriptions are auto-generated first drafts and are still under review.

A Firebolt engine reads its settings from a single YAML configuration file. This page documents every supported parameter, grouped by the top-level block it belongs to, along with its type and default value.

The file is a nested YAML document. Top-level blocks — such as auth, engine, execution, and storage — group related settings, and each block contains scalar values or further nested blocks. Every file must declare the schema version it targets:

schema_version: "1.0"

auth:
  mode: native
engine:
  id: my-engine
storage:
  type: s3
  bucket_name: my-bucket

Value types

Each scalar parameter has one of the following types. The Type column in the reference below uses these names.

Type	Description	Example
string	Free-form text.	my-engine
integer	A whole number.	8123
float	A decimal number.	0.9
boolean	true or false.	true
duration	A time span written as a number with a unit suffix (s, m, h, d).	30s, 1h, 1d
byte size	A size in bytes, optionally with a unit suffix (KB, MB, GB, GiB, …).	8GiB, 100MB
ulid	A ULID identifier.	01KP98J0000000000000000000
enum	One of a fixed set of values, listed in the parameter’s description.	s3

Parameter kinds

The Type column also tells you an entry’s kind:

• A scalar holds a single value of one of the types above (for example string or duration).
• An object (shown as object) is a nested block of named parameters.
• A list (shown as object[]) is a sequence of objects; every element repeats the same structure.

The Default Value column shows the value used when you omit a parameter. Whether a parameter is required can depend on which parent block or sibling option you set, so each parameter’s description explains when it’s needed.

Overview

auth

Path	Type	Default Value	Description
auth ↓	object	{}	Authentication settings for the database.
auth.instance_id ↓	string	https://localhost	Identifier for this instance.
auth.mode ↓	enum	disabled	Selects how clients authenticate.
auth.native ↓	object	null	Settings for native authentication, used when auth.mode is native.
auth.native.initial_user ↓	object	null	Bootstrap user created on startup so you can connect to a fresh instance.
auth.native.initial_user.name ↓	string		Username for the bootstrap user created at startup in native authentication mode.
auth.native.initial_user.password ↓	string		Password for the bootstrap user created at startup in native authentication mode.
auth.native.jwt ↓	object	{}	JWT settings for native mode.
auth.native.jwt.clock_skew_tolerance ↓	duration	30s	Allowed clock skew when validating time-based JWT claims such as exp, nbf, and iat.
auth.native.jwt.max_token_age ↓	duration	1d	Maximum age of a token, measured from its iat (issued-at) claim.
auth.native.jwt.token_expiry ↓	duration	1h	Lifetime of the access tokens that the engine issues.
auth.native.signing_algorithm ↓	enum	RS256	Algorithm used to sign issued tokens.
auth.native.signing_keys ↓	object[]	[]	Keys used to sign issued tokens.
auth.native.signing_keys[*].id ↓	string		Identifier for this signing key.
auth.native.signing_keys[*].private_key_path ↓	string		Filesystem path to the PEM-encoded private key used for signing.
auth.oidc ↓	object	null	Settings for OIDC authentication, used when auth.mode is oidc.
auth.oidc.jwt ↓	object	{}	JWT validation settings for OIDC mode.
auth.oidc.jwt.clock_skew_tolerance ↓	duration	30s	Allowed clock skew when validating time-based JWT claims such as exp, nbf, and iat.
auth.oidc.jwt.max_token_age ↓	duration	1d	Maximum age of a token, measured from its iat (issued-at) claim.
auth.oidc.postgres_password_fallback_enabled ↓	boolean	false	When enabled, connections over the Postgres wire protocol can fall back to password-based authentication instead of OIDC tokens.
auth.oidc.providers ↓	object[]	[]	Trusted OIDC identity providers.
auth.oidc.providers[*].discovery ↓	object	{}	Controls how the engine refreshes the provider’s discovery document.
auth.oidc.providers[*].discovery.refresh_interval ↓	duration	1d	How often the engine re-fetches the provider’s OpenID configuration (discovery) document.
auth.oidc.providers[*].discovery_url ↓	string		URL of the provider’s OpenID Connect discovery document — the .../.well-known/openid-configuration endpoint.
auth.oidc.providers[*].jit_provisioning ↓	object	{}	Just-in-time (JIT) provisioning settings.
auth.oidc.providers[*].jit_provisioning.default_role ↓	string	public	Role granted to users created through just-in-time provisioning.
auth.oidc.providers[*].jit_provisioning.enabled ↓	boolean	false	Whether to create users automatically on first login through this provider.
auth.oidc.providers[*].jwks ↓	object	{}	Controls how the engine caches the provider’s JSON Web Key Set (JWKS), which it uses to verify token signatures.
auth.oidc.providers[*].jwks.cache_ttl ↓	duration	1h	How long the engine caches the provider’s JWKS document before re-fetching it.
auth.oidc.providers[*].name ↓	string		Name or alias for this provider.
auth.oidc.providers[*].username_mapping ↓	string		Template that maps OIDC token claims to an engine username.

data_source_encryption

Path	Type	Default Value	Description
data_source_encryption ↓	object	{}	Encryption of external data-source (location and table) credentials.
data_source_encryption.decrypted_cache_timeout_ms ↓	integer	600000	How long, in milliseconds, a decrypted data-source credential is cached in memory.
data_source_encryption.enabled ↓	boolean	false	Encrypt external data-source credentials with KMS before storing them in the metadata service.
data_source_encryption.kms_arn ↓	string	“	ARN of the KMS key used to encrypt data-source credentials.
data_source_encryption.local_kms_access_key ↓	string	“	Access key for the local KMS service.
data_source_encryption.local_kms_endpoint ↓	string	“	Endpoint URL of the local KMS service.
data_source_encryption.local_kms_secret_key ↓	string	“	Secret key for the local KMS service.
data_source_encryption.skip_s3_access_check ↓	boolean	false	Skip validating S3 access when creating an external location or table.
data_source_encryption.use_local_kms ↓	boolean	false	Use a local KMS-compatible endpoint (for example, localstack) instead of AWS KMS.

endpoints

Path	Type	Default Value	Description
endpoints ↓	object	{}	Network listener configuration that defines how clients connect to the engine over HTTP and the PostgreSQL wire protocol.
endpoints.http ↓	object	{}	HTTP listener configuration for the query API.
endpoints.http.listeners ↓	object[]	[]	List of HTTP listener bindings.
endpoints.http.listeners[*].path ↓	string	null	Filesystem path for a Unix-domain-socket HTTP listener.
endpoints.http.listeners[*].port ↓	integer	null	TCP port for an HTTP listener (for example, 8123).
endpoints.http.listeners[*].type ↓	enum		Listener transport: tcp (network socket) or unix (Unix-domain socket).
endpoints.postgres ↓	object	{}	PostgreSQL wire-protocol listener configuration.
endpoints.postgres.listeners ↓	object[]	[]	List of PostgreSQL listener bindings.
endpoints.postgres.listeners[*].path ↓	string	null	Not used for PostgreSQL listeners; Unix-domain sockets aren’t supported for the Postgres protocol.
endpoints.postgres.listeners[*].port ↓	integer	null	TCP port for PostgreSQL connections (for example, 5432).
endpoints.postgres.listeners[*].type ↓	enum		Listener transport for PostgreSQL.
endpoints.unix_socket_only ↓	boolean	false	When enabled, the server exposes every endpoint (the query API, health check, metrics, the PostgreSQL wire protocol, and its internal services) over Unix domain sockets under the data directory instead of fixed TCP ports.

engine

Path	Type	Default Value	Description
engine ↓	object	{}	Configuration for the query execution engine — instance identity, node topology, memory limits, tablet eviction, and multi-cluster broadcasting.
engine.auto_vacuum ↓	object	null	Background auto-vacuum tuning.
engine.auto_vacuum.assessment_frequency ↓	integer	null	How frequently the engine assesses tablets to decide whether an auto-vacuum job is needed.
engine.auto_vacuum.debug_sleep_before_commit_ms ↓	integer	null	Debugging knob: artificial delay, in milliseconds, inserted before an auto-vacuum job commits.
engine.auto_vacuum.enabled ↓	boolean	null	Whether background auto-vacuum runs.
engine.auto_vacuum.max_concurrency ↓	integer	null	Maximum number of auto-vacuum jobs allowed to run concurrently.
engine.auto_vacuum.max_tablets_in_job ↓	integer	null	Maximum number of tablets processed in a single auto-vacuum job.
engine.auto_vacuum.memory_allowance ↓	float	null	Fraction of engine memory that auto-vacuum may use while running.
engine.auto_vacuum.min_bad_tablets_threshold ↓	integer	null	Minimum number of tablets needing cleanup before an auto-vacuum job is triggered.
engine.auto_vacuum.run_on_first_dml ↓	boolean	null	Whether to trigger an auto-vacuum assessment on the first DML statement after startup.
engine.cluster_id ↓	string	null	Unique identifier for this engine cluster.
engine.cluster_ordinal ↓	integer	null	Zero-based ordinal of this cluster within a multi-cluster deployment.
engine.eviction ↓	object	{}	Tablet memory-eviction policy, controlling when tablets are evicted from in-memory caches to disk as memory fills.
engine.eviction.max_tablets_per_mb_of_total_memory ↓	float	1.5	Upper bound on how many tablets the node keeps resident, expressed as tablets per MB of total memory.
engine.eviction.prefetch_space_ratio_threshold ↓	float	0.13	Fraction of memory (0.0–1.0) reserved for tablet prefetching before eviction pressure throttles it.
engine.eviction.tablet_eviction_soft_threshold ↓	float	0.4	Memory-usage fraction (0.0–1.0, default 0.4) that governs soft eviction of least-recently-used tablets.
engine.eviction.tablet_eviction_threshold ↓	float	0.2	Memory-usage fraction (0.0–1.0, default 0.2) that governs hard eviction of tablets from memory to reclaim space.
engine.eviction.tablet_min_ttl_before_memory_eviction_seconds ↓	integer	1800	Minimum age in seconds a tablet must reach before it becomes eligible for eviction from memory.
engine.eviction.tablet_ttl_before_full_eviction_seconds ↓	integer	21600	Age in seconds after which an unused tablet is fully evicted from the node — dropped from the local disk cache to reclaim space.
engine.id ↓	string	default-engine-id	Human-readable identifier for this engine, shown in logs, metrics, and system views.
engine.max_server_memory_usage ↓	byte size	0B	Maximum memory the server may use (bytes, or a size such as 8GiB).
engine.max_server_memory_usage_headroom_bytes ↓	byte size	0B	Amount of host memory to keep free (bytes, or a size).
engine.max_server_memory_usage_to_ram_ratio ↓	float	0.9	Fraction of host RAM (0.0–1.0, default 0.9) the engine may use when max_server_memory_usage isn’t set explicitly.
engine.metrics_collection_frequency_per_minute ↓	integer	12	How many times per minute the engine collects and emits metrics.
engine.multi_cluster ↓	object	null	Multi-cluster broadcast configuration for query execution across engine clusters.
engine.multi_cluster.broadcast_endpoint ↓	string		Address (host:port) of the multi-cluster broadcast service.
engine.multi_cluster.broadcast_ssl_enabled ↓	boolean	false	Whether to use TLS when connecting to the broadcast endpoint.
engine.multi_cluster.broadcast_tuple_limit_per_engine_cluster ↓	integer	0	Soft limit on rows broadcast per execution stage across the cluster.
engine.nodes ↓	object[]	null	List of engine nodes in this instance.
engine.nodes[*].aragog_port ↓	integer	5678	TCP port for this node’s Aragog distributed-execution service.
engine.nodes[*].host ↓	string		Hostname or IP address of this node, used by other nodes and services to reach it.
engine.nodes[*].shufflepuff_port ↓	integer	16000	TCP port for this node’s Shufflepuff data-shuffle service.
engine.nodes[*].storage_agent_port ↓	integer	3434	TCP port for this node’s Storage Agent (local tablet I/O).
engine.nodes[*].storage_manager_port ↓	integer	1717	TCP port for this node’s Storage Manager (tablet lifecycle and metadata).
engine.termination_grace_period ↓	duration	1m	How long to wait for in-flight queries to finish during graceful shutdown before forcing termination.

execution

Path	Type	Default Value	Description
execution ↓	object	{}	Query execution settings — thread limits, tablet handling, hybrid-header compression, AI mutation mode, and admission control.
execution.admission_controller ↓	object	{}	Admission control settings that govern how many queries run concurrently and how memory is shared, to avoid out-of-memory conditions and improve throughput.
execution.admission_controller.enabled ↓	boolean	false	Enable admission control.
execution.admission_controller.max_concurrent_admitted_queries ↓	integer	100	Maximum number of concurrently admitted queries; the per-node limit scales with cluster size.
execution.admission_controller.max_required_relative_memory_for_retry ↓	float	0.75	Cap on the extra memory an out-of-memory retry may request, as a fraction of available memory.
execution.admission_controller.max_retries_per_query ↓	integer	3	Maximum number of automatic retries when a query fails with an out-of-memory error.
execution.admission_controller.reduce_required_memory_after_seconds_at_front_of_queue ↓	integer	10	After a query waits this many seconds at the front of the admission queue, its estimated memory requirement is reduced to improve its chance of admission.
execution.admission_controller.seconds_between_no_admission_warnings ↓	integer	3600	Minimum interval, in seconds, between warnings logged when no query can be admitted.
execution.admission_controller.seconds_until_no_admission_warning ↓	integer	300	Log a warning when no query has been admitted for this many seconds.
execution.admission_controller.total_memory_tracker_hard_limit_ratio ↓	float	0.9	Fraction of the memory tracker’s hard limit that admission control may allocate per node.
execution.ai_mutations_mode ↓	enum	reevaluate	Execution mode for AI mutation queries: native_only, reevaluate (default), or hybrid.
execution.allow_amazon_bedrock ↓	boolean	true	Allow queries that call Amazon Bedrock AI functions.
execution.enable_shufflepuff ↓	boolean	true	Enable the Shufflepuff shuffle subsystem used for distributed (multi-node) query execution.
execution.hybrid_headers_format_version ↓	integer	3	On-disk format version for Hybrid Headers tablet storage.
execution.hybrid_headers_primary_index_compression_level ↓	integer	2	Compression level for the Hybrid Headers primary index.
execution.hybrid_headers_primary_index_compression_method ↓	enum	BROTLI	Compression algorithm for the Hybrid Headers primary index: one of none, gzip, zlib, xz, zstd, brotli, lz4, or snappy.
execution.max_threads ↓	integer	0	Maximum number of threads used to execute a single query.
execution.merge_committed_tablets ↓	boolean	true	Allow background merging of committed tablets during maintenance.
execution.min_bytes_for_wide_part ↓	integer	104857600	Minimum uncompressed size, in bytes, for a tablet to use the wide format instead of the compact format.
execution.regexp_cache_max_keys ↓	integer	10000	Maximum number of compiled regular expressions to cache.
execution.storage_manager_cache_tablets_on_proxy ↓	boolean	true	Cache tablet-assignment information on the storage-manager proxy to reduce metadata lookups.

instance

Path	Type	Default Value	Description
instance ↓	object	{}	Instance identity and deployment topology — the instance ID and whether this is a single-engine or multi-engine deployment.
instance.account_name ↓	string	default-account	Name of the account this instance belongs to.
instance.id ↓	ulid	01KP98J0000000000000000000	Unique instance identifier in ULID format.
instance.multi_engine ↓	object	null	Multi-engine settings.
instance.multi_engine.metadata_endpoint ↓	string		Address (host:port) of the external Pensieve metadata service.
instance.organization_id ↓	ulid	01KP98J0000000000000000001	ULID of the organization this instance belongs to.
instance.organization_name ↓	string	default-org	Name of the organization this instance belongs to.
instance.type ↓	enum	single_engine	Deployment topology: single_engine (metadata runs locally) or multi_engine (metadata served by an external Pensieve service).

logging

Path	Type	Default Value	Description
logging ↓	object	{}	Logging configuration — the default level, output format, per-component overrides, and output sinks.
logging.components ↓	object[]	[]	Per-component log-level overrides.
logging.components[*].level ↓	enum		Log level for this component, overriding logging.level.
logging.components[*].name ↓	string		Name of the logger component this override applies to.
logging.format ↓	enum	json	Log output format: text (human-readable) or json (structured).
logging.level ↓	enum	info	Default log level for all messages: one of trace, debug, info, warn, error, or fatal.
logging.sinks ↓	object[]	null	Log output targets.
logging.sinks[*].file ↓	object	null	File-sink settings.
logging.sinks[*].file.path ↓	string		Filesystem path the file sink writes to.
logging.sinks[*].level ↓	enum	null	Log level for this sink.
logging.sinks[*].type ↓	enum		Sink destination: stderr or file.

otel

Path	Type	Default Value	Description
otel ↓	object	{}	OpenTelemetry tracing.
otel.enabled ↓	boolean	false	Whether OpenTelemetry trace export is enabled.
otel.endpoint ↓	string	“	OTLP endpoint URL the engine exports traces to.
otel.protocol ↓	string	http/protobuf	OTLP export protocol.

planner

Path	Type	Default Value	Description
planner ↓	object	{}	Query planner configuration.
planner.automated_column_statistics ↓	object	{}	Settings for the automated column-statistics cache used by the optimizer.
planner.automated_column_statistics.cache_max_size_bytes ↓	integer	104857600	Maximum size, in bytes, of the automated column-statistics cache.

query_log

Path	Type	Default Value	Description
query_log ↓	object	{}	Query history export.
query_log.kafka_brokers ↓	string	“	Comma-separated list of Kafka brokers to publish the query log to.

schema_version

Path	Type	Default Value	Description
schema_version ↓	string		Version of the configuration schema.

storage

Path	Type	Default Value	Description
storage ↓	object	{}	Managed-table storage settings — provider type, bucket/location, provider credentials, and garbage-collection behavior.
storage.allow_collect_garbage ↓	boolean	false	Allow manual garbage collection of orphaned tablets via CALL collect_garbage().
storage.allow_local_file_system_access ↓	boolean	true	Whether SQL may read from and write to the local file system (for example external tables or COPY over local paths).
storage.api_scheme ↓	string	null	Storage URI scheme (for example, s3://, gs://, or azure://).
storage.aws ↓	object	null	AWS settings for S3-backed managed tables.
storage.aws.intermediary_access_role ↓	string	null	AWS IAM role assumed for federated, cross-account or cross-tenant S3 access.
storage.aws.region ↓	string	null	AWS region of the bucket used for managed-table storage, for example eu-west-1.
storage.azure ↓	object	null	Azure settings for Blob-Storage-backed managed tables.
storage.azure.intermediary_service_principal_client_id ↓	string	null	Client ID of a federated Azure service principal for cross-tenant access.
storage.azure.storage_account_name ↓	string	null	Azure Blob Storage account name for managed tables, accessed via workload identity.
storage.bucket_name ↓	string	null	Bucket used for managed-table objects.
storage.collect_garbage_limit_per_query ↓	integer	0	Maximum tablets cleaned per collect_garbage() call.
storage.default_s3_endpoint_override ↓	string	null	Override the S3-compatible endpoint URL, redirecting S3 API calls to a custom or on-premises endpoint.
storage.download_chunk_prefetch_max_threads ↓	integer	96	Maximum number of threads used to prefetch download chunks from object storage.
storage.enable_managed_location ↓	boolean	false	Allow CREATE TABLE to specify a LOCATION for managed tables.
storage.gc_ttl_seconds ↓	integer	604800	Grace period, in seconds, before a tablet marked for garbage collection is permanently removed from object storage.
storage.gcp ↓	object	null	Google Cloud settings for GCS-backed managed tables.
storage.gcp.intermediary_service_account_id ↓	string	null	GCP service account used for federated, cross-project or cross-tenant GCS access.
storage.minio ↓	object	null	MinIO settings for local or self-hosted S3-compatible storage.
storage.minio.endpoint ↓	string		MinIO server endpoint URL (for example, http://localhost:9000).
storage.type ↓	enum	s3	Object-storage provider for managed tables: s3, gcs, abs, azurite, or minio.
storage.upload_max_tries ↓	integer	null	Maximum number of retries for object-storage uploads.

Details

auth

auth — object, default {}

Authentication settings for the database. Authentication is disabled by default; set auth.mode to enable native or OIDC authentication, then configure the matching block below.

auth.instance_id — string, default https://localhost

Identifier for this instance. In native mode it’s used as the JWT iss (issuer) claim; in both native and OIDC modes it’s used as the expected aud (audience) claim. Defaults to https://localhost.

auth.mode — enum, default disabled

Selects how clients authenticate. Use disabled for no authentication (the default), native to have the engine issue and validate its own tokens, or oidc to validate tokens issued by an external identity provider. When you choose native or oidc, configure the matching block below.

auth.native — object, default null

Settings for native authentication, used when auth.mode is native. In this mode the engine issues and validates its own JWTs.

auth.native.initial_user — object, default null

Bootstrap user created on startup so you can connect to a fresh instance. Provide a name and a password. This is required when you run a single-engine instance with native authentication.

auth.native.initial_user.name — string

Username for the bootstrap user created at startup in native authentication mode.

auth.native.initial_user.password — string

Password for the bootstrap user created at startup in native authentication mode.

auth.native.jwt — object, default {}

JWT settings for native mode. Because the engine issues tokens itself in this mode, these settings control the lifetime and temporal validation of the tokens it generates.

auth.native.jwt.clock_skew_tolerance — duration, default 30s

Allowed clock skew when validating time-based JWT claims such as exp, nbf, and iat. Tokens within this tolerance of the current time are still accepted. Defaults to 30s.

auth.native.jwt.max_token_age — duration, default 1d

Maximum age of a token, measured from its iat (issued-at) claim. The engine rejects tokens older than this even if they haven’t expired. Defaults to 1d.

auth.native.jwt.token_expiry — duration, default 1h

Lifetime of the access tokens that the engine issues. After this duration a token expires and the client must obtain a new one. Defaults to 1h.

auth.native.signing_algorithm — enum, default RS256

Algorithm used to sign issued tokens. Choose one of the RSA algorithms (RS256, RS384, RS512) or ECDSA algorithms (ES256, ES384, ES512). Defaults to RS256.

auth.native.signing_keys — object[], default []

Keys used to sign issued tokens. Each entry points to a private key on disk. Leave the list empty to run in development mode, where the engine generates an ephemeral signing key on startup.

auth.native.signing_keys[*].id — string

Identifier for this signing key. The engine publishes it as the JWT kid (key ID) header so clients can select the correct key when verifying a token.

auth.native.signing_keys[*].private_key_path — string

Filesystem path to the PEM-encoded private key used for signing.

auth.oidc — object, default null

Settings for OIDC authentication, used when auth.mode is oidc. In this mode the engine validates tokens issued by one or more external identity providers and doesn’t issue tokens itself.

auth.oidc.jwt — object, default {}

JWT validation settings for OIDC mode. Because the upstream identity provider issues the tokens, only validation settings apply here — there are no token-issuance options.

auth.oidc.jwt.clock_skew_tolerance — duration, default 30s

Allowed clock skew when validating time-based JWT claims such as exp, nbf, and iat. Tokens within this tolerance of the current time are still accepted. Defaults to 30s.

auth.oidc.jwt.max_token_age — duration, default 1d

Maximum age of a token, measured from its iat (issued-at) claim. The engine rejects tokens older than this even if they haven’t expired. Defaults to 1d.

auth.oidc.postgres_password_fallback_enabled — boolean, default false

When enabled, connections over the Postgres wire protocol can fall back to password-based authentication instead of OIDC tokens. Disabled by default.

auth.oidc.providers — object[], default []

Trusted OIDC identity providers. A single provider is supported at launch; the list form leaves room for multiple providers in the future.

auth.oidc.providers[*].discovery — object, default {}

Controls how the engine refreshes the provider’s discovery document.

auth.oidc.providers[*].discovery.refresh_interval — duration, default 1d

How often the engine re-fetches the provider’s OpenID configuration (discovery) document. Defaults to 1d.

auth.oidc.providers[*].discovery_url — string

URL of the provider’s OpenID Connect discovery document — the .../.well-known/openid-configuration endpoint. The engine reads the provider’s metadata, including its JWKS URL, from this document.

auth.oidc.providers[*].jit_provisioning — object, default {}

Just-in-time (JIT) provisioning settings. When enabled, the engine creates a user automatically the first time someone authenticates through this provider.

auth.oidc.providers[*].jit_provisioning.default_role — string, default public

Role granted to users created through just-in-time provisioning. Defaults to public.

auth.oidc.providers[*].jit_provisioning.enabled — boolean, default false

Whether to create users automatically on first login through this provider. Disabled by default.

auth.oidc.providers[*].jwks — object, default {}

Controls how the engine caches the provider’s JSON Web Key Set (JWKS), which it uses to verify token signatures.

auth.oidc.providers[*].jwks.cache_ttl — duration, default 1h

How long the engine caches the provider’s JWKS document before re-fetching it. Defaults to 1h.

auth.oidc.providers[*].name — string

Name or alias for this provider. The engine uses it to identify the provider in logs and configuration.

auth.oidc.providers[*].username_mapping — string

Template that maps OIDC token claims to an engine username. Reference claims with {{ claim }} syntax — for example {{ email }}, {{ sub }}, or {{ iss }}|{{ sub }} to namespace usernames by issuer.

data_source_encryption

data_source_encryption — object, default {}

Encryption of external data-source (location and table) credentials. When enabled, the engine encrypts S3 credentials with KMS before storing them in the metadata service.

data_source_encryption.decrypted_cache_timeout_ms — integer, default 600000

How long, in milliseconds, a decrypted data-source credential is cached in memory. Defaults to 600000 (10 minutes).

data_source_encryption.enabled — boolean, default false

Encrypt external data-source credentials with KMS before storing them in the metadata service.

data_source_encryption.kms_arn — string, default “

ARN of the KMS key used to encrypt data-source credentials.

data_source_encryption.local_kms_access_key — string, default “

Access key for the local KMS service. Required when use_local_kms is true.

data_source_encryption.local_kms_endpoint — string, default “

Endpoint URL of the local KMS service. Required when use_local_kms is true.

data_source_encryption.local_kms_secret_key — string, default “

Secret key for the local KMS service. Required when use_local_kms is true.

data_source_encryption.skip_s3_access_check — boolean, default false

Skip validating S3 access when creating an external location or table. Useful when credentials are placeholders.

data_source_encryption.use_local_kms — boolean, default false

Use a local KMS-compatible endpoint (for example, localstack) instead of AWS KMS. Intended for self-deployed and test environments.

endpoints

endpoints — object, default {}

Network listener configuration that defines how clients connect to the engine over HTTP and the PostgreSQL wire protocol.

endpoints.http — object, default {}

HTTP listener configuration for the query API.

endpoints.http.listeners — object[], default []

List of HTTP listener bindings. You can define a TCP listener and a Unix-socket listener, each at most once.

endpoints.http.listeners[*].path — string, default null

Filesystem path for a Unix-domain-socket HTTP listener. Required for unix listeners; omit it for tcp listeners.

endpoints.http.listeners[*].port — integer, default null

TCP port for an HTTP listener (for example, 8123). Required for tcp listeners; omit it for unix listeners.

endpoints.http.listeners[*].type — enum

Listener transport: tcp (network socket) or unix (Unix-domain socket).

endpoints.postgres — object, default {}

PostgreSQL wire-protocol listener configuration. Clients connect using standard Postgres drivers and psql.

endpoints.postgres.listeners — object[], default []

List of PostgreSQL listener bindings. TCP only — Unix sockets aren’t supported for the Postgres protocol.

endpoints.postgres.listeners[*].path — string, default null

Not used for PostgreSQL listeners; Unix-domain sockets aren’t supported for the Postgres protocol.

endpoints.postgres.listeners[*].port — integer, default null

TCP port for PostgreSQL connections (for example, 5432). Required for every Postgres listener.

endpoints.postgres.listeners[*].type — enum

Listener transport for PostgreSQL. Only tcp is supported.

endpoints.unix_socket_only — boolean, default false

When enabled, the server exposes every endpoint (the query API, health check, metrics, the PostgreSQL wire protocol, and its internal services) over Unix domain sockets under the data directory instead of fixed TCP ports. Several servers can then run on one host without colliding on a port. It is enabled automatically for a server started embedded alongside the CLI; leave it off (the default) for a server that listens on TCP.

engine

engine — object, default {}

Configuration for the query execution engine — instance identity, node topology, memory limits, tablet eviction, and multi-cluster broadcasting.

engine.auto_vacuum — object, default null

Background auto-vacuum tuning. Auto-vacuum compacts and cleans up tablets in the background. It’s disabled by default; every field is optional and overrides the built-in default only when you set it.

engine.auto_vacuum.assessment_frequency — integer, default null

How frequently the engine assesses tablets to decide whether an auto-vacuum job is needed.

engine.auto_vacuum.debug_sleep_before_commit_ms — integer, default null

Debugging knob: artificial delay, in milliseconds, inserted before an auto-vacuum job commits. Intended for testing only.

engine.auto_vacuum.enabled — boolean, default null

Whether background auto-vacuum runs. Disabled by default.

engine.auto_vacuum.max_concurrency — integer, default null

Maximum number of auto-vacuum jobs allowed to run concurrently.

engine.auto_vacuum.max_tablets_in_job — integer, default null

Maximum number of tablets processed in a single auto-vacuum job.

engine.auto_vacuum.memory_allowance — float, default null

Fraction of engine memory that auto-vacuum may use while running.

engine.auto_vacuum.min_bad_tablets_threshold — integer, default null

Minimum number of tablets needing cleanup before an auto-vacuum job is triggered.

engine.auto_vacuum.run_on_first_dml — boolean, default null

Whether to trigger an auto-vacuum assessment on the first DML statement after startup.

engine.cluster_id — string, default null

Unique identifier for this engine cluster. Required when multi-cluster broadcasting is enabled, where it tags outbound requests for cross-cluster coordination.

engine.cluster_ordinal — integer, default null

Zero-based ordinal of this cluster within a multi-cluster deployment. Required when multi-cluster broadcasting is enabled, to distinguish cluster instances.

engine.eviction — object, default {}

Tablet memory-eviction policy, controlling when tablets are evicted from in-memory caches to disk as memory fills.

engine.eviction.max_tablets_per_mb_of_total_memory — float, default 1.5

Upper bound on how many tablets the node keeps resident, expressed as tablets per MB of total memory. Defaults to 1.5. Caps tablet residency relative to available memory.

engine.eviction.prefetch_space_ratio_threshold — float, default 0.13

Fraction of memory (0.0–1.0) reserved for tablet prefetching before eviction pressure throttles it. Defaults to 0.13.

engine.eviction.tablet_eviction_soft_threshold — float, default 0.4

Memory-usage fraction (0.0–1.0, default 0.4) that governs soft eviction of least-recently-used tablets. Soft-evicted tablets remain available on disk and are re-cached on access.

engine.eviction.tablet_eviction_threshold — float, default 0.2

Memory-usage fraction (0.0–1.0, default 0.2) that governs hard eviction of tablets from memory to reclaim space.

engine.eviction.tablet_min_ttl_before_memory_eviction_seconds — integer, default 1800

Minimum age in seconds a tablet must reach before it becomes eligible for eviction from memory. Defaults to 1800 (30 minutes).

engine.eviction.tablet_ttl_before_full_eviction_seconds — integer, default 21600

Age in seconds after which an unused tablet is fully evicted from the node — dropped from the local disk cache to reclaim space. Defaults to 21600 (6 hours).

engine.id — string, default default-engine-id

Human-readable identifier for this engine, shown in logs, metrics, and system views. Defaults to default-engine-id.

engine.max_server_memory_usage — byte size, default 0B

Maximum memory the server may use (bytes, or a size such as 8GiB). When 0 (the default), the limit is derived from host RAM using max_server_memory_usage_to_ram_ratio and max_server_memory_usage_headroom_bytes.

engine.max_server_memory_usage_headroom_bytes — byte size, default 0B

Amount of host memory to keep free (bytes, or a size). Used with the ratio to cap server memory when max_server_memory_usage isn’t set explicitly. Default 0.

engine.max_server_memory_usage_to_ram_ratio — float, default 0.9

Fraction of host RAM (0.0–1.0, default 0.9) the engine may use when max_server_memory_usage isn’t set explicitly.

engine.metrics_collection_frequency_per_minute — integer, default 12

How many times per minute the engine collects and emits metrics. Default 12 (every five seconds).

engine.multi_cluster — object, default null

Multi-cluster broadcast configuration for query execution across engine clusters. Omit this block for a standalone or single-cluster engine.

engine.multi_cluster.broadcast_endpoint — string

Address (host:port) of the multi-cluster broadcast service. Required and non-empty when multi-cluster broadcasting is enabled.

engine.multi_cluster.broadcast_ssl_enabled — boolean, default false

Whether to use TLS when connecting to the broadcast endpoint. Default false.

engine.multi_cluster.broadcast_tuple_limit_per_engine_cluster — integer, default 0

Soft limit on rows broadcast per execution stage across the cluster. Default 0 (unlimited); set a positive value to cap intermediate result sizes.

engine.nodes — object[], default null

List of engine nodes in this instance. When omitted, a single node on 127.0.0.1 with default ports is used.

engine.nodes[*].aragog_port — integer, default 5678

TCP port for this node’s Aragog distributed-execution service. Default 5678.

engine.nodes[*].host — string

Hostname or IP address of this node, used by other nodes and services to reach it.

engine.nodes[*].shufflepuff_port — integer, default 16000

TCP port for this node’s Shufflepuff data-shuffle service. Default 16000.

engine.nodes[*].storage_agent_port — integer, default 3434

TCP port for this node’s Storage Agent (local tablet I/O). Default 3434.

engine.nodes[*].storage_manager_port — integer, default 1717

TCP port for this node’s Storage Manager (tablet lifecycle and metadata). Default 1717.

engine.termination_grace_period — duration, default 1m

How long to wait for in-flight queries to finish during graceful shutdown before forcing termination. Default 1m.

execution

execution — object, default {}

Query execution settings — thread limits, tablet handling, hybrid-header compression, AI mutation mode, and admission control.

execution.admission_controller — object, default {}

Admission control settings that govern how many queries run concurrently and how memory is shared, to avoid out-of-memory conditions and improve throughput.

execution.admission_controller.enabled — boolean, default false

Enable admission control. When enabled, queries are queued and prioritized based on available memory and concurrency limits. Default false.

execution.admission_controller.max_concurrent_admitted_queries — integer, default 100

Maximum number of concurrently admitted queries; the per-node limit scales with cluster size. Default 100.

execution.admission_controller.max_required_relative_memory_for_retry — float, default 0.75

Cap on the extra memory an out-of-memory retry may request, as a fraction of available memory. Default 0.75.

execution.admission_controller.max_retries_per_query — integer, default 3

Maximum number of automatic retries when a query fails with an out-of-memory error. Default 3.

execution.admission_controller.reduce_required_memory_after_seconds_at_front_of_queue — integer, default 10

After a query waits this many seconds at the front of the admission queue, its estimated memory requirement is reduced to improve its chance of admission. Default 10.

execution.admission_controller.seconds_between_no_admission_warnings — integer, default 3600

Minimum interval, in seconds, between warnings logged when no query can be admitted. Default 3600.

execution.admission_controller.seconds_until_no_admission_warning — integer, default 300

Log a warning when no query has been admitted for this many seconds. Default 300.

execution.admission_controller.total_memory_tracker_hard_limit_ratio — float, default 0.9

Fraction of the memory tracker’s hard limit that admission control may allocate per node. Default 0.9.

execution.ai_mutations_mode — enum, default reevaluate

Execution mode for AI mutation queries: native_only, reevaluate (default), or hybrid.

execution.allow_amazon_bedrock — boolean, default true

Allow queries that call Amazon Bedrock AI functions. Enabled by default.

execution.enable_shufflepuff — boolean, default true

Enable the Shufflepuff shuffle subsystem used for distributed (multi-node) query execution. When enabled, the engine registers io_uring buffers at startup, which requires sufficient locked memory (RLIMIT_MEMLOCK). Default true.

execution.hybrid_headers_format_version — integer, default 3

On-disk format version for Hybrid Headers tablet storage. Default 3: version 1 is the original format, 2 adds primary-index compression, and 3 adds compact/subcompact tablets.

execution.hybrid_headers_primary_index_compression_level — integer, default 2

Compression level for the Hybrid Headers primary index. Default 2; the valid range depends on the chosen method.

execution.hybrid_headers_primary_index_compression_method — enum, default BROTLI

Compression algorithm for the Hybrid Headers primary index: one of none, gzip, zlib, xz, zstd, brotli, lz4, or snappy. Default brotli.

execution.max_threads — integer, default 0

Maximum number of threads used to execute a single query. 0 (default) lets the engine choose automatically.

execution.merge_committed_tablets — boolean, default true

Allow background merging of committed tablets during maintenance. Default true.

execution.min_bytes_for_wide_part — integer, default 104857600

Minimum uncompressed size, in bytes, for a tablet to use the wide format instead of the compact format.

execution.regexp_cache_max_keys — integer, default 10000

Maximum number of compiled regular expressions to cache. Default 10000.

execution.storage_manager_cache_tablets_on_proxy — boolean, default true

Cache tablet-assignment information on the storage-manager proxy to reduce metadata lookups. Default true.

instance

instance — object, default {}

Instance identity and deployment topology — the instance ID and whether this is a single-engine or multi-engine deployment.

instance.account_name — string, default default-account

Name of the account this instance belongs to. Defaults to default-account.

instance.id — ulid, default 01KP98J0000000000000000000

Unique instance identifier in ULID format. Set automatically in cloud-managed deployments; override it for custom Firebolt Core setups.

instance.multi_engine — object, default null

Multi-engine settings. Required when instance.type is multi_engine and ignored for single_engine. Configures the connection to a shared, remote metadata service.

instance.multi_engine.metadata_endpoint — string

Address (host:port) of the external Pensieve metadata service. Required when instance.type is multi_engine.

instance.organization_id — ulid, default 01KP98J0000000000000000001

ULID of the organization this instance belongs to. Set automatically in cloud-managed deployments.

instance.organization_name — string, default default-org

Name of the organization this instance belongs to. Defaults to default-org.

instance.type — enum, default single_engine

Deployment topology: single_engine (metadata runs locally) or multi_engine (metadata served by an external Pensieve service). Default single_engine.

logging

logging — object, default {}

Logging configuration — the default level, output format, per-component overrides, and output sinks.

logging.components — object[], default []

Per-component log-level overrides. Each entry sets a level for one logger component, independent of the global default.

logging.components[*].level — enum

Log level for this component, overriding logging.level. One of trace, debug, info, warn, error, or fatal.

logging.components[*].name — string

Name of the logger component this override applies to.

logging.format — enum, default json

Log output format: text (human-readable) or json (structured). Default json.

logging.level — enum, default info

Default log level for all messages: one of trace, debug, info, warn, error, or fatal. Default info. Components and sinks can override it.

logging.sinks — object[], default null

Log output targets. Each sink writes to stderr or a file. When omitted, a single stderr sink at the global level is installed.

logging.sinks[*].file — object, default null

File-sink settings. Required when the sink type is file; must be absent when the type is stderr.

logging.sinks[*].file.path — string

Filesystem path the file sink writes to. Required when the sink type is file.

logging.sinks[*].level — enum, default null

Log level for this sink. Inherits logging.level when omitted. One of trace, debug, info, warn, error, or fatal.

logging.sinks[*].type — enum

Sink destination: stderr or file. Required for each sink.

otel

otel — object, default {}

OpenTelemetry tracing. When enabled, the engine exports traces over OTLP.

otel.enabled — boolean, default false

Whether OpenTelemetry trace export is enabled. Disabled by default.

otel.endpoint — string, default “

OTLP endpoint URL the engine exports traces to.

otel.protocol — string, default http/protobuf

OTLP export protocol. One of http/protobuf (the default) or http/json.

planner

planner — object, default {}

Query planner configuration.

planner.automated_column_statistics — object, default {}

Settings for the automated column-statistics cache used by the optimizer.

planner.automated_column_statistics.cache_max_size_bytes — integer, default 104857600

Maximum size, in bytes, of the automated column-statistics cache. Default 100 MiB (104857600). Raise it to cache more statistics, lower it to reduce memory use.

query_log

query_log — object, default {}

Query history export. When a Kafka broker list is configured, the engine publishes the query log to Kafka.

query_log.kafka_brokers — string, default “

Comma-separated list of Kafka brokers to publish the query log to. Leave empty to disable query-log export.

schema_version

schema_version — string

Version of the configuration schema. Required at the root and must be "1.0". It lets the configuration format evolve through future migrations.

storage

storage — object, default {}

Managed-table storage settings — provider type, bucket/location, provider credentials, and garbage-collection behavior.

storage.allow_collect_garbage — boolean, default false

Allow manual garbage collection of orphaned tablets via CALL collect_garbage(). Default false.

storage.allow_local_file_system_access — boolean, default true

Whether SQL may read from and write to the local file system (for example external tables or COPY over local paths). When false, those operations are rejected and queries are confined to object storage.

storage.api_scheme — string, default null

Storage URI scheme (for example, s3://, gs://, or azure://). Defaults to the scheme for the configured storage.type; set it only to override that default.

storage.aws — object, default null

AWS settings for S3-backed managed tables. Set this block only when storage.type is s3.

storage.aws.intermediary_access_role — string, default null

AWS IAM role assumed for federated, cross-account or cross-tenant S3 access. Leave unset to use the engine’s own AWS identity.

storage.aws.region — string, default null

AWS region of the bucket used for managed-table storage, for example eu-west-1. Set this when the bucket is not in us-east-1; leave unset to use the global S3 endpoint.

storage.azure — object, default null

Azure settings for Blob-Storage-backed managed tables. Set this block only when storage.type is abs or azurite.

storage.azure.intermediary_service_principal_client_id — string, default null

Client ID of a federated Azure service principal for cross-tenant access. Leave unset to use the engine’s own workload identity.

storage.azure.storage_account_name — string, default null

Azure Blob Storage account name for managed tables, accessed via workload identity. Required when storage.type is abs.

storage.bucket_name — string, default null

Bucket used for managed-table objects. When set, it overrides the default bucket — useful for Firebolt Core to point at a custom location.

storage.collect_garbage_limit_per_query — integer, default 0

Maximum tablets cleaned per collect_garbage() call. 0 (default) means no per-query limit; set a positive value to process large cleanups in batches.

storage.default_s3_endpoint_override — string, default null

Override the S3-compatible endpoint URL, redirecting S3 API calls to a custom or on-premises endpoint.

storage.download_chunk_prefetch_max_threads — integer, default 96

Maximum number of threads used to prefetch download chunks from object storage.

storage.enable_managed_location — boolean, default false

Allow CREATE TABLE to specify a LOCATION for managed tables. When false (default), managed tables live only in the system-managed bucket.

storage.gc_ttl_seconds — integer, default 604800

Grace period, in seconds, before a tablet marked for garbage collection is permanently removed from object storage. Default 604800 (7 days).

storage.gcp — object, default null

Google Cloud settings for GCS-backed managed tables. Set this block only when storage.type is gcs.

storage.gcp.intermediary_service_account_id — string, default null

GCP service account used for federated, cross-project or cross-tenant GCS access. Leave unset to use the engine’s own workload identity.

storage.minio — object, default null

MinIO settings for local or self-hosted S3-compatible storage. Set this block only when storage.type is minio.

storage.minio.endpoint — string

MinIO server endpoint URL (for example, http://localhost:9000). Required when storage.type is minio.

storage.type — enum, default s3

Object-storage provider for managed tables: s3, gcs, abs, azurite, or minio. Default s3. Set exactly one matching provider block (aws, gcp, azure, or minio).

storage.upload_max_tries — integer, default null

Maximum number of retries for object-storage uploads. Leave unset to use the cloud SDK default.