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, whether it’s required, and its 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.

Each parameter is also marked as either required or optional:

• required parameters must be set — the engine won’t start without them.
• optional parameters fall back to the listed Default Value when you omit them.

Overview

auth

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

endpoints

Path	Type	Required	Default Value	Description
endpoints	object	optional	{}	Network listener configuration that defines how clients connect to the engine over HTTP and the PostgreSQL wire protocol.
endpoints.http	object	optional	{}	HTTP listener configuration for the query API.
endpoints.http.listeners	object[]	optional	[]	List of HTTP listener bindings.
endpoints.http.listeners[*].path	string	optional	null	Filesystem path for a Unix-domain-socket HTTP listener.
endpoints.http.listeners[*].port	integer	optional	null	TCP port for an HTTP listener (for example, 8123).
endpoints.http.listeners[*].type	enum	required		Listener transport: tcp (network socket) or unix (Unix-domain socket).
endpoints.postgres	object	optional	{}	PostgreSQL wire-protocol listener configuration.
endpoints.postgres.listeners	object[]	optional	[]	List of PostgreSQL listener bindings.
endpoints.postgres.listeners[*].path	string	optional	null	Not used for PostgreSQL listeners; Unix-domain sockets aren’t supported for the Postgres protocol.
endpoints.postgres.listeners[*].port	integer	optional	null	TCP port for PostgreSQL connections (for example, 5432).
endpoints.postgres.listeners[*].type	enum	required		Listener transport for PostgreSQL.

engine

Path	Type	Required	Default Value	Description
engine	object	optional	{}	Configuration for the query execution engine — instance identity, node topology, memory limits, tablet eviction, and multi-cluster broadcasting.
engine.auto_vacuum	object	optional	null	Background auto-vacuum tuning.
engine.auto_vacuum.assessment_frequency	integer	optional	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	optional	null	Debugging knob: artificial delay, in milliseconds, inserted before an auto-vacuum job commits.
engine.auto_vacuum.enabled	boolean	optional	null	Whether background auto-vacuum runs.
engine.auto_vacuum.max_concurrency	integer	optional	null	Maximum number of auto-vacuum jobs allowed to run concurrently.
engine.auto_vacuum.max_tablets_in_job	integer	optional	null	Maximum number of tablets processed in a single auto-vacuum job.
engine.auto_vacuum.memory_allowance	float	optional	null	Fraction of engine memory that auto-vacuum may use while running.
engine.auto_vacuum.min_bad_tablets_threshold	integer	optional	null	Minimum number of tablets needing cleanup before an auto-vacuum job is triggered.
engine.auto_vacuum.run_on_first_dml	boolean	optional	null	Whether to trigger an auto-vacuum assessment on the first DML statement after startup.
engine.cluster_id	string	optional	null	Unique identifier for this engine cluster.
engine.cluster_ordinal	integer	optional	null	Zero-based ordinal of this cluster within a multi-cluster deployment.
engine.eviction	object	optional	{}	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	optional	1.5	Upper bound on how many tablets the node keeps resident, expressed as tablets per MB of total memory.
engine.eviction.tablet_eviction_soft_threshold	float	optional	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	optional	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	optional	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	optional	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	optional	default-engine-id	Human-readable identifier for this engine, shown in logs, metrics, and system views.
engine.max_server_memory_usage	byte size	optional	0B	Maximum memory the server may use (bytes, or a size such as 8GiB).
engine.max_server_memory_usage_headroom_bytes	byte size	optional	0B	Amount of host memory to keep free (bytes, or a size).
engine.max_server_memory_usage_to_ram_ratio	float	optional	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	optional	12	How many times per minute the engine collects and emits metrics.
engine.multi_cluster	object	optional	null	Multi-cluster broadcast configuration for query execution across engine clusters.
engine.multi_cluster.broadcast_endpoint	string	required		Address (host:port) of the multi-cluster broadcast service.
engine.multi_cluster.broadcast_ssl_enabled	boolean	optional	false	Whether to use TLS when connecting to the broadcast endpoint.
engine.multi_cluster.broadcast_tuple_limit_per_engine_cluster	integer	optional	0	Soft limit on rows broadcast per execution stage across the cluster.
engine.nodes	object[]	optional	null	List of engine nodes in this instance.
engine.nodes[*].aragog_port	integer	optional	5678	TCP port for this node’s Aragog distributed-execution service.
engine.nodes[*].host	string	required		Hostname or IP address of this node, used by other nodes and services to reach it.
engine.nodes[*].shufflepuff_port	integer	optional	16000	TCP port for this node’s Shufflepuff data-shuffle service.
engine.nodes[*].storage_agent_port	integer	optional	3434	TCP port for this node’s Storage Agent (local tablet I/O).
engine.nodes[*].storage_manager_port	integer	optional	1717	TCP port for this node’s Storage Manager (tablet lifecycle and metadata).
engine.termination_grace_period	duration	optional	1m	How long to wait for in-flight queries to finish during graceful shutdown before forcing termination.

execution

Path	Type	Required	Default Value	Description
execution	object	optional	{}	Query execution settings — thread limits, tablet handling, hybrid-header compression, AI mutation mode, and admission control.
execution.admission_controller	object	optional	{}	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	optional	false	Enable admission control.
execution.admission_controller.max_concurrent_admitted_queries	integer	optional	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	optional	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	optional	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	optional	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	optional	3600	Minimum interval, in seconds, between warnings logged when no query can be admitted.
execution.admission_controller.seconds_until_no_admission_warning	integer	optional	300	Log a warning when no query has been admitted for this many seconds.
execution.admission_controller.total_memory_tracker_hard_limit_ratio	float	optional	0.9	Fraction of the memory tracker’s hard limit that admission control may allocate per node.
execution.ai_mutations_mode	enum	optional	reevaluate	Execution mode for AI mutation queries: native_only, reevaluate (default), or hybrid.
execution.enable_shufflepuff	boolean	optional	true	Enable the Shufflepuff shuffle subsystem used for distributed (multi-node) query execution.
execution.hybrid_headers_format_version	integer	optional	3	On-disk format version for Hybrid Headers tablet storage.
execution.hybrid_headers_primary_index_compression_level	integer	optional	2	Compression level for the Hybrid Headers primary index.
execution.hybrid_headers_primary_index_compression_method	enum	optional	BROTLI	Compression algorithm for the Hybrid Headers primary index: one of none, gzip, zlib, xz, zstd, brotli, lz4, or snappy.
execution.max_threads	integer	optional	0	Maximum number of threads used to execute a single query.
execution.merge_committed_tablets	boolean	optional	true	Allow background merging of committed tablets during maintenance.
execution.min_bytes_for_wide_part	integer	optional	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	optional	10000	Maximum number of compiled regular expressions to cache.
execution.storage_manager_cache_tablets_on_proxy	boolean	optional	true	Cache tablet-assignment information on the storage-manager proxy to reduce metadata lookups.

instance

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

logging

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

planner

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

schema_version

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

storage

Path	Type	Required	Default Value	Description
storage	object	optional	{}	Managed-table storage settings — provider type, bucket/location, provider credentials, and garbage-collection behavior.
storage.allow_collect_garbage	boolean	optional	false	Allow manual garbage collection of orphaned tablets via CALL collect_garbage().
storage.api_scheme	string	optional	null	Storage URI scheme (for example, s3://, gs://, or azure://).
storage.aws	object	optional	null	AWS settings for S3-backed managed tables.
storage.aws.intermediary_access_role	string	optional	null	AWS IAM role assumed for federated, cross-account or cross-tenant S3 access.
storage.azure	object	optional	null	Azure settings for Blob-Storage-backed managed tables.
storage.azure.intermediary_service_principal_client_id	string	optional	null	Client ID of a federated Azure service principal for cross-tenant access.
storage.azure.storage_account_name	string	optional	null	Azure Blob Storage account name for managed tables, accessed via workload identity.
storage.bucket_name	string	optional	null	Bucket used for managed-table objects.
storage.collect_garbage_limit_per_query	integer	optional	0	Maximum tablets cleaned per collect_garbage() call.
storage.default_s3_endpoint_override	string	optional	null	Override the S3-compatible endpoint URL, redirecting S3 API calls to a custom or on-premises endpoint.
storage.enable_managed_location	boolean	optional	false	Allow CREATE TABLE to specify a LOCATION for managed tables.
storage.gc_ttl_seconds	integer	optional	604800	Grace period, in seconds, before a tablet marked for garbage collection is permanently removed from object storage.
storage.gcp	object	optional	null	Google Cloud settings for GCS-backed managed tables.
storage.gcp.intermediary_service_account_id	string	optional	null	GCP service account used for federated, cross-project or cross-tenant GCS access.
storage.minio	object	optional	null	MinIO settings for local or self-hosted S3-compatible storage.
storage.minio.endpoint	string	required		MinIO server endpoint URL (for example, http://localhost:9000).
storage.type	enum	optional	s3	Object-storage provider for managed tables: s3, gcs, abs, azurite, or minio.
storage.upload_max_tries	integer	optional	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 PackDB 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 PackDB 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 · required

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

auth.native.initial_user.password · string · required

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

auth.native.jwt · object · default: "{}"

JWT settings for native mode. Because PackDB 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. PackDB 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 PackDB 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 PackDB generates an ephemeral signing key on startup.

auth.native.signing_keys[*].id · string · required

Identifier for this signing key. PackDB 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 · required

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 PackDB 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. PackDB 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 PackDB refreshes the provider’s discovery document.

auth.oidc.providers[*].discovery.refresh_interval · duration · default: "1d"

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

auth.oidc.providers[*].discovery_url · string · required

URL of the provider’s OpenID Connect discovery document — the .../.well-known/openid-configuration endpoint. PackDB 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, PackDB 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 PackDB 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 PackDB caches the provider’s JWKS document before re-fetching it. Defaults to 1h.

auth.oidc.providers[*].name · string · required

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

auth.oidc.providers[*].username_mapping · string · required

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

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 · required

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 · required

Listener transport for PostgreSQL. Only tcp is supported.

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.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 · required

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 · required

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.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.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 · required

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

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 · required

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

logging.components[*].name · string · required

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 · required

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 · required

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

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.

schema_version

schema_version · string · required

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.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.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.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 · required

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.