Other server settings - ClickHouse Documentation

These settings configure the ClickHouse server and are autogenerated from ClickHouse source.

abort_on_logical_error

Crash the server on LOGICAL_ERROR exceptions. Only for experts.

allowed_disks_for_table_engines

List of disks allowed for use with Iceberg

auth_use_forwarded_address

Use originating address for authentication for clients connected through proxy.

Default: false

This setting should be used with extra caution since forwarded addresses can be easily spoofed - servers accepting such authentication should not be accessed directly but rather exclusively through a trusted proxy.

bcrypt_workfactor

Work factor for the bcrypt_password authentication type which uses the Bcrypt algorithm. The work factor defines the amount of computations and time needed to compute the hash and verify the password.

Default: 12

<bcrypt_workfactor>12</bcrypt_workfactor>

For applications with high-frequency authentication, consider alternative authentication methods due to bcrypt’s computational overhead at higher work factors.

blob_storage_log

Settings for the blob_storage_log system table. The following settings can be configured by sub-tags:

Setting	Description	Default	Note
`database`	Name of the database.
`table`	Name of the system table.
`engine`	MergeTree Engine Definition for a system table.		Cannot be used if `partition_by` or `order_by` defined. If not specified `MergeTree` is selected by default
`partition_by`	Custom partitioning key for a system table.		If `engine` is specified for system table, `partition_by` parameter should be specified directly inside ‘engine’
`ttl`	Specifies the table TTL.		If `engine` is specified for system table, `ttl` parameter should be specified directly inside ‘engine’
`order_by`	Custom sorting key for a system table. Can’t be used if `engine` defined.		If `engine` is specified for system table, `order_by` parameter should be specified directly inside ‘engine’
`storage_policy`	Name of the storage policy to use for the table (optional).		If `engine` is specified for system table, `storage_policy` parameter should be specified directly inside ‘engine’
`settings`	Additional parameters that control the behavior of the MergeTree (optional).		If `engine` is specified for system table, `settings` parameter should be specified directly inside ‘engine’
`flush_interval_milliseconds`	Interval for flushing data from the buffer in memory to the table.	`7500`
`max_size_rows`	Maximal size in lines for the logs. When the amount of non-flushed logs reaches the max_size, logs are dumped to the disk.	`1048576`
`reserved_size_rows`	Pre-allocated memory size in lines for the logs.	`8192`
`buffer_size_rows_flush_threshold`	Threshold for amount of lines. If the threshold is reached, flushing logs to the disk is launched in background.	`max_size_rows / 2`
`flush_on_crash`	Sets whether logs should be dumped to the disk in case of a crash.	`false`

Additionally, the following server-level setting controls the default flush policy for all system log tables:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

Setting	Description	Default
`skip_alias_columns`	When `true`, ALIAS columns are omitted from system log table schemas. Required for S3-backed system logs.	`false`

Example:

<blob_storage_log>
    <database>system</database
    <table>blob_storage_log</table
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds
    <ttl>event_date + INTERVAL 30 DAY</ttl>
</blob_storage_log>

builtin_dictionaries_reload_interval

The interval in seconds before reloading built-in dictionaries. ClickHouse reloads built-in dictionaries every x seconds. This makes it possible to edit dictionaries “on the fly” without restarting the server. Example

<builtin_dictionaries_reload_interval>3600</builtin_dictionaries_reload_interval>

cache_size_to_ram_max_ratio

Set cache size to RAM max ratio. Allows lowering the cache size on low-memory systems.

cannot_allocate_thread_fault_injection_probability

For testing purposes.

cgroups_memory_usage_observer_wait_time

Interval in seconds during which the server’s maximum allowed memory consumption is adjusted by the corresponding threshold in cgroups. To disable the cgroup observer, set this value to 0.

compression

Data compression settings for MergeTree-engine tables.

We recommend not changing this if you have just started using ClickHouse.

Configuration template:

<compression>
    <case>
      <min_part_size>...</min_part_size>
      <min_part_size_ratio>...</min_part_size_ratio>
      <method>...</method>
      <level>...</level>
    </case>
    ...
</compression>

<case> fields:

min_part_size – The minimum size of a data part.
min_part_size_ratio – The ratio of the data part size to the table size.
method – Compression method. Acceptable values: lz4, lz4hc, zstd,deflate_qpl.
level – Compression level. See Codecs.

You can configure multiple <case> sections.

Actions when conditions are met:

If a data part matches a condition set, ClickHouse uses the specified compression method.
If a data part matches multiple condition sets, ClickHouse uses the first matched condition set.

If no conditions are met for a data part, ClickHouse uses the lz4 compression.

Example

<compression incl="clickhouse_compression">
    <case>
        <min_part_size>10000000000</min_part_size>
        <min_part_size_ratio>0.01</min_part_size_ratio>
        <method>zstd</method>
        <level>1</level>
    </case>
</compression>

config-file

Points to the server config file.

config_reload_interval_ms

How often clickhouse will reload config and check for new changes

core_dump

Configures soft limit for core dump file size.

Hard limit is configured via system tools

Example

<core_dump>
     <size_limit>1073741824</size_limit>
</core_dump>

crash_log

Settings for the crash_log system table operation. The following settings can be configured by sub-tags:

Setting	Description	Default	Note
`buffer_size_rows_flush_threshold`	Threshold for amount of lines. If the threshold is reached, flushing logs to the disk is launched in background.	`max_size_rows / 2`
`database`	Name of the database.
`engine`	MergeTree Engine Definition for a system table.		Cannot be used if `partition_by` or `order_by` defined. If not specified `MergeTree` is selected by default
`flush_interval_milliseconds`	Interval for flushing data from the buffer in memory to the table.	`7500`
`flush_on_crash`	Sets whether logs should be dumped to the disk in case of a crash.	`false`
`max_size_rows`	Maximal size in lines for the logs. When the amount of non-flushed logs reaches the max_size, logs are dumped to the disk.	`1024`
`order_by`	Custom sorting key for a system table. Can’t be used if `engine` defined.		If `engine` is specified for system table, `order_by` parameter should be specified directly inside ‘engine’
`partition_by`	Custom partitioning key for a system table.		If `engine` is specified for system table, `partition_by` parameter should be specified directly inside ‘engine’
`reserved_size_rows`	Pre-allocated memory size in lines for the logs.	`1024`
`settings`	Additional parameters that control the behavior of the MergeTree (optional).		If `engine` is specified for system table, `settings` parameter should be specified directly inside ‘engine’
`storage_policy`	Name of the storage policy to use for the table (optional).		If `engine` is specified for system table, `storage_policy` parameter should be specified directly inside ‘engine’
`table`	Name of the system table.
`ttl`	Specifies the table TTL.		If `engine` is specified for system table, `ttl` parameter should be specified directly inside ‘engine’

The default server configuration file config.xml contains the following settings section:

<crash_log>
    <database>system</database>
    <table>crash_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1024</max_size_rows>
    <reserved_size_rows>1024</reserved_size_rows>
    <buffer_size_rows_flush_threshold>512</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</crash_log>

create_union_system_log_tables

Requests the creation of all_... tables next to the system log tables (system.all_query_log for system.query_log, system.all_text_log for system.text_log, and so on). Such a table is a union of the corresponding log table, its rotated versions (query_log_0, query_log_1, …) and/or the same tables across all replicas of a cluster, and allows querying them all at once without remembering constructs like clusterAllReplicas(default, merge(system, '^query_log')). The section is optional. If it is present, at least one of the following settings has to be specified:

Setting	Description
`merge_rotated_tables`	If `true`, the `all_...` table selects from the log table and its rotated versions with the `merge` table function.
`cluster`	If specified, the `all_...` table selects from all replicas of this cluster with the `clusterAllReplicas` table function (with `SETTINGS skip_unavailable_shards = 1`, so that unavailable replicas do not fail the queries).

If both settings are specified, the table is a union of the rotated tables across all replicas of the cluster. The option applies to all system log tables; it does not allow for a different configuration for different system logs. The tables are created in the same database as the system log tables at the first flush of each log and are automatically recreated when the structure of the log table changes (on rotation). They have no state, so it is safe to drop them at any time. The creation is supported only for the Atomic, Replicated and Shared database engines.

When the cluster setting is used, the table definition references the cluster, and the cluster has to exist for the table to be loaded. If you remove the cluster from the configuration, also drop the all_... tables (they will be recreated according to the new configuration at the next flush).

Example

<create_union_system_log_tables>
    <merge_rotated_tables>true</merge_rotated_tables>
    <cluster>default</cluster>
</create_union_system_log_tables>

database_atomic_delay_before_drop_table_sec

The delay during which a dropped table can be restored using the UNDROP statement. If DROP TABLE ran with a SYNC modifier, the setting is ignored. The default for this setting is 480 (8 minutes).

dead_letter_queue

Setting for the ‘dead_letter_queue’ system table. The following settings can be configured by sub-tags:

Setting	Description	Default	Note
`database`	Name of the database.
`table`	Name of the system table.
`engine`	MergeTree Engine Definition for a system table.		Cannot be used if `partition_by` or `order_by` defined. If not specified `MergeTree` is selected by default
`partition_by`	Custom partitioning key for a system table.		If `engine` is specified for system table, `partition_by` parameter should be specified directly inside ‘engine’
`ttl`	Specifies the table TTL.		If `engine` is specified for system table, `ttl` parameter should be specified directly inside ‘engine’
`order_by`	Custom sorting key for a system table. Can’t be used if `engine` defined.		If `engine` is specified for system table, `order_by` parameter should be specified directly inside ‘engine’
`storage_policy`	Name of the storage policy to use for the table (optional).		If `engine` is specified for system table, `storage_policy` parameter should be specified directly inside ‘engine’
`settings`	Additional parameters that control the behavior of the MergeTree (optional).		If `engine` is specified for system table, `settings` parameter should be specified directly inside ‘engine’
`flush_interval_milliseconds`	Interval for flushing data from the buffer in memory to the table.	`7500`
`max_size_rows`	Maximal size in lines for the logs. When the amount of non-flushed logs reaches the max_size, logs are dumped to the disk.	`1048576`
`reserved_size_rows`	Pre-allocated memory size in lines for the logs.	`8192`
`buffer_size_rows_flush_threshold`	Threshold for amount of lines. If the threshold is reached, flushing logs to the disk is launched in background.	`max_size_rows / 2`
`flush_on_crash`	Sets whether logs should be dumped to the disk in case of a crash.	`false`

Additionally, the following server-level setting controls the default flush policy for all system log tables:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

Setting	Description	Default
`skip_alias_columns`	When `true`, ALIAS columns are omitted from system log table schemas. Required for S3-backed system logs.	`false`

The default settings are:

<dead_letter_queue>
    <database>system</database>
    <table>dead_letter</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
</dead_letter_queue>

dictionary_background_reconnect_interval

Interval in milliseconds for reconnection attempts of failed MySQL and Postgres dictionaries having background_reconnect enabled.

disk_transaction_wait_for_blob_removal

Default value for the per-disk wait_for_blob_removal setting. When enabled, the server waits for background blob removal to complete before acknowledging the operation.

display_secrets_in_show_and_select

Enables or disables showing secrets in SHOW and SELECT queries for tables, databases, table functions, and dictionaries. User wishing to see secrets must also have format_display_secrets_in_show_and_select format setting turned on and a displaySecretsInShowAndSelect privilege. Possible values:

0 — Disabled.
1 — Enabled.

dns_max_consecutive_failures

Stop further attempts to update a hostname’s DNS cache after this number of consecutive failures. The information still remains in the DNS cache. Zero means unlimited. See also

SYSTEM DROP DNS CACHE

dynamic_user_defined_executable_functions_path

The directory used to keep configuration files of executable UDFs created dynamically by drivers (see CREATE FUNCTION ... ENGINE = DriverName(...)). On server restart, the directory is scanned for configuration files and the corresponding UDFs are loaded without invoking the driver again. Example

<dynamic_user_defined_executable_functions_path>/var/lib/clickhouse/dynamic_user_defined_executable_functions/</dynamic_user_defined_executable_functions_path>

encryption

Configures a command to obtain a key to be used by encryption codecs. Key (or keys) should be written in environment variables or set in the configuration file. Keys can be hex or string with a length equal to 16 bytes. Example Loading from config:

<encryption_codecs>
    <aes_128_gcm_siv>
        <key>1234567812345678</key>
    </aes_128_gcm_siv>
</encryption_codecs>

Storing keys in the configuration file is not recommended. It isn’t secure. You can move the keys into a separate config file on a secure disk and put a symlink to that config file to config.d/ folder.

Loading from config, when the key is in hex:

<encryption_codecs>
    <aes_128_gcm_siv>
        <key_hex>00112233445566778899aabbccddeeff</key_hex>
    </aes_128_gcm_siv>
</encryption_codecs>

Loading key from the environment variable:

<encryption_codecs>
    <aes_128_gcm_siv>
        <key_hex from_env="ENVVAR"></key_hex>
    </aes_128_gcm_siv>
</encryption_codecs>

Here current_key_id sets the current key for encryption, and all specified keys can be used for decryption. Each of these methods can be applied for multiple keys:

<encryption_codecs>
    <aes_128_gcm_siv>
        <key_hex id="0">00112233445566778899aabbccddeeff</key_hex>
        <key_hex id="1" from_env="ENVVAR"></key_hex>
        <current_key_id>1</current_key_id>
    </aes_128_gcm_siv>
</encryption_codecs>

Here current_key_id shows current key for encryption. Also, users can add nonce that must be 12 bytes long (by default encryption and decryption processes use nonce that consists of zero bytes):

<encryption_codecs>
    <aes_128_gcm_siv>
        <nonce>012345678910</nonce>
    </aes_128_gcm_siv>
</encryption_codecs>

Or it can be set in hex:

<encryption_codecs>
    <aes_128_gcm_siv>
        <nonce_hex>abcdefabcdef</nonce_hex>
    </aes_128_gcm_siv>
</encryption_codecs>

Everything mentioned above can be applied for aes_256_gcm_siv (but the key must be 32 bytes long).

enforce_keeper_component_tracking

If enabled, every ZooKeeper request must have a component name set via Coordination::setCurrentComponent. Throws a LOGICAL_ERROR exception if the component is missing.

error_log

It is disabled by default. Enabling To manually turn on error history collection system.error_log, create /etc/clickhouse-server/config.d/error_log.xml with the following content:

<clickhouse>
    <error_log>
        <database>system</database>
        <table>error_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <collect_interval_milliseconds>1000</collect_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
    </error_log>
</clickhouse>

Disabling To disable error_log setting, you should create the following file /etc/clickhouse-server/config.d/disable_error_log.xml with the following content:

<clickhouse>
    <error_log remove="1" />
</clickhouse>

The following settings can be configured by sub-tags:

Setting	Description	Default	Note
`database`	Name of the database.
`table`	Name of the system table.
`engine`	MergeTree Engine Definition for a system table.		Cannot be used if `partition_by` or `order_by` defined. If not specified `MergeTree` is selected by default
`partition_by`	Custom partitioning key for a system table.		If `engine` is specified for system table, `partition_by` parameter should be specified directly inside ‘engine’
`ttl`	Specifies the table TTL.		If `engine` is specified for system table, `ttl` parameter should be specified directly inside ‘engine’
`order_by`	Custom sorting key for a system table. Can’t be used if `engine` defined.		If `engine` is specified for system table, `order_by` parameter should be specified directly inside ‘engine’
`storage_policy`	Name of the storage policy to use for the table (optional).		If `engine` is specified for system table, `storage_policy` parameter should be specified directly inside ‘engine’
`settings`	Additional parameters that control the behavior of the MergeTree (optional).		If `engine` is specified for system table, `settings` parameter should be specified directly inside ‘engine’
`flush_interval_milliseconds`	Interval for flushing data from the buffer in memory to the table.	`7500`
`max_size_rows`	Maximal size in lines for the logs. When the amount of non-flushed logs reaches the max_size, logs are dumped to the disk.	`1048576`
`reserved_size_rows`	Pre-allocated memory size in lines for the logs.	`8192`
`buffer_size_rows_flush_threshold`	Threshold for amount of lines. If the threshold is reached, flushing logs to the disk is launched in background.	`max_size_rows / 2`
`flush_on_crash`	Sets whether logs should be dumped to the disk in case of a crash.	`false`

Additionally, the following server-level setting controls the default flush policy for all system log tables:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

Setting	Description	Default
`skip_alias_columns`	When `true`, ALIAS columns are omitted from system log table schemas. Required for S3-backed system logs.	`false`

filesystem_caches_path

This setting specifies the cache path. Example

<filesystem_caches_path>/var/lib/clickhouse/filesystem_caches/</filesystem_caches_path>

google_protos_path

Defines a directory containing proto files for Protobuf types. Example

<google_protos_path>/usr/share/clickhouse/protos/</google_protos_path>

handshake_timeout_milliseconds

Wall-clock timeout in milliseconds for the entire TCP handshake phase (Hello + Addendum). Limits how long an unauthenticated connection can hold a thread. Set to 0 to disable.

hdfs.libhdfs3_conf

Points libhdfs3 to the right location for its config.

hsts_max_age

Expired time for HSTS in seconds.

A value of 0 means ClickHouse disables HSTS. If you set a positive number, the HSTS will be enabled and the max-age is the number you set.

Example

<hsts_max_age>600000</hsts_max_age>

iceberg_background_schedule_pool_size

Size of thread pool to asynchronously fetch the latest metadata from a remote iceberg catalog; the pool is shared by all the active tables.

ignore_empty_sql_security_in_create_view_query

If true, a CREATE VIEW or CREATE MATERIALIZED VIEW query that specifies neither DEFINER nor SQL SECURITY is stored as written, and the view gets an empty SQL security type. Specifying DEFINER alone counts as SQL SECURITY DEFINER, so such a query is unaffected by this setting. A normal view with an empty SQL security type runs with the permissions of the invoker. For a materialized view with an explicitly specified target table, the access checks on the target table are skipped: inserting into the source table does not require the INSERT privilege on the target table, and reading from the view does not require the SELECT privilege on it. If false, the defaults from the default_normal_view_sql_security, default_materialized_view_sql_security, and default_view_definer settings are written into the view definition at creation time. With the default values of those settings, a materialized view created with neither clause records the creating user as its definer and runs with that user’s permissions. Refreshable materialized views always receive the defaults, regardless of this setting.

Changing this setting affects only views created afterwards; the stored definitions of existing views stay unchanged.

include_from

The path to the file with substitutions. Both XML and YAML formats are supported. For more information, see the section Configuration files. Empty by default, which means that no substitutions file is used. Before version 26.8 the file /etc/metrika.xml was used implicitly whenever it existed; if you rely on it, specify the path explicitly. Note that configuration files that are loaded separately from the main server configuration — the users’ configuration (e.g. users.xml when it is not included in the main file) and XML dictionary configurations — read the include_from element from their own contents, not from the server configuration. Each such file that relies on substitutions needs its own include_from element. Example

<include_from>/etc/clickhouse-server/substitutions.xml</include_from>

insert_deduplication_version

Deprecated migration guard. ClickHouse versions 26.7 and later support only the unified insert deduplication hash (new_unified_hash); the server refuses to start if this setting is present with any other value (such as old_separate_hashes or compatible_double_hashes). Complete the deduplication migration on the previous version before upgrading by running compatible_double_hashes (which writes both the legacy and unified hashes). For replicated tables run it for at least replicated_deduplication_window_seconds (one hour by default); the default windows retain the unified hashes of all inserts for that window, which is considered enough to cover an insert retry loop. For non-replicated tables with non_replicated_deduplication_window > 0 the window is count-based rather than time-based, so run compatible_double_hashes for at least that many inserts before upgrading.

io_thread_pool_queue_size

The maximum number of jobs that can be scheduled on the IO Thread pool.

A value of 0 means unlimited.

keep_alive_timeout

The number of seconds that ClickHouse waits for incoming requests for HTTP protocol before closing the connection. Example

<keep_alive_timeout>30</keep_alive_timeout>

ldap_servers

List LDAP servers with their connection parameters here to:

use them as authenticators for dedicated local users, who have an ‘ldap’ authentication mechanism specified instead of ‘password’
use them as remote user directories.

The following settings can be configured by sub-tags:

Setting	Description
`bind_dn`	Template used to construct the DN to bind to. The resulting DN will be constructed by replacing all `\{user_name\}` substrings of the template with the actual user name during each authentication attempt.
`enable_tls`	Flag to trigger use of secure connection to the LDAP server. Specify `no` for plain text (`ldap://`) protocol (not recommended). Specify `yes` for LDAP over SSL/TLS (`ldaps://`) protocol (recommended, the default). Specify `starttls` for legacy StartTLS protocol (plain text (`ldap://`) protocol, upgraded to TLS).
`host`	LDAP server hostname or IP, this parameter is mandatory and cannot be empty.
`port`	LDAP server port, default is 636 if `enable_tls` is set to true, `389` otherwise.
`tls_ca_cert_dir`	path to the directory containing CA certificates.
`tls_ca_cert_file`	path to CA certificate file.
`tls_cert_file`	path to certificate file.
`tls_cipher_suite`	allowed cipher suite (in OpenSSL notation).
`tls_key_file`	path to certificate key file.
`tls_minimum_protocol_version`	The minimum protocol version of SSL/TLS. Accepted values are: `ssl2`, `ssl3`, `tls1.0`, `tls1.1`, `tls1.2` (the default).
`tls_require_cert`	SSL/TLS peer certificate verification behavior. Accepted values are: `never`, `allow`, `try`, `demand` (the default).
`user_dn_detection`	Section with LDAP search parameters for detecting the actual user DN of the bound user. This is mainly used in search filters for further role mapping when the server is Active Directory. The resulting user DN will be used when replacing `\{user_dn\}` substrings wherever they are allowed. By default, user DN is set equal to bind DN, but once search is performed, it will be updated with to the actual detected user DN value.
`verification_cooldown`	A period of time, in seconds, after a successful bind attempt, during which a user will be assumed to be successfully authenticated for all consecutive requests without contacting the LDAP server. Specify `0` (the default) to disable caching and force contacting the LDAP server for each authentication request.

Setting user_dn_detection can be configured with sub-tags:

Setting	Description
`base_dn`	template used to construct the base DN for the LDAP search. The resulting DN will be constructed by replacing all `\{user_name\}` and ‘{bind_dn}’ substrings of the template with the actual user name and bind DN during the LDAP search.
`scope`	scope of the LDAP search. Accepted values are: `base`, `one_level`, `children`, `subtree` (the default).
`search_filter`	template used to construct the search filter for the LDAP search. The resulting filter will be constructed by replacing all `\{user_name\}`, `\{bind_dn\}`, and `\{base_dn\}` substrings of the template with the actual user name, bind DN, and base DN during the LDAP search. Note, that the special characters must be escaped properly in XML.

Example:

<my_ldap_server>
    <host>localhost</host>
    <port>636</port>
    <bind_dn>uid={user_name},ou=users,dc=example,dc=com</bind_dn>
    <verification_cooldown>300</verification_cooldown>
    <enable_tls>yes</enable_tls>
    <tls_minimum_protocol_version>tls1.2</tls_minimum_protocol_version>
    <tls_require_cert>demand</tls_require_cert>
    <tls_cert_file>/path/to/tls_cert_file</tls_cert_file>
    <tls_key_file>/path/to/tls_key_file</tls_key_file>
    <tls_ca_cert_file>/path/to/tls_ca_cert_file</tls_ca_cert_file>
    <tls_ca_cert_dir>/path/to/tls_ca_cert_dir</tls_ca_cert_dir>
    <tls_cipher_suite>ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384</tls_cipher_suite>
</my_ldap_server>

Example (typical Active Directory with configured user DN detection for further role mapping):

<my_ad_server>
    <host>localhost</host>
    <port>389</port>
    <bind_dn>EXAMPLE\{user_name}</bind_dn>
    <user_dn_detection>
        <base_dn>CN=Users,DC=example,DC=com</base_dn>
        <search_filter>(&amp;(objectClass=user)(sAMAccountName={user_name}))</search_filter>
    </user_dn_detection>
    <enable_tls>no</enable_tls>
</my_ad_server>

logger

The location and format of log messages. Keys:

Key	Description
`async`	When `true` (default) logging will happen asynchronously (one background thread per output channel). Otherwise it will log inside the thread calling LOG
`async_queue_max_size`	When using async logging, the max amount of messages that will be kept in the the queue waiting for flushing. Extra messages will be dropped
`console`	Enable logging to the console. Set to `1` or `true` to enable. Default is `1` if ClickHouse does not run in daemon mode, `0` otherwise.
`console_log_level`	Log level for console output. Defaults to `level`.
`console_shutdown_log_level`	Shutdown level is used to set the console log level at server Shutdown.
`console_startup_log_level`	Startup level is used to set the console log level at server startup. After startup log level is reverted to the `console_log_level` setting
`count`	Rotation policy: How many historical log files ClickHouse are kept at most.
`errorlog`	The path to the error log file.
`formatting.type`	Log format for console output. Currently, only `json` is supported
`level`	Log level. Acceptable values: `none` (turn logging off), `fatal`, `critical`, `error`, `warning`, `notice`, `information`,`debug`, `trace`, `test`
`log`	The path to the log file.
`rotation`	Rotation policy: Controls when log files are rotated. Rotation can be based on size, time, or a combination of both. Examples: 100M, daily, 100M,daily. Once the log file exceeds the specified size or when the specified time interval is reached, it is renamed and archived, and a new log file is created.
`shutdown_level`	Shutdown level is used to set the root logger level at server Shutdown.
`size`	Rotation policy: Maximum size of the log files in bytes. Once the log file size exceeds this threshold, it is renamed and archived, and a new log file is created.
`startup_level`	Startup level is used to set the root logger level at server startup. After startup log level is reverted to the `level` setting
`stream_compress`	Compress log messages using LZ4. Set to `1` or `true` to enable.
`syslog_level`	Log level for logging to syslog.
`use_syslog`	Also forward log output to syslog.

Log format specifiers File names in log and errorLog paths support below format specifiers for the resulting file name (the directory part does not support them). Column “Example” shows the output at 2023-07-06 18:32:07.

Specifier	Description	Example
`%%`	Literal %	`%`
`%n`	New-line character
`%t`	Horizontal tab character
`%Y`	Year as a decimal number, e.g. 2017	`2023`
`%y`	Last 2 digits of year as a decimal number (range [00,99])	`23`
`%C`	First 2 digits of year as a decimal number (range [00,99])	`20`
`%G`	Four-digit ISO 8601 week-based year, i.e. the year that contains the specified week. Normally useful only with `%V`	`2023`
`%g`	Last 2 digits of ISO 8601 week-based year, i.e. the year that contains the specified week.	`23`
`%b`	Abbreviated month name, e.g. Oct (locale dependent)	`Jul`
`%h`	Synonym of %b	`Jul`
`%B`	Full month name, e.g. October (locale dependent)	`July`
`%m`	Month as a decimal number (range [01,12])	`07`
`%U`	Week of the year as a decimal number (Sunday is the first day of the week) (range [00,53])	`27`
`%W`	Week of the year as a decimal number (Monday is the first day of the week) (range [00,53])	`27`
`%V`	ISO 8601 week number (range [01,53])	`27`
`%j`	Day of the year as a decimal number (range [001,366])	`187`
`%d`	Day of the month as a zero-padded decimal number (range [01,31]). Single digit is preceded by zero.	`06`
`%e`	Day of the month as a space-padded decimal number (range [1,31]). Single digit is preceded by a space.	`  6`
`%a`	Abbreviated weekday name, e.g. Fri (locale dependent)	`Thu`
`%A`	Full weekday name, e.g. Friday (locale dependent)	`Thursday`
`%w`	Weekday as a integer number with Sunday as 0 (range [0-6])	`4`
`%u`	Weekday as a decimal number, where Monday is 1 (ISO 8601 format) (range [1-7])	`4`
`%H`	Hour as a decimal number, 24 hour clock (range [00-23])	`18`
`%I`	Hour as a decimal number, 12 hour clock (range [01,12])	`06`
`%M`	Minute as a decimal number (range [00,59])	`32`
`%S`	Second as a decimal number (range [00,60])	`07`
`%c`	Standard date and time string, e.g. Sun Oct 17 04:41:13 2010 (locale dependent)	`Thu Jul 6 18:32:07 2023`
`%x`	Localized date representation (locale dependent)	`07/06/23`
`%X`	Localized time representation, e.g. 18:40:20 or 6:40:20 PM (locale dependent)	`18:32:07`
`%D`	Short MM/DD/YY date, equivalent to %m/%d/%y	`07/06/23`
`%F`	Short YYYY-MM-DD date, equivalent to %Y-%m-%d	`2023-07-06`
`%r`	Localized 12-hour clock time (locale dependent)	`06:32:07 PM`
`%R`	Equivalent to “%H:%M”	`18:32`
`%T`	Equivalent to “%H:%M:%S” (the ISO 8601 time format)	`18:32:07`
`%p`	Localized a.m. or p.m. designation (locale dependent)	`PM`
`%z`	Offset from UTC in the ISO 8601 format (e.g. -0430), or no characters if the time zone information is not available	`+0800`
`%Z`	Locale-dependent time zone name or abbreviation, or no characters if the time zone information is not available	`Z AWST`

Example

<logger>
    <level>trace</level>
    <log>/var/log/clickhouse-server/clickhouse-server-%F-%T.log</log>
    <errorlog>/var/log/clickhouse-server/clickhouse-server-%F-%T.err.log</errorlog>
    <size>1000M</size>
    <count>10</count>
    <stream_compress>true</stream_compress>
</logger>

To print log messages only in the console:

<logger>
    <level>information</level>
    <console>true</console>
</logger>

Per-level Overrides The log level of individual log names can be overridden. For example, to mute all messages of loggers “Backup” and “RBAC”.

<logger>
    <levels>
        <logger>
            <name>Backup</name>
            <level>none</level>
        </logger>
        <logger>
            <name>RBAC</name>
            <level>none</level>
        </logger>
    </levels>
</logger>

syslog To write log messages additionally to syslog:

<logger>
    <use_syslog>1</use_syslog>
    <syslog>
        <address>syslog.remote:10514</address>
        <hostname>myhost.local</hostname>
        <facility>LOG_LOCAL6</facility>
        <format>syslog</format>
    </syslog>
</logger>

Keys for <syslog>:

Key	Description
`address`	The address of syslog in format `host\[:port\]`. If omitted, the local daemon is used.
`hostname`	The name of the host from which logs are send (optional).
`facility`	The syslog facility keyword. Must be specified uppercase with a “LOG_” prefix, e.g. `LOG_USER`, `LOG_DAEMON`, `LOG_LOCAL3`, etc. Default: `LOG_USER` if `address` is specified, `LOG_DAEMON` otherwise.
`format`	Log message format. Possible values: `bsd` and `syslog.`

Log formats You can specify the log format that will be outputted in the console log. Currently, only JSON is supported. Example Here is an example of an output JSON log:

{
  "date_time_utc": "2024-11-06T09:06:09Z",
  "date_time": "1650918987.180175",
  "thread_name": "#1",
  "thread_id": "254545",
  "level": "Trace",
  "query_id": "",
  "logger_name": "BaseDaemon",
  "message": "Received signal 2",
  "source_file": "../base/daemon/BaseDaemon.cpp; virtual void SignalListener::run()",
  "source_line": "192"
}

To enable JSON logging support, use the following snippet:

<logger>
    <formatting>
        <type>json</type>
        <!-- Can be configured on a per-channel basis (log, errorlog, console, syslog), or globally for all channels (then just omit it). -->
        <!-- <channel></channel> -->
        <names>
            <date_time>date_time</date_time>
            <thread_name>thread_name</thread_name>
            <thread_id>thread_id</thread_id>
            <level>level</level>
            <query_id>query_id</query_id>
            <logger_name>logger_name</logger_name>
            <message>message</message>
            <source_file>source_file</source_file>
            <source_line>source_line</source_line>
        </names>
    </formatting>
</logger>

Renaming keys for JSON logs Key names can be modified by changing tag values inside the <names> tag. For example, to change DATE_TIME to MY_DATE_TIME, you can use <date_time>MY_DATE_TIME</date_time>. Omitting keys for JSON logs Log properties can be omitted by commenting out the property. For example, if you do not want your log to print query_id, you can comment out the <query_id> tag.

logger.count

Rotation policy: How many historical log files ClickHouse are kept at most.

logger.errorlog

The path to the error log file.

logger.formatting.type

Log format for console output. Currently, only <json> is supported.

logger.level

Log level. Acceptable values: <none> (turn logging off), <fatal>, <critical>, <error>, <warning>, <notice>, <information>, <debug>, <trace>, <test>.

logger.log

The path to the log file.

logger.rotation

Rotation policy: Controls when log files are rotated. Rotation can be based on size, time, or a combination of both. Examples: 100M, daily, 100M,daily. Once the log file exceeds the specified size or when the specified time interval is reached, it is renamed and archived, and a new log file is created.

logger.shutdown_level

Shutdown level is used to set the root logger level at server Shutdown.

logger.size

Rotation policy: Maximum size of the log files in bytes. Once the log file size exceeds this threshold, it is renamed and archived, and a new log file is created.

logger.startup_level

Startup level is used to set the root logger level at server startup. After startup log level is reverted to the <level> setting.

logger.stream_compress

Compress log messages using LZ4. Set to <1> or <true> to enable.

logger.syslog_level

Log level for logging to syslog.

logger.use_syslog

Also forward log output to syslog.

macros

Parameter substitutions for replicated tables. Can be omitted if replicated tables are not used. For more information, see the section Creating replicated tables. Example

<macros incl="macros" optional="true" />

message_queue_disable_insertion

Disable insertion from message queue engines (Kafka, RabbitMQ, NATS) into attached materialized views

metric_log

It is disabled by default. Enabling To manually turn on metrics history collection system.metric_log, create /etc/clickhouse-server/config.d/metric_log.xml with the following content:

<clickhouse>
    <metric_log>
        <database>system</database>
        <table>metric_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <collect_interval_milliseconds>1000</collect_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
    </metric_log>
</clickhouse>

Disabling To disable metric_log setting, you should create the following file /etc/clickhouse-server/config.d/disable_metric_log.xml with the following content:

<clickhouse>
    <metric_log remove="1" />
</clickhouse>

The following settings can be configured by sub-tags:

Setting	Description	Default	Note
`database`	Name of the database.
`table`	Name of the system table.
`engine`	MergeTree Engine Definition for a system table.		Cannot be used if `partition_by` or `order_by` defined. If not specified `MergeTree` is selected by default
`partition_by`	Custom partitioning key for a system table.		If `engine` is specified for system table, `partition_by` parameter should be specified directly inside ‘engine’
`ttl`	Specifies the table TTL.		If `engine` is specified for system table, `ttl` parameter should be specified directly inside ‘engine’
`order_by`	Custom sorting key for a system table. Can’t be used if `engine` defined.		If `engine` is specified for system table, `order_by` parameter should be specified directly inside ‘engine’
`storage_policy`	Name of the storage policy to use for the table (optional).		If `engine` is specified for system table, `storage_policy` parameter should be specified directly inside ‘engine’
`settings`	Additional parameters that control the behavior of the MergeTree (optional).		If `engine` is specified for system table, `settings` parameter should be specified directly inside ‘engine’
`flush_interval_milliseconds`	Interval for flushing data from the buffer in memory to the table.	`7500`
`max_size_rows`	Maximal size in lines for the logs. When the amount of non-flushed logs reaches the max_size, logs are dumped to the disk.	`1048576`
`reserved_size_rows`	Pre-allocated memory size in lines for the logs.	`8192`
`buffer_size_rows_flush_threshold`	Threshold for amount of lines. If the threshold is reached, flushing logs to the disk is launched in background.	`max_size_rows / 2`
`flush_on_crash`	Sets whether logs should be dumped to the disk in case of a crash.	`false`

Additionally, the following server-level setting controls the default flush policy for all system log tables:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

Setting	Description	Default
`skip_alias_columns`	When `true`, ALIAS columns are omitted from system log table schemas. Required for S3-backed system logs.	`false`

mmap_cache_size

This setting allows avoiding frequent open/close calls (which are very expensive due to consequent page faults), and to reuse mappings from several threads and queries. The setting value is the number of mapped regions (usually equal to the number of mapped files). The amount of data in mapped files can be monitored in the following system tables with the following metrics:

MMappedFiles/MMappedFileBytes/MMapCacheCells in system.metrics, system.metric_log
CreatedReadBufferMMap/CreatedReadBufferMMapFailed/MMappedFileCacheHits/MMappedFileCacheMisses in system.events, system.processes, system.query_log, system.query_thread_log, system.query_views_log

The amount of data in mapped files does not consume memory directly and is not accounted for in query or server memory usage — because this memory can be discarded similar to the OS page cache. The cache is dropped (the files are closed) automatically on the removal of old parts in tables of the MergeTree family, also it can be dropped manually by the SYSTEM DROP MMAP CACHE query.This setting can be modified at runtime and will take effect immediately.

mutation_workload

Used to regulate how resources are utilized and shared between mutations and other workloads. Specified value is used as workload setting value for all background mutations. Can be overridden by a merge tree setting. See Also

Workload Scheduling

named_collections_storage.type

The storage type for named collections. Possible values are local, local_encrypted, keeper, keeper_encrypted, zookeeper, and zookeeper_encrypted. Configured as named_collections_storage.type (<named_collections_storage><type> in XML).

oom_score

On Linux systems this can control the behavior of OOM killer.

openSSL

SSL client/server configuration. Support for SSL is provided by the libpoco library. The available configuration options are explained in SSLManager.h. Default values can be found in SSLManager.cpp. The files referenced by certificateFile, privateKeyFile and caConfig are reloaded without a restart when they change or on SYSTEM RELOAD CONFIG. New connections use the reloaded certificates, established connections are not affected. Keys for server/client settings:

Option	Description	Default Value
`cacheSessions`	Enables or disables caching sessions. Must be used in combination with `sessionIdContext`. Acceptable values: `true`, `false`.	`false`
`caConfig`	Path to the file or directory that contains trusted CA certificates. If this points to a file, it must be in PEM format and can contain several CA certificates. If this points to a directory, it must contain one .pem file per CA certificate. The filenames are looked up by the CA subject name hash value. Details can be found in the man page of SSL_CTX_load_verify_locations. Like `certificateFile` and `privateKeyFile`, the CA certificates are reloaded without a restart when the file changes or on `SYSTEM RELOAD CONFIG`.
`certificateFile`	Path to the client/server certificate file in PEM format. You can omit it if `privateKeyFile` contains the certificate.
`cipherList`	Supported OpenSSL encryptions.	`ALL:!ADH:!LOW:!EXP:!MD5:!3DES:@STRENGTH`
`disableProtocols`	Protocols that are not allowed to be used.
`extendedVerification`	If enabled, verify that the certificate CN or SAN matches the peer hostname.	`false`
`fips`	Activates OpenSSL FIPS mode. Supported if the library’s OpenSSL version supports FIPS.	`false`
`invalidCertificateHandler`	Class (a subclass of CertificateHandler) for verifying invalid certificates. For example: `<invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>` .	`RejectCertificateHandler`
`loadDefaultCAFile`	Wether built-in CA certificates for OpenSSL will be used. ClickHouse assumes that builtin CA certificates are in the file `/etc/ssl/cert.pem` (resp. the directory `/etc/ssl/certs`) or in file (resp. directory) specified by the environment variable `SSL_CERT_FILE` (resp. `SSL_CERT_DIR`).	`true`
`preferServerCiphers`	Client-preferred server ciphers.	`false`
`privateKeyFile`	Path to the file with the secret key of the PEM certificate. The file may contain a key and certificate at the same time.
`privateKeyPassphraseHandler`	Class (PrivateKeyPassphraseHandler subclass) that requests the passphrase for accessing the private key. For example: `<privateKeyPassphraseHandler>`, `<name>KeyFileHandler</name>`, `<options><password>test</password></options>`, `</privateKeyPassphraseHandler>`.	`KeyConsoleHandler`
`requireTLSv1`	Require a TLSv1 connection. Acceptable values: `true`, `false`.	`false`
`requireTLSv1_1`	Require a TLSv1.1 connection. Acceptable values: `true`, `false`.	`false`
`requireTLSv1_2`	Require a TLSv1.2 connection. Acceptable values: `true`, `false`.	`false`
`sessionCacheSize`	The maximum number of sessions that the server caches. A value of `0` means unlimited sessions.	1024*20
`sessionIdContext`	A unique set of random characters that the server appends to each generated identifier. The length of the string must not exceed `SSL_MAX_SSL_SESSION_ID_LENGTH`. This parameter is always recommended since it helps avoid problems both if the server caches the session and if the client requested caching.	`$\{application.name\}`
`sessionTimeout`	Time for caching the session on the server in hours.	`2`
`verificationDepth`	The maximum length of the verification chain. Verification will fail if the certificate chain length exceeds the set value.	`9`
`verificationMode`	The method for checking the node’s certificates. Details are in the description of the Context class. Possible values: `none`, `relaxed`, `strict`, `once`.	`relaxed`

Example of settings:

<openSSL>
    <server>
        <!-- openssl req -subj "/CN=localhost" -new -newkey rsa:2048 -days 365 -nodes -x509 -keyout /etc/clickhouse-server/server.key -out /etc/clickhouse-server/server.crt -->
        <certificateFile>/etc/clickhouse-server/server.crt</certificateFile>
        <privateKeyFile>/etc/clickhouse-server/server.key</privateKeyFile>
        <!-- openssl dhparam -out /etc/clickhouse-server/dhparam.pem 4096 -->
        <dhParamsFile>/etc/clickhouse-server/dhparam.pem</dhParamsFile>
        <verificationMode>none</verificationMode>
        <loadDefaultCAFile>true</loadDefaultCAFile>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
    </server>
    <client>
        <loadDefaultCAFile>true</loadDefaultCAFile>
        <cacheSessions>true</cacheSessions>
        <disableProtocols>sslv2,sslv3</disableProtocols>
        <preferServerCiphers>true</preferServerCiphers>
        <!-- Use for self-signed: <verificationMode>none</verificationMode> -->
        <invalidCertificateHandler>
            <!-- Use for self-signed: <name>AcceptCertificateHandler</name> -->
            <name>RejectCertificateHandler</name>
        </invalidCertificateHandler>
    </client>
</openSSL>

openSSL.client.caConfig

Path to the file or directory that contains trusted CA certificates. If this points to a file, it must be in PEM format and can contain several CA certificates. If this points to a directory, it must contain one .pem file per CA certificate. The filenames are looked up by the CA subject name hash value. Details can be found in the man page of SSL_CTX_load_verify_locations. The CA certificates are reloaded without a restart when the file changes or on SYSTEM RELOAD CONFIG; new connections are verified against the reloaded certificates.

openSSL.client.cacheSessions

Enables or disables caching sessions. Must be used in combination with <sessionIdContext>. Acceptable values: <true>, <false>.

openSSL.client.certificateFile

Path to the client/server certificate file in PEM format. You can omit it if <privateKeyFile> contains the certificate.

openSSL.client.cipherList

Supported OpenSSL encryptions.

openSSL.client.disableProtocols

Protocols that are not allowed to be used.

openSSL.client.extendedVerification

If enabled, verify that the certificate CN or SAN matches the peer hostname.

openSSL.client.fips

Activates OpenSSL FIPS mode. Supported if the library’s OpenSSL version supports FIPS.

openSSL.client.invalidCertificateHandler.name

Class (a subclass of CertificateHandler) for verifying invalid certificates. For example: <<invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>>.

openSSL.client.loadDefaultCAFile

Determines whether built-in CA certificates for OpenSSL will be used. ClickHouse assumes that builtin CA certificates are in the file </etc/ssl/cert.pem> (resp. the directory </etc/ssl/certs>) or in file (resp. directory) specified by the environment variable <SSL_CERT_FILE> (resp. <SSL_CERT_DIR>).

openSSL.client.preferServerCiphers

Client-preferred server ciphers.

openSSL.client.privateKeyFile

Path to the file with the secret key of the PEM certificate. The file may contain a key and certificate at the same time.

openSSL.client.privateKeyPassphraseHandler.name

Class (PrivateKeyPassphraseHandler subclass) that requests the passphrase for accessing the private key. For example: <<privateKeyPassphraseHandler>>, <<name>KeyFileHandler</name>>, <<options><password>test</password></options>>, <</privateKeyPassphraseHandler>>

openSSL.client.verificationDepth

The maximum length of the verification chain. Verification will fail if the certificate chain length exceeds the set value.

openSSL.client.verificationMode

The method for checking the node’s certificates. Details are in the description of the Context class. Possible values: <none>, <relaxed>, <strict>, <once>.

openSSL.server.caConfig

openSSL.server.cacheSessions

Enables or disables caching sessions. Must be used in combination with <sessionIdContext>. Acceptable values: <true>, <false>.

openSSL.server.certificateFile

Path to the client/server certificate file in PEM format. You can omit it if <privateKeyFile> contains the certificate.

openSSL.server.cipherList

Supported OpenSSL encryptions.

openSSL.server.disableProtocols

Protocols that are not allowed to be used.

openSSL.server.extendedVerification

If enabled, verify that the certificate CN or SAN matches the peer hostname.

openSSL.server.fips

Activates OpenSSL FIPS mode. Supported if the library’s OpenSSL version supports FIPS.

openSSL.server.invalidCertificateHandler.name

Class (a subclass of CertificateHandler) for verifying invalid certificates. For example: <<invalidCertificateHandler> <name>RejectCertificateHandler</name> </invalidCertificateHandler>>.

openSSL.server.loadDefaultCAFile

openSSL.server.preferServerCiphers

Client-preferred server ciphers.

openSSL.server.privateKeyFile

Path to the file with the secret key of the PEM certificate. The file may contain a key and certificate at the same time.

openSSL.server.privateKeyPassphraseHandler.name

openSSL.server.sessionCacheSize

The maximum number of sessions that the server caches. A value of 0 means unlimited sessions.

openSSL.server.sessionIdContext

A unique set of random characters that the server appends to each generated identifier. The length of the string must not exceed <SSL_MAX_SSL_SESSION_ID_LENGTH>. This parameter is always recommended since it helps avoid problems both if the server caches the session and if the client requested caching.

openSSL.server.sessionTimeout

Time for caching the session on the server in hours.

openSSL.server.verificationDepth

The maximum length of the verification chain. Verification will fail if the certificate chain length exceeds the set value.

openSSL.server.verificationMode

The method for checking the node’s certificates. Details are in the description of the Context class. Possible values: <none>, <relaxed>, <strict>, <once>.

opentelemetry_span_log

Settings for the opentelemetry_span_log system table. The following settings can be configured by sub-tags:

Setting	Description	Default	Note
`database`	Name of the database.
`table`	Name of the system table.
`engine`	MergeTree Engine Definition for a system table.		Cannot be used if `partition_by` or `order_by` defined. If not specified `MergeTree` is selected by default
`partition_by`	Custom partitioning key for a system table.		If `engine` is specified for system table, `partition_by` parameter should be specified directly inside ‘engine’
`ttl`	Specifies the table TTL.		If `engine` is specified for system table, `ttl` parameter should be specified directly inside ‘engine’
`order_by`	Custom sorting key for a system table. Can’t be used if `engine` defined.		If `engine` is specified for system table, `order_by` parameter should be specified directly inside ‘engine’
`storage_policy`	Name of the storage policy to use for the table (optional).		If `engine` is specified for system table, `storage_policy` parameter should be specified directly inside ‘engine’
`settings`	Additional parameters that control the behavior of the MergeTree (optional).		If `engine` is specified for system table, `settings` parameter should be specified directly inside ‘engine’
`flush_interval_milliseconds`	Interval for flushing data from the buffer in memory to the table.	`7500`
`max_size_rows`	Maximal size in lines for the logs. When the amount of non-flushed logs reaches the max_size, logs are dumped to the disk.	`1048576`
`reserved_size_rows`	Pre-allocated memory size in lines for the logs.	`8192`
`buffer_size_rows_flush_threshold`	Threshold for amount of lines. If the threshold is reached, flushing logs to the disk is launched in background.	`max_size_rows / 2`
`flush_on_crash`	Sets whether logs should be dumped to the disk in case of a crash.	`false`

Additionally, the following server-level setting controls the default flush policy for all system log tables:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

Setting	Description	Default
`skip_alias_columns`	When `true`, ALIAS columns are omitted from system log table schemas. Required for S3-backed system logs.	`false`

Example:

<opentelemetry_span_log>
    <engine>
        engine MergeTree
        partition by toYYYYMM(finish_date)
        order by (finish_date, finish_time_us, trace_id)
    </engine>
    <database>system</database>
    <table>opentelemetry_span_log</table>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</opentelemetry_span_log>

part_log

Logging events that are associated with MergeTree. For instance, adding or merging data. You can use the log to simulate merge algorithms and compare their characteristics. You can visualize the merge process. Queries are logged in the system.part_log table, not in a separate file. You can configure the name of this table in the table parameter (see below). The following settings can be configured by sub-tags:

Setting	Description	Default	Note
`database`	Name of the database.
`table`	Name of the system table.
`engine`	MergeTree Engine Definition for a system table.		Cannot be used if `partition_by` or `order_by` defined. If not specified `MergeTree` is selected by default
`partition_by`	Custom partitioning key for a system table.		If `engine` is specified for system table, `partition_by` parameter should be specified directly inside ‘engine’
`ttl`	Specifies the table TTL.		If `engine` is specified for system table, `ttl` parameter should be specified directly inside ‘engine’
`order_by`	Custom sorting key for a system table. Can’t be used if `engine` defined.		If `engine` is specified for system table, `order_by` parameter should be specified directly inside ‘engine’
`storage_policy`	Name of the storage policy to use for the table (optional).		If `engine` is specified for system table, `storage_policy` parameter should be specified directly inside ‘engine’
`settings`	Additional parameters that control the behavior of the MergeTree (optional).		If `engine` is specified for system table, `settings` parameter should be specified directly inside ‘engine’
`flush_interval_milliseconds`	Interval for flushing data from the buffer in memory to the table.	`7500`
`max_size_rows`	Maximal size in lines for the logs. When the amount of non-flushed logs reaches the max_size, logs are dumped to the disk.	`1048576`
`reserved_size_rows`	Pre-allocated memory size in lines for the logs.	`8192`
`buffer_size_rows_flush_threshold`	Threshold for amount of lines. If the threshold is reached, flushing logs to the disk is launched in background.	`max_size_rows / 2`
`flush_on_crash`	Sets whether logs should be dumped to the disk in case of a crash.	`false`

Additionally, the following server-level setting controls the default flush policy for all system log tables:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

Setting	Description	Default
`skip_alias_columns`	When `true`, ALIAS columns are omitted from system log table schemas. Required for S3-backed system logs.	`false`

Example

<part_log>
    <database>system</database>
    <table>part_log</table>
    <partition_by>toMonday(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</part_log>

path

The path to the directory containing data.

The trailing slash is mandatory.

Example

<path>/var/lib/clickhouse/</path>

per_cpu_untracked_memory_thread_buffer

Amount of untracked memory, in bytes, each thread may hold without touching the shared per-CPU budget. It amortizes the cost of the per-CPU bookkeeping for small allocations and is the slack added on top of max_per_cpu_untracked_memory * number_of_cpus in the worst case. A value of 0 removes the slack: every allocation updates the shared per-CPU counter (most precise, but more contention). Linux only.

point_in_polygon_cache_size

Maximum size in bytes of the cache of preprocessed polygons used by the function pointInPolygon with a constant polygon argument. Entries above the limit are evicted in least recently used order. Setting it to 0 disables the cache: all cached polygons are evicted, and every subsequent query preprocesses its constant polygon anew. The cache can also be cleared manually, without changing this limit, with the SYSTEM DROP POINT IN POLYGON CACHE query.

This setting can be modified at runtime and will take effect immediately.

prefixes_deserialization_thread_pool_thread_pool_queue_size

The maximum number of jobs that can be scheduled on the prefixes deserialization Thread pool.

A value of 0 means unlimited.

prepare_system_log_tables_on_startup

If true, ClickHouse creates all configured system.*_log tables before the startup. It can be helpful if some startup scripts depend on these tables.

process_query_plan_packet

This setting allows reading QueryPlan packet. This packet is sent for distributed queries when serialize_query_plan is enabled. Disabled by default to avoid possible security issues which can be caused by bugs in query plan binary deserialization. Example

<process_query_plan_packet>true</process_query_plan_packet>

processors_profile_log

Settings for the processors_profile_log system table. The following settings can be configured by sub-tags:

Setting	Description	Default	Note
`database`	Name of the database.
`table`	Name of the system table.
`engine`	MergeTree Engine Definition for a system table.		Cannot be used if `partition_by` or `order_by` defined. If not specified `MergeTree` is selected by default
`partition_by`	Custom partitioning key for a system table.		If `engine` is specified for system table, `partition_by` parameter should be specified directly inside ‘engine’
`ttl`	Specifies the table TTL.		If `engine` is specified for system table, `ttl` parameter should be specified directly inside ‘engine’
`order_by`	Custom sorting key for a system table. Can’t be used if `engine` defined.		If `engine` is specified for system table, `order_by` parameter should be specified directly inside ‘engine’
`storage_policy`	Name of the storage policy to use for the table (optional).		If `engine` is specified for system table, `storage_policy` parameter should be specified directly inside ‘engine’
`settings`	Additional parameters that control the behavior of the MergeTree (optional).		If `engine` is specified for system table, `settings` parameter should be specified directly inside ‘engine’
`flush_interval_milliseconds`	Interval for flushing data from the buffer in memory to the table.	`7500`
`max_size_rows`	Maximal size in lines for the logs. When the amount of non-flushed logs reaches the max_size, logs are dumped to the disk.	`1048576`
`reserved_size_rows`	Pre-allocated memory size in lines for the logs.	`8192`
`buffer_size_rows_flush_threshold`	Threshold for amount of lines. If the threshold is reached, flushing logs to the disk is launched in background.	`max_size_rows / 2`
`flush_on_crash`	Sets whether logs should be dumped to the disk in case of a crash.	`false`

Additionally, the following server-level setting controls the default flush policy for all system log tables:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

Setting	Description	Default
`skip_alias_columns`	When `true`, ALIAS columns are omitted from system log table schemas. Required for S3-backed system logs.	`false`

The default settings are:

<processors_profile_log>
    <database>system</database>
    <table>processors_profile_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</processors_profile_log>

prometheus

Exposing metrics data for scraping from Prometheus. Settings:

endpoint – HTTP endpoint for scraping metrics by prometheus server. Start from ’/’.
port – Port for endpoint.
metrics – Expose metrics from the system.metrics table.
events – Expose metrics from the system.events table.
asynchronous_metrics – Expose current metrics values from the system.asynchronous_metrics table. Key-value metrics (those broken down per CPU core, block device, network interface, or disk) are exposed as one sample per key, carrying the key as a label: ClickHouseAsyncMetrics_BlockReadBytes{device="sda"}. The asynchronous_metrics_key_values_mode server setting exposes them under their pre-26.8 mangled names instead (ClickHouseAsyncMetrics_BlockReadBytes_sda), or both ways at once.
errors - Expose the number of errors by error codes occurred since the last server restart. This information could be obtained from the system.errors as well.
labels – Constant labels added to every exposed metric. Each child element defines one label: the element name is the label name (must match [a-zA-Z_][a-zA-Z0-9_]*) and the element value is the label value. Label values support standard config substitutions such as the from_env attribute. A label name is rejected when it starts with __ (reserved by Prometheus), or when it would collide with a label this endpoint already writes for one of its enabled sections — otherwise a sample would carry the same label name twice. The reserved set therefore follows the endpoint’s active export surface: le when histograms is enabled; the ClickHouse_Info labels (name, version, version_describe, version_major, version_minor, version_patch) when info is enabled; the key labels of the key-value asynchronous metrics (channel, cpu, device, disk, interface, mc, sensor) when asynchronous_metrics is enabled and they are published in the key-value form, which the asynchronous_metrics_key_values_mode server setting decides; and any label used by an exposed histogram or dimensional metric family (for example group, direction, or operation_type) when histograms/dimensional_metrics is enabled. Because it depends on what the endpoint actually exposes, a name can be valid on one endpoint but rejected on another — for example a Keeper keeper_metrics_only endpoint exposes only the keeper_* families, so labels used only by server families are accepted there. The constant labels are validated against the same rule when a configuration is loaded, including on SYSTEM RELOAD CONFIG: a reload that would make a constant label collide - by adding such a label, or by changing asynchronous_metrics_key_values_mode so that the key labels start being written - is rejected as a whole before it takes effect, instead of exposing the same label twice. An accepted change of the mode re-creates the endpoints that expose the metrics, so that the new form and the labels of the same configuration are published together.

Example

<clickhouse>
    <listen_host>0.0.0.0</listen_host>
    <http_port>8123</http_port>
    <tcp_port>9000</tcp_port>
    <prometheus>
        <endpoint>/metrics</endpoint>
        <port>9363</port>
        <metrics>true</metrics>
        <events>true</events>
        <asynchronous_metrics>true</asynchronous_metrics>
        <errors>true</errors>
        <labels>
            <environment>production</environment>
            <shard from_env="SHARD_NAME"></shard>
        </labels>
    </prometheus>
</clickhouse>

Check (replace 127.0.0.1 with the IP addr or hostname of your ClickHouse server):

curl 127.0.0.1:9363/metrics

prometheus.keeper_metrics_only

Expose the keeper related metrics

proxy

Define proxy servers for HTTP and HTTPS requests, currently supported by S3 storage, S3 table functions, and URL functions. There are three ways to define proxy servers:

environment variables
proxy lists
remote proxy resolvers.

Bypassing proxy servers for specific hosts is also supported with the use of no_proxy. Environment variables The http_proxy and https_proxy environment variables allow you to specify a proxy server for a given protocol. If you have it set on your system, it should work seamlessly. This is the simplest approach if a given protocol has only one proxy server and that proxy server doesn’t change. Proxy lists This approach allows you to specify one or more proxy servers for a protocol. If more than one proxy server is defined, ClickHouse uses the different proxies on a round-robin basis, balancing the load across the servers. This is the simplest approach if there is more than one proxy server for a protocol and the list of proxy servers doesn’t change. Configuration template

<proxy>
    <http>
        <uri>http://proxy1</uri>
        <uri>http://proxy2:3128</uri>
    </http>
    <https>
        <uri>http://proxy1:3128</uri>
    </https>
</proxy>

Select a parent field in the tabs below to view their children:

<proxy>
<http> and <https>

Field	Description
`<http>`	A list of one or more HTTP proxies
`<https>`	A list of one or more HTTPS proxies

Field	Description
`<uri>`	The URI of the proxy

Remote proxy resolvers It’s possible that the proxy servers change dynamically. In that case, you can define the endpoint of a resolver. ClickHouse sends an empty GET request to that endpoint, the remote resolver should return the proxy host. ClickHouse will use it to form the proxy URI using the following template: \{proxy_scheme\}://\{proxy_host\}:{proxy_port} Configuration template

<proxy>
    <http>
        <resolver>
            <endpoint>http://resolver:8080/hostname</endpoint>
            <proxy_scheme>http</proxy_scheme>
            <proxy_port>80</proxy_port>
            <proxy_cache_time>10</proxy_cache_time>
        </resolver>
    </http>

    <https>
        <resolver>
            <endpoint>http://resolver:8080/hostname</endpoint>
            <proxy_scheme>http</proxy_scheme>
            <proxy_port>3128</proxy_port>
            <proxy_cache_time>10</proxy_cache_time>
        </resolver>
    </https>

</proxy>

Select a parent field in the tabs below to view their children:

<proxy>
<http> and <https>
<resolver>

Field	Description
`<http>`	A list of one or more resolvers*
`<https>`	A list of one or more resolvers*

Field	Description
`<resolver>`	The endpoint and other details for a resolver

You can have multiple <resolver> elements, but only the first <resolver> for a given protocol is used. Any other <resolver> elements for that protocol are ignored. That means load balancing (if needed) should be implemented by the remote resolver.

Field	Description
`<endpoint>`	The URI of the proxy resolver
`<proxy_scheme>`	The protocol of the final proxy URI. This can be either `http` or `https`.
`<proxy_port>`	The port number of the proxy resolver
`<proxy_cache_time>`	The time in seconds that values from the resolver should be cached by ClickHouse. Setting this value to `0` causes ClickHouse to contact the resolver for every HTTP or HTTPS request.

Precedence Proxy settings are determined in the following order:

Order	Setting
1.	Remote proxy resolvers
2.	Proxy lists
3.	Environment variables

ClickHouse will check the highest priority resolver type for the request protocol. If it is not defined, it will check the next highest priority resolver type, until it reaches the environment resolver. This also allows a mix of resolver types can be used.

remap_executable

Setting to reallocate memory for machine code (“text”) using huge pages.

This feature is highly experimental.

Example

<remap_executable>false</remap_executable>

replica_group_name

Replica group name for database Replicated. The cluster created by Replicated database will consist of replicas in the same group. DDL queries will only wait for the replicas in the same group.

Default: ""

Example

<replica_group_name>backups</replica_group_name>

replicated_merge_tree

Fine-tuning for tables in the ReplicatedMergeTree. This setting has a higher priority. For more information, see the MergeTreeSettings.h header file. Example

<replicated_merge_tree>
    <max_suspicious_broken_parts>5</max_suspicious_broken_parts>
</replicated_merge_tree>

restore_threads

The maximum number of threads to execute RESTORE requests.

send_crash_reports

Settings for sending of crash reports to the ClickHouse core developers team. Enabling it, especially in pre-production environments, is highly appreciated. Keys:

Key	Description
`enabled`	Boolean flag to enable the feature, `true` by default. Set to `false` to avoid sending crash reports.
`endpoint`	You can override the endpoint URL for sending crash reports.
`send_logical_errors`	`LOGICAL_ERROR` is like an `assert`, it is a bug in ClickHouse. This boolean flag enables sending this exceptions (Default: `true`).

Recommended usage

<send_crash_reports>
    <enabled>true</enabled>
</send_crash_reports>

series_keeper_path

Path in Keeper with auto-incremental numbers, generated by the generateSerialID function. Each series will be a node under this path.

ssh_server

The public part of the host key will be written to the known_hosts file on the SSH client side on the first connect. Host Key Configurations are inactive by default. Uncomment the host key configurations, and provide the path to the respective ssh key to active them: Example:

<ssh_server>
    <host_rsa_key>path_to_the_ssh_key</host_rsa_key>
    <host_ecdsa_key>path_to_the_ssh_key</host_ecdsa_key>
    <host_ed25519_key>path_to_the_ssh_key</host_ed25519_key>
</ssh_server>

table_engines_require_grant

If set to true, users require a grant to create a table with a specific engine e.g. GRANT TABLE ENGINE ON TinyLog to user.

Default: false

By default, for backward compatibility creating table with a specific table engine ignores grant, however you can change this behaviour by setting this to true.

tcp_ssh_port

Port for the SSH server which allows the user to connect and execute queries in an interactive fashion using the embedded client over the PTY. Example:

<tcp_ssh_port>9022</tcp_ssh_port>

text_log

Settings for the text_log system table for logging text messages. The following settings can be configured by sub-tags:

Setting	Description	Default	Note
`database`	Name of the database.
`table`	Name of the system table.
`engine`	MergeTree Engine Definition for a system table.		Cannot be used if `partition_by` or `order_by` defined. If not specified `MergeTree` is selected by default
`partition_by`	Custom partitioning key for a system table.		If `engine` is specified for system table, `partition_by` parameter should be specified directly inside ‘engine’
`ttl`	Specifies the table TTL.		If `engine` is specified for system table, `ttl` parameter should be specified directly inside ‘engine’
`order_by`	Custom sorting key for a system table. Can’t be used if `engine` defined.		If `engine` is specified for system table, `order_by` parameter should be specified directly inside ‘engine’
`storage_policy`	Name of the storage policy to use for the table (optional).		If `engine` is specified for system table, `storage_policy` parameter should be specified directly inside ‘engine’
`settings`	Additional parameters that control the behavior of the MergeTree (optional).		If `engine` is specified for system table, `settings` parameter should be specified directly inside ‘engine’
`flush_interval_milliseconds`	Interval for flushing data from the buffer in memory to the table.	`7500`
`max_size_rows`	Maximal size in lines for the logs. When the amount of non-flushed logs reaches the max_size, logs are dumped to the disk.	`1048576`
`reserved_size_rows`	Pre-allocated memory size in lines for the logs.	`8192`
`buffer_size_rows_flush_threshold`	Threshold for amount of lines. If the threshold is reached, flushing logs to the disk is launched in background.	`max_size_rows / 2`
`flush_on_crash`	Sets whether logs should be dumped to the disk in case of a crash.	`false`

Additionally, the following server-level setting controls the default flush policy for all system log tables:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

Setting	Description	Default
`skip_alias_columns`	When `true`, ALIAS columns are omitted from system log table schemas. Required for S3-backed system logs.	`false`

Additionally:

Setting	Description	Default Value
`level`	Maximum Message Level (by default `Trace`) which will be stored in a table.	`Trace`

Example

<clickhouse>
    <text_log>
        <level>notice</level>
        <database>system</database>
        <table>text_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
        <!-- <partition_by>event_date</partition_by> -->
        <engine>Engine = MergeTree PARTITION BY event_date ORDER BY event_time TTL event_date + INTERVAL 30 day</engine>
    </text_log>
</clickhouse>

thread_pool_queue_size

The maximum number of jobs that can be scheduled on the Global Thread pool. Increasing queue size leads to larger memory usage. It is recommended to keep this value equal to max_thread_pool_size.

A value of 0 means unlimited.

Example

<thread_pool_queue_size>12000</thread_pool_queue_size>

throw_on_unknown_workload

Defines behaviour on access to unknown WORKLOAD with query setting ‘workload’.

If true, RESOURCE_ACCESS_DENIED exception is thrown from a query that is trying to access unknown workload. Useful to enforce resource scheduling for all queries after WORKLOAD hierarchy is established and contains WORKLOAD default.
If false (default), unlimited access w/o resource scheduling is provided to a query with ‘workload’ setting pointing to unknown WORKLOAD. This is important during setting up hierarchy of WORKLOAD, before WORKLOAD default is added.

Example

<throw_on_unknown_workload>true</throw_on_unknown_workload>

See Also

Workload Scheduling

timezone

The server’s time zone. Specified as an IANA identifier for the UTC timezone or geographic location (for example, Africa/Abidjan). The time zone is necessary for conversions between String and DateTime formats when DateTime fields are output to text format (printed on the screen or in a file), and when getting DateTime from a string. Besides, the time zone is used in functions that work with the time and date if they didn’t receive the time zone in the input parameters. Example

<timezone>Asia/Istanbul</timezone>

See also

session_timezone

trace_log

Settings for the trace_log system table operation. The following settings can be configured by sub-tags:

Setting	Description	Default	Note
`database`	Name of the database.
`table`	Name of the system table.
`engine`	MergeTree Engine Definition for a system table.		Cannot be used if `partition_by` or `order_by` defined. If not specified `MergeTree` is selected by default
`partition_by`	Custom partitioning key for a system table.		If `engine` is specified for system table, `partition_by` parameter should be specified directly inside ‘engine’
`ttl`	Specifies the table TTL.		If `engine` is specified for system table, `ttl` parameter should be specified directly inside ‘engine’
`order_by`	Custom sorting key for a system table. Can’t be used if `engine` defined.		If `engine` is specified for system table, `order_by` parameter should be specified directly inside ‘engine’
`storage_policy`	Name of the storage policy to use for the table (optional).		If `engine` is specified for system table, `storage_policy` parameter should be specified directly inside ‘engine’
`settings`	Additional parameters that control the behavior of the MergeTree (optional).		If `engine` is specified for system table, `settings` parameter should be specified directly inside ‘engine’
`flush_interval_milliseconds`	Interval for flushing data from the buffer in memory to the table.	`7500`
`max_size_rows`	Maximal size in lines for the logs. When the amount of non-flushed logs reaches the max_size, logs are dumped to the disk.	`1048576`
`reserved_size_rows`	Pre-allocated memory size in lines for the logs.	`8192`
`buffer_size_rows_flush_threshold`	Threshold for amount of lines. If the threshold is reached, flushing logs to the disk is launched in background.	`max_size_rows / 2`
`flush_on_crash`	Sets whether logs should be dumped to the disk in case of a crash.	`false`

Additionally, the following server-level setting controls the default flush policy for all system log tables:

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>

Setting	Description	Default
`skip_alias_columns`	When `true`, ALIAS columns are omitted from system log table schemas. Required for S3-backed system logs.	`false`

The default server configuration file config.xml contains the following settings section:

<trace_log>
    <database>system</database>
    <table>trace_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
    <symbolize>true</symbolize>
</trace_log>

url_scheme_mappers

Configuration for translating shortened or symbolic URL prefixes into full URLs. Example:

<url_scheme_mappers>
    <s3>
        <to>https://{bucket}.s3.amazonaws.com</to>
    </s3>
    <gs>
        <to>https://storage.googleapis.com/{bucket}</to>
    </gs>
    <oss>
        <to>https://{bucket}.oss.aliyuncs.com</to>
    </oss>
</url_scheme_mappers>

validate_tcp_client_information

Determines whether validation of client information is enabled when a query packet is received. By default, it is false:

<validate_tcp_client_information>false</validate_tcp_client_information>

wait_dictionaries_load_at_startup

This setting allows to specify behavior if dictionaries_lazy_load is false. (If dictionaries_lazy_load is true this setting doesn’t affect anything.) If wait_dictionaries_load_at_startup is false, then the server will start loading all the dictionaries at startup and it will receive connections in parallel with that loading. When a dictionary is used in a query for the first time then the query will wait until the dictionary is loaded if it’s not loaded yet. Setting wait_dictionaries_load_at_startup to false can make ClickHouse start faster, however some queries can be executed slower (because they will have to wait for some dictionaries to be loaded). If wait_dictionaries_load_at_startup is true, then the server will wait at startup until all the dictionaries finish their loading (successfully or not) before receiving any connections. Example

<wait_dictionaries_load_at_startup>true</wait_dictionaries_load_at_startup>

webassembly_udf_engine

The engine used to execute WebAssembly UDFs. The only supported value is ‘wasmtime’.

webterminal_allowed_origins

Comma-separated list of full origins (scheme + host + optional port) allowed to open /webterminal WebSocket sessions. When empty, the same-origin policy is enforced strictly (Origin must match the request scheme, host, and port). Set this for deployments behind a TLS-terminating reverse proxy where request.isSecure() is false even though the browser uses https. Example: https://example.com,https://app.example.com:8443.

Last modified on September 3, 2026

​abort_on_logical_error

​allowed_disks_for_table_engines

​auth_use_forwarded_address

​bcrypt_workfactor

​blob_storage_log

​builtin_dictionaries_reload_interval

​cache_size_to_ram_max_ratio

​cannot_allocate_thread_fault_injection_probability

​cgroups_memory_usage_observer_wait_time

​compression

​config-file

​config_reload_interval_ms

​core_dump

​crash_log

​create_union_system_log_tables

​database_atomic_delay_before_drop_table_sec

​dead_letter_queue

​dictionary_background_reconnect_interval

​disk_transaction_wait_for_blob_removal

​display_secrets_in_show_and_select

​dns_max_consecutive_failures

​dynamic_user_defined_executable_functions_path

​encryption

​enforce_keeper_component_tracking

​error_log

​filesystem_caches_path

​google_protos_path

​handshake_timeout_milliseconds

​hdfs.libhdfs3_conf

​hsts_max_age

​iceberg_background_schedule_pool_size

​ignore_empty_sql_security_in_create_view_query

​include_from

​insert_deduplication_version

​io_thread_pool_queue_size

​keep_alive_timeout

​ldap_servers

​logger

​logger.count

​logger.errorlog

​logger.formatting.type

​logger.level

​logger.log

​logger.rotation

​logger.shutdown_level

​logger.size

​logger.startup_level

​logger.stream_compress

​logger.syslog_level

​logger.use_syslog

​macros

​message_queue_disable_insertion

​metric_log

​mmap_cache_size

​mutation_workload

​named_collections_storage.type

​oom_score

​openSSL

​openSSL.client.caConfig

​openSSL.client.cacheSessions

​openSSL.client.certificateFile

​openSSL.client.cipherList

​openSSL.client.disableProtocols

​openSSL.client.extendedVerification

​openSSL.client.fips

​openSSL.client.invalidCertificateHandler.name

​openSSL.client.loadDefaultCAFile

​openSSL.client.preferServerCiphers

​openSSL.client.privateKeyFile

​openSSL.client.privateKeyPassphraseHandler.name

​openSSL.client.verificationDepth

​openSSL.client.verificationMode

​openSSL.server.caConfig

​openSSL.server.cacheSessions

​openSSL.server.certificateFile

​openSSL.server.cipherList

​openSSL.server.disableProtocols

​openSSL.server.extendedVerification

​openSSL.server.fips

​openSSL.server.invalidCertificateHandler.name

abort_on_logical_error

allowed_disks_for_table_engines

auth_use_forwarded_address

bcrypt_workfactor

blob_storage_log

builtin_dictionaries_reload_interval

cache_size_to_ram_max_ratio

cannot_allocate_thread_fault_injection_probability

cgroups_memory_usage_observer_wait_time

compression

config-file

config_reload_interval_ms

core_dump

crash_log

create_union_system_log_tables

database_atomic_delay_before_drop_table_sec

dead_letter_queue

dictionary_background_reconnect_interval

disk_transaction_wait_for_blob_removal

display_secrets_in_show_and_select

dns_max_consecutive_failures

dynamic_user_defined_executable_functions_path

encryption

enforce_keeper_component_tracking

error_log

filesystem_caches_path

google_protos_path

handshake_timeout_milliseconds

hdfs.libhdfs3_conf

hsts_max_age

iceberg_background_schedule_pool_size

ignore_empty_sql_security_in_create_view_query

include_from

insert_deduplication_version

io_thread_pool_queue_size

keep_alive_timeout

ldap_servers

logger

logger.count

logger.errorlog

logger.formatting.type

logger.level

logger.log

logger.rotation

logger.shutdown_level

logger.size

logger.startup_level

logger.stream_compress

logger.syslog_level

logger.use_syslog

macros

message_queue_disable_insertion

metric_log

mmap_cache_size

mutation_workload

named_collections_storage.type

oom_score

openSSL

openSSL.client.caConfig

openSSL.client.cacheSessions

openSSL.client.certificateFile

openSSL.client.cipherList

openSSL.client.disableProtocols

openSSL.client.extendedVerification

openSSL.client.fips

openSSL.client.invalidCertificateHandler.name

openSSL.client.loadDefaultCAFile

openSSL.client.preferServerCiphers

openSSL.client.privateKeyFile

openSSL.client.privateKeyPassphraseHandler.name

openSSL.client.verificationDepth

openSSL.client.verificationMode

openSSL.server.caConfig

openSSL.server.cacheSessions

openSSL.server.certificateFile

openSSL.server.cipherList

openSSL.server.disableProtocols

openSSL.server.extendedVerification

openSSL.server.fips

openSSL.server.invalidCertificateHandler.name