Configuration Reference

This document provides a comprehensive reference for all Polaris configuration options.

All properties listed here are runtime properties and can be changed without rebuilding Polaris.

Table of Contents🔗

• Features & Behavior
• Authentication & Authorization
• Storage & Credentials
• Persistence
• Events
• Operational
• Other

Features & Behavior🔗

polaris.features🔗

Feature configurations for Polaris. These are stable, user-facing settings.

polaris.features."ADD_TRAILING_SLASH_TO_LOCATION"🔗

When set, the base location for a table or namespace will have / added as a suffix if not present

• Type: Boolean
• Default: true
• Catalog Config: polaris.config.add-trailing-slash-to-location

polaris.features."ALLOW_DROPPING_NON_EMPTY_PASSTHROUGH_FACADE_CATALOG"🔗

If enabled, allow dropping a passthrough-facade catalog even if it contains namespaces or tables. passthrough-facade catalogs may contain leftover entities when syncing with source catalog.In the short term these entities will be ignored, in the long term there will be method/background job to clean them up.

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.allow-dropping-non-empty-passthrough-facade-catalog

polaris.features."ALLOW_EXTERNAL_CATALOG_CREDENTIAL_VENDING"🔗

If set to true, allow credential vending for external catalogs.

• Type: Boolean
• Default: true
• Catalog Config: polaris.config.enable.credential.vending

polaris.features."ALLOW_EXTERNAL_METADATA_FILE_LOCATION"🔗

If set to true, allows metadata files to be located outside the default metadata directory.

• Type: Boolean
• Default: false

polaris.features."ALLOW_EXTERNAL_TABLE_LOCATION"🔗

If set to true, allows tables to have external locations outside the default structure.

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.allow.external.table.location

polaris.features."ALLOW_FEDERATED_CATALOGS_CREDENTIAL_VENDING"🔗

If set to true (default), allow credential vending for external catalogs. Note this requires ALLOW_EXTERNAL_CATALOG_CREDENTIAL_VENDING to be true first.

• Type: Boolean
• Default: true
• Catalog Config: polaris.config.allow-federated-catalogs-credential-vending

polaris.features."ALLOW_INSECURE_STORAGE_TYPES"🔗

Allow usage of FileIO implementations that are considered insecure. Enabling this setting may expose the service to possibly severe security risks! This should only be set to ’true’ for tests!

• Type: Boolean
• Default: false

polaris.features."ALLOW_NAMESPACE_LOCATION_OVERLAP"🔗

If set to true, allow one namespace’s location to reside within another namespace’s location. This is only enforced within a parent catalog or namespace.

• Type: Boolean
• Default: false

polaris.features."ALLOW_OPTIMIZED_SIBLING_CHECK"🔗

When set to true, Polaris will permit enabling the feature OPTIMIZED_SIBLING_CHECK for catalogs, this is done to prevent accidental enabling the feature in cases such as schema migrations, without backfill and hence leading to potential data integrity issues. This will be removed in 2.0.0 when polaris ships with the necessary migrations to backfill the index.

• Type: Boolean
• Default: false

polaris.features."ALLOW_OVERLAPPING_CATALOG_URLS"🔗

If set to true, allows catalog URLs to overlap.

• Type: Boolean
• Default: false

polaris.features."ALLOW_SETTING_S3_ENDPOINTS"🔗

If set to true (default), Polaris will permit S3 storage configurations to have custom endpoints. If set to false, Polaris will not accept catalog create and update requests that contain S3 endpoint properties.

• Type: Boolean
• Default: true

polaris.features."ALLOW_SETTING_SUB_CATALOG_RBAC_FOR_FEDERATED_CATALOGS"🔗

If set to true (default), Polaris will allow setting or changing catalog property polaris.config.enable-sub-catalog-rbac-for-federated-catalogs.If set to false, Polaris will disallow setting or changing the above catalog property

• Type: Boolean
• Default: true

polaris.features."ALLOW_SPECIFYING_FILE_IO_IMPL"🔗

Config key for whether to allow setting the FILE_IO_IMPL using catalog properties. Must only be enabled in dev/test environments, should not be in production systems.

• Type: Boolean
• Default: false

polaris.features."ALLOW_TABLE_LOCATION_OVERLAP"🔗

If set to true, allow one table’s location to reside within another table’s location. This is only enforced within a given namespace.

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.allow.overlapping.table.location

polaris.features."ALLOW_UNSTRUCTURED_TABLE_LOCATION"🔗

If set to true, allows unstructured table locations.

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.allow.unstructured.table.location

polaris.features."ALLOW_WILDCARD_LOCATION"🔗

Indicates whether asterisks (’*’) in configuration values defining allowed storage locations are processed as meaning ‘any location’.

• Type: Boolean
• Default: false

polaris.features."AZURE_RETRY_COUNT"🔗

Number of retry attempts for Azure API requests. Uses exponential backoff with jitter to handle transient failures.

• Type: Integer
• Default: 3

polaris.features."AZURE_RETRY_DELAY_MILLIS"🔗

Initial delay in milliseconds before first retry for Azure API requests. Delay doubles with each retry (exponential backoff).

• Type: Integer
• Default: 2000

polaris.features."AZURE_RETRY_JITTER_FACTOR"🔗

Jitter factor (0.0 to 1.0) applied to retry delays for Azure API requests. The jitter is applied as a random percentage of the computed exponential backoff delay. For example, 0.5 means up to 50%% random jitter will be added to each retry delay. Helps prevent thundering herd when multiple requests fail simultaneously.

• Type: Double
• Default: 0.5

polaris.features."AZURE_TIMEOUT_MILLIS"🔗

Timeout in milliseconds for Azure API requests. Prevents indefinite blocking when Azure endpoints are slow or unresponsive. Used internally by Azure storage integration for credential vending and other operations.

• Type: Integer
• Default: 15000

polaris.features."CLEANUP_ON_CATALOG_DROP"🔗

If set to true, clean up data when a catalog is dropped

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.cleanup.on.catalog.drop

polaris.features."CLEANUP_ON_NAMESPACE_DROP"🔗

If set to true, clean up data when a namespace is dropped

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.cleanup.on.namespace.drop

polaris.features."DEFAULT_LOCATION_OBJECT_STORAGE_PREFIX_ENABLED"🔗

When enabled, Iceberg tables and views created without a location specified will have a prefix applied to the location within the catalog’s base location, rather than a location directly inside the parent namespace. Note that this requires ALLOW_EXTERNAL_TABLE_LOCATION to be enabled, but with OPTIMIZED_SIBLING_CHECK enabled it is still possible to enforce the uniqueness of table locations within a catalog.

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.default-table-location-object-storage-prefix.enabled

polaris.features."DROP_WITH_PURGE_ENABLED"🔗

If set to true, allows tables to be dropped with the purge parameter set to true.

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.drop-with-purge.enabled

polaris.features."ENABLE_CATALOG_FEDERATION"🔗

If true, allows creating and using ExternalCatalogs containing ConnectionConfigInfos to perform federation to remote catalogs.

• Type: Boolean
• Default: false

polaris.features."ENABLE_CREDENTIAL_RESET"🔗

Flag to enable or disable the API to reset principal credentials. Defaults to enabled, but service providers may want to disable it.

• Type: Boolean
• Default: true

polaris.features."ENABLE_FINE_GRAINED_UPDATE_TABLE_PRIVILEGES"🔗

When true, enables finer grained update table privileges which are passed to the authorizer for update table operations

• Type: Boolean
• Default: true
• Catalog Config: polaris.config.enable-fine-grained-update-table-privileges

polaris.features."ENABLE_GENERIC_TABLES"🔗

If true, the generic-tables endpoints are enabled

• Type: Boolean
• Default: true

polaris.features."ENABLE_POLICY_STORE"🔗

If true, the policy-store endpoints are enabled

• Type: Boolean
• Default: true

polaris.features."ENABLE_SUB_CATALOG_RBAC_FOR_FEDERATED_CATALOGS"🔗

When enabled, allows RBAC operations to create synthetic entities for entities in federated catalogs that don’t exist in the local metastore.

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.enable-sub-catalog-rbac-for-federated-catalogs

polaris.features."ENFORCE_PRINCIPAL_CREDENTIAL_ROTATION_REQUIRED_CHECKING"🔗

If set to true, require that principals must rotate their credentials before being used for anything else.

• Type: Boolean
• Default: false

polaris.features."ENTITY_CACHE_WEIGHER_TARGET"🔗

The maximum weight for the entity cache. This is a heuristic value without any particular unit of measurement. It roughly correlates with the total heap size of cached values. Fine-tuning requires experimentation in the specific deployment environment

• Type: Long
• Default: 104857600

polaris.features."ICEBERG_COMMIT_MAX_RETRIES"🔗

The max number of times to try committing to an Iceberg table

• Type: Integer
• Default: 4
• Catalog Config: polaris.config.iceberg-commit-max-retries

polaris.features."ICEBERG_ROLLBACK_COMPACTION_ON_CONFLICTS"🔗

Rollback replace snapshots created by compaction which have polaris.internal.conflict-resolution.by-operation-type.replace property set to rollback in their snapshot summary

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.rollback.compaction.on-conflicts.enabled

polaris.features."INCLUDE_PRINCIPAL_NAME_IN_SUBSCOPED_CREDENTIAL"🔗

If set to true, principal name will be included in temporary subscoped credentials. Currently only AWS credentials are supported for which session name of the generated credentials will look like ‘polaris-’ rather than simple ‘polaris’. Note that enabling this feature leads to degradation in temporary credential caching as catalog will no longer be able to reuse credentials for multiple principals.

• Type: Boolean
• Default: false

polaris.features."INCLUDE_SESSION_TAGS_IN_SUBSCOPED_CREDENTIAL"🔗

If set to true, session tags (catalog, namespace, table, principal, roles) will be included in AWS STS AssumeRole requests for credential vending. These tags appear in CloudTrail events, enabling correlation between catalog operations and S3 data access. Requires the IAM role trust policy to allow sts:TagSession action. Note that enabling this feature may lead to degradation in temporary credential caching as catalog will no longer be able to reuse credentials for different tables/namespaces/roles.

• Type: Boolean
• Default: false

polaris.features."INCLUDE_TRACE_ID_IN_SESSION_TAGS"🔗

If set to true (and INCLUDE_SESSION_TAGS_IN_SUBSCOPED_CREDENTIAL is also true), the OpenTelemetry trace ID will be included as a session tag in AWS STS AssumeRole requests. This enables end-to-end correlation between catalog operations (Polaris events), credential vending (CloudTrail), and metrics reports from compute engines. WARNING: Enabling this feature completely disables credential caching because every request has a unique trace ID. This may significantly increase latency and STS API costs. Consider leaving this disabled unless end-to-end tracing correlation is critical.

• Type: Boolean
• Default: false

polaris.features."LIST_PAGINATION_ENABLED"🔗

If set to true, pagination for APIs like listTables is enabled.

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.list-pagination-enabled

polaris.features."MAX_METADATA_REFRESH_RETRIES"🔗

How many times to retry refreshing metadata when the previous error was retryable

• Type: Integer
• Default: 2

polaris.features."OPTIMIZED_SIBLING_CHECK"🔗

When set, an index is used to perform the sibling check between tables, views, and namespaces. New locations will be checked against previous ones based on components, so the new location /foo/bar/ will check for a sibling at /, /foo/ and /foo/bar/%. In order for this check to be correct, locations should end with a slash. See ADD_TRAILING_SLASH_TO_LOCATION for a way to enforce this when new locations are added. Only supported by the JDBC metastore.

• Type: Boolean
• Default: false

polaris.features."POLARIS_TASK_TIMEOUT_MILLIS"🔗

Polaris task expiry timeout (milliseconds). Older unfinished tasks may not be processed.

• Type: Long
• Default: 300000

polaris.features."PURGE_VIEW_METADATA_ON_DROP"🔗

If set to true, Polaris will attempt to delete view metadata files when a view is dropped.

• Type: Boolean
• Default: true
• Catalog Config: polaris.config.purge-view-metadata-on-drop

polaris.features."RESOLVE_CREDENTIALS_BY_STORAGE_NAME"🔗

If set to true, resolve AWS credentials based on the storageName field of the storage configuration. When disabled, the default AWS credentials are used for all storages.

• Type: Boolean
• Default: false

polaris.features."SKIP_CREDENTIAL_SUBSCOPING_INDIRECTION"🔗

If set to true, skip credential-subscoping indirection entirely whenever trying to obtain storage credentials for instantiating a FileIO. If ’true’, no attempt is made to use StorageConfigs to generate table-specific storage credentials, but instead the default fallthrough of table-level credential properties or else provider-specific APPLICATION_DEFAULT credential-loading will be used for the FileIO. Typically this setting is used in single-tenant server deployments that don’t rely on “credential-vending” and can use server-default environment variables or credential config files for all storage access, or in test/dev scenarios.

• Type: Boolean
• Default: false

polaris.features."STORAGE_CREDENTIAL_CACHE_DURATION_SECONDS"🔗

How long to store storage credentials in the local cache. This should be less than STORAGE_CREDENTIAL_DURATION_SECONDS

• Type: Integer
• Default: 1800

polaris.features."STORAGE_CREDENTIAL_DURATION_SECONDS"🔗

The duration of time that vended storage credentials are valid for. Support for longer (or shorter) durations is dependent on the storage provider. GCS current does not respect this value.

• Type: Integer
• Default: 3600

polaris.features."SUPPORTED_CATALOG_CONNECTION_TYPES"🔗

The list of supported catalog connection types for federation

• Type: List<String>
• Default: [ICEBERG_REST]

polaris.features."SUPPORTED_CATALOG_STORAGE_TYPES"🔗

The list of supported storage types for a catalog

• Type: List<String>
• Default: [S3, AZURE, GCS]
• Catalog Config: polaris.config.supported.storage.types

polaris.features."SUPPORTED_EXTERNAL_CATALOG_AUTHENTICATION_TYPES"🔗

The list of supported authentication types for catalog federation

• Type: List<String>
• Default: [OAUTH, BEARER, SIGV4]

polaris.features."TABLE_METADATA_CLEANUP_BATCH_SIZE"🔗

Metadata batch size for tasks that clean up dropped tables’ files.

• Type: Integer
• Default: 10

polaris.behavior-changes🔗

Internal behavior change configurations. These are unstable and may be removed.

polaris.behavior-changes."ALLOW_NAMESPACE_CUSTOM_LOCATION"🔗

If set to true, allow namespaces with completely arbitrary locations. This should not affect credential vending.

• Type: Boolean
• Default: false
• Catalog Config: polaris.config.namespace-custom-location.enabled

polaris.behavior-changes."ENTITY_CACHE_SOFT_VALUES"🔗

Whether or not to use soft values in the entity cache

• Type: Boolean
• Default: false

polaris.behavior-changes."SCHEMA_VERSION_FALL_BACK_ON_DNE"🔗

If set to true, exceptions encountered while loading the VERSION table which appear to be caused by the VERSION table not existing will be interpreted as meaning that the schema version is currently 0.

• Type: Boolean
• Default: true

polaris.behavior-changes."STORAGE_CONFIGURATION_MAX_LOCATIONS"🔗

How many locations can be associated with a storage configuration, or -1 for unlimited locations

• Type: Integer
• Default: -1

polaris.behavior-changes."TABLE_OPERATIONS_MAKE_METADATA_CURRENT_ON_COMMIT"🔗

If true, BasePolarisTableOperations should mark the metadata that is passed into commit as current, and reuse it to skip a trip to object storage to re-construct the committed metadata again.

• Type: Boolean
• Default: true

polaris.behavior-changes."VALIDATE_VIEW_LOCATION_OVERLAP"🔗

If true, validate that view locations don’t overlap when views are created

• Type: Boolean
• Default: true

Authentication & Authorization🔗

polaris.authentication🔗

polaris.authorization🔗

polaris.authorization.opa🔗

Configuration for OPA (Open Policy Agent) authorization.

Beta Feature: OPA authorization is currently in Beta and is not a stable release. It may undergo breaking changes in future versions. Use with caution in production environments.

polaris.oidc🔗

Polaris-specific configuration for OIDC tenants.

polaris.service-identity🔗

Configuration interface for managing service identities across multiple realms in Polaris.

A service identity represents the Polaris service itself when it needs to authenticate to external systems (e.g., AWS services for SigV4 authentication). Each realm can configure its own set of service identities for different cloud providers.

This interface supports multi-tenant deployments where each realm (tenant) can have distinct service identities, as well as single-tenant deployments with a default configuration shared across all catalogs.

Configuration is loaded from polaris.service-identity.* properties at startup and includes credentials that Polaris uses to assume customer-provided roles when accessing federated catalogs.

Example Configuration:

 # Default service identity (used when no realm-specific configuration exists)
 polaris.service-identity.aws-iam.iam-arn=arn:aws:iam::123456789012:user/polaris-default-user
 # Optional: provide static credentials, or omit to use AWS default credential chain
 polaris.service-identity.aws-iam.access-key-id=<access-key-id>
 polaris.service-identity.aws-iam.secret-access-key=<secret-access-key>
 polaris.service-identity.aws-iam.session-token=<optional-session-token>
 # Realm-specific service identity for multi-tenant deployments
 polaris.service-identity.my-realm.aws-iam.iam-arn=arn:aws:iam::123456789012:user/my-realm-user
 polaris.service-identity.my-realm.aws-iam.access-key-id=<access-key-id>
 polaris.service-identity.my-realm.aws-iam.secret-access-key=<secret-access-key>

Storage & Credentials🔗

polaris.storage🔗

Configuration interface containing parameters for clients accessing S3 services from Polaris servers.

Currently, this configuration does not apply to all of Polaris code, but only to select services.

polaris.storage-credential-cache🔗

polaris.credential-manager🔗

Quarkus configuration mapping for Polaris Credential Manager.

Defines which (PolarisCredentialManager) implementation should be used at runtime. This allows switching between different credential management strategies via configuration.

polaris.secrets-manager🔗

polaris.file-io🔗

Persistence🔗

polaris.persistence🔗

polaris.persistence.cache🔗

Persistence cache configuration.

polaris.persistence.distributed-cache-invalidations🔗

polaris.persistence.nosql🔗

Polaris persistence backend configuration.

polaris.persistence.nosql.maintenance🔗

Maintenance service configuration.

polaris.persistence.nosql.maintenance.catalog🔗

No SQL persistence implementation of Polaris stores a history of changes per kind of object (principals, principal roles, grants, immediate tasks, catalog roles and catalog state).

The rules are defined using a CEL script . The default rules for all kinds of objects are to retain the history for 3 days, for the catalog state for 30 days.

The scripts have access to the following declared values:

• ref (string) name of the reference
• commits (64-bit int) number of the currently processed commit, starting at 1
• ageDays (64-bit int) age of currently processed commit in days
• ageHours (64-bit int) age of currently processed commit in hours
• ageMinutes (64-bit int) age of currently processed commit in minutes

Scripts must return a boolean yielding whether the commit shall be retained. Note that maintenance-service implementations can keep the first not-to-be-retained commit.

Example scripts

• ageDays < 30 || commits <= 10 retains the reference history with at least 10 commits and commits that are younger than 30 days
• true retains the whole reference history
• false retains the most recent commit

polaris.persistence.nosql.mongodb🔗

Polaris persistence, MongoDB backend specific configuration.

polaris.persistence.relational.jdbc🔗

Events🔗

polaris.event-listener🔗

polaris.event-listener.persistence-in-memory-buffer🔗

polaris.event-listener.aws-cloudwatch🔗

Configuration interface for AWS CloudWatch event listener integration.

Operational🔗

polaris.tasks🔗

polaris.async🔗

Advanced configuration options to tune async activities.

polaris.rate-limiter.filter🔗

polaris.rate-limiter.token-bucket🔗

polaris.metrics🔗

polaris.iceberg-metrics.reporting🔗

polaris.log🔗

polaris.readiness🔗

polaris.node🔗

Node management configuration.

Other🔗

polaris.realm-context🔗