> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebolt.io/llms.txt
> Use this file to discover all available pages before exploring further.
> Reference for the YAML configuration file that configures a Firebolt engine.
# 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:
```yaml theme={"theme":{"light":"css-variables","dark":"css-variables"}}
schema_version: "1.0"
instance:
account_name: my-account
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](https://github.com/ulid/spec) 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[]` | `[]` | 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[]` | `[]` | 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.termination_grace_period` ↓ | `duration` | `1m` | How long to wait for in-flight queries to finish during graceful shutdown before forcing termination. |
### execution
| Path | Type | Default Value | Description |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `execution` ↓ | `object` | `{}` | Query execution settings — thread limits, tablet handling, hybrid-header compression, AI mutation mode, and admission control. |
| `execution.admission_controller` ↓ | `object` | `{}` | Admission control settings that govern how many queries run concurrently and how memory is shared, to avoid out-of-memory conditions and improve throughput. |
| `execution.admission_controller.enabled` ↓ | `boolean` | `false` | Enable admission control. |
| `execution.admission_controller.max_concurrent_admitted_queries` ↓ | `integer` | `100` | Maximum number of concurrently admitted queries; the per-node limit scales with cluster size. |
| `execution.admission_controller.max_required_relative_memory_for_retry` ↓ | `float` | `0.75` | Cap on the extra memory an out-of-memory retry may request, as a fraction of available memory. |
| `execution.admission_controller.max_retries_per_query` ↓ | `integer` | `3` | Maximum number of automatic retries when a query fails with an out-of-memory error. |
| `execution.admission_controller.reduce_required_memory_after_seconds_at_front_of_queue` ↓ | `integer` | `10` | After a query waits this many seconds at the front of the admission queue, its estimated memory requirement is reduced to improve its chance of admission. |
| `execution.admission_controller.seconds_between_no_admission_warnings` ↓ | `integer` | `3600` | Minimum interval, in seconds, between warnings logged when no query can be admitted. |
| `execution.admission_controller.seconds_until_no_admission_warning` ↓ | `integer` | `300` | Log a warning when no query has been admitted for this many seconds. |
| `execution.admission_controller.total_memory_tracker_hard_limit_ratio` ↓ | `float` | `0.9` | Fraction of the memory tracker's hard limit that admission control may allocate per node. |
| `execution.ai_mutations_mode` ↓ | `enum` | `reevaluate` | Execution mode for AI mutation queries: `native_only`, `reevaluate` (default), or `hybrid`. |
| `execution.allow_amazon_bedrock` ↓ | `boolean` | `true` | Allow queries that call Amazon Bedrock AI functions. |
| `execution.enable_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=` 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 — provider type, bucket/location, provider credentials, and garbage-collection behavior. |
| `storage.allow_collect_garbage` ↓ | `boolean` | `false` | Allow manual garbage collection of orphaned tablets via `CALL collect_garbage()`. |
| `storage.allow_local_file_system_access` ↓ | `boolean` | `true` | Whether SQL may read from and write to the local file system (for example external tables or `COPY` over local paths). |
| `storage.api_scheme` ↓ | `string` | `null` | Storage URI scheme (for example, `s3://`, `gs://`, or `azure://`). |
| `storage.aws` ↓ | `object` | `null` | AWS settings for S3-backed managed tables. |
| `storage.aws.intermediary_access_role` ↓ | `string` | `null` | AWS IAM role assumed for federated, cross-account or cross-tenant S3 access. |
| `storage.aws.region` ↓ | `string` | `null` | AWS region of the bucket used for managed-table storage, for example `eu-west-1`. |
| `storage.azure` ↓ | `object` | `null` | Azure settings for Blob-Storage-backed managed tables. |
| `storage.azure.intermediary_service_principal_client_id` ↓ | `string` | `null` | Client ID of a federated Azure service principal for cross-tenant access. |
| `storage.azure.storage_account_name` ↓ | `string` | `null` | Azure Blob Storage account name for managed tables, accessed via workload identity. |
| `storage.bucket_name` ↓ | `string` | `null` | Bucket used for managed-table objects. |
| `storage.collect_garbage_limit_per_query` ↓ | `integer` | `0` | Maximum tablets cleaned per `collect_garbage()` call. |
| `storage.default_s3_endpoint_override` ↓ | `string` | `null` | Override the S3-compatible endpoint URL, redirecting S3 API calls to a custom or on-premises endpoint. |
| `storage.download_chunk_prefetch_max_threads` ↓ | `integer` | `96` | Maximum number of threads used to prefetch download chunks from object storage. |
| `storage.enable_managed_location` ↓ | `boolean` | `false` | Allow `CREATE TABLE` to specify a `LOCATION` for managed tables. |
| `storage.gc_ttl_seconds` ↓ | `integer` | `604800` | Grace period, in seconds, before a tablet marked for garbage collection is permanently removed from object storage. |
| `storage.gcp` ↓ | `object` | `null` | Google Cloud settings for GCS-backed managed tables. |
| `storage.gcp.intermediary_service_account_id` ↓ | `string` | `null` | GCP service account used for federated, cross-project or cross-tenant GCS access. |
| `storage.minio` ↓ | `object` | `null` | MinIO settings for local or self-hosted S3-compatible storage. |
| `storage.minio.endpoint` ↓ | `string` | | MinIO server endpoint URL (for example, `http://localhost:9000`). |
| `storage.type` ↓ | `enum` | `s3` | Object-storage provider for managed tables: `s3`, `gcs`, `abs`, `azurite`, or `minio`. |
| `storage.upload_max_tries` ↓ | `integer` | `null` | Maximum number of retries for object-storage uploads. |
## Details
### data\_source\_encryption
[`data_source_encryption`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-endpoints) — `object`, default `{}`
Network listener configuration that defines how clients connect to the engine over HTTP and the PostgreSQL wire protocol.
[`endpoints.http`](#param-endpoints-http) — `object`, default `{}`
HTTP listener configuration for the query API.
[`endpoints.http.listeners`](#param-endpoints-http-listeners) — `object[]`, default `[]`
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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-endpoints-postgres) — `object`, default `{}`
PostgreSQL wire-protocol listener configuration. Clients connect using standard Postgres drivers and `psql`.
[`endpoints.postgres.listeners`](#param-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`](#param-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`](#param-endpoints-postgres-listeners-port) — `integer`, default `null`
TCP port for PostgreSQL connections (for example, `5432`). Required for every Postgres listener.
[`endpoints.postgres.listeners[*].tls`](#param-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`](#param-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`](#param-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`](#param-endpoints-postgres-listeners-type) — `enum`
Listener transport for PostgreSQL. Only `tcp` is supported.
[`endpoints.unix_socket_only`](#param-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`](#param-engine) — `object`, default `{}`
Configuration for the query execution engine — instance identity, node topology, memory limits, tablet eviction, and multi-cluster broadcasting.
[`engine.auto_vacuum`](#param-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`](#param-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`](#param-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`](#param-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`](#param-engine-auto-vacuum-enabled) — `boolean`, default `null`
Whether background auto-vacuum runs. Disabled by default.
[`engine.auto_vacuum.max_tablet_bytes`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-engine-nodes-aragog-port) — `integer`, default `5678`
TCP port for this node's Aragog distributed-execution service. Default `5678`.
[`engine.nodes[*].health_check_port`](#param-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`](#param-engine-nodes-host) — `string`
Hostname or IP address of this node, used by other nodes and services to reach it.
[`engine.nodes[*].prometheus_port`](#param-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`](#param-engine-nodes-shufflepuff-port) — `integer`, default `16000`
TCP port for this node's Shufflepuff data-shuffle service. Default `16000`.
[`engine.nodes[*].storage_agent_port`](#param-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`](#param-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`](#param-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`](#param-execution) — `object`, default `{}`
Query execution settings — thread limits, tablet handling, hybrid-header compression, AI mutation mode, and admission control.
[`execution.admission_controller`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-execution-ai-mutations-mode) — `enum`, default `reevaluate`
Execution mode for AI mutation queries: `native_only`, `reevaluate` (default), or `hybrid`.
[`execution.allow_amazon_bedrock`](#param-execution-allow-amazon-bedrock) — `boolean`, default `true`
Allow queries that call Amazon Bedrock AI functions. Enabled by default.
[`execution.enable_distributed_shuffle`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-execution-merge-committed-tablets) — `boolean`, default `true`
Allow background merging of committed tablets during maintenance. Default `true`.
[`execution.min_bytes_for_wide_part`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-instance-account-name) — `string`, default `default-account`
Name of the account this instance belongs to. Defaults to `default-account`.
[`instance.auth`](#param-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`](#param-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`](#param-instance-auth-admin-name) — `string`, default `firebolt`
Username for the bootstrap administrator account. Defaults to `firebolt`.
[`instance.auth.admin.password_env`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-instance-auth-local-signing-keys-private-key-path) — `string`
Filesystem path to the PEM-encoded private key used for signing.
[`instance.auth.oidc`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-instance-auth-oidc-providers-name) — `string`
Machine identifier for this provider, used in the `?auth=` query parameter and CLI flags. Also identifies the provider in logs and configuration.
[`instance.auth.oidc.providers[*].title`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-instance-organization-id) — `ulid`, default `01KP98J0000000000000000001`
ULID of the organization this instance belongs to. Set automatically in cloud-managed deployments.
[`instance.organization_name`](#param-instance-organization-name) — `string`, default `default-org`
Name of the organization this instance belongs to. Defaults to `default-org`.
[`instance.type`](#param-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`](#param-logging) — `object`, default `{}`
Logging configuration — the default level, output format, per-component overrides, and output sinks.
[`logging.components`](#param-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`](#param-logging-components-level) — `enum`
Log level for this component, overriding `logging.level`. One of `trace`, `debug`, `info`, `warn`, `error`, or `fatal`.
[`logging.components[*].name`](#param-logging-components-name) — `string`
Name of the logger component this override applies to.
[`logging.format`](#param-logging-format) — `enum`, default `json`
Log output format: `text` (human-readable) or `json` (structured). Default `json`.
[`logging.level`](#param-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`](#param-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`](#param-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`](#param-logging-sinks-file-path) — `string`
Filesystem path the file sink writes to. Required when the sink type is `file`.
[`logging.sinks[*].level`](#param-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`](#param-logging-sinks-type) — `enum`
Sink destination: `stderr` or `file`. Required for each sink.
### otel
[`otel`](#param-otel) — `object`, default `{}`
OpenTelemetry tracing. When enabled, the engine exports traces over OTLP.
[`otel.enabled`](#param-otel-enabled) — `boolean`, default `false`
Whether OpenTelemetry trace export is enabled. Disabled by default.
[`otel.endpoint`](#param-otel-endpoint) — `string`, default \`\`
OTLP endpoint URL the engine exports traces to.
[`otel.protocol`](#param-otel-protocol) — `string`, default `http/protobuf`
OTLP export protocol. One of `http/protobuf` (the default) or `http/json`.
### planner
[`planner`](#param-planner) — `object`, default `{}`
Query planner configuration.
[`planner.automated_column_statistics`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-storage) — `object`, default `{}`
Managed-table storage settings — provider type, bucket/location, provider credentials, and garbage-collection behavior.
[`storage.allow_collect_garbage`](#param-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`](#param-storage-allow-local-file-system-access) — `boolean`, default `true`
Whether SQL may read from and write to the local file system (for example external tables or `COPY` over local paths). When false, those operations are rejected and queries are confined to object storage.
[`storage.api_scheme`](#param-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`](#param-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`](#param-storage-aws-intermediary-access-role) — `string`, default `null`
AWS IAM role assumed for federated, cross-account or cross-tenant S3 access. Leave unset to use the engine's own AWS identity.
[`storage.aws.region`](#param-storage-aws-region) — `string`, default `null`
AWS region of the bucket used for managed-table storage, for example `eu-west-1`. Set this when the bucket is not in `us-east-1`; leave unset to use the global S3 endpoint.
[`storage.azure`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-storage-default-s3-endpoint-override) — `string`, default `null`
Override the S3-compatible endpoint URL, redirecting S3 API calls to a custom or on-premises endpoint.
[`storage.download_chunk_prefetch_max_threads`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-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`](#param-storage-minio-endpoint) — `string`
MinIO server endpoint URL (for example, `http://localhost:9000`). Required when `storage.type` is `minio`.
[`storage.type`](#param-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`](#param-storage-upload-max-tries) — `integer`, default `null`
Maximum number of retries for object-storage uploads. Leave unset to use the cloud SDK default.