Skip to content

Bare-metal config file reference

The config file of a bare-metal node is a standard TOML file with several sections. You can override any option with an environment variable in the format NANOOK__<SECTION>__<KEY>. For example, NANOOK__instance_id=node-2 overrides the instance_id for a node, and NANOOK__monitoring__host_metrics__enabled=false disables the host metrics collection for a node. Other variables the command reads are on the Environment variables page. Durations take an ISO 8601 duration such as PT5S or a jiff friendly duration such as 5 secs.

Example configurations has complete configuration files.

Top-level configuration

Key Type Description
cluster_id string Logical ID for the cluster. Workers and scheduler that share this ID form a single cluster.
e.g. prod-eu-1 (must be unique among all clusters).
instance_id string Unique ID for this node within the cluster, used for addressing and leader selection.
e.g. node-0, node-1 (must be unique per cluster).
license string Path to the Enterprise license file required to start the process. Shorthand for license.on_prem_enterprise.license_path.
e.g. /etc/polars/license.json. See Install and license.
memory_limit integer Hard memory budget (in bytes) for all components in this node, enforced via cgroups when delegated. Only a plain integer is accepted here, not a quantity string such as 10Gi. See Worker resources and memory.
e.g. 1073741824 (1 GiB), 10737418240 (10 GiB).
cpu_reserved integer or string CPU reserved for this node, in fractional cores. Nodes with a higher reserved CPU count are given priority when the scheduler assigns tasks, and the value is used for the resource percentage calculations in the observatory. Accepts a plain number, or a string with a decimal SI (m, k, M, G, ...), binary SI (Ki, Mi, Gi, ...) or scientific suffix.
e.g. 8, "7.5", "500m".

[license] section

The license key can be specified either as a string (shorthand for an enterprise license file path, see Top-level configuration) or as one of the sections below. See Install on bare-metal for a connected cluster and Install and license for an air-gapped one.

Key Type Description
license.on_prem_enterprise object Offline licensing using a license file.
license.on_prem_enterprise.license_path path Path to the Enterprise license file.
e.g. /etc/polars/license.json.
license.license_server.uri string URI of the offline license server that licenses this cluster.
e.g. https://license.internal:50051.
license.on_prem object Online licensing against the Polars control plane. Configure the fields below on the leader node.
license.on_prem.token string Compute token generated when the compute was created in Polars Nanook.
license.on_prem.cert_dir path Directory where the leader node keeps the compute token from its registration.
e.g. /etc/polars/certs.
license.on_prem.workspace_id string Workspace ID (UUID) used to authenticate against the control plane.
license.on_prem.client_id string Client ID used to authenticate against the control plane.
license.on_prem.client_secret string Client secret used to authenticate against the control plane.

[scheduler] section

Key Type Description
enabled boolean Whether the scheduler component runs in this process.
true for the leader node, false on pure workers.
allow_local_sinks boolean Whether workers are allowed to write to a shared/local disk visible to the scheduler.
false for fully remote/storage-only setups, true if you have a shared filesystem.
allow_local_scans boolean Whether queries are allowed to read data from the local filesystem (e.g. file:///path/to/data).
false for fully remote/storage-only setups, true if you have a shared filesystem.
deny_anonymous_users boolean Whether to reject queries submitted without a username. Setting this to true requires all queries to be sent with a username, and false (the default) allows anonymous queries. See User names.
max_workers_per_query integer Upper bound on the number of workers a single query may use. A query asking for more is capped at this value.
e.g. 4.
default_workers_per_query integer Number of workers a query uses when it does not request a count itself. This is also the number of workers a query is planned for, and the capacity requested from the autoscaler, so it must be set when [scaling] is configured.
e.g. 4.
n_workers integer Deprecated: prefer max_workers_per_query and default_workers_per_query, which this seeds when they are not set themselves. Expected number of workers in this cluster.
e.g. 4.
default_partitions_per_worker integer Default number of partitions per worker when not specified in the query settings. Defaults to 1.
anonymous_result_location object Destination for stored results. Supports a local mounted path (must be reachable on the exact same path and allow_local_sinks enabled) or an object store on S3, Google Cloud Storage, or Azure Blob Storage. All options must be network reachable by scheduler, workers, and client.
e.g. /mnt/storage/polars/results.
e.g. s3://<BUCKET>/<PREFIX>
anonymous_result_location.local object Object used for local disk-backed anonymous results.
anonymous_result_location.local.path path Local path where anonymous results are stored.
e.g. /mnt/storage/polars/results.
anonymous_result_location.s3 object Object used for S3-backed anonymous results.
anonymous_result_location.s3.url string S3 bucket url.
e.g. s3://<BUCKET>/<PREFIX>.
anonymous_result_location.s3.aws_endpoint_url string Storage option configuration, see scan_parquet().
anonymous_result_location.s3.aws_region string Storage option configuration.
e.g. eu-west-1
anonymous_result_location.s3.aws_access_key_id string Storage option configuration.
anonymous_result_location.s3.aws_secret_access_key string Storage option configuration.
anonymous_result_location.s3.external_endpoint string Endpoint to use when generating the presigned URLs handed out to clients. Set this when clients reach the bucket at a different address than the cluster does. It takes priority over aws_endpoint_url for presigning only.
e.g. https://minio.example.com:9000.
anonymous_result_location.s3.presign_duration string How long the presigned URLs generated for results stay valid. Defaults to 8h.
e.g. 1 hour.
e.g. PT1H.
anonymous_result_location.s3.allow_deletes boolean Whether clients may delete anonymous results from this location. Defaults to true for S3.
anonymous_result_location.gcs object Object used for Google Cloud Storage-backed anonymous results.
anonymous_result_location.gcs.url string GCS bucket url.
e.g. gs://<BUCKET>/<PREFIX>.
anonymous_result_location.gcs.google_service_account_path string Storage option configuration, see scan_parquet().
e.g. /etc/polars/gcs-service-account.json.
anonymous_result_location.gcs.presign_duration string How long the presigned URLs generated for results stay valid. Defaults to 8h.
anonymous_result_location.gcs.allow_deletes boolean Whether clients may delete anonymous results from this location. Defaults to false.
anonymous_result_location.abs object Object used for Azure Blob Storage-backed anonymous results.
anonymous_result_location.abs.url string Azure container url.
e.g. az://<CONTAINER>/<PREFIX>.
anonymous_result_location.abs.azure_storage_account_name string Storage option configuration, see scan_parquet().
anonymous_result_location.abs.azure_storage_account_key string Storage option configuration.
anonymous_result_location.abs.presign_duration string How long the presigned URLs generated for results stay valid. Defaults to 8h.
anonymous_result_location.abs.allow_deletes boolean Whether clients may delete anonymous results from this location. Defaults to false.
client_service object Object used for configuring the bind address of the client service. This is the service used by the polars-nanook Python client. Defaults to 0.0.0.0:5051.
client_service.bind_addr string Bind address for the client service.
e.g. 0.0.0.0:5051.
client_service.bind_addr.ip string IP address for the client service bind address.
e.g. 192.168.1.1.
client_service.bind_addr.port integer Port for the client service bind address.
e.g. 5051.
client_service.bind_addr.hostname string Alternative to ip, resolved once at startup.
e.g. my-host-1.
worker_service object Object used for configuring the bind address of the worker service. This is an internal service used by the workers. Defaults to 0.0.0.0:5050.
worker_service.bind_addr string Bind address for the worker service.
e.g. 0.0.0.0:5050.
worker_service.bind_addr.ip string IP address for the worker service bind address.
e.g. 192.168.1.1.
worker_service.bind_addr.port integer Port for the worker service bind address.
e.g. 5050.
worker_service.bind_addr.hostname string Alternative to ip, resolved once at startup.
e.g. my-host-2.
checkpoint object Enables checkpointing for queries. Requires the worker to have checkpoint_location configured. See worker.checkpoint_location.
checkpoint.enabled boolean Whether checkpointing runs on this cluster. The section enables it. Set to false to disable it without removing the section.
checkpoint.period string Required. How often checkpoints are created: a checkpoint is created once this period has passed after a stage completes.
e.g. 5 secs.
e.g. PT5S.

[scaling] section

Delegates scaling of the worker pool to an external scaling service that you run. If omitted, the cluster is fixed-size or externally scaled, and queries are sized by default_workers_per_query, which is required when [scaling] is configured. Configure exactly one of the two transports below. See Scaling service protocol for the contract the service must implement.

Key Type Description
enabled boolean Whether autoscaling is active. Defaults to true. Set to false to disable without removing the section.
grpc object Delegates scaling to a gRPC scaling service, which streams its configuration to the scheduler.
grpc.uri string Address of the scaling service.
e.g. http://scaler.internal:8080.
grpc.scale_up_timeout string How long a query waits for the workers it asked for before giving up. Defaults to 5 minutes.
e.g. 10 mins.
e.g. PT10M.
grpc.scale_down_on_idle_only boolean Set this to true when your service cannot honor workers_to_keep and picks which workers to terminate itself. The scheduler then only scales down while no query is running. Defaults to false.
rest object Delegates scaling to a REST scaling service, which the scheduler polls for configuration changes.
rest.uri string Base URL of the scaling service.
e.g. http://scaler.internal:8080.
rest.scale_up_timeout string How long a query waits for the workers it asked for before giving up. Defaults to 5 minutes.
e.g. 10 mins.
e.g. PT10M.
rest.scale_down_on_idle_only boolean Set this to true when your service cannot honor workers_to_keep and picks which workers to terminate itself. The scheduler then only scales down while no query is running. Defaults to false.

[worker] section

Key Type Description
enabled boolean Whether the worker component runs in this process.
true on worker nodes, false on the dedicated scheduler.
heartbeat_period string Interval for worker heartbeats towards the scheduler, used for liveness and load reporting.
e.g. 5 secs.
e.g. PT5S.
shuffle_location object Required. Object used for shuffle data storage. Supports worker-local disk, a shared filesystem, or an object store on S3, Google Cloud Storage, or Azure Blob Storage. See Shuffle storage.
shuffle_location.local object Object used for local disk-backed shuffle data storage.
shuffle_location.local.path path Local path where shuffle/intermediate data is stored. Fast local SSD is recommended.
e.g. /mnt/storage/polars/shuffle.
shuffle_location.shared_filesystem object Object used for shared filesystem-backed shuffle data storage.
shuffle_location.shared_filesystem.path path Shared filesystem path where shuffle/intermediate data is stored. Must be accessible by all workers on the same path.
e.g. /mnt/storage/polars/shuffle.
shuffle_location.s3 object Object used for S3-backed shuffle data storage.
shuffle_location.s3.url path Destination for shuffle/intermediate data.
e.g. s3://<BUCKET>/<PREFIX>.
shuffle_location.s3.aws_endpoint_url string Storage option configuration, see scan_parquet().
shuffle_location.s3.aws_region string Storage option configuration.
e.g. eu-west-1
shuffle_location.s3.aws_access_key_id string Storage option configuration.
shuffle_location.s3.aws_secret_access_key string Storage option configuration.
shuffle_location.gcs object Object used for Google Cloud Storage-backed shuffle data storage.
shuffle_location.gcs.url path Destination for shuffle/intermediate data.
e.g. gs://<BUCKET>/<PREFIX>.
shuffle_location.gcs.google_service_account_path string Storage option configuration, see scan_parquet().
e.g. /etc/polars/gcs-service-account.json.
shuffle_location.abs object Object used for Azure Blob Storage-backed shuffle data storage.
shuffle_location.abs.url path Destination for shuffle/intermediate data.
e.g. az://<CONTAINER>/<PREFIX>.
shuffle_location.abs.azure_storage_account_name string Storage option configuration, see scan_parquet().
shuffle_location.abs.azure_storage_account_key string Storage option configuration.
checkpoint_location object Location where checkpoints for queries are stored. Required when the scheduler has [scheduler.checkpoint] enabled. Supports a shared filesystem or an object store on S3, Google Cloud Storage, or Azure Blob Storage. Unlike shuffle_location there is no local variant, since checkpoints must survive the loss of a single worker. See Checkpointing.
checkpoint_location.shared_filesystem.path path Shared filesystem path where checkpoint data is stored. Must be accessible by all workers on the same path.
e.g. /mnt/storage/polars/checkpoints.
checkpoint_location.s3 object Object used for S3-backed checkpoint storage.
checkpoint_location.s3.url path Destination for checkpoint data.
e.g. s3://<BUCKET>/<PREFIX>.
checkpoint_location.s3.aws_endpoint_url string Storage option configuration, see scan_parquet().
checkpoint_location.s3.aws_region string Storage option configuration.
e.g. eu-west-1
checkpoint_location.s3.aws_access_key_id string Storage option configuration.
checkpoint_location.s3.aws_secret_access_key string Storage option configuration.
checkpoint_location.gcs object Object used for Google Cloud Storage-backed checkpoint storage.
checkpoint_location.gcs.url path Destination for checkpoint data.
e.g. gs://<BUCKET>/<PREFIX>.
checkpoint_location.gcs.google_service_account_path string Storage option configuration, see scan_parquet().
e.g. /etc/polars/gcs-service-account.json.
checkpoint_location.abs object Object used for Azure Blob Storage-backed checkpoint storage.
checkpoint_location.abs.url path Destination for checkpoint data.
e.g. az://<CONTAINER>/<PREFIX>.
checkpoint_location.abs.azure_storage_account_name string Storage option configuration, see scan_parquet().
checkpoint_location.abs.azure_storage_account_key string Storage option configuration.
task_service object Object used for configuring the bind address of the task service. This is an internal service in the worker for receiving tasks from the scheduler. Defaults to 0.0.0.0:5052.
task_service.bind_addr string Bind address for the task service.
e.g. 0.0.0.0:5052.
task_service.bind_addr.ip string IP address for the task service bind address.
e.g. 192.168.1.1.
task_service.bind_addr.port integer Port for the task service bind address.
e.g. 5052.
task_service.bind_addr.hostname string Alternative to ip, resolved once at startup.
e.g. my-host-2.
task_service.public_addr string Address at which this service is reachable by the scheduler. Defaults to the bind address if not set. This field is required when the bind address is 0.0.0.0.
e.g. 192.168.1.1.
task_service.public_addr.ip string IP address for the task service public address.
e.g. 192.168.1.2.
task_service.public_addr.port integer Port for the task service public address.
e.g. 5052.
task_service.public_addr.hostname string Alternative to ip, resolved once at startup.
e.g. my-host-2.
shuffle_service object Object used for configuring the bind address of the shuffle service. This is an internal service in the worker for serving shuffle data to the other workers. Defaults to 0.0.0.0:5053.
shuffle_service.bind_addr string Bind address for the shuffle service.
e.g. 0.0.0.0:5053.
shuffle_service.bind_addr.ip string IP address for the shuffle service bind address.
e.g. 192.168.1.1.
shuffle_service.bind_addr.port integer Port for the shuffle service bind address.
e.g. 5053.
shuffle_service.bind_addr.hostname string Alternative to ip, resolved once at startup.
e.g. my-host-2.
shuffle_service.public_addr string Address at which this service is reachable by the other workers. Defaults to the bind address if not set. This field is required when the bind address is 0.0.0.0.
e.g. 192.168.1.1.
shuffle_service.public_addr.ip string IP address for the shuffle service public address.
e.g. 192.168.1.2.
shuffle_service.public_addr.port integer Port for the shuffle service public address.
e.g. 5053.
shuffle_service.public_addr.hostname string Alternative to ip, resolved once at startup.
e.g. my-host-2.
env_vars object Environment variable overrides used by Polars or user code, as a table of key/value string pairs.
e.g. { POLARS_MAX_THREADS = "8" }.
extras.hdfs.enabled boolean Enable HDFS support.
extras.pyiceberg.enabled boolean Enable PyIceberg support.
extras.cudf_polars.enabled boolean Enable GPU queries. See Run queries on GPUs.

[observatory] section

Key Type Description
enabled boolean Run the observatory, which receives and stores the profiling data for the query profiler. It runs only on the leader; the other nodes send their profiling data through the [monitoring] section.
max_metrics_bytes_total integer How many bytes all the worker host metrics use in total. The full amount is allocated up front to keep memory usage predictable. The budget is divided over the autoscaler's maximum, or else the deprecated scheduler.n_workers, plus one. When neither is set, the observatory assumes 500 workers, so such a cluster needs a much larger total. If a system-wide memory limit is set, this is added to the share that the scheduler takes. For every worker, about 50 bytes of metrics are stored per second.
database_path string Location of the profiling data. The observatory creates an SQLite database file here, or opens the file if it already exists. If the path ends with /, it creates a file in that directory, which must exist. The observatory adds the cluster_id to the file name to keep it unique within the directory. Without it, the database is temporary and the query history is lost when the service stops.
service object Object used for configuring the bind address of the observatory service. This is an internal service in the scheduler for receiving profiling data from all nodes. Defaults to 0.0.0.0:5049.
service.bind_addr string Bind address for the observatory service.
e.g. 0.0.0.0:5049.
service.bind_addr.ip string IP address for the observatory service bind address.
e.g. 192.168.1.1.
service.bind_addr.port integer Port for the observatory service bind address.
e.g. 5049.
service.bind_addr.hostname string Alternative to ip, resolved once at startup.
e.g. my-host-2.
rest_api.enabled boolean Whether the observatory REST API is exposed. Enabled by default. This is a public service for reading the profiling data and host metrics through a web interface.
rest_api.service object Object used for configuring the bind address of the observatory REST API service. Defaults to 0.0.0.0:3001.
rest_api.service.bind_addr string Bind address for the observatory REST API service.
e.g. 0.0.0.0:3001.
rest_api.service.bind_addr.ip string IP address for the observatory REST API service bind address.
e.g. 192.168.1.1.
rest_api.service.bind_addr.port integer Port for the observatory REST API service bind address.
e.g. 3001.
rest_api.service.bind_addr.hostname string Alternative to ip, resolved once at startup.
e.g. my-host-2.

[monitoring] section

Key Type Description
enabled boolean Enable sending monitoring data to the observatory service at static_leader.observatory_service.public_addr.
host_metrics object Object used for configuring the host metrics exporter.
host_metrics.enabled boolean Whether this node exports host metrics.
host_metrics.disk_usage_metrics boolean Whether to export disk usage metrics for the shuffle directory.
host_metrics.disk_io_metrics boolean Whether to export disk read/write throughput metrics for the shuffle directory (enabled by default if IO accounting is enabled for the used cgroup).

[static_leader] section

Key Type Description
leader_instance_id string ID of the leader node, which should match the scheduler's instance_id.
e.g. node-0.
scheduler_service.public_addr string Address at which the scheduler worker service is reachable from this node.
e.g. 192.168.1.1.
scheduler_service.public_addr.ip string IP address for the scheduler worker service public address.
e.g. 192.168.1.1.
scheduler_service.public_addr.port integer Port for the scheduler worker service public address.
Defaults to 5050.
scheduler_service.public_addr.hostname string Alternative to ip, resolved once at startup.
e.g. my-host-2.
observatory_service.public_addr string Address at which the observatory service is reachable from this node.
e.g. 192.168.1.1.
observatory_service.public_addr.ip string IP address for the observatory service public address.
e.g. 192.168.1.1.
observatory_service.public_addr.port integer Port for the observatory service public address.
e.g. 5049.
observatory_service.public_addr.hostname string Alternative to ip, resolved once at startup.
e.g. my-host-2.

[lineage] section

Key Type Description
enabled boolean Enable the OpenLineage service.
transport.http.endpoint string HTTP or HTTPS endpoint of the OpenLineage collector.
e.g. http://marquez.example.com:5000.