Engine configuration reference

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 instance, 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"

instance:
  account_name: my-account
engine:
  id: my-engine
storage:
  managed_table_storage: s3
  managed_table_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

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[]`	`null`	List of query API 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[*].tls` ↓	`object`	`null`	TLS configuration for this query API listener.
`endpoints.http.listeners[*].tls.certificate_file` ↓	`string`	`null`	Filesystem path to the PEM certificate chain for this TLS listener.
`endpoints.http.listeners[*].tls.private_key_file` ↓	`string`	`null`	Filesystem path to the PEM private key for this TLS listener.
`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[]`	`null`	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[*].tls` ↓	`object`	`null`	TLS configuration for this PostgreSQL listener.
`endpoints.postgres.listeners[*].tls.certificate_file` ↓	`string`	`null`	Filesystem path to the PEM certificate chain for a future PostgreSQL TLS listener.
`endpoints.postgres.listeners[*].tls.private_key_file` ↓	`string`	`null`	Filesystem path to the PEM private key for a future PostgreSQL TLS listener.
`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.debug_sleep_in_merge_loop_ms` ↓	`integer`	`null`	Debugging knob: artificial delay, in milliseconds, inserted per block inside the merge loop of an auto-vacuum job.
`engine.auto_vacuum.enabled` ↓	`boolean`	`null`	Whether background auto-vacuum runs.
`engine.auto_vacuum.max_tablet_bytes` ↓	`byte size`	`null`	Maximum size, in bytes, of a tablet produced by an auto-vacuum merge.
`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.num_workers_per_node` ↓	`integer`	`null`	Number of worker threads in the per-node auto-vacuum job pool, which bounds how many auto-vacuum jobs run concurrently per node.
`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.listen_host` ↓	`string`	`null`	Address the engine binds all of its listeners to.
`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[*].health_check_port` ↓	`integer`	`8122`	HTTP port for this node’s liveness and readiness probes.
`engine.nodes[*].host` ↓	`string`		Hostname or IP address of this node, used by other nodes and services to reach it.
`engine.nodes[*].prometheus_port` ↓	`integer`	`9090`	HTTP port where this node exposes its Prometheus metrics scrape endpoint.
`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.query_cache_memory_fraction` ↓	`float`	`0.2`	Fraction of the engine cache memory allocated to the query cache.
`engine.termination_grace_period` ↓	`duration`	`1m`	How long to wait for in-flight queries to finish during graceful shutdown before forcing termination.
`engine.vector_index_cache_memory_fraction` ↓	`float`	`0.5`	Fraction of the engine cache memory allocated to the vector index cache.

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_distributed_shuffle` ↓	`boolean`	`true`	Enable the distributed (multi-node) shuffle subsystem (Shufflepuff).
`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.
`execution.umask` ↓	`string`	`null`	Octal file-mode creation mask applied to the server process.

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.auth` ↓	`object`	`{}`	Authentication settings for the instance.
`instance.auth.admin` ↓	`object`	`null`	The instance administrator, created on startup so you can connect to a fresh instance.
`instance.auth.admin.name` ↓	`string`	`firebolt`	Username for the bootstrap administrator account.
`instance.auth.admin.password_env` ↓	`string`	`null`	Name of an environment variable the engine reads at startup to obtain the admin password.
`instance.auth.admin.password_file` ↓	`string`	`null`	Absolute path to a file containing the admin password.
`instance.auth.admin.password_value` ↓	`string`	`null`	Admin password supplied as a literal string.
`instance.auth.enabled` ↓	`boolean`	`false`	Whether authentication is enabled.
`instance.auth.local` ↓	`object`	`{}`	Settings for the embedded Authorization Server.
`instance.auth.local.jwt` ↓	`object`	`{}`	JWT settings for the embedded Authorization Server.
`instance.auth.local.jwt.clock_skew_tolerance` ↓	`duration`	`30s`	Allowed clock skew when validating time-based JWT claims such as `exp`, `nbf`, and `iat`.
`instance.auth.local.jwt.max_token_age` ↓	`duration`	`1d`	Maximum age of a token, measured from its `iat` (issued-at) claim.
`instance.auth.local.jwt.token_expiry` ↓	`duration`	`1h`	Lifetime of the access tokens that the engine issues.
`instance.auth.local.signing_algorithm` ↓	`enum`	`RS256`	Algorithm used to sign issued tokens.
`instance.auth.local.signing_keys` ↓	`object[]`	`[]`	Keys used to sign issued tokens.
`instance.auth.local.signing_keys[*].id` ↓	`string`		Identifier for this signing key.
`instance.auth.local.signing_keys[*].private_key_path` ↓	`string`		Filesystem path to the PEM-encoded private key used for signing.
`instance.auth.oidc` ↓	`object`	`null`	Settings for OIDC authentication.
`instance.auth.oidc.jwt` ↓	`object`	`{}`	JWT validation settings for OIDC mode.
`instance.auth.oidc.jwt.clock_skew_tolerance` ↓	`duration`	`30s`	Allowed clock skew when validating time-based JWT claims such as `exp`, `nbf`, and `iat`.
`instance.auth.oidc.jwt.max_token_age` ↓	`duration`	`1d`	Maximum age of a token, measured from its `iat` (issued-at) claim.
`instance.auth.oidc.providers` ↓	`object[]`	`[]`	Trusted OIDC identity providers.
`instance.auth.oidc.providers[*].audience` ↓	`string`	`null`	Expected `aud` (audience) claim for tokens minted by this provider.
`instance.auth.oidc.providers[*].discovery` ↓	`object`	`{}`	Controls how the engine refreshes the provider’s OpenID Connect discovery document.
`instance.auth.oidc.providers[*].discovery.refresh_interval` ↓	`duration`	`1d`	How often the engine re-fetches the provider’s OpenID configuration (discovery) document.
`instance.auth.oidc.providers[*].discovery_url` ↓	`string`		URL of the provider’s OpenID Connect discovery document — the `.../.well-known/openid-configuration` endpoint.
`instance.auth.oidc.providers[*].jit_provisioning` ↓	`object`	`{}`	Just-in-time (JIT) provisioning settings.
`instance.auth.oidc.providers[*].jit_provisioning.default_roles` ↓	`string[]`	`[]`	Roles granted to users created through just-in-time provisioning.
`instance.auth.oidc.providers[*].jit_provisioning.enabled` ↓	`boolean`	`false`	Whether to create users automatically on first login through this provider.
`instance.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.
`instance.auth.oidc.providers[*].jwks.cache_ttl` ↓	`duration`	`1h`	How long the engine caches the provider’s JWKS document before re-fetching it.
`instance.auth.oidc.providers[*].name` ↓	`string`		Machine identifier for this provider, used in the `?auth=<name>` query parameter and CLI flags.
`instance.auth.oidc.providers[*].title` ↓	`string`	`null`	Human-readable label shown by interactive UIs.
`instance.auth.oidc.providers[*].username_mapping` ↓	`string`		Template that maps OIDC token claims to an engine username.
`instance.auth.password_login` ↓	`enum`	`admin_only`	Default policy for password-based logins (for example over the PostgreSQL wire protocol): `admin_only` (the default) restricts password login to the admin user, while `any_user` allows it for all users.
`instance.auth.preferred_authorization_server` ↓	`string`	`null`	Name of the authorization server clients should use by default when the connection string does not select one explicitly.
`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 — the storage service (`managed_table_storage`), bucket/location, per-cloud connection blocks, 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.aws` ↓	`object`	`null`	Default AWS S3 connection settings — used for managed tables when `managed_table_storage` is `s3`, and for external S3 scans.
`storage.aws.endpoint` ↓	`string`	`null`	Custom S3-compatible endpoint URL (for example a self-hosted object store).
`storage.aws.intermediary_access_role` ↓	`string`	`null`	AWS IAM role assumed for federated, cross-account or cross-tenant S3 access.
`storage.aws.path_style_addressing` ↓	`boolean`	`true`	Use path-style addressing (`endpoint/bucket/key`) for a custom S3 `endpoint` instead of virtual-hosted (`bucket.endpoint/key`).
`storage.aws.region` ↓	`string`	`null`	AWS region of the bucket used for managed-table storage, for example `eu-west-1`.
`storage.aws.tcp_connections` ↓	`integer`	`null`	Maximum number of concurrent TCP connections used by each AWS S3 or S3-compatible client.
`storage.aws.verify_ssl` ↓	`boolean`	`true`	Whether to verify TLS certificates when connecting to a custom S3 `endpoint`.
`storage.azure` ↓	`object`	`null`	Default Azure Blob Storage connection settings — used for managed tables when `managed_table_storage` is `abs`, and for external Azure scans.
`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.azure.use_azurite_emulator` ↓	`boolean`	`false`	Route Azure Blob Storage access to the local Azurite emulator at `http://devstoreaccount1.blob.azurite:10000`.
`storage.collect_garbage_limit_per_query` ↓	`integer`	`0`	Maximum tablets cleaned per `collect_garbage()` call.
`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`	Default Google Cloud Storage connection settings — used for managed tables when `managed_table_storage` is `gcs`, and for external GCS scans.
`storage.gcp.intermediary_service_account_id` ↓	`string`	`null`	GCP service account used for federated, cross-project or cross-tenant GCS access.
`storage.managed_table_bucket_name` ↓	`string`	`null`	Bucket or container used for managed-table objects.
`storage.managed_table_storage` ↓	`enum`	`s3`	Storage service that backs managed tables: `s3`, `gcs`, or `abs`.
`storage.tablet_recovery_cache` ↓	`object`	`{}`	On-disk tablet recovery cache and its Firebolt Core startup garbage collection of outdated tablets.
`storage.tablet_recovery_cache.enabled` ↓	`boolean`	`true`	Populate the tablet recovery cache from local disk during startup so previously downloaded tablets can be reused instead of re-fetched.
`storage.tablet_recovery_cache.run_gc_on_startup` ↓	`boolean`	`true`	Remove outdated on-disk tablets (those no longer referenced by metadata) during Firebolt Core startup.
`storage.upload_max_tries` ↓	`integer`	`null`	Maximum number of retries for object-storage uploads.

Details

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 null List of query API listener bindings. You can define plain and TLS TCP listeners, plus plain and TLS Unix-socket listeners, 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[*].tls — object, default null TLS configuration for this query API listener. When set, a tcp listener serves HTTPS and a unix listener serves HTTP over TLS on the Unix-domain socket. The current implementation uses a process-wide TLS context, so all TLS listeners must use the same certificate and private key. Per-listener TLS contexts are planned for a future release. endpoints.http.listeners[*].tls.certificate_file — string, default null Filesystem path to the PEM certificate chain for this TLS listener. Omit it only when private_key_file points to a combined PEM file that also contains the certificate. Startup health probes use this file as their trust bundle for HTTPS listeners, so include the issuing CA for self-signed or internal-CA deployments. endpoints.http.listeners[*].tls.private_key_file — string, default null Filesystem path to the PEM private key for this TLS listener. Required. This can point to a combined PEM file that contains both the private key and certificate chain; in that form, startup health probes also use it as their trust bundle for HTTPS listeners. endpoints.http.listeners[*].type — enum Listener transport: tcp (network socket) or unix (Unix-domain socket). Add tls to the listener to serve HTTP over TLS on that transport. endpoints.postgres — object, default {} PostgreSQL wire-protocol listener configuration. Clients connect using standard Postgres drivers and psql. endpoints.postgres.listeners — object[], default null 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[*].tls — object, default null TLS configuration for this PostgreSQL listener. This field is reserved for future PostgreSQL TLS support and is rejected today. endpoints.postgres.listeners[*].tls.certificate_file — string, default null Filesystem path to the PEM certificate chain for a future PostgreSQL TLS listener. This field is rejected until PostgreSQL TLS support is implemented. endpoints.postgres.listeners[*].tls.private_key_file — string, default null Filesystem path to the PEM private key for a future PostgreSQL TLS listener. This field is rejected until PostgreSQL TLS support is implemented. 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.debug_sleep_in_merge_loop_ms — integer, default null Debugging knob: artificial delay, in milliseconds, inserted per block inside the merge loop of an auto-vacuum job. Intended for testing only. engine.auto_vacuum.enabled — boolean, default null Whether background auto-vacuum runs. Disabled by default. engine.auto_vacuum.max_tablet_bytes — byte size, default null Maximum size, in bytes, of a tablet produced by an auto-vacuum merge. 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.num_workers_per_node — integer, default null Number of worker threads in the per-node auto-vacuum job pool, which bounds how many auto-vacuum jobs run concurrently per node. 0 (the default) uses max_threads, matching a manual VACUUM’s per-node parallelism. Hot-reloadable: changing it resizes the existing pools. 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.listen_host — string, default null Address the engine binds all of its listeners to. Defaults to 0.0.0.0 (all interfaces). Set it to a specific address so two engines can co-locate on one host without their fixed-port services (such as the leader’s storage manager) colliding; it must be an address the engine’s nodes[].host entries resolve to. 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[*].health_check_port — integer, default 8122 HTTP port for this node’s liveness and readiness probes. Not part of query execution. Default 8122. engine.nodes[*].host — string Hostname or IP address of this node, used by other nodes and services to reach it. engine.nodes[*].prometheus_port — integer, default 9090 HTTP port where this node exposes its Prometheus metrics scrape endpoint. Not part of query execution. Default 9090. 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.query_cache_memory_fraction — float, default 0.2 Fraction of the engine cache memory allocated to the query cache. 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. engine.vector_index_cache_memory_fraction — float, default 0.5 Fraction of the engine cache memory allocated to the vector index cache.

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_distributed_shuffle — boolean, default true Enable the distributed (multi-node) shuffle subsystem (Shufflepuff). 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. execution.umask — string, default null Octal file-mode creation mask applied to the server process. umask clears the matching permission bits from every file and directory the process creates. The default 0007 grants the owner and group full access and denies others, which preserves the group permission bits the OpenShift arbitrary-UID model depends on: there the process runs as a random UID but always in group 0, with the data directories group-owned by root. Set 0077 for owner-only access.

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.auth — object, default {} Authentication settings for the instance. Authentication is disabled by default; set auth.enabled to true, designate an admin user, and configure the embedded Authorization Server (local) and/or one or more external oidc providers below. instance.auth.admin — object, default null The instance administrator, created on startup so you can connect to a fresh instance. Required when auth.enabled is true. Set the username with name and supply the password through exactly one of password_value, password_env, or password_file. instance.auth.admin.name — string, default firebolt Username for the bootstrap administrator account. Defaults to firebolt. instance.auth.admin.password_env — string, default null Name of an environment variable the engine reads at startup to obtain the admin password. Keeps the secret out of the config file. Exactly one of password_value, password_env, or password_file must be set. instance.auth.admin.password_file — string, default null Absolute path to a file containing the admin password. The engine reads the file at startup and trims a single trailing newline. Exactly one of password_value, password_env, or password_file must be set. instance.auth.admin.password_value — string, default null Admin password supplied as a literal string. Intended for development only — prefer password_env or password_file in production. Exactly one of password_value, password_env, or password_file must be set. instance.auth.enabled — boolean, default false Whether authentication is enabled. When false (the default) the instance is accessible without credentials; when true every connection must present valid credentials and an admin user must be configured. instance.auth.local — object, default {} Settings for the embedded Authorization Server. When configured, the engine issues and validates its own JWTs, so these settings control the signing keys, algorithm, and token lifetimes. The whole block is optional and defaults to a development-friendly configuration. instance.auth.local.jwt — object, default {} JWT settings for the embedded Authorization Server. Because the engine issues tokens itself, these settings control the lifetime and temporal validation of the tokens it generates. instance.auth.local.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. instance.auth.local.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 have not expired. Defaults to 1d. instance.auth.local.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. instance.auth.local.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. instance.auth.local.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. instance.auth.local.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. instance.auth.local.signing_keys[*].private_key_path — string Filesystem path to the PEM-encoded private key used for signing. instance.auth.oidc — object, default null Settings for OIDC authentication. In this mode the engine validates tokens issued by one or more external identity providers and does not issue tokens itself. instance.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. instance.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. instance.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 have not expired. Defaults to 1d. instance.auth.oidc.providers — object[], default [] Trusted OIDC identity providers. At least one entry is required when the oidc block is present. instance.auth.oidc.providers[*].audience — string, default null Expected aud (audience) claim for tokens minted by this provider. When omitted, the engine’s canonical instance URL is used. instance.auth.oidc.providers[*].discovery — object, default {} Controls how the engine refreshes the provider’s OpenID Connect discovery document. instance.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. instance.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. instance.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. instance.auth.oidc.providers[*].jit_provisioning.default_roles — string[], default [] Roles granted to users created through just-in-time provisioning. Defaults to [public] when omitted. instance.auth.oidc.providers[*].jit_provisioning.enabled — boolean, default false Whether to create users automatically on first login through this provider. Disabled by default. instance.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. instance.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. instance.auth.oidc.providers[*].name — string Machine identifier for this provider, used in the ?auth=<name> query parameter and CLI flags. Also identifies the provider in logs and configuration. instance.auth.oidc.providers[*].title — string, default null Human-readable label shown by interactive UIs. Defaults to name when omitted. instance.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. instance.auth.password_login — enum, default admin_only Default policy for password-based logins (for example over the PostgreSQL wire protocol): admin_only (the default) restricts password login to the admin user, while any_user allows it for all users. Ignored when no oidc providers are configured. instance.auth.preferred_authorization_server — string, default null Name of the authorization server clients should use by default when the connection string does not select one explicitly. Must name a configured server — the embedded _local server or one of the oidc.providers[].name entries — otherwise the engine refuses to start. Advisory to clients; surfaced as preferredAuthorizationServer in the /.well-known/firebolt discovery document. 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 — the storage service (managed_table_storage), bucket/location, per-cloud connection blocks, 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.aws — object, default null Default AWS S3 connection settings — used for managed tables when managed_table_storage is s3, and for external S3 scans. May be set alongside gcp and azure. storage.aws.endpoint — string, default null Custom S3-compatible endpoint URL (for example a self-hosted object store). Leave unset for AWS 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.path_style_addressing — boolean, default true Use path-style addressing (endpoint/bucket/key) for a custom S3 endpoint instead of virtual-hosted (bucket.endpoint/key). Default true, which most S3-compatible stores (such as MinIO) require; set false for endpoints that need virtual-hosted addressing (e.g. AWS S3). 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.aws.tcp_connections — integer, default null Maximum number of concurrent TCP connections used by each AWS S3 or S3-compatible client. storage.aws.verify_ssl — boolean, default true Whether to verify TLS certificates when connecting to a custom S3 endpoint. Default true. Has no effect on a plaintext (http://) endpoint. storage.azure — object, default null Default Azure Blob Storage connection settings — used for managed tables when managed_table_storage is abs, and for external Azure scans. May be set alongside aws and gcp. 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.azure.use_azurite_emulator — boolean, default false Route Azure Blob Storage access to the local Azurite emulator at http://devstoreaccount1.blob.azurite:10000. For test and development use only. Default false. 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.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 Default Google Cloud Storage connection settings — used for managed tables when managed_table_storage is gcs, and for external GCS scans. May be set alongside aws and azure. 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.managed_table_bucket_name — string, default null Bucket or container used for managed-table objects. When set, it overrides the default location. storage.managed_table_storage — enum, default s3 Storage service that backs managed tables: s3, gcs, or abs. Default s3. The matching provider block (aws, gcp, or azure) supplies that cloud’s connection settings. storage.tablet_recovery_cache — object, default {} On-disk tablet recovery cache and its Firebolt Core startup garbage collection of outdated tablets. storage.tablet_recovery_cache.enabled — boolean, default true Populate the tablet recovery cache from local disk during startup so previously downloaded tablets can be reused instead of re-fetched. Default true. storage.tablet_recovery_cache.run_gc_on_startup — boolean, default true Remove outdated on-disk tablets (those no longer referenced by metadata) during Firebolt Core startup. When false, outdated tablets are left on disk. Default true. storage.upload_max_tries — integer, default null Maximum number of retries for object-storage uploads. Leave unset to use the cloud SDK default.

Overview

Performance and Observability

Security

Self-Managed

Managed service

Guides

SQL reference

Release notes

API reference

Legal

Value types

Parameter kinds

Overview

data_source_encryption

endpoints

engine

execution

instance

logging

otel

planner

query_log

schema_version

storage

Details

data_source_encryption

endpoints

engine

execution

instance

logging

otel

planner

query_log

schema_version

storage

​Value types

​Parameter kinds

​Overview

​data_source_encryption

​endpoints

​engine

​execution

​instance

​logging

​otel

​planner

​query_log

​schema_version

​storage

​Details

​data_source_encryption

​endpoints

​engine

​execution

​instance

​logging

​otel

​planner

​query_log

​schema_version

​storage

Value types

Parameter kinds

Overview

data_source_encryption

endpoints

engine

execution

instance

logging

otel

planner

query_log

schema_version

storage

Details

data_source_encryption

endpoints

engine

execution

instance

logging

otel

planner

query_log

schema_version

storage