Session settings

This page describes the RawTree engine binary used to generate this reference. It does not define Query API support. Descriptions retain upstream ClickHouse terminology. See SQL interface scope.

adaptive_aggregator_freeze_threshold

Type: UInt64
Default: 16384
Tier: Production
The number of keys at which the adaptive aggregator freezes a thread's local hash table (see enable_adaptive_aggregator). Smaller values keep the frozen tables cache-resident, larger values let them absorb more of the frequent keys. 0 freezes the tables at the first opportunity, which makes the algorithm behave similarly to the sharded aggregator (enable_sharding_aggregator): every key is routed by its hash and aggregated by a single owner, just deferred to the merge phase instead of exchanged between threads during the scan.

adaptive_aggregator_freeze_threshold_bytes

Type: UInt64
Default: 4194304
Tier: Production
The memory size at which the adaptive aggregator freezes a thread's local hash table (see enable_adaptive_aggregator). A table freezes at whichever of this and adaptive_aggregator_freeze_threshold is reached first. The size is the local table's own allocated bytes (its hash-table buffer plus its arenas), checked between blocks. The byte bound matters when the keys or the aggregation states are wide: the key-count threshold alone would let such tables outgrow the CPU caches. At the default, tables of ordinary key and state widths keep freezing by the key count. 0 disables the byte bound, so the key-count threshold alone decides.

add_http_cors_header

Type: Bool
Default: 0
Tier: Production
Write add http CORS header.

additional_result_filter

Type: String
Default: ``
Tier: Production
An additional filter expression to apply to the result of SELECT query. This setting is not applied to any subquery. Example sql INSERT INTO table_1 VALUES (1, 'a'), (2, 'bb'), (3, 'ccc'), (4, 'dddd'); SElECT * FROM table_1; response ┌─x─┬─y────┐ │ 1 │ a │ │ 2 │ bb │ │ 3 │ ccc │ │ 4 │ dddd │ └───┴──────┘ sql SELECT * FROM table_1 SETTINGS additional_result_filter = 'x != 2' response ┌─x─┬─y────┐ │ 1 │ a │ │ 3 │ ccc │ │ 4 │ dddd │ └───┴──────┘

additional_table_filters

Type: Map
Default: {}
Tier: Production
An additional filter expression that is applied after reading from the specified table. Example sql INSERT INTO table_1 VALUES (1, 'a'), (2, 'bb'), (3, 'ccc'), (4, 'dddd'); SELECT * FROM table_1; response ┌─x─┬─y────┐ │ 1 │ a │ │ 2 │ bb │ │ 3 │ ccc │ │ 4 │ dddd │ └───┴──────┘ sql SELECT * FROM table_1 SETTINGS additional_table_filters = {'table_1': 'x != 2'} response ┌─x─┬─y────┐ │ 1 │ a │ │ 3 │ ccc │ │ 4 │ dddd │ └───┴──────┘ Filters keyed on a table read through a view with SQL SECURITY DEFINER or NONE are not applied inside the view.

aggregate_function_input_format

Type: AggregateFunctionInputFormat
Default: state
Tier: Production
Format for AggregateFunction input during INSERT operations. Possible values: - state — Binary string with the serialized state (the default). This is the default behavior where AggregateFunction values are expected as binary data. - value — The format expects a single value of the argument of the aggregate function, or in the case of multiple arguments, a tuple of them. They will be deserialized using the corresponding IDataType or DataTypeTuple and then aggregated to form the state. - array — The format expects an Array of values, as described in the value option above. All elements of the array will be aggregated to form the state. Examples For a table with structure: sql CREATE TABLE example ( user_id UInt64, avg_session_length AggregateFunction(avg, UInt32) ); With aggregate_function_input_format = 'value': sql INSERT INTO example FORMAT CSV 123,456 With aggregate_function_input_format = 'array': sql INSERT INTO example FORMAT CSV 123,"[456,789,101]" Note: The value and array formats are slower than the default state format as they require creating and aggregating values during insertion.

aggregate_functions_null_for_empty

Type: Bool
Default: 0
Tier: Production
Enables or disables rewriting all aggregate functions in a query, adding -OrNull suffix to them. Enable it for SQL standard compatibility. It is implemented via query rewrite (similar to count_distinct_implementation setting) to get consistent results for distributed queries. Possible values: - 0 — Disabled. - 1 — Enabled. Example Consider the following query with aggregate functions: sql SELECT SUM(-1), MAX(0) FROM system.one WHERE 0; With aggregate_functions_null_for_empty = 0 it would produce: text ┌─SUM(-1)─┬─MAX(0)─┐ │ 0 │ 0 │ └─────────┴────────┘ With aggregate_functions_null_for_empty = 1 the result would be: text ┌─SUMOrNull(-1)─┬─MAXOrNull(0)─┐ │ NULL │ NULL │ └───────────────┴──────────────┘

aggregation_in_order_max_block_bytes

Type: UInt64
Default: 50000000
Tier: Production
Maximal size of block in bytes accumulated during aggregation in order of primary key. Lower block size allows to parallelize more final merge stage of aggregation.

aggregation_memory_efficient_merge_threads

Type: UInt64
Default: 0
Tier: Production
Number of threads to use for merge intermediate aggregation results in memory efficient mode. When bigger, then more memory is consumed. 0 means - same as 'max_threads'.

ai_function_allow_insecure_endpoint

Type: Bool
Default: 0
Tier: Beta
If false (default), AI functions refuse to use a named-collection endpoint that would send prompts and API keys over an unencrypted connection to a remote host: any non-HTTPS endpoint whose host is not loopback is rejected with an exception. Loopback endpoints (e.g. a local http://localhost model server) are always allowed. Set to true to permit plaintext http:// endpoints on remote hosts.

ai_function_embedding_default_credentials

Type: String
Default: ``
Tier: Beta
Name of the named collection used by the embedding functions (aiEmbed, aiSimilarity) when the call does not pass credentials in its parameter map. Empty means no default: such calls must pass credentials explicitly. These functions take model as a required positional argument, not from the named collection. Kept separate from ai_function_text_default_credentials because an embeddings endpoint differs from a chat one.

ai_function_embedding_max_batch_size

Type: NonZeroUInt64
Default: 100
Tier: Beta
Maximum number of texts to include in a single HTTP request made by the embedding functions (aiEmbed, aiSimilarity). Texts are grouped into batches of this size to reduce API call overhead. For example, 500 unique texts with a batch size of 100 result in 5 HTTP requests.

ai_function_max_api_calls_per_query

Type: UInt64
Default: 0
Tier: Beta
Maximum number of HTTP requests that AI functions may dispatch per query. 0 (default) disables the limit. Enforced independently by each server and query fragment: within one execution context it is an exact cap shared by every AI function, block, and thread there, but a distributed query (across shards or parallel-replica fragments) may dispatch up to this many requests per shard/fragment. It must be set in the top-level query - a sub-query SETTINGS override is ignored.

ai_function_max_input_tokens_per_query

Type: UInt64
Default: 0
Tier: Beta
Maximum total input (prompt) tokens across all AI function API calls in a single query. 0 (default) disables the limit. Tracked cumulatively from provider responses. Note that this limit may be exceeded by up to one call's worth of input tokens per in-flight request, since a call's input tokens are not known until its response arrives. Like the other AI quotas, it is enforced per server / query fragment, not summed across a distributed query, and must be set in the top-level query - a sub-query SETTINGS override is ignored. This limit is only enforced for providers that report a usage object in their response (OpenAI, Anthropic, vLLM). Providers that omit token usage (notably HuggingFace TEI) cause the counter to stay at 0 — use ai_function_max_api_calls_per_query instead to bound such calls.

ai_function_max_output_tokens_per_query

Type: UInt64
Default: 0
Tier: Beta
Maximum total output (completion) tokens across all AI function API calls in a single query. 0 (default) disables the limit. Tracked cumulatively from provider responses. Note that this limit may be exceeded by up to one call's worth of output tokens per in-flight request, since a call's output tokens are not known until its response arrives. Like the other AI quotas, it is enforced per server / query fragment, not summed across a distributed query, and must be set in the top-level query - a sub-query SETTINGS override is ignored. This limit is only enforced for providers that report a usage object in their response (OpenAI, Anthropic, vLLM). It does not apply to the embedding functions (aiEmbed, aiSimilarity), which never produce output tokens.

ai_function_max_retries

Type: UInt64
Default: 1
Tier: Beta
Maximum number of retry attempts for transient errors per individual API request. Each retry uses exponential backoff starting from ai_function_retry_initial_delay_ms.

ai_function_request_timeout_sec

Type: UInt64
Default: 60
Tier: Beta
Timeout in seconds for individual HTTP requests made by AI functions (AI chat completions and embedding API calls). If a request does not complete within this time, it is considered failed and may be retried according to ai_function_max_retries.

ai_function_retry_initial_delay_ms

Type: UInt64
Default: 1000
Tier: Beta
Initial delay in milliseconds before the first retry of a failed AI function API request. The delay doubles on each subsequent attempt (exponential backoff). For example, with default settings: 1000ms, 2000ms, 4000ms.

ai_function_text_default_credentials

Type: String
Default: ``
Tier: Beta
Name of the named collection used by the text AI functions (aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact) when the call does not pass credentials in its parameter map. Empty means no default: such calls must pass credentials explicitly. A chat-completions endpoint differs from an embeddings one, so this is separate from ai_function_embedding_default_credentials.

ai_function_throw_on_error

Type: Bool
Default: 1
Tier: Beta
If true (default), an AI function call that fails permanently after exhausting all retries aborts the query with an exception. If false, the failed row receives the default value for the column type (empty string for String) and processing continues.

ai_function_throw_on_quota_exceeded

Type: Bool
Default: 1
Tier: Beta
If true (default), exceeding an AI function quota limit (ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query, or ai_function_max_api_calls_per_query) aborts the query with an exception. All three limits are disabled by default, so this has no effect until one of them is set. If false, remaining rows receive the default value for the column type (empty string for String). Like the quota limits, this must be set in the top-level query - a sub-query SETTINGS override is ignored.

allow_aggregate_partitions_independently

Type: Bool
Default: 1
Tier: Production
Enable independent aggregation of partitions on separate threads when partition key suits group by key. Beneficial when number of partitions close to number of cores and partitions have roughly the same size. Heuristics in ReadFromMergeTree automatically disable the optimization for unfavorable layouts (too few partitions, too many partitions, or significantly skewed partition sizes); see force_aggregate_partitions_independently to bypass those checks.

allow_archive_path_syntax

Type: Bool
Default: 1
Tier: Production
File/S3 engines/table function will parse paths with '::' as <archive> :: <file> if the archive has correct extension.

allow_asynchronous_read_from_io_pool_for_merge_tree

Type: Bool
Default: 0
Tier: Production
Use background I/O pool to read from MergeTree tables. This setting may increase performance for I/O bound queries

allow_calculating_subcolumns_sizes_for_merge_tree_reading

Type: Bool
Default: 1
Tier: Production
When enabled, ClickHouse will calculate the size of files required for each subcolumn reading for better task and block sizes calculation.

allow_changing_replica_until_first_data_packet

Type: Bool
Default: 0
Tier: Production
If it's enabled, in hedged requests we can start new connection until receiving first data packet even if we have already made some progress (but progress haven't updated for receive_data_timeout timeout), otherwise we disable changing replica after the first time we made progress.

allow_create_index_without_type

Type: Bool
Default: 0
Tier: Production
Allow CREATE INDEX query without TYPE. Query will be ignored. Made for SQL compatibility tests.

allow_creating_set_partitions_independently

Type: Bool
Default: 1
Tier: Production
Enable parallel per-partition pre-deduplication of the subquery result when building the set for IN (subquery), when the partition expression of the subquery's MergeTree table is a deterministic function of the subquery output columns. Each partition is read through a separate stream and deduplicated independently, so the single set-filling transform only hashes unique rows. Not applied with FINAL, parallel replicas, or GLOBAL IN. The optimization requests the per-partition read itself only when the data has more than one partition and the largest partition holds at most twice the rows of the average partition (see force_creating_set_partitions_independently to bypass the skew check); when the streams are already partition-disjoint because another per-partition feature split them (for example per-partition LIMIT BY), the pre-deduplication is applied regardless, since the read layout is already fixed. While the set is being built, the per-stream deduplication tables together hold roughly one extra copy of the unique keys.

allow_custom_error_code_in_throwif

Type: Bool
Default: 0
Tier: Production
Enable custom error code in function throwIf(). If true, thrown exceptions may have unexpected error codes.

allow_database_glue_catalog

Type: Bool
Default: 0
Tier: Beta
Allow experimental database engine DataLakeCatalog with catalog_type = 'glue' Cloud default value: 1.

allow_database_iceberg

Type: Bool
Default: 0
Tier: Beta
Allow experimental database engine DataLakeCatalog with catalog_type = 'iceberg' Cloud default value: 1.

allow_database_unity_catalog

Type: Bool
Default: 0
Tier: Beta
Allow experimental database engine DataLakeCatalog with catalog_type = 'unity' Cloud default value: 1.

allow_ddl

Type: Bool
Default: 1
Tier: Production
If it is set to true, then a user is allowed to executed DDL queries.

allow_delta_kernel_rs

Type: Bool
Default: 1
Tier: Beta
Allow the delta-kernel-rs implementation for reading Delta Lake tables.

allow_delta_lake_writes

Type: Bool
Default: 0
Tier: Beta
Enables delta-kernel writes feature.

allow_deprecated_database_ordinary

Type: Bool
Default: 0
Tier: Production
Allow to create databases with deprecated Ordinary engine

allow_deprecated_error_prone_window_functions

Type: Bool
Default: 0
Tier: Production
Allow usage of deprecated error prone window functions (neighbor, runningAccumulate, runningDifferenceStartingWithFirstValue, runningDifference)

allow_deprecated_syntax_for_merge_tree

Type: Bool
Default: 0
Tier: Production
Allow to create *MergeTree tables with deprecated engine definition syntax

allow_distinct_partitions_independently

Type: Bool
Default: 1
Tier: Production
Enable independent DISTINCT evaluation per partition on separate threads when the partition expression is a deterministic function of the DISTINCT columns, skipping the cross-stream merge. Beneficial when the number of partitions is close to the number of cores and partitions have roughly the same size; otherwise a cost heuristic skips it, see max_number_of_partitions_for_independent_distinct and force_distinct_partitions_independently. Not applied with FINAL or parallel replicas. Not applied when max_rows_in_distinct or max_bytes_in_distinct is set: those limits are enforced by the single DISTINCT transform that sees the whole merged result, so the cross-stream merge is kept to preserve their global meaning.

allow_distributed_ddl

Type: Bool
Default: 1
Tier: Production
If it is set to true, then a user is allowed to executed distributed DDL queries.

allow_drop_detached

Type: Bool
Default: 0
Tier: Production
Allow ALTER TABLE ... DROP DETACHED PART[ITION] ... queries

allow_dynamic_type_in_join_keys

Type: Bool
Default: 0
Tier: Production
Allows using Dynamic type in JOIN keys. Added for compatibility. It's not recommended to use Dynamic type in JOIN keys because comparison with other types may lead to unexpected results.

allow_executable_tables

Type: Bool
Default: 1
Tier: Production
Allow reading through the executable table function and from Executable and ExecutablePool tables. Disabling this refuses reads only: creating, attaching, dropping and describing such tables still works. ExecutablePool processes that have already started are left running rather than terminated, but each read is still refused until the setting is enabled again.

allow_execute_multiif_columnar

Type: Bool
Default: 1
Tier: Production
Allow execute multiIf function columnar

allow_experimental_analyzer

Type: Bool
Default: 1
Tier: Production
Allow the analyzer.

allow_experimental_cleanup_old_data_files_compaction

Type: Bool
Default: 0
Tier: Experimental
Allow to clean up old data files during Iceberg compaction.

allow_experimental_codecs

Type: Bool
Default: 0
Tier: Experimental
If it is set to true, allow to specify any experimental compression codec.

allow_experimental_correlated_subqueries

Type: Bool
Default: 1
Tier: Beta
Allow to execute correlated subqueries.

allow_experimental_database_glue_catalog

Type: Bool
Default: 0
Tier: Beta
Allow experimental database engine DataLakeCatalog with catalog_type = 'glue' Cloud default value: 1.

allow_experimental_database_hms_catalog

Type: Bool
Default: 0
Tier: Experimental
Allow experimental database engine DataLakeCatalog with catalog_type = 'hms'

allow_experimental_database_iceberg

Type: Bool
Default: 0
Tier: Beta
Allow experimental database engine DataLakeCatalog with catalog_type = 'iceberg' Cloud default value: 1.

allow_experimental_database_materialized_postgresql

Type: Bool
Default: 0
Tier: Experimental
Allow to create database with Engine=MaterializedPostgreSQL(...).

allow_experimental_database_paimon_rest_catalog

Type: Bool
Default: 0
Tier: Experimental
Allow experimental database engine DataLakeCatalog with catalog_type = 'paimon_rest'

allow_experimental_database_unity_catalog

Type: Bool
Default: 0
Tier: Beta
Allow experimental database engine DataLakeCatalog with catalog_type = 'unity' Cloud default value: 1.

allow_experimental_delta_kernel_rs

Type: Bool
Default: 1
Tier: Beta
Allow the delta-kernel-rs implementation for reading Delta Lake tables.

allow_experimental_delta_lake_writes

Type: Bool
Default: 0
Tier: Beta
Enables delta-kernel writes feature.

allow_experimental_eval_table_function

Type: Bool
Default: 0
Tier: Experimental
Enable experimental table function eval.

allow_experimental_expire_snapshots

Type: Bool
Default: 0
Tier: Experimental
Allow to execute experimental Iceberg command ALTER TABLE ... EXECUTE expire_snapshots.

allow_experimental_full_text_index

Type: Bool
Default: 1
Tier: Production
If set to true, allow using the text index.

allow_experimental_funnel_functions

Type: Bool
Default: 0
Tier: Experimental
Enable experimental functions for funnel analysis.

allow_experimental_geo_types_in_iceberg

Type: Bool
Default: 0
Tier: Production
Allow parsing Iceberg geometry and geography field types as ClickHouse Geometry (Variant) type.

allow_experimental_hash_functions

Type: Bool
Default: 0
Tier: Experimental
Enable experimental hash functions

allow_experimental_iceberg_compaction

Type: Bool
Default: 0
Tier: Experimental
Allow to explicitly use 'OPTIMIZE' for iceberg tables.

allow_experimental_insert_into_iceberg

Type: Bool
Default: 0
Tier: Beta
Allow to execute insert queries into iceberg.

allow_experimental_join_right_table_sorting

Type: Bool
Default: 0
Tier: Experimental
If it is set to true, and the conditions of join_to_sort_minimum_perkey_rows and join_to_sort_maximum_table_rows are met, rerange the right table by key to improve the performance in left or inner hash join.

allow_experimental_json_lazy_type_hints

Type: Bool
Default: 0
Tier: Experimental
Enable experimental lazy type hints for JSON type. This feature allows optimizing JSON type conversions by deferring type hint evaluation.

allow_experimental_kafka_offsets_storage_in_keeper

Type: Bool
Default: 0
Tier: Experimental
Allow experimental feature to store Kafka related offsets in RawTree Keeper. When enabled a RawTree Keeper path and replica name can be specified to the Kafka table engine. As a result instead of the regular Kafka engine, a new type of storage engine will be used that stores the committed offsets primarily in RawTree Keeper

allow_experimental_kusto_dialect

Type: Bool
Default: 0
Tier: Experimental
Enable Kusto Query Language (KQL) - an alternative to SQL.

allow_experimental_lightweight_delete

Type: Bool
Default: 1
Tier: Production
Enable lightweight DELETE mutations for mergetree tables.

allow_experimental_lightweight_update

Type: Bool
Default: 1
Tier: Beta
Allow to use lightweight updates.

allow_experimental_materialized_postgresql_table

Type: Bool
Default: 0
Tier: Experimental
Allows to use the MaterializedPostgreSQL table engine. Disabled by default, because this feature is experimental

allow_experimental_nlp_functions

Type: Bool
Default: 0
Tier: Experimental
Enable experimental functions for natural language processing.

allow_experimental_nullable_tuple_type

Type: Bool
Default: 0
Tier: Beta
Allows creation of Nullable Tuple columns in tables. This setting does not control whether extracted tuple subcolumns can be Nullable (for example, from Dynamic, Variant, JSON, or Tuple columns). Use allow_nullable_tuple_in_extracted_subcolumns to control whether extracted tuple subcolumns can be Nullable.

allow_experimental_object_storage_queue_hive_partitioning

Type: Bool
Default: 0
Tier: Experimental
Allow to use hive partitioning with S3Queue/AzureQueue engines

allow_experimental_paimon_storage_engine

Type: Bool
Default: 0
Tier: Experimental
Allow to create tables with Paimon* table engines.

allow_experimental_parallel_reading_from_replicas

Type: UInt64
Default: 0
Tier: Production
Use up to max_parallel_replicas the number of replicas from each shard for SELECT query execution. Reading is parallelized and coordinated dynamically. 0 - disabled, 1 - enabled, silently disable them in case of failure, 2 - enabled, throw an exception in case of failure

allow_experimental_polyglot_dialect

Type: Bool
Default: 0
Tier: Experimental
Enable polyglot SQL transpiler - transpiles SQL from 30+ dialects (MySQL, PostgreSQL, SQLite, Snowflake, DuckDB, etc.) into ClickHouse SQL.

allow_experimental_projection_optimization

Type: Bool
Default: 1
Tier: Production
Enables or disables projection optimization when processing SELECT queries. Possible values: - 0 — Projection optimization disabled. - 1 — Projection optimization enabled.

allow_experimental_prql_dialect

Type: Bool
Default: 0
Tier: Experimental
Enable PRQL - an alternative to SQL.

allow_experimental_statistics

Type: Bool
Default: 1
Tier: Production
Allows defining columns with statistics and manipulate statistics.

allow_experimental_time_series_aggregate_functions

Type: Bool
Default: 0
Tier: Experimental
Experimental timeSeries* aggregate functions for Prometheus-like timeseries resampling, rate, delta calculation.

allow_experimental_time_series_table

Type: Bool
Default: 0
Tier: Experimental
Allows creation of tables with the TimeSeries table engine. Possible values: - 0 — the TimeSeries table engine is disabled. - 1 — the TimeSeries table engine is enabled.

allow_experimental_time_time64_type

Type: Bool
Default: 1
Tier: Production
Allows creation of Time and Time64 data types.

allow_experimental_ts_to_grid_aggregate_function

Type: Bool
Default: 0
Tier: Experimental
Experimental timeSeries* aggregate functions for Prometheus-like timeseries resampling, rate, delta calculation.

allow_experimental_unique_key

Type: Bool
Default: 0
Tier: Experimental
Allows creation of tables with the UNIQUE KEY clause on MergeTree-family engines.

allow_experimental_url_wildcard_from_index_pages

Type: Bool
Default: 0
Tier: Experimental
Allow experimental wildcard expansion for url() and ENGINE = URL from HTTP index pages.

allow_experimental_window_view

Type: Bool
Default: 0
Tier: Experimental
Enable WINDOW VIEW. Not mature enough.

allow_experimental_ytsaurus_dictionary_source

Type: Bool
Default: 0
Tier: Experimental
Experimental dictionary source for integration with YTsaurus.

allow_experimental_ytsaurus_table_engine

Type: Bool
Default: 0
Tier: Experimental
Experimental table engine for integration with YTsaurus.

allow_experimental_ytsaurus_table_function

Type: Bool
Default: 0
Tier: Experimental
Experimental table engine for integration with YTsaurus.

allow_fuzz_query_functions

Type: Bool
Default: 0
Tier: Experimental
Enables the fuzzQuery function that applies random AST mutations to a query string.

allow_general_join_planning

Type: Bool
Default: 1
Tier: Production
Allows a more general join planning algorithm that can handle more complex conditions, but only works with hash join. If hash join is not enabled, then the usual join planning algorithm is used regardless of the value of this setting.

allow_get_client_http_header

Type: Bool
Default: 0
Tier: Production
Allow to use the function getClientHTTPHeader which lets to obtain a value of the current HTTP request's header. It is not enabled by default for security reasons, because some headers, such as Cookie, could contain sensitive info. Note that the X-RawTree-*, X-ClickHouse-*, Authentication and Authorization headers are always restricted and cannot be obtained with this function.

allow_hyperscan

Type: Bool
Default: 1
Tier: Production
Allow functions that use Hyperscan library. Disable to avoid potentially long compilation times and excessive resource usage.

allow_iceberg_remove_orphan_files

Type: Bool
Default: 0
Tier: Experimental
Allow to use 'ALTER TABLE ... EXECUTE remove_orphan_files()' for iceberg tables.

allow_insert_into_iceberg

Type: Bool
Default: 0
Tier: Beta
Allow to execute insert queries into iceberg.

allow_introspection_functions

Type: Bool
Default: 0
Tier: Production
Enables or disables introspection functions for query profiling. Possible values: - 1 — Introspection functions enabled. - 0 — Introspection functions disabled. See Also - Sampling Query Profiler - System table trace_log

allow_key_condition_coalesce_rewrite

Type: Bool
Default: 1
Tier: Production
Rewrite predicates of the form coalesce(a_1, ..., a_N) <op> const (and equivalently ifNull, or with the constant on the left) into the disjunction (a_1 <op> const) OR (a_1 IS NULL AND a_2 <op> const) OR ... OR (a_1 IS NULL AND ... AND a_{N-1} IS NULL AND a_N <op> const) before index analysis, so per-column primary key and skip indexes on each a_i can be used. Partial-constant forms such as coalesce(a, 42, b) and coalesce(a, b, 42) are handled: the argument list is normalized like coalesce itself (NULL literals dropped, arguments after the first non-Nullable one dropped), and a trailing non-NULL constant, if any, is emitted as the final branch. The rewrite is strictly additive for index pruning; runtime filtering still uses the original predicate. Additionally, exact equality predicates of the form nullIf(key, sentinel) = const (where sentinel != const and types match exactly) are rewritten to key = const so primary key, partition, and skip indexes on key can prune granules directly. Range and disjunctive nullIf pruning is not supported.

allow_limit_by_partitions_independently

Type: Bool
Default: 1
Tier: Production
Enable independent LIMIT BY evaluation per partition on separate threads when the partition expression is a deterministic function of the LIMIT BY columns.

allow_lossy_numeric_supertype

Type: Bool
Default: 0
Tier: Production
When enabled, if/multiIf/coalesce/ifNull/array/map over a set of numeric arguments that has no lossless common type (for example a Decimal and a Float64, or an Int64 and a Float64) resolve to a numeric supertype (Float64) instead of failing, with possible precision loss. This allows the result to be used directly with value-combining aggregate functions like sum, avg, min and max. This is independent of use_variant_as_common_type: the numeric supertype is produced whether or not use_variant_as_common_type is enabled. When disabled (the default), such argument sets have no common type, so they either become a Variant (if use_variant_as_common_type is enabled) or raise NO_COMMON_TYPE.

allow_materialized_view_with_bad_select

Type: Bool
Default: 0
Tier: Production
Allow CREATE MATERIALIZED VIEW with SELECT query that references nonexistent tables or columns. It must still be syntactically valid. Doesn't apply to refreshable MVs. Doesn't apply if the MV schema needs to be inferred from the SELECT query (i.e. if the CREATE has no column list and no TO table). Can be used for creating MV before its source table.

allow_metadata_only_named_tuple_alter

Type: Bool
Default: 0
Tier: Production
If true, ALTER MODIFY COLUMN on a named Tuple that only adds new subfields is metadata-only (no data mutation). Set to false to force the old full-mutation behavior.

allow_minmax_index_for_json

Type: Bool
Default: 0
Tier: Production
Allow creating minmax skip indexes on JSON (Object) columns. Disabled by default because the minmax index serialization path cannot handle heterogeneous Field values that JSON columns may contain.

allow_non_metadata_alters

Type: Bool
Default: 1
Tier: Production
Allow to execute alters which affects not only tables metadata, but also data on disk

allow_nonconst_timezone_arguments

Type: Bool
Default: 0
Tier: Production
Allow non-const timezone arguments in certain time-related functions like toTimeZone(), fromUnixTimestamp*(), snowflakeIDToDateTime*(). This setting exists only for compatibility reasons. In RawTree, the time zone is a property of the data type, respectively of the column. Enabling this setting gives the wrong impression that different values within a column can have different timezones. Therefore, please do not enable this setting.

allow_nondeterministic_mutations

Type: Bool
Default: 0
Tier: Production
User-level setting that allows mutations on replicated tables to make use of non-deterministic functions such as dictGet. Given that, for example, dictionaries, can be out of sync across nodes, mutations that pull values from them are disallowed on replicated tables by default. Enabling this setting allows this behavior, making it the user's responsibility to ensure that the data used is in sync across all nodes. Example xml <profiles> <default> <allow_nondeterministic_mutations>1</allow_nondeterministic_mutations> </default> </profiles>

allow_nondeterministic_optimize_skip_unused_shards

Type: Bool
Default: 0
Tier: Production
Allow nondeterministic (like rand or dictGet, since later has some caveats with updates) functions in sharding key. Possible values: - 0 — Disallowed. - 1 — Allowed.

allow_nullable_tuple_in_extracted_subcolumns

Type: Bool
Default: 0
Tier: Production
Controls whether extracted subcolumns of type Tuple(...) can be typed as Nullable(Tuple(...)). - false: Return Tuple(...) and use default tuple values for rows where the subcolumn is missing. - true: Return Nullable(Tuple(...)) and use NULL for rows where the subcolumn is missing. This setting controls extracted subcolumn behavior only. It does not control whether Nullable(Tuple(...)) columns can be created in tables; that is controlled by enable_nullable_tuple_type. ClickHouse uses the value for this setting loaded at server startup. Changes made with SET or query-level SETTINGS do not change extracted subcolumn behavior. To change extracted subcolumn behavior, update allow_nullable_tuple_in_extracted_subcolumns in startup profile configuration (for example, users.xml) and restart the server.

allow_prefetched_read_pool_for_local_filesystem

Type: Bool
Default: 0
Tier: Production
Prefer prefetched threadpool if all parts are on local filesystem

allow_prefetched_read_pool_for_remote_filesystem

Type: Bool
Default: 1
Tier: Production
Prefer prefetched threadpool if all parts are on remote filesystem

allow_push_predicate_ast_for_distributed_subqueries

Type: Bool
Default: 1
Tier: Production
Allows push predicate on AST level for distributed subqueries with enabled anlyzer

allow_push_predicate_when_subquery_contains_with

Type: Bool
Default: 1
Tier: Production
Allows push predicate when subquery contains WITH clause

allow_rank_dense_rank_arguments

Type: Bool
Default: 0
Tier: Production
Allow passing arguments to the RANK and DENSE_RANK window functions for backward compatibility. Per SQL standard, RANK and DENSE_RANK take zero arguments — they rank rows based on the OVER (ORDER BY ...) window only. In ClickHouse versions before 26.5, queries such as RANK(x) OVER (...) silently accepted and ignored the argument, which led to user confusion (the visible argument suggested it influenced the ranking, but it did not). When this setting is false (the default), RANK and DENSE_RANK reject any arguments and throw NUMBER_OF_ARGUMENTS_DOESNT_MATCH. When set to true, the legacy lenient behavior is restored — arguments are silently ignored, matching the pre-26.5 behavior.

allow_reorder_prewhere_conditions

Type: Bool
Default: 1
Tier: Production
When moving conditions from WHERE to PREWHERE, allow reordering them to optimize filtering

allow_replace_partition_from_empty_source

Type: Bool
Default: 0
Tier: Production
Allow ALTER TABLE ... REPLACE PARTITION ... FROM ... to silently drop the destination partition when the source has no parts in that partition. By default this is disallowed: REPLACE PARTITION from a source that has no data in the requested partition raises an exception, because in this case the operation effectively becomes a silent DROP PARTITION on the destination (the destination's data is removed and nothing replaces it), a common cause of accidental data loss (see #23727). Enable this setting to restore the previous behavior, for example when you intentionally use an empty source partition to clear data in the destination. For an unconditional drop, prefer ALTER TABLE ... DROP PARTITION ... instead.

allow_settings_after_format_in_insert

Type: Bool
Default: 0
Tier: Production
Control whether SETTINGS after FORMAT in INSERT queries is allowed or not. It is not recommended to use this, since this may interpret part of SETTINGS as values. Example: sql INSERT INTO FUNCTION null('foo String') SETTINGS max_threads=1 VALUES ('bar'); But the following query will work only with allow_settings_after_format_in_insert: sql SET allow_settings_after_format_in_insert=1; INSERT INTO FUNCTION null('foo String') VALUES ('bar') SETTINGS max_threads=1; Possible values: - 0 — Disallow. - 1 — Allow. :::note Use this setting only for backward compatibility if your use cases depend on old syntax. :::

allow_simdjson

Type: Bool
Default: 1
Tier: Production
Allow using simdjson library in 'JSON*' functions if AVX2 instructions are available. If disabled rapidjson will be used.

allow_special_bool_values_inside_variant

Type: Bool
Default: 0
Tier: Production
Allows to parse Bool values inside Variant type from special text bool values like "on", "off", "enable", "disable", etc.

allow_special_serialization_kinds_in_output_formats

Type: Bool
Default: 1
Tier: Production
Allows to output columns with special serialization kinds like Sparse and Replicated without converting them to full column representation. It helps to avoid unnecessary data copy during formatting.

allow_statistic_optimize

Type: Bool
Default: 1
Tier: Production
Allows using statistics to optimize queries

allow_statistics

Type: Bool
Default: 1
Tier: Production
Allows defining columns with statistics and manipulate statistics.

allow_statistics_optimize

Type: Bool
Default: 1
Tier: Production
Allows using statistics to optimize queries

allow_suspicious_codecs

Type: Bool
Default: 0
Tier: Production
If it is set to true, allow to specify meaningless compression codecs.

allow_suspicious_fixed_string_types

Type: Bool
Default: 0
Tier: Production
In CREATE TABLE statement allows creating columns of type FixedString(n) with n > 256. FixedString with length >= 256 is suspicious and most likely indicates a misuse

allow_suspicious_indices

Type: Bool
Default: 0
Tier: Production
Reject primary/secondary indexes and sorting keys with identical expressions

allow_suspicious_low_cardinality_types

Type: Bool
Default: 0
Tier: Production
Allows or restricts using LowCardinality with data types with fixed size of 8 bytes or less: numeric data types and FixedString(8_bytes_or_less). For small fixed values using of LowCardinality is usually inefficient, because RawTree stores a numeric index for each row. As a result: - Disk space usage can rise. - RAM consumption can be higher, depending on a dictionary size. - Some functions can work slower due to extra coding/encoding operations. Merge times in MergeTree-engine tables can grow due to all the reasons described above. Possible values: - 1 — Usage of LowCardinality is not restricted. - 0 — Usage of LowCardinality is restricted.

allow_suspicious_primary_key

Type: Bool
Default: 0
Tier: Production
Allow suspicious PRIMARY KEY/ORDER BY for MergeTree (i.e. SimpleAggregateFunction).

allow_suspicious_ttl_expressions

Type: Bool
Default: 0
Tier: Production
Reject TTL expressions that don't depend on any of table's columns. It indicates a user error most of the time.

allow_suspicious_types_in_group_by

Type: Bool
Default: 1
Tier: Production
Allows or restricts using Variant and Dynamic types in GROUP BY keys.

allow_suspicious_types_in_order_by

Type: Bool
Default: 1
Tier: Production
Allows or restricts using Variant and Dynamic types in ORDER BY keys.

allow_suspicious_variant_types

Type: Bool
Default: 0
Tier: Production
In CREATE TABLE statement allows specifying Variant type with similar variant types (for example, with different numeric or date types). Enabling this setting may introduce some ambiguity when working with values with similar types.

allow_unrestricted_reads_from_keeper

Type: Bool
Default: 0
Tier: Production
Allow unrestricted (without condition on path) reads from system.zookeeper table, can be handy, but is not safe for zookeeper

allow_window_partitions_independently

Type: Bool
Default: 1
Tier: Production
Enable independent evaluation of window functions per partition on separate threads when the partition expression of the MergeTree table is a deterministic function of the window PARTITION BY columns. Each partition is read through a separate stream, sorted independently by the window sort description, and processed by its own window transform, skipping the hash scatter that ordinarily reshuffles every row across threads. Beneficial when the number of partitions is close to the number of cores and partitions have roughly the same size; otherwise a cost heuristic skips it, see max_number_of_partitions_for_independent_window and force_window_partitions_independently. Not applied with FINAL or parallel replicas.

alter_move_to_space_execute_async

Type: Bool
Default: 0
Tier: Production
Execute ALTER TABLE MOVE ... TO [DISK|VOLUME] asynchronously

alter_partition_verbose_result

Type: Bool
Default: 0
Tier: Production
Enables or disables the display of information about the parts to which the manipulation operations with partitions and parts have been successfully applied. Applicable to ATTACH PARTITION|PART and to FREEZE PARTITION. Possible values: - 0 — disable verbosity. - 1 — enable verbosity. Example sql CREATE TABLE test(a Int64, d Date, s String) ENGINE = MergeTree PARTITION BY toYYYYMDECLARE(d) ORDER BY a; INSERT INTO test VALUES(1, '2021-01-01', ''); INSERT INTO test VALUES(1, '2021-01-01', ''); ALTER TABLE test DETACH PARTITION ID '202101'; ALTER TABLE test ATTACH PARTITION ID '202101' SETTINGS alter_partition_verbose_result = 1; ┌─command_type─────┬─partition_id─┬─part_name────┬─old_part_name─┐ │ ATTACH PARTITION │ 202101 │ 202101_7_7_0 │ 202101_5_5_0 │ │ ATTACH PARTITION │ 202101 │ 202101_8_8_0 │ 202101_6_6_0 │ └──────────────────┴──────────────┴──────────────┴───────────────┘ ALTER TABLE test FREEZE SETTINGS alter_partition_verbose_result = 1; ┌─command_type─┬─partition_id─┬─part_name────┬─backup_name─┬─backup_path───────────────────┬─part_backup_path────────────────────────────────────────────┐ │ FREEZE ALL │ 202101 │ 202101_7_7_0 │ 8 │ /var/lib/rawtree/shadow/8/ │ /var/lib/rawtree/shadow/8/data/default/test/202101_7_7_0 │ │ FREEZE ALL │ 202101 │ 202101_8_8_0 │ 8 │ /var/lib/rawtree/shadow/8/ │ /var/lib/rawtree/shadow/8/data/default/test/202101_8_8_0 │ └──────────────┴──────────────┴──────────────┴─────────────┴───────────────────────────────┴─────────────────────────────────────────────────────────────┘

alter_sync

Type: UInt64
Default: 1
Tier: Production
Allows you to specify the wait behavior for actions that are to be executed on replicas by ALTER, OPTIMIZE or TRUNCATE queries. Possible values: - 0 — Do not wait. - 1 — Wait for own execution. - 2 — Wait for everyone. - 3 - Only wait for active replicas. Cloud default value: 0. :::note alter_sync is applicable to Replicated and SharedMergeTree tables only, it does nothing to alter non Replicated or Shared tables. :::

alter_update_mode

Type: AlterUpdateMode
Default: heavy
Tier: Production
A mode for ALTER queries that have the UPDATE commands. Possible values: - heavy - run regular mutation. - lightweight - run lightweight update if possible, run regular mutation otherwise. - lightweight_force - run lightweight update if possible, throw otherwise.

analyze_index_with_space_filling_curves

Type: Bool
Default: 1
Tier: Production
If a table has a space-filling curve in its index, e.g. ORDER BY mortonEncode(x, y) or ORDER BY hilbertEncode(x, y), and the query has conditions on its arguments, e.g. x >= 10 AND x <= 20 AND y >= 20 AND y <= 30, use the space-filling curve for index analysis.

analyzer_compatibility_allow_compound_identifiers_in_unflatten_nested

Type: Bool
Default: 1
Tier: Production
Allow to add compound identifiers to nested. This is a compatibility setting because it changes the query result. When disabled, SELECT a.b.c FROM table ARRAY JOIN a does not work, and SELECT a FROM table does not include a.b.c column into Nested a result.

analyzer_compatibility_allow_cte_redefinition

Type: Bool
Default: 0
Tier: Production
Allow a Common Table Expression name to be defined more than once in a single WITH clause. A reference to such a name binds to the latest definition that is not being resolved at that moment: a redefinition can read the previous definition of the same name, and the query body reads the last one. This matches the query analysis that ClickHouse used before v24.3, where a later definition silently shadowed the earlier ones. One shape differs from that analysis: a CTE declared between two definitions of a name also binds to the last definition, where the old analysis bound it to the definition visible at its declaration point. By default a redefinition is rejected with MULTIPLE_EXPRESSIONS_FOR_ALIAS. A CTE declared as MATERIALIZED and a CTE in a WITH RECURSIVE clause cannot be redefined even when the setting is enabled. Possible values: - 0 - A CTE name can be defined only once in a WITH clause. - 1 - A later definition of a CTE name shadows the earlier ones.

analyzer_compatibility_allow_non_aggregate_in_having

Type: Bool
Default: 0
Tier: Production
When enabled, the analyzer mimics the legacy behavior of moving non-aggregate AND-conjuncts from HAVING to WHERE instead of raising NOT_AN_AGGREGATE. The standard-compliant rejection is the default; this is a migration aid for queries that were silently accepted by the old analyzer (enable_analyzer = 0). Conjuncts containing aggregate, grouping, or non-deterministic functions stay in HAVING. If any conjunct contains a window function or a stateful function (for example rowNumberInBlock), the rewrite is disabled for the whole HAVING, matching the legacy PredicateExpressionsOptimizer behavior. The setting is also ignored when GROUP BY uses WITH CUBE, WITH ROLLUP, WITH TOTALS, or GROUPING SETS.

analyzer_compatibility_apply_final_to_all_joined_tables

Type: Bool
Default: 0
Tier: Production
Restores the behavior of versions before 26.6, where the FINAL modifier specified on the left-most table of a JOIN was incorrectly applied to all other joined tables as well (for engines that support FINAL, e.g. ReplacingMergeTree). By default FINAL applies only to the table it is written on. Enable for compatibility with queries that rely on the old behavior; the recommended fix is to write FINAL explicitly on every table that needs it. Possible values: - 0 - FINAL applies only to the table it is specified on. - 1 - FINAL on the left-most table of a JOIN is applied to all joined tables.

analyzer_compatibility_join_using_top_level_identifier

Type: Bool
Default: 0
Tier: Production
Force to resolve identifier in JOIN USING from projection (for example, in SELECT a + 1 AS b FROM t1 JOIN t2 USING (b) join will be performed by t1.a + 1 = t2.b, rather then t1.b = t2.b). Aliases defined on subexpressions inside the SELECT list are also considered (for example, in SELECT uniqExact(a + 1 AS b) FROM t1 JOIN t2 USING (b) the join is performed by t1.a + 1 = t2.b). When the matching alias is defined on a subexpression inside the SELECT list rather than as a top-level alias, parallel replicas are disabled for the query. For queries sent to remote servers (Distributed tables, the remote table function), such a query is rejected with an exception only when the identifier cannot be resolved on the remote server at all; if the alias shadows a real column of the left table, the remote server joins by that column instead, so the results may differ from local execution.

analyzer_compatibility_multiple_joins_qualify_column_names

Type: Bool
Default: 0
Tier: Production
When enabled and the FROM clause of a query contains two or more JOINs (comma-separated tables count; ARRAY JOIN does not), the analyzer names result columns the way the old analyzer's multiple-joins rewrite did: - columns produced by expanding *, <table>.* or COLUMNS('<regexp>') get names of the form <alias-or-table>.<column> (the qualifier is the table expression's alias if it has one, otherwise the table name without the database, otherwise the CTE name; columns of a joined subquery without an alias are left unqualified). Two kinds of column keep their bare name because they belong to the join rather than to a single table expression: a column produced by ARRAY JOIN, and a key merged by JOIN ... USING. Outer references such as SELECT ll.arr or SELECT ll.k therefore do not resolve in those two shapes; - the identifier-list form COLUMNS(col1, col2) is not a matcher expansion: each column keeps the name exactly as its identifier was written, so COLUMNS(x) produces x and COLUMNS(a.x) produces a.x; - an unaliased column reference in the SELECT list keeps its name exactly as written (e.g. SELECT a.x produces a column named a.x even when x is unambiguous). This makes outer queries that reference such columns by their qualified names work, for example: sql SELECT ll.Date FROM (SELECT * FROM t AS ll LEFT JOIN t1 ON ll.k = t1.k LEFT JOIN t2 ON ll.k = t2.k); Takes effect only when the analyzer is enabled (enable_analyzer = 1).

analyzer_compatibility_prefer_alias_over_subcolumn

Type: Bool
Default: 0
Tier: Production
When a multi-part identifier like b.id could refer to either the column id of a table aliased b or to a Tuple subcolumn b.id of some other column, prefer the alias-prefix interpretation (column id of b). By default the analyzer prefers the subcolumn. Enable to match the old analyzer's resolution.

analyzer_inline_views

Type: Bool
Default: 0
Tier: Experimental
When enabled, the analyzer substitutes ordinary (non-materialized, non-parameterized) views with their defining subqueries, enabling cross-boundary optimizations such as predicate pushdown and column pruning.

any_join_distinct_right_table_keys

Type: Bool
Default: 0
Tier: Production
Enables legacy RawTree server behaviour in ANY INNER|LEFT JOIN operations. :::note Use this setting only for backward compatibility if your use cases depend on legacy JOIN behaviour. ::: When the legacy behaviour is enabled: - Results of t1 ANY LEFT JOIN t2 and t2 ANY RIGHT JOIN t1 operations are not equal because RawTree uses the logic with many-to-one left-to-right table keys mapping. - Results of ANY INNER JOIN operations contain all rows from the left table like the SEMI LEFT JOIN operations do. When the legacy behaviour is disabled: - Results of t1 ANY LEFT JOIN t2 and t2 ANY RIGHT JOIN t1 operations are equal because RawTree uses the logic which provides one-to-many keys mapping in ANY RIGHT JOIN operations. - Results of ANY INNER JOIN operations contain one row per key from both the left and right tables. Possible values: - 0 — Legacy behaviour is disabled. - 1 — Legacy behaviour is enabled. See also: - JOIN strictness

apply_deleted_mask

Type: Bool
Default: 1
Tier: Production
Enables filtering out rows deleted with lightweight DELETE. If disabled, a query will be able to read those rows. This is useful for debugging and "undelete" scenarios

apply_mutations_on_fly

Type: Bool
Default: 0
Tier: Production
If true, mutations (UPDATEs and DELETEs) which are not materialized in data part will be applied on SELECTs.

apply_patch_parts

Type: Bool
Default: 1
Tier: Production
If true, patch parts (that represent lightweight updates) are applied on SELECTs.

apply_patch_parts_join_cache_buckets

Type: NonZeroUInt64
Default: 8
Tier: Production
The number of buckets in the temporary cache for applying patch parts in Join mode.

apply_prewhere_after_final

Type: Bool
Default: 0
Tier: Production
When enabled, PREWHERE conditions are applied after FINAL processing for ReplacingMergeTree and similar engines. This can be useful when PREWHERE references columns that may have different values across duplicate rows, and you want FINAL to select the winning row before filtering. When disabled, PREWHERE is applied during reading. Note: If apply_row_level_security_after_final is enabled and row policy uses non-sorting-key columns, PREWHERE will also be deferred to maintain correct execution order (row policy must be applied before PREWHERE).

apply_row_policy_after_final

Type: Bool
Default: 1
Tier: Production
When enabled, row policies and PREWHERE are applied after FINAL processing for *MergeTree tables. (Especially for ReplacingMergeTree) When disabled, row policies are applied before FINAL, which can cause different results when the policy filters out rows that should be used for deduplication in ReplacingMergeTree or similar engines. If the row policy expression depends only on columns in ORDER BY, it will still be applied before FINAL as an optimization, since such filtering cannot affect the deduplication result. Possible values: - 0 — Row policy and PREWHERE are applied before FINAL (default). - 1 — Row policy and PREWHERE are applied after FINAL.

apply_settings_from_server

Type: Bool
Default: 1
Tier: Production
Whether the client should accept settings from server. This only affects operations performed on the client side, in particular parsing the INSERT input data and formatting the query result. Most of query execution happens on the server and is not affected by this setting. Normally this setting should be set in user profile (users.xml or queries like ALTER USER), not through the client (client command line arguments, SET query, or SETTINGS section of SELECT query). Through the client it can be changed to false, but can't be changed to true (because the server won't send the settings if user profile has apply_settings_from_server = false). Note that initially (24.12) there was a server setting (send_settings_to_client), but latter it got replaced with this client setting, for better usability.

archive_adaptive_buffer_max_size_bytes

Type: UInt64
Default: 8388608
Tier: Production
Limits the maximum size of the adaptive buffer used when writing to archive files (for example, tar archives

arrow_flight_request_descriptor_type

Type: ArrowFlightDescriptorType
Default: path
Tier: Production
Type of descriptor to use for Arrow Flight requests. 'path' sends the dataset name as a path descriptor. 'command' sends a SQL query as a command descriptor (required for Dremio). Possible values: - 'path' — Use FlightDescriptor::Path (default, works with most Arrow Flight servers) - 'command' — Use FlightDescriptor::Command with a SELECT query (required for Dremio)

ast_fuzzer_any_query

Type: Bool
Default: 0
Tier: Experimental
When false (default), the server-side AST fuzzer (controlled by ast_fuzzer_runs) only fuzzes read-only queries (SELECT, EXPLAIN, SHOW, DESCRIBE, EXISTS). When true, all query types including DDL and INSERT are fuzzed.

ast_fuzzer_runs

Type: Float
Default: 0
Tier: Experimental
Enables the server-side AST fuzzer that runs randomized queries after each normal query, discarding their results. - 0: disabled (default). - A value between 0 and 1 (exclusive): probability of running a single fuzzed query. - A value >= 1: the number of fuzzed queries to run per normal query. The fuzzer accumulates AST fragments from all queries across all sessions, producing increasingly interesting mutations over time. Fuzzed queries that fail are silently discarded; results are never returned to the client.

asterisk_include_alias_columns

Type: Bool
Default: 0
Tier: Production
Include ALIAS columns for wildcard query (SELECT *). Possible values: - 0 - disabled - 1 - enabled

asterisk_include_materialized_columns

Type: Bool
Default: 0
Tier: Production
Include MATERIALIZED columns for wildcard query (SELECT *). Possible values: - 0 - disabled - 1 - enabled

asterisk_include_virtual_columns

Type: Bool
Default: 0
Tier: Production
Include virtual columns for wildcard query (SELECT *). Possible values: - 0 - disabled - 1 - enabled

async_insert

Type: Bool
Default: 1
Tier: Production
If true, data from INSERT query is stored in queue and later flushed to table in background. If wait_for_async_insert is false, INSERT query is processed almost instantly, otherwise client will wait until data will be flushed to table

async_insert_busy_timeout_decrease_rate

Type: Double
Default: 0.2
Tier: Production
The exponential growth rate at which the adaptive asynchronous insert timeout decreases

async_insert_busy_timeout_increase_rate

Type: Double
Default: 0.2
Tier: Production
The exponential growth rate at which the adaptive asynchronous insert timeout increases

async_insert_busy_timeout_max_ms

Type: Milliseconds
Default: 200
Tier: Production
Maximum time to wait before dumping collected data per query since the first data appeared. Cloud default value: 1000 (1s).

async_insert_busy_timeout_min_ms

Type: Milliseconds
Default: 50
Tier: Production
If auto-adjusting is enabled through async_insert_use_adaptive_busy_timeout, minimum time to wait before dumping collected data per query since the first data appeared. It also serves as the initial value for the adaptive algorithm

async_insert_busy_timeout_ms

Type: Milliseconds
Default: 200
Tier: Production
Maximum time to wait before dumping collected data per query since the first data appeared. Cloud default value: 1000 (1s).

async_insert_deduplicate

Type: Bool
Default: 0
Tier: Production
For async INSERT queries in the replicated table, specifies that deduplication of inserting blocks should be performed. This setting only takes effect when deduplicate_insert is set to backward_compatible_choice.

async_insert_max_data_size

Type: UInt64
Default: 10485760
Tier: Production
Maximum size in bytes of unparsed data collected per query before being inserted Cloud default value: 104857600 (100 MiB).

async_insert_max_query_number

Type: UInt64
Default: 450
Tier: Production
Maximum number of insert queries before being inserted. Only takes effect if setting async_insert_deduplicate is 1.

async_insert_poll_timeout_ms

Type: Milliseconds
Default: 10
Tier: Production
Timeout for polling data from asynchronous insert queue

async_insert_use_adaptive_busy_timeout

Type: Bool
Default: 1
Tier: Production
If it is set to true, use adaptive busy timeout for asynchronous inserts

async_query_sending_for_remote

Type: Bool
Default: 1
Tier: Production
Enables asynchronous connection creation and query sending while executing remote query. Enabled by default.

async_socket_for_remote

Type: Bool
Default: 1
Tier: Production
Enables asynchronous read from socket while executing remote query. Enabled by default.

autodetect_primary_key_columns_depth_limit

Type: UInt64
Default: 1
Tier: Production
The maximum depth of the auto-detected primary key for raw MergeTree tables. Available only in RawTree.

autodetect_primary_key_columns_limit

Type: UInt64
Default: 6
Tier: Production
The number of columns to use for the auto-detected primary key for raw MergeTree tables. Available only in RawTree.

autodetect_primary_key_columns_max_candidates

Type: UInt64
Default: 32
Tier: Production
The maximum number of columns to consider for the auto-detected primary key for raw MergeTree tables. Available only in RawTree.

autodetect_primary_key_columns_min_column_cardinality

Type: UInt64
Default: 4
Tier: Production
The minimum cardinality a column must have to be considered for the auto-detected primary key for raw MergeTree tables. Available only in RawTree.

automatic_parallel_replicas_min_bytes_per_replica

Type: UInt64
Default: 1048576
Tier: Experimental
Threshold of bytes to read per replica to enable parallel replicas automatically (applies only when automatic_parallel_replicas_mode=1). 0 means no threshold. The total number of bytes to read is estimated based on the collected statistics.

automatic_parallel_replicas_mode

Type: UInt64
Default: 0
Tier: Experimental
Enable automatic switching to execution with parallel replicas based on collected statistics. Requires enable_analyzer = 1, enable_parallel_replicas != 0, parallel_replicas_local_plan = 1 and providing cluster_for_parallel_replicas. 0 - disabled, 1 - enabled, 2 - only statistics collection is enabled (switching to execution with parallel replicas is disabled).

azure_allow_parallel_part_upload

Type: Bool
Default: 1
Tier: Production
Use multiple threads for azure multipart upload.

azure_check_objects_after_upload

Type: Bool
Default: 0
Tier: Production
Check each uploaded object in azure blob storage to be sure that upload was successful

azure_connect_timeout_ms

Type: UInt64
Default: 1000
Tier: Production
Connection timeout for host from azure disks.

azure_create_new_file_on_insert

Type: Bool
Default: 0
Tier: Production
Enables or disables creating a new file on each insert in azure engine tables

azure_ignore_file_doesnt_exist

Type: Bool
Default: 0
Tier: Production
Ignore absence of file if it does not exist when reading certain keys. Possible values: - 1 — SELECT returns empty result. - 0 — SELECT throws an exception.

azure_list_object_keys_size

Type: UInt64
Default: 1000
Tier: Production
Maximum number of files that could be returned in batch by ListObject request

azure_max_blocks_in_multipart_upload

Type: UInt64
Default: 50000
Tier: Production
Maximum number of blocks in multipart upload for Azure.

azure_max_get_burst

Type: UInt64
Default: 0
Tier: Production
Max number of requests that can be issued simultaneously before hitting request per second limit. By default (0) equals to azure_max_get_rps

azure_max_get_rps

Type: UInt64
Default: 0
Tier: Production
Limit on Azure GET request per second rate before throttling. Zero means unlimited.

azure_max_inflight_parts_for_one_file

Type: UInt64
Default: 20
Tier: Production
The maximum number of a concurrent loaded parts in multipart upload request. 0 means unlimited.

azure_max_put_burst

Type: UInt64
Default: 0
Tier: Production
Max number of requests that can be issued simultaneously before hitting request per second limit. By default (0) equals to azure_max_put_rps

azure_max_put_rps

Type: UInt64
Default: 0
Tier: Production
Limit on Azure PUT request per second rate before throttling. Zero means unlimited.

azure_max_redirects

Type: UInt64
Default: 10
Tier: Production
Max number of azure redirects hops allowed.

azure_max_single_part_copy_size

Type: UInt64
Default: 268435456
Tier: Production
The maximum size of object to copy using single part copy to Azure blob storage.

azure_max_single_part_upload_size

Type: UInt64
Default: 33554432
Tier: Production
The maximum size of object to upload using singlepart upload to Azure blob storage.

azure_max_single_read_retries

Type: UInt64
Default: 4
Tier: Production
The maximum number of retries during single Azure blob storage read.

azure_max_unexpected_write_error_retries

Type: UInt64
Default: 4
Tier: Production
The maximum number of retries in case of unexpected errors during Azure blob storage write

azure_max_upload_part_size

Type: UInt64
Default: 5368709120
Tier: Production
The maximum size of part to upload during multipart upload to Azure blob storage.

azure_min_upload_part_size

Type: UInt64
Default: 16777216
Tier: Production
The minimum size of part to upload during multipart upload to Azure blob storage.

azure_request_timeout_ms

Type: UInt64
Default: 30000
Tier: Production
Idleness timeout for sending and receiving data to/from azure. Fail if a single TCP read or write call blocks for this long.

azure_sdk_max_retries

Type: UInt64
Default: 10
Tier: Production
Maximum number of retries in azure sdk

azure_sdk_retry_initial_backoff_ms

Type: UInt64
Default: 10
Tier: Production
Minimal backoff between retries in azure sdk

azure_sdk_retry_max_backoff_ms

Type: UInt64
Default: 1000
Tier: Production
Maximal backoff between retries in azure sdk

azure_skip_empty_files

Type: Bool
Default: 0
Tier: Production
Enables or disables skipping empty files in S3 engine. Possible values: - 0 — SELECT throws an exception if empty file is not compatible with requested format. - 1 — SELECT returns empty result for empty file.

azure_strict_upload_part_size

Type: UInt64
Default: 0
Tier: Production
The exact size of part to upload during multipart upload to Azure blob storage.

azure_throw_on_zero_files_match

Type: Bool
Default: 0
Tier: Production
Throw an error if matched zero files according to glob expansion rules. Possible values: - 1 — SELECT throws an exception. - 0 — SELECT returns empty result.

azure_truncate_on_insert

Type: Bool
Default: 0
Tier: Production
Enables or disables truncate before insert in azure engine tables.

azure_upload_part_size_multiply_factor

Type: UInt64
Default: 2
Tier: Production
Multiply azure_min_upload_part_size by this factor each time azure_multiply_parts_count_threshold parts were uploaded from a single write to Azure blob storage.

azure_upload_part_size_multiply_parts_count_threshold

Type: UInt64
Default: 500
Tier: Production
Each time this number of parts was uploaded to Azure blob storage, azure_min_upload_part_size is multiplied by azure_upload_part_size_multiply_factor.

azure_use_adaptive_timeouts

Type: Bool
Default: 1
Tier: Production
When set to true than for all azure requests first two attempts are made with low send and receive timeouts. When set to false than all attempts are made with identical timeouts.

azure_validate_etag_on_read

Type: Bool
Default: 1
Tier: Production
When reading a blob from Azure Blob Storage through the azureBlobStorage / azureBlobStorageCluster table functions or the AzureBlobStorage table engine, pin every GET request to the generation of the blob that was observed when it was listed by sending its ETag in If-Match, and check the ETag of the response. A single file read issues many ranged GET requests; if the blob is overwritten in place between them (for example by an external writer rewriting a fixed key), the reads can otherwise be stitched together from two different generations of the blob and surface as a corrupted checksum or parse error. The size recorded at listing time is also used as the right bound of the read, so it is only correct for the generation it was recorded for. When a mismatch is detected the read fails with AZURE_OBJECT_CHANGED_DURING_READ instead of returning inconsistent data. Disable only for workloads that intentionally read blobs that are being overwritten and can tolerate inconsistent reads.

backup_restore_batch_size_for_keeper_multi

Type: UInt64
Default: 1000
Tier: Production
Maximum size of batch for multi request to [Zoo]Keeper during backup or restore

backup_restore_batch_size_for_keeper_multiread

Type: UInt64
Default: 10000
Tier: Production
Maximum size of batch for multiread request to [Zoo]Keeper during backup or restore

backup_restore_failure_after_host_disconnected_for_seconds

Type: UInt64
Default: 3600
Tier: Production
If a host during a BACKUP ON CLUSTER or RESTORE ON CLUSTER operation doesn't recreate its ephemeral 'alive' node in ZooKeeper for this amount of time then the whole backup or restore is considered as failed. This value should be bigger than any reasonable time for a host to reconnect to ZooKeeper after a failure. Zero means unlimited.

backup_restore_finish_timeout_after_error_sec

Type: UInt64
Default: 180
Tier: Production
How long the initiator should wait for other host to react to the 'error' node and stop their work on the current BACKUP ON CLUSTER or RESTORE ON CLUSTER operation.

backup_restore_keeper_fault_injection_probability

Type: Float
Default: 0
Tier: Production
Approximate probability of failure for a keeper request during backup or restore. Valid value is in interval [0.0f, 1.0f]

backup_restore_keeper_fault_injection_seed

Type: UInt64
Default: 0
Tier: Production
0 - random seed, otherwise the setting value

backup_restore_keeper_max_retries

Type: UInt64
Default: 1000
Tier: Production
Max retries for [Zoo]Keeper operations in the middle of a BACKUP or RESTORE operation. Should be big enough so the whole operation won't fail because of a temporary [Zoo]Keeper failure.

backup_restore_keeper_max_retries_while_handling_error

Type: UInt64
Default: 20
Tier: Production
Max retries for [Zoo]Keeper operations while handling an error of a BACKUP ON CLUSTER or RESTORE ON CLUSTER operation.

backup_restore_keeper_max_retries_while_initializing

Type: UInt64
Default: 20
Tier: Production
Max retries for [Zoo]Keeper operations during the initialization of a BACKUP ON CLUSTER or RESTORE ON CLUSTER operation.

backup_restore_keeper_retry_initial_backoff_ms

Type: UInt64
Default: 100
Tier: Production
Initial backoff timeout for [Zoo]Keeper operations during backup or restore

backup_restore_keeper_retry_max_backoff_ms

Type: UInt64
Default: 5000
Tier: Production
Max backoff timeout for [Zoo]Keeper operations during backup or restore Cloud default value: 60000.

backup_restore_keeper_value_max_size

Type: UInt64
Default: 1048576
Tier: Production
Maximum size of data of a [Zoo]Keeper's node during backup

backup_restore_s3_retry_attempts

Type: UInt64
Default: 1000
Tier: Production
Setting for Aws::Client::RetryStrategy, Aws::Client does retries itself, 0 means no retries. It takes place only for backup/restore.

backup_restore_s3_retry_initial_backoff_ms

Type: UInt64
Default: 25
Tier: Production
Initial backoff delay in milliseconds before the first retry attempt during backup and restore. Each subsequent retry increases the delay exponentially, up to the maximum specified by backup_restore_s3_retry_max_backoff_ms

backup_restore_s3_retry_jitter_factor

Type: Float
Default: 0.1
Tier: Production
Jitter factor applied to the retry backoff delay in Aws::Client::RetryStrategy during backup and restore operations. The computed backoff delay is multiplied by a random factor in the range [1.0, 1.0 + jitter], up to the maximum backup_restore_s3_retry_max_backoff_ms. Must be in [0.0, 1.0] interval

backup_restore_s3_retry_max_backoff_ms

Type: UInt64
Default: 5000
Tier: Production
Maximum delay in milliseconds between retries during backup and restore operations.

backup_s3_expired_token_retry_timeout_ms

Type: UInt64
Default: 120000
Tier: Production
Maximum time in milliseconds to retry an S3 request whose response identifies ExpiredToken during backup or restore. Retries also stop at backup_restore_s3_retry_attempts. Zero disables these retries. AWS S3 HEAD responses expose only a generic HTTP status, so this retry does not cover HEAD metadata requests.

backup_slow_all_threads_after_retryable_s3_error

Type: Bool
Default: 0
Tier: Production
When set to true, all threads executing S3 requests to the same backup endpoint are slowed down after any single S3 request encounters a retryable S3 error, such as 'Slow Down'. When set to false, each thread handles s3 request backoff independently of the others.

bool_false_representation

Type: String
Default: false
Tier: Production
Text to represent false bool value in TSV/CSV/Vertical/Pretty formats.

bool_true_representation

Type: String
Default: true
Tier: Production
Text to represent true bool value in TSV/CSV/Vertical/Pretty formats.

cache_warmer_threads

Type: UInt64
Default: 4
Tier: Production
Only has an effect in RawTree Cloud. Number of background threads for speculatively downloading new data parts into the filesystem cache, when cache_populated_by_fetch is enabled. Zero to disable.

calculate_text_stack_trace

Type: Bool
Default: 1
Tier: Production
Calculate text stack trace in case of exceptions during query execution. This is the default. It requires symbol lookups that may slow down fuzzing tests when a huge amount of wrong queries are executed. In normal cases, you should not disable this option.

cancel_http_readonly_queries_on_client_close

Type: Bool
Default: 0
Tier: Production
Cancels HTTP read-only queries (e.g. SELECT) when a client closes the connection without waiting for the response. Cloud default value: 1.

cast_ipv4_ipv6_default_on_conversion_error

Type: Bool
Default: 0
Tier: Production
CAST operator into IPv4, CAST operator into IPV6 type, toIPv4, toIPv6 functions will return default value instead of throwing exception on conversion error.

cast_keep_nullable

Type: Bool
Default: 0
Tier: Production
Enables or disables keeping of the Nullable data type in CAST operations. When the setting is enabled and the argument of CAST function is Nullable, the result is also transformed to Nullable type. When the setting is disabled, the result always has the destination type exactly. Possible values: - 0 — The CAST result has exactly the destination type specified. - 1 — If the argument type is Nullable, the CAST result is transformed to Nullable(DestinationDataType). Examples The following query results in the destination data type exactly: sql SET cast_keep_nullable = 0; SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x); Result: text ┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐ │ 0 │ Int32 │ └───┴───────────────────────────────────────────────────┘ The following query results in the Nullable modification on the destination data type: sql SET cast_keep_nullable = 1; SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x); Result: text ┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐ │ 0 │ Nullable(Int32) │ └───┴───────────────────────────────────────────────────┘ See Also - CAST function

cast_string_to_date_time_mode

Type: DateTimeInputFormat
Default: best_effort
Tier: Production
Allows choosing a parser of the text representation of date and time during cast from String. Possible values: - 'best_effort' — Enables extended parsing. RawTree can parse the basic YYYY-MM-DD HH:MM:SS format and all ISO 8601 date and time formats. For example, '2018-06-08T01:02:03.000Z'. - 'best_effort_us' — Similar to best_effort (see the difference in parseDateTimeBestEffortUS - 'basic' — Use basic parser. RawTree can parse only the basic YYYY-MM-DD HH:MM:SS or YYYY-MM-DD format. For example, 2019-08-20 10:18:56 or 2019-08-20. See also: - DateTime data type. - Functions for working with dates and times.

cast_string_to_dynamic_use_inference

Type: Bool
Default: 0
Tier: Production
Use types inference during String to Dynamic conversion

cast_string_to_variant_use_inference

Type: Bool
Default: 1
Tier: Production
Use types inference during String to Variant conversion.

check_conversion_from_numbers_to_enum

Type: Bool
Default: 1
Tier: Production
Throw an exception during Numbers to Enum conversion if the value does not exist in Enum. Possible values: - 0 — Disabled. - 1 — Enabled. Example text CREATE TABLE tab ( val Enum('first' = 1, 'second' = 2, 'third' = 3) ) ENGINE = Memory; INSERT INTO tab SETTINGS check_conversion_from_numbers_to_enum = 1 VALUES (4); -- returns an error

check_named_collection_dependencies

Type: Bool
Default: 1
Tier: Production
Check that DROP NAMED COLLECTION will not break tables that depend on it

check_query_single_value_result

Type: Bool
Default: 0
Tier: Production
Defines the level of detail for the CHECK TABLE query result for MergeTree family engines . Possible values: - 0 — the query shows a check status for every individual data part of a table. - 1 — the query shows the general table check status.

check_referential_table_dependencies

Type: Bool
Default: 0
Tier: Production
Check that DDL query (such as DROP TABLE or RENAME) will not break referential dependencies

check_table_dependencies

Type: Bool
Default: 1
Tier: Production
Check that DDL query (such as DROP TABLE or RENAME) will not break dependencies

checksum_on_read

Type: Bool
Default: 1
Tier: Production
Validate checksums on reading. It is enabled by default and should be always enabled in production. Please do not expect any benefits in disabling this setting. It may only be used for experiments and benchmarks. The setting is only applicable for tables of MergeTree family. Checksums are always validated for other table engines and when receiving data over the network.

cloud_mode

Type: Bool
Default: 0
Tier: Production
Cloud mode Cloud default value: 1.

cloud_mode_engine

Type: UInt64
Default: 1
Tier: Production
The engine family allowed in Cloud. - 0 - allow everything - 1 - rewrite DDLs to use *ReplicatedMergeTree - 2 - rewrite DDLs to use SharedMergeTree - 3 - rewrite DDLs to use SharedMergeTree except when explicitly passed remote disk is specified - 4 - same as 3, plus additionally use Alias instead of Distributed (the Alias table will point to the destination table of the Distributed table, so it will use the corresponding local table) UInt64 to minimize public part Cloud default value: 2.

cluster_for_parallel_replicas

Type: String
Default: ``
Tier: Production
Cluster for a shard in which current server is located Cloud default value: default.

cluster_function_process_archive_on_multiple_nodes

Type: Bool
Default: 1
Tier: Production
If set to true, increases performance of processing archives in cluster functions. Should be set to false for compatibility and to avoid errors during upgrade to 25.7+ if using cluster functions with archives on earlier versions.

cluster_table_function_buckets_batch_size

Type: UInt64
Default: 0
Tier: Production
Defines the approximate size of a batch (in bytes) used in distributed processing of tasks in cluster table functions with bucket split granularity. The system accumulates data until at least this amount is reached. The actual size may be slightly larger to align with data boundaries.

cluster_table_function_split_granularity

Type: ObjectStorageGranularityLevel
Default: file
Tier: Production
Controls how data is split into tasks when executing a CLUSTER TABLE FUNCTION. This setting defines the granularity of work distribution across the cluster: - file — each task processes an entire file. - bucket — tasks are created per internal data block within a file (for example, Parquet row groups). Choosing finer granularity (like bucket) can improve parallelism when working with a small number of large files. For instance, if a Parquet file contains multiple row groups, enabling bucket granularity allows each group to be processed independently by different workers.

collect_hash_table_stats_during_aggregation

Type: Bool
Default: 1
Tier: Production
Enable collecting hash table statistics to optimize memory allocation

collect_hash_table_stats_during_joins

Type: Bool
Default: 1
Tier: Production
Enable collecting hash table statistics to optimize memory allocation

column_names_for_schema_inference

Type: String
Default: ``
Tier: Production
The list of column names to use in schema inference for formats without column names. The format: 'column1,column2,column3,...'

compatibility

Type: String
Default: ``
Tier: Production
The compatibility setting causes RawTree to use the default settings of a previous version, where the previous version is provided as the setting. If settings are set to non-default values, then those settings are honored (only settings that have not been modified are affected by the compatibility setting). This setting takes a version number as a string, like 22.3, 22.8. An empty value means that this setting is disabled. Disabled by default. :::note The compatibility setting can be overridden at the user, role, profile, query, or session level using standard setting mechanisms such as SET compatibility = '22.3' in a session or SETTINGS compatibility = '22.3' in a query. :::

compatibility_ignore_auto_increment_in_create_table

Type: Bool
Default: 0
Tier: Production
Ignore AUTO_INCREMENT keyword in column declaration if true, otherwise return error. It simplifies migration from MySQL

compatibility_ignore_collation_in_create_table

Type: Bool
Default: 1
Tier: Production
Compatibility ignore collation in create table

compatibility_s3_presigned_url_query_in_path

Type: Bool
Default: 0
Tier: Production
Compatibility: when enabled, folds pre-signed URL query parameters (e.g. X-Amz-*) into the S3 key (legacy behavior), so '?' acts as a wildcard in the path. When disabled (default), pre-signed URL query parameters are kept in the URL query to avoid interpreting '?' as a wildcard.

compile_aggregate_expressions

Type: Bool
Default: 1
Tier: Production
Enables or disables JIT-compilation of aggregate functions to native code. Enabling this setting can improve the performance. Possible values: - 0 — Aggregation is done without JIT compilation. - 1 — Aggregation is done using JIT compilation. See Also - min_count_to_compile_aggregate_expression

compile_expressions

Type: Bool
Default: 1
Tier: Production
Compile some scalar functions and operators to native code.

compile_regular_expressions

Type: Bool
Default: 1
Tier: Production
Compile simple regular expressions used in functions like match and extract to native code. Patterns outside the supported subset transparently fall back to the general engine.

compile_sort_description

Type: Bool
Default: 1
Tier: Production
Compile sort description to native code.

compression

Type: String
Default: ``
Tier: Production
Applies a generic compression to the response body, e.g., compression=gz. Note this is independent of Content-Encoding (HTTP compression) and the legacy compress parameter (RawTree-native compression). Specifying a compressed file extension in the URL path is equivalent. This is an HTTP-interface response-shaping setting: it is consumed before the query is executed (the response buffers are set up up-front), so it must be supplied via the HTTP URL parameter, the URL path file extension, or a user profile, not via an in-query SETTINGS clause (where it has no effect and is rejected).

connect_timeout

Type: Seconds
Default: 10
Tier: Production
Connection timeout if there are no replicas.

connect_timeout_with_failover_ms

Type: Milliseconds
Default: 1000
Tier: Production
The timeout in milliseconds for connecting to a remote server for a Distributed table engine, if the 'shard' and 'replica' sections are used in the cluster definition. If unsuccessful, several attempts are made to connect to various replicas.

connect_timeout_with_failover_secure_ms

Type: Milliseconds
Default: 1000
Tier: Production
Connection timeout for selecting first healthy replica (for secure connections).

connection_pool_max_wait_ms

Type: Milliseconds
Default: 0
Tier: Production
The wait time in milliseconds for a connection when the connection pool is full. Possible values: - Positive integer. - 0 — Infinite timeout.

connections_with_failover_max_tries

Type: UInt64
Default: 3
Tier: Production
The maximum number of connection attempts with each replica for the Distributed table engine.

convert_query_to_cnf

Type: Bool
Default: 0
Tier: Production
When set to true, a SELECT query will be converted to conjuctive normal form (CNF). There are scenarios where rewriting a query in CNF may execute faster (view this Github issue for an explanation). For example, notice how the following SELECT query is not modified (the default behavior): sql EXPLAIN SYNTAX SELECT * FROM ( SELECT number AS x FROM numbers(20) ) AS a WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15)) SETTINGS convert_query_to_cnf = false; The result is: response ┌─explain────────────────────────────────────────────────────────┐ │ SELECT x │ │ FROM │ │ ( │ │ SELECT number AS x │ │ FROM numbers(20) │ │ WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15)) │ │ ) AS a │ │ WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15)) │ │ SETTINGS convert_query_to_cnf = 0 │ └────────────────────────────────────────────────────────────────┘ Let's set convert_query_to_cnf to true and see what changes: sql EXPLAIN SYNTAX SELECT * FROM ( SELECT number AS x FROM numbers(20) ) AS a WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15)) SETTINGS convert_query_to_cnf = true; Notice the WHERE clause is rewritten in CNF, but the result set is the identical - the Boolean logic is unchanged: response ┌─explain───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ SELECT x │ │ FROM │ │ ( │ │ SELECT number AS x │ │ FROM numbers(20) │ │ WHERE ((x <= 15) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x >= 10) OR (x >= 1)) │ │ ) AS a │ │ WHERE ((x >= 10) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x <= 15) OR (x <= 5)) │ │ SETTINGS convert_query_to_cnf = 1 │ └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ Possible values: true, false

correlated_subqueries_default_join_kind

Type: DecorrelationJoinKind
Default: right
Tier: Production
Controls the kind of joins in the decorrelated query plan. The default value is right, which means that decorrelated plan will contain RIGHT JOINs with subquery input on the right side. Possible values: - left - Decorrelation process will produce LEFT JOINs and input table will appear on the left side. - right - Decorrelation process will produce RIGHT JOINs and input table will appear on the right side. When the subquery input is shared through an in-memory buffer (see correlated_subqueries_use_in_memory_buffer), right is used regardless of this setting, because only that layout evaluates the buffer writer before its reader. The join kind is an internal detail of the decorrelated plan and does not change the result.

correlated_subqueries_substitute_equivalent_expressions

Type: Bool
Default: 1
Tier: Production
Use filter expressions to inference equivalent expressions and substitute them instead of creating a CROSS JOIN.

correlated_subqueries_use_in_memory_buffer

Type: Bool
Default: 1
Tier: Production
Use in-memory buffer for correlated subquery input to avoid its repeated evaluation.

count_distinct_implementation

Type: String
Default: uniqExact
Tier: Production
Specifies which of the uniq* functions should be used to perform the COUNT(DISTINCT ...) construction. Possible values: - uniq - uniqCombined - uniqCombined64 - uniqHLL12 - uniqExact

count_distinct_optimization

Type: Bool
Default: 0
Tier: Production
Rewrite count distinct to subquery of group by

count_matches_stop_at_empty_match

Type: Bool
Default: 0
Tier: Production
Stop counting once a pattern matches zero-length in the countMatches function.

create_if_not_exists

Type: Bool
Default: 0
Tier: Production
Enable IF NOT EXISTS for CREATE statement by default. If either this setting or IF NOT EXISTS is specified and a table with the provided name already exists, no exception will be thrown.

create_index_ignore_unique

Type: Bool
Default: 0
Tier: Production
Ignore UNIQUE keyword in CREATE UNIQUE INDEX. Made for SQL compatibility tests.

create_replicated_merge_tree_fault_injection_probability

Type: Float
Default: 0
Tier: Production
The probability of a fault injection during table creation after creating metadata in ZooKeeper

create_table_empty_primary_key_by_default

Type: Bool
Default: 1
Tier: Production
Allow to create *MergeTree tables with empty primary key when ORDER BY and PRIMARY KEY not specified

cross_join_min_bytes_to_compress

Type: UInt64
Default: 1073741824
Tier: Production
Minimal size of block to compress in CROSS JOIN. Zero value means - disable this threshold. This block is compressed when any of the two thresholds (by rows or by bytes) are reached.

cross_join_min_rows_to_compress

Type: UInt64
Default: 10000000
Tier: Production
Minimal count of rows to compress block in CROSS JOIN. Zero value means - disable this threshold. This block is compressed when any of the two thresholds (by rows or by bytes) are reached.

cross_to_inner_join_rewrite

Type: UInt64
Default: 1
Tier: Production
Use inner join instead of comma/cross join if there are joining expressions in the WHERE section. Values: 0 - no rewrite, 1 - apply if possible for comma/cross, 2 - force rewrite all comma joins, cross - if possible

data_type_default_nullable

Type: Bool
Default: 0
Tier: Production
Allows data types without explicit modifiers NULL or NOT NULL in column definition will be Nullable. Possible values: - 1 — The data types in column definitions are set to Nullable by default. - 0 — The data types in column definitions are set to not Nullable by default.

database

Type: String
Default: ``
Tier: Production
Sets the current database for the query — the database in which unqualified table names are resolved, the same effect as USE <database>. Unlike the USE statement, this is an ordinary session setting: like any other setting it accepts a value without validating it, and an unknown database is reported when the setting takes effect (when a query runs), not at SET time. It follows the privilege contract of the client-supplied default database (which it generalizes), not of USE: selecting the current database does not require the SHOW_DATABASES privilege, while access to the tables inside it is checked as usual. Used as the destination for the HTTP interface database URL parameter and the X-RawTree-Database header.

database_atomic_wait_for_drop_and_detach_synchronously

Type: Bool
Default: 0
Tier: Production
Adds a modifier SYNC to all DROP and DETACH queries. Possible values: - 0 — Queries will be executed with delay. - 1 — Queries will be executed without delay.

database_datalake_require_metadata_access

Type: Bool
Default: 1
Tier: Production
Either to throw error or not if we don't have rights to get table's metadata in database engine DataLakeCatalog.

database_replicated_allow_explicit_uuid

Type: UInt64
Default: 0
Tier: Production
0 - Don't allow to explicitly specify UUIDs for tables in Replicated databases. 1 - Allow. 2 - Allow, but ignore the specified UUID and generate a random one instead.

database_replicated_allow_heavy_create

Type: Bool
Default: 0
Tier: Production
Allow long-running DDL queries (CREATE AS SELECT and POPULATE) in Replicated database engine. Note that it can block DDL queue for a long time.

database_replicated_allow_only_replicated_engine

Type: Bool
Default: 0
Tier: Production
Allow to create only Replicated tables in database with engine Replicated Cloud default value: 1.

database_replicated_allow_replicated_engine_arguments

Type: UInt64
Default: 0
Tier: Production
0 - Don't allow to explicitly specify ZooKeeper path and replica name for *MergeTree tables in Replicated databases. 1 - Allow. 2 - Allow, but ignore the specified path and use default one instead. 3 - Allow and don't log a warning.

database_replicated_always_detach_permanently

Type: Bool
Default: 0
Tier: Production
Execute DETACH TABLE as DETACH TABLE PERMANENTLY if database engine is Replicated

database_replicated_enforce_synchronous_settings

Type: Bool
Default: 0
Tier: Production
Enforces synchronous waiting for some queries (see also database_atomic_wait_for_drop_and_detach_synchronously, mutations_sync, alter_sync). Not recommended to enable these settings.

database_replicated_initial_query_timeout_sec

Type: UInt64
Default: 300
Tier: Production
Sets how long initial DDL query should wait for Replicated database to process previous DDL queue entries in seconds. Possible values: - Positive integer. - 0 — Unlimited.

database_shared_drop_table_delay_seconds

Type: UInt64
Default: 28800
Tier: Production
The delay in seconds before a dropped table is actually removed from a Shared database. This allows to recover the table within this time using UNDROP TABLE statement.

date_time_64_output_format_cut_trailing_zeros_align_to_groups_of_thousands

Type: Bool
Default: 0
Tier: Production
Dynamically trim the trailing zeros of datetime64 values to adjust the output scale to [0, 3, 6], corresponding to 'seconds', 'milliseconds', and 'microseconds'

date_time_input_format

Type: DateTimeInputFormat
Default: best_effort
Tier: Production
Allows choosing a parser of the text representation of date and time. The setting does not apply to date and time functions. Possible values: - 'best_effort' — Enables extended parsing. RawTree can parse the basic YYYY-MM-DD HH:MM:SS format and all ISO 8601 date and time formats. For example, '2018-06-08T01:02:03.000Z'. - 'best_effort_us' — Similar to best_effort (see the difference in parseDateTimeBestEffortUS - 'basic' — Use basic parser. RawTree can parse only the basic YYYY-MM-DD HH:MM:SS or YYYY-MM-DD format. For example, 2019-08-20 10:18:56 or 2019-08-20. See also: - DateTime data type. - Functions for working with dates and times.

date_time_output_format

Type: DateTimeOutputFormat
Default: simple
Tier: Production
Allows choosing different output formats of the text representation of date and time. Possible values: - simple - Simple output format. RawTree output date and time YYYY-MM-DD hh:mm:ss format. For example, 2019-08-20 10:18:56. The calculation is performed according to the data type's time zone (if present) or server time zone. - iso - ISO output format. RawTree output date and time in ISO 8601 YYYY-MM-DDThh:mm:ssZ format. For example, 2019-08-20T10:18:56Z. Note that output is in UTC (Z means UTC). - unix_timestamp - Unix timestamp output format. RawTree output date and time in Unix timestamp format. For example 1566285536. See also: - DateTime data type. - Functions for working with dates and times.

date_time_overflow_behavior

Type: DateTimeOverflowBehavior
Default: ignore
Tier: Production
Defines the behavior when Date, Date32, DateTime, DateTime64 or integers are converted into Date, Date32, DateTime or DateTime64 but the value cannot be represented in the result type. It also applies when a Date or DateTime is parsed from text, including by an input format. Possible values: - ignore — Silently ignore overflows. Result are undefined. - throw — Throw an exception in case of overflow. - saturate — Saturate the result. If the value is smaller than the smallest value that can be represented by the target type, the result is chosen as the smallest representable value. If the value is bigger than the largest value that can be represented by the target type, the result is chosen as the largest representable value. Default value: ignore.

dead_blobs_to_delay_insert

Type: UInt64
Default: 0
Tier: Production
If the dead blobs queues of the destination table's disks contain at least that many blobs pending removal, artificially slow down insert into table. 0 - use the table setting.

dead_blobs_to_throw_insert

Type: UInt64
Default: 0
Tier: Production
If the dead blobs queues of the destination table's disks contain more than this number of blobs pending removal, throw 'Too many dead blobs ...' exception. 0 - use the table setting.

decimal_check_overflow

Type: Bool
Default: 1
Tier: Production
Check overflow of decimal arithmetic/comparison operations

deduplicate_blocks_in_dependent_materialized_views

Type: Bool
Default: 1
Tier: Production
Enables or disables the deduplication check for materialized views that receive data from Replicated* tables. Possible values: - 0 — Disabled. - 1 — Enabled. When enabled, RawTree performs deduplication of blocks in materialized views that depend on Replicated* tables. This setting is useful for ensuring that materialized views do not contain duplicate data when the insertion operation is being retried due to a failure. See Also - NULL Processing in IN Operators

deduplicate_insert

Type: DeduplicateInsertMode
Default: enable
Tier: Production
Enables or disables block deduplication of INSERT INTO (for Replicated* tables). The setting applies to both synchronous and asynchronous inserts, and it supersedes the insert_deduplicate and async_insert_deduplicate settings. That setting has three possible values: - disable — Deduplication is disabled for INSERT INTO query. - enable — Deduplication is enabled for INSERT INTO query. - backward_compatible_choice — Deduplication is enabled if insert_deduplicate or async_insert_deduplicate are enabled for specific insert type. For INSERT SELECT queries, deduplicate_insert_select is consulted first. Deduplication also requires the destination table to keep a deduplication log, see replicated_deduplication_window and non_replicated_deduplication_window.

deduplicate_insert_select

Type: DeduplicateInsertSelectMode
Default: enable_when_possible
Tier: Production
Enables or disables block deduplication of INSERT SELECT (for Replicated* tables). For INSERT SELECT queries this setting is consulted before deduplicate_insert. A SELECT is stable when it carries ORDER BY ALL and its pipeline ends in a single stream. A non-empty insert_deduplication_token is an equivalent substitute for stability. That setting has four possible values: - disable — Deduplication is disabled for INSERT SELECT query. - force_enable — Deduplication is enabled for INSERT SELECT query, regardless of deduplicate_insert. If select result is not stable and no token is provided, exception is thrown. - enable_when_possible — Deduplication is enabled if it is enabled by deduplicate_insert and the select result is stable, otherwise disabled. - enable_even_for_bad_queries - Deduplication is enabled if it is enabled by deduplicate_insert, regardless of whether the select result is stable. If select result is not stable, a message is logged, but query is executed with deduplication. This option is for backward compatibility. Consider to use other options instead as it may lead to unexpected results.

default_format

Type: String
Default: ``
Tier: Production
Specifies the format of the query result when the query has no FORMAT clause and no other format override is applied.

default_materialized_view_sql_security

Type: SQLSecurityType
Default: DEFINER
Tier: Production
Allows to set a default value for SQL SECURITY option when creating a materialized view. More about SQL security. The default value is DEFINER.

default_max_bytes_in_join

Type: UInt64
Default: 1000000000
Tier: Production
Maximum size of right-side table if limit is required but max_bytes_in_join is not set.

default_normal_view_sql_security

Type: SQLSecurityType
Default: INVOKER
Tier: Production
Allows to set default SQL SECURITY option while creating a normal view. More about SQL security. The default value is INVOKER.

default_table_engine

Type: DefaultTableEngine
Default: MergeTree
Tier: Production
Default table engine to use when ENGINE is not set in a CREATE statement. Possible values: - a string representing any valid table engine name Cloud default value: SharedMergeTree. Example Query: sql SET default_table_engine = 'Log'; SELECT name, value, changed FROM system.settings WHERE name = 'default_table_engine'; Result: response ┌─name─────────────────┬─value─┬─changed─┐ │ default_table_engine │ Log │ 1 │ └──────────────────────┴───────┴─────────┘ In this example, any new table that does not specify an Engine will use the Log table engine: Query: sql CREATE TABLE my_table ( x UInt32, y UInt32 ); SHOW CREATE TABLE my_table; Result: response ┌─statement────────────────────────────────────────────────────────────────┐ │ CREATE TABLE default.my_table ( `x` UInt32, `y` UInt32 ) ENGINE = Log └──────────────────────────────────────────────────────────────────────────┘

default_temporary_table_engine

Type: DefaultTableEngine
Default: Memory
Tier: Production
Same as default_table_engine but for temporary tables. In this example, any new temporary table that does not specify an Engine will use the Log table engine: Query: sql SET default_temporary_table_engine = 'Log'; CREATE TEMPORARY TABLE my_table ( x UInt32, y UInt32 ); SHOW CREATE TEMPORARY TABLE my_table; Result: response ┌─statement────────────────────────────────────────────────────────────────┐ │ CREATE TEMPORARY TABLE default.my_table ( `x` UInt32, `y` UInt32 ) ENGINE = Log └──────────────────────────────────────────────────────────────────────────┘

default_view_definer

Type: String
Default: CURRENT_USER
Tier: Production
Allows to set default DEFINER option while creating a view. More about SQL security. The default value is CURRENT_USER.

defer_partition_pruning_after_final

Type: Bool
Default: 1
Tier: Production
When enabled (default), partition pruning is skipped for FINAL queries on tables whose partition-key columns are not part of the sorting key. This is the correctness-safe behavior introduced in 26.3: FINAL may need to deduplicate rows that share a primary key but live in different partitions, and partition pruning would silently exclude such rows from the deduplication input. When disabled, partition pruning is applied even with FINAL, restoring the pre-26.3 behavior. This can be substantially faster for queries with WHERE predicates on the partition column, but is only correct when rows with the same primary key cannot exist in different partitions — e.g. event-log tables whose partition column is set at insert time and never changes. This setting only affects partitioned tables whose partition-key columns are not contained in the sorting key; for other tables partition pruning is always applied. Possible values: - 0 — Apply partition pruning before FINAL (pre-26.3 behavior, faster but unsafe in the general case). - 1 — Defer partition pruning to after FINAL (default, correctness-safe).

delta_lake_enable_engine_predicate

Type: Bool
Default: 1
Tier: Production
Enables delta-kernel internal data pruning.

delta_lake_enable_expression_visitor_logging

Type: Bool
Default: 0
Tier: Production
Enables Test level logs of DeltaLake expression visitor. These logs can be too verbose even for test logging.

delta_lake_insert_max_bytes_in_data_file

Type: NonZeroUInt64
Default: 1073741824
Tier: Production
Defines a bytes limit for a single inserted data file in delta lake.

delta_lake_insert_max_rows_in_data_file

Type: NonZeroUInt64
Default: 1000000
Tier: Production
Defines a rows limit for a single inserted data file in delta lake.

delta_lake_log_metadata

Type: Bool
Default: 0
Tier: Production
Enables logging delta lake metadata files into system table.

delta_lake_reload_schema_for_consistency

Type: Bool
Default: 0
Tier: Production
If enabled, schema is reloaded from the DeltaLake metadata before each query execution to ensure consistency between the schema used during query analysis and the schema used during execution.

delta_lake_snapshot_end_version

Type: Int64
Default: -1
Tier: Production
End version of delta lake snapshot to read. Value -1 means to read latest version (value 0 is a valid snapshot version).

delta_lake_snapshot_start_version

Type: Int64
Default: -1
Tier: Production
Start version of delta lake snapshot to read. Value -1 means to read latest version (value 0 is a valid snapshot version).

delta_lake_snapshot_version

Type: Int64
Default: -1
Tier: Production
Version of delta lake snapshot to read. Value -1 means to read latest version (value 0 is a valid snapshot version).

delta_lake_throw_on_engine_predicate_error

Type: Bool
Default: 0
Tier: Production
Enables throwing an exception if there was an error when analyzing scan predicate in delta-kernel.

describe_compact_output

Type: Bool
Default: 0
Tier: Production
If true, include only column names and types into result of DESCRIBE query

describe_include_subcolumns

Type: Bool
Default: 0
Tier: Production
Enables describing subcolumns for a DESCRIBE query. For example, members of a Tuple or subcolumns of a Map, Nullable or an Array data type. Possible values: - 0 — Subcolumns are not included in DESCRIBE queries. - 1 — Subcolumns are included in DESCRIBE queries. Example See an example for the DESCRIBE statement.

describe_include_virtual_columns

Type: Bool
Default: 0
Tier: Production
If true, virtual columns of table will be included into result of DESCRIBE query

dialect

Type: Dialect
Default: clickhouse
Tier: Production
Which dialect will be used to parse query. Supported values: - clickhouse (default) — standard RawTree SQL. - kusto — Kusto Query Language. Requires the experimental setting allow_experimental_kusto_dialect. - prql — PRQL. Requires the experimental setting allow_experimental_prql_dialect. - polyglot — transpiles SQL from other dialects (MySQL, PostgreSQL, etc.) into RawTree SQL. Requires the experimental setting allow_experimental_polyglot_dialect. - promql — PromQL (Prometheus Query Language) evaluated over a TimeSeries table, configured by the promql_database, promql_table, and promql_evaluation_time settings. - clickhouse_json — instead of SQL text, the query is interpreted as a JSON AST (the output of parseQueryToJSON). The SET query is still recognized in plain form so that the dialect can be switched back. Requires the experimental setting enable_json_ast_dialect.

dictionary_lazy_load

Type: BoolAuto
Default: auto
Tier: Production
Controls loading of a dictionary when specified in the SETTINGS clause of CREATE DICTIONARY: 1 defers loading until first use, 0 loads the dictionary at creation, 'auto' follows the server setting dictionaries_lazy_load. Has no effect when set on a session or query level.

dictionary_use_async_executor

Type: Bool
Default: 0
Tier: Production
Execute a pipeline for reading dictionary source in several threads. It's supported only by dictionaries with local CLICKHOUSE source.

dictionary_validate_primary_key_type

Type: Bool
Default: 0
Tier: Production
Validate primary key type for dictionaries. By default id type for simple layouts will be implicitly converted to UInt64.

discard_query_data

Type: Bool
Default: 0
Tier: Production
If enabled, the server skips sending query result rows to the client. The query is still executed and logged fully on the server, and the client still receives the remaining packets. Used for shadow traffic, benchmarks, and fuzzing. Has no effect for secondary queries. Affects only the native TCP protocol.

distinct_overflow_mode

Type: OverflowMode
Default: throw
Tier: Production
Sets what happens when the amount of data exceeds one of the limits. Possible values: - throw: throw an exception (default). - break: stop executing the query and return the partial result, as if the source data ran out.

distributed_aggregation_memory_efficient

Type: Bool
Default: 1
Tier: Production
Is the memory-saving mode of distributed aggregation enabled.

distributed_background_insert_batch

Type: Bool
Default: 0
Tier: Production
Enables/disables inserted data sending in batches. When batch sending is enabled, the Distributed table engine tries to send multiple files of inserted data in one operation instead of sending them separately. Batch sending improves cluster performance by better-utilizing server and network resources. Possible values: - 1 — Enabled. - 0 — Disabled.

distributed_background_insert_max_sleep_time_ms

Type: Milliseconds
Default: 30000
Tier: Production
Maximum interval for the Distributed table engine to send data. Limits exponential growth of the interval set in the distributed_background_insert_sleep_time_ms setting. Possible values: - A positive integer number of milliseconds.

distributed_background_insert_sleep_time_ms

Type: Milliseconds
Default: 100
Tier: Production
Base interval for the Distributed table engine to send data. The actual interval grows exponentially in the event of errors. Possible values: - A positive integer number of milliseconds.

distributed_background_insert_split_batch_on_failure

Type: Bool
Default: 0
Tier: Production
Enables/disables splitting batches on failures. Sometimes sending particular batch to the remote shard may fail, because of some complex pipeline after (i.e. MATERIALIZED VIEW with GROUP BY) due to Memory limit exceeded or similar errors. In this case, retrying will not help (and this will stuck distributed sends for the table) but sending files from that batch one by one may succeed INSERT. So installing this setting to 1 will disable batching for such batches (i.e. temporary disables distributed_background_insert_batch for failed batches). Possible values: - 1 — Enabled. - 0 — Disabled. :::note This setting also affects broken batches (that may appears because of abnormal server (machine) termination and no fsync_after_insert/fsync_directories for Distributed table engine). ::: :::note You should not rely on automatic batch splitting, since this may hurt performance. :::

distributed_background_insert_timeout

Type: UInt64
Default: 0
Tier: Production
Timeout for insert query into distributed. Setting is used only with insert_distributed_sync enabled. Zero value means no timeout.

distributed_cache_alignment

Type: UInt64
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. A setting for testing purposes, do not change it

distributed_cache_bypass_connection_pool

Type: Bool
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. Allow to bypass distributed cache connection pool

distributed_cache_client_id

Type: String
Default: ``
Tier: Production
Only has an effect in ClickHouse Cloud. A setting used only for CI tests - overrides the registry-configured distributed cache client id for this query's requests when non-empty. Lets tests spread data across a bounded set of client ids while keeping the same data on the same client id. It requires ci_mode to be enabled in the distributed cache client config: when it is not (the default, as in production), a query that routes a read or write through the distributed cache fails with SUPPORT_IS_DISABLED instead of silently falling back to the configured client id. Queries that never reach the distributed cache are unaffected, so the value is ignored there.

distributed_cache_connect_backoff_max_ms

Type: UInt64
Default: 50
Tier: Production
Only has an effect in RawTree Cloud. Maximum backoff milliseconds for distributed cache connection creation.

distributed_cache_connect_backoff_min_ms

Type: UInt64
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. Minimum backoff milliseconds for distributed cache connection creation.

distributed_cache_connect_max_tries

Type: UInt64
Default: 5
Tier: Production
Only has an effect in RawTree Cloud. Number of tries to connect to distributed cache if unsuccessful

distributed_cache_connect_timeout_ms

Type: UInt64
Default: 50
Tier: Production
Only has an effect in RawTree Cloud. Connection timeout when connecting to distributed cache server.

distributed_cache_credentials_refresh_period_seconds

Type: UInt64
Default: 5
Tier: Production
Only has an effect in RawTree Cloud. A period of credentials refresh.

distributed_cache_data_packet_ack_window

Type: UInt64
Default: 5
Tier: Production
Only has an effect in RawTree Cloud. A window for sending ACK for DataPacket sequence in a single distributed cache read request

distributed_cache_discard_connection_if_unread_data

Type: Bool
Default: 1
Tier: Production
Only has an effect in RawTree Cloud. Discard connection if some data is unread.

distributed_cache_fetch_metrics_only_from_current_az

Type: Bool
Default: 1
Tier: Production
Only has an effect in RawTree Cloud. Fetch metrics only from current availability zone in system.distributed_cache_metrics, system.distributed_cache_events

distributed_cache_file_cache_name

Type: String
Default: ``
Tier: Production
Only has an effect in RawTree Cloud. A setting used only for CI tests - filesystem cache name to use on distributed cache.

distributed_cache_log_mode

Type: DistributedCacheLogMode
Default: on_error
Tier: Production
Only has an effect in RawTree Cloud. Mode for writing to system.distributed_cache_log

distributed_cache_max_unacked_inflight_packets

Type: UInt64
Default: 10
Tier: Production
Only has an effect in RawTree Cloud. A maximum number of unacknowledged in-flight packets in a single distributed cache read request

distributed_cache_min_bytes_for_seek

Type: UInt64
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. Minimum number of bytes to do seek in distributed cache.

distributed_cache_min_inflight_bytes_to_discard_connection_on_seek

Type: UInt64
Default: 4194304
Tier: Production
Only has an effect in RawTree Cloud. On a seek away from the current position of an open distributed cache stream, if the estimated number of in-flight bytes that would have to be discarded to keep reusing the connection (via the read range id mechanism) exceeds this value, drop the connection and open a new one instead. This avoids draining a large amount of unused data when seeks are frequent. 0 disables this and always reuses the connection.

distributed_cache_pool_behaviour_on_limit

Type: DistributedCachePoolBehaviourOnLimit
Default: wait
Tier: Production
Only has an effect in RawTree Cloud. Identifies behaviour of distributed cache connection on pool limit reached

distributed_cache_prefer_bigger_buffer_size

Type: Bool
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. Same as filesystem_cache_prefer_bigger_buffer_size, but for distributed cache.

distributed_cache_read_only_from_current_az

Type: Bool
Default: 1
Tier: Production
Only has an effect in RawTree Cloud. Allow to read only from current availability zone. If disabled, will read from all cache servers in all availability zones.

distributed_cache_read_request_max_tries

Type: UInt64
Default: 10
Tier: Production
Only has an effect in RawTree Cloud. Number of tries to do distributed cache read request if unsuccessful

distributed_cache_receive_response_wait_milliseconds

Type: UInt64
Default: 60000
Tier: Production
Only has an effect in RawTree Cloud. Wait time in milliseconds to receive data for request from distributed cache

distributed_cache_receive_timeout_milliseconds

Type: UInt64
Default: 10000
Tier: Production
Only has an effect in RawTree Cloud. Wait time in milliseconds to receive any kind of response from distributed cache Cloud default value: 20000.

distributed_cache_receive_timeout_ms

Type: UInt64
Default: 3000
Tier: Production
Only has an effect in RawTree Cloud. Timeout for receiving data from distributed cache server, in milliseconds. If no bytes were received in this interval, the exception is thrown.

distributed_cache_registry_show_certificate_and_signature

Type: Bool
Default: 0
Tier: Production
Only has an effect in ClickHouse Cloud. Show the certificate and signature columns in the system.distributed_cache_registry table. By default these columns are empty to keep the output compact; enable this setting to inspect them.

distributed_cache_send_timeout_ms

Type: UInt64
Default: 3000
Tier: Production
Only has an effect in RawTree Cloud. Timeout for sending data to istributed cache server, in milliseconds. If a client needs to send some data but is not able to send any bytes in this interval, the exception is thrown.

distributed_cache_tcp_keep_alive_timeout_ms

Type: UInt64
Default: 2900
Tier: Production
Only has an effect in RawTree Cloud. The time in milliseconds the connection to distributed cache server needs to remain idle before TCP starts sending keepalive probes.

distributed_cache_throw_on_error

Type: Bool
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. Rethrow exception happened during communication with distributed cache or exception received from distributed cache. Otherwise fallback to skipping distributed cache on error

distributed_cache_use_clients_cache_for_read

Type: Bool
Default: 1
Tier: Production
Only has an effect in RawTree Cloud. Use clients cache for read requests.

distributed_cache_wait_connection_from_pool_milliseconds

Type: UInt64
Default: 100
Tier: Production
Only has an effect in RawTree Cloud. Wait time in milliseconds to receive connection from connection pool if distributed_cache_pool_behaviour_on_limit is wait

distributed_cache_write_request_max_tries

Type: UInt64
Default: 10
Tier: Production
Only has an effect in RawTree Cloud. Number of tries to do distributed cache write request if unsuccessful

distributed_connections_pool_size

Type: UInt64
Default: 1024
Tier: Production
The maximum number of simultaneous connections with remote servers for distributed processing of all queries to a single Distributed table. We recommend setting a value no less than the number of servers in the cluster.

distributed_ddl_entry_format_version

Type: UInt64
Default: 5
Tier: Production
Compatibility version of distributed DDL (ON CLUSTER) queries Cloud default value: 6.

distributed_ddl_output_mode

Type: DistributedDDLOutputMode
Default: throw
Tier: Production
Sets format of distributed DDL query result. Possible values: - throw — Returns result set with query execution status for all hosts where query is finished. If query has failed on some hosts, then it will rethrow the first exception. If query is not finished yet on some hosts and distributed_ddl_task_timeout exceeded, then it throws TIMEOUT_EXCEEDED exception. - none — Is similar to throw, but distributed DDL query returns no result set. - null_status_on_timeout — Returns NULL as execution status in some rows of result set instead of throwing TIMEOUT_EXCEEDED if query is not finished on the corresponding hosts. - never_throw — Do not throw TIMEOUT_EXCEEDED and do not rethrow exceptions if query has failed on some hosts. - none_only_active - similar to none, but doesn't wait for inactive replicas of the Replicated database. Note: with this mode it's impossible to figure out that the query was not executed on some replica and will be executed in background. - null_status_on_timeout_only_active — similar to null_status_on_timeout, but doesn't wait for inactive replicas of the Replicated database - throw_only_active — similar to throw, but doesn't wait for inactive replicas of the Replicated database Cloud default value: none_only_active.

distributed_ddl_task_timeout

Type: Int64
Default: 180
Tier: Production
Sets timeout for DDL query responses from all hosts in cluster. If a DDL request has not been performed on all hosts, a response will contain a timeout error and a request will be executed in an async mode. Negative value means infinite. Possible values: - Positive integer. - 0 — Async mode. - Negative integer — infinite timeout.

distributed_directory_monitor_batch_inserts

Type: Bool
Default: 0
Tier: Production
Enables/disables inserted data sending in batches. When batch sending is enabled, the Distributed table engine tries to send multiple files of inserted data in one operation instead of sending them separately. Batch sending improves cluster performance by better-utilizing server and network resources. Possible values: - 1 — Enabled. - 0 — Disabled.

distributed_directory_monitor_max_sleep_time_ms

Type: Milliseconds
Default: 30000
Tier: Production
Maximum interval for the Distributed table engine to send data. Limits exponential growth of the interval set in the distributed_background_insert_sleep_time_ms setting. Possible values: - A positive integer number of milliseconds.

distributed_directory_monitor_sleep_time_ms

Type: Milliseconds
Default: 100
Tier: Production
Base interval for the Distributed table engine to send data. The actual interval grows exponentially in the event of errors. Possible values: - A positive integer number of milliseconds.

distributed_directory_monitor_split_batch_on_failure

Type: Bool
Default: 0
Tier: Production
Enables/disables splitting batches on failures. Sometimes sending particular batch to the remote shard may fail, because of some complex pipeline after (i.e. MATERIALIZED VIEW with GROUP BY) due to Memory limit exceeded or similar errors. In this case, retrying will not help (and this will stuck distributed sends for the table) but sending files from that batch one by one may succeed INSERT. So installing this setting to 1 will disable batching for such batches (i.e. temporary disables distributed_background_insert_batch for failed batches). Possible values: - 1 — Enabled. - 0 — Disabled. :::note This setting also affects broken batches (that may appears because of abnormal server (machine) termination and no fsync_after_insert/fsync_directories for Distributed table engine). ::: :::note You should not rely on automatic batch splitting, since this may hurt performance. :::

distributed_foreground_insert

Type: Bool
Default: 0
Tier: Production
Enables or disables synchronous data insertion into a Distributed table. By default, when inserting data into a Distributed table, the RawTree server sends data to cluster nodes in background mode. When distributed_foreground_insert=1, the data is processed synchronously, and the INSERT operation succeeds only after all the data is saved on all shards (at least one replica for each shard if internal_replication is true). Possible values: - 0 — Data is inserted in background mode. - 1 — Data is inserted in synchronous mode. Cloud default value: 1. See Also - Distributed Table Engine - Managing Distributed Tables

distributed_group_by_no_merge

Type: UInt64
Default: 0
Tier: Production
Do not merge aggregation states from different servers for distributed query processing, you can use this in case it is for certain that there are different keys on different shards Possible values: - 0 — Disabled (final query processing is done on the initiator node). - 1 - Do not merge aggregation states from different servers for distributed query processing (query completely processed on the shard, initiator only proxy the data), can be used in case it is for certain that there are different keys on different shards. - 2 - Same as 1 but applies ORDER BY and LIMIT (it is not possible when the query processed completely on the remote node, like for distributed_group_by_no_merge=1) on the initiator (can be used for queries with ORDER BY and/or LIMIT). Example sql SELECT * FROM remote('127.0.0.{2,3}', system.one) GROUP BY dummy LIMIT 1 SETTINGS distributed_group_by_no_merge = 1 FORMAT PrettyCompactMonoBlock ┌─dummy─┐ │ 0 │ │ 0 │ └───────┘ sql SELECT * FROM remote('127.0.0.{2,3}', system.one) GROUP BY dummy LIMIT 1 SETTINGS distributed_group_by_no_merge = 2 FORMAT PrettyCompactMonoBlock ┌─dummy─┐ │ 0 │ └───────┘

distributed_index_analysis

Type: Bool
Default: 0
Tier: Experimental
Index analysis will be distributed across replicas. Beneficial for shared storage and huge amount of data in cluster. Uses replicas from cluster_for_parallel_replicas. See also - distributed_index_analysis_for_non_shared_merge_tree - distributed_index_analysis_min_parts_to_activate - distributed_index_analysis_min_indexes_bytes_to_activate

distributed_index_analysis_for_non_shared_merge_tree

Type: Bool
Default: 0
Tier: Production
Enable distributed index analysis even for non SharedMergeTree (cloud only engine).

distributed_index_analysis_only_on_coordinator

Type: Bool
Default: 0
Tier: Production
If enabled, distributed index analysis runs only on the coordinator. This prevents O(N^2) spawned queries when the predicate contains subqueries (e.g., IN (SELECT ...)), because each follower replica would otherwise independently trigger its own distributed index analysis, but makes distributed index analysis less efficient if large tables are used in the subqueries.

distributed_insert_skip_read_only_replicas

Type: Bool
Default: 0
Tier: Production
Enables skipping read-only replicas for INSERT queries into Distributed. Possible values: - 0 — INSERT was as usual, if it will go to read-only replica it will fail - 1 — Initiator will skip read-only replicas before sending data to shards.

distributed_plan_default_reader_bucket_count

Type: NonZeroUInt64
Default: 8
Tier: Experimental
Default number of tasks for parallel reading in distributed query. Tasks are spread across between replicas. Used by the rule-based distributed planner. The cost-based optimizer chooses the read fan-out by estimated cost and does not use this setting.

distributed_plan_default_shuffle_join_bucket_count

Type: NonZeroUInt64
Default: 8
Tier: Experimental
Default number of buckets for distributed shuffle-hash-join. Used by the rule-based distributed planner. The cost-based optimizer chooses the fan-out by estimated cost and does not use this setting.

distributed_plan_execute_locally

Type: Bool
Default: 0
Tier: Experimental
Run all tasks of a distributed query plan locally. Useful for testing and debugging.

distributed_plan_force_exchange_kind

Type: String
Default: ``
Tier: Experimental
Force specified kind of Exchange operators between distributed query stages. Possible values: - '' - do not force any kind of Exchange operators, let the optimizer choose, - 'Persisted' - use temporary files in object storage, - 'Streaming' - stream exchange data over network.

distributed_plan_force_shuffle_aggregation

Type: Bool
Default: 0
Tier: Experimental
Use Shuffle aggregation strategy instead of PartialAggregation + Merge in distributed query plan. Ignored where the Shuffle strategy cannot produce a correct result, for example for GROUPING SETS or when the aggregation must produce results in bucket order.

distributed_plan_max_rows_to_broadcast

Type: UInt64
Default: 20000
Tier: Experimental
Maximum rows to use broadcast join instead of shuffle join in distributed query plan. A heuristic for the rule-based distributed planner. When the cost-based optimizer is enabled, the broadcast-vs-shuffle choice is made by estimated cost and this setting has no effect.

distributed_plan_optimize_exchanges

Type: Bool
Default: 1
Tier: Production
Removes unnecessary exchanges in distributed query plan. Disable it for debugging.

distributed_plan_prefer_replicas_over_workers

Type: Bool
Default: 0
Tier: Experimental
Serialize the distributed query plan for execution at replicas.

distributed_plan_workers_num

Type: UInt64
Default: 0
Tier: Experimental
How many stateless workers will be used to execute this query. Zero disables stateless-worker leasing for distributed plans.

distributed_plan_workers_provisioning_timeout_ms

Type: UInt64
Default: 10000
Tier: Experimental
Total wall-clock time, in milliseconds, a query may spend provisioning stateless workers before execution: leasing them from the discovery service and verifying they are reachable. The query blocks up to this budget for the leased workers to become ready; when it elapses the query proceeds with the workers verified so far, or fails if none became available. Zero waits only for the initial lease-and-verify pass (no retries).

distributed_product_mode

Type: DistributedProductMode
Default: deny
Tier: Production
Changes the behaviour of distributed subqueries. RawTree applies this setting when the query contains the product of distributed tables, i.e. when the query for a distributed table contains a non-GLOBAL subquery for the distributed table. Restrictions: - Only applied for IN and JOIN subqueries. - Only if the FROM section uses a distributed table containing more than one shard. - If the subquery concerns a distributed table containing more than one shard. - Not used for a table-valued remote function. Possible values: - deny — Default value. Prohibits using these types of subqueries (returns the "Double-distributed in/JOIN subqueries is denied" exception). - local — Replaces the database and table in the subquery with local ones for the destination server (shard), leaving the normal IN/JOIN. - global — Replaces the IN/JOIN query with GLOBAL IN/GLOBAL JOIN. - allow — Allows the use of these types of subqueries.

distributed_push_down_limit

Type: UInt64
Default: 1
Tier: Production
Enables or disables LIMIT applying on each shard separately. This will allow to avoid: - Sending extra rows over network; - Processing rows behind the limit on the initiator. Starting from 21.9 version you cannot get inaccurate results anymore, since distributed_push_down_limit changes query execution only if at least one of the conditions met: - distributed_group_by_no_merge > 0. - Query does not have GROUP BY/DISTINCT/LIMIT BY, but it has ORDER BY/LIMIT. - Query has GROUP BY/DISTINCT/LIMIT BY with ORDER BY/LIMIT and: - optimize_skip_unused_shards is enabled. - optimize_distributed_group_by_sharding_key is enabled. Possible values: - 0 — Disabled. - 1 — Enabled. See also: - distributed_group_by_no_merge - optimize_skip_unused_shards - optimize_distributed_group_by_sharding_key

distributed_replica_error_cap

Type: UInt64
Default: 1000
Tier: Production

• Type: unsigned int - Default value: 1000 The error count of each replica is capped at this value, preventing a single replica from accumulating too many errors. See also: - load_balancing - Table engine Distributed - distributed_replica_error_half_life - distributed_replica_max_ignored_errors

distributed_replica_error_half_life

Type: Seconds
Default: 60
Tier: Production

• Type: seconds - Default value: 60 seconds Controls how fast errors in distributed tables are zeroed. If a replica is unavailable for some time, accumulates 5 errors, and distributed_replica_error_half_life is set to 1 second, then the replica is considered normal 3 seconds after the last error. See also: - load_balancing - Table engine Distributed - distributed_replica_error_cap - distributed_replica_max_ignored_errors

distributed_replica_max_ignored_errors

Type: UInt64
Default: 0
Tier: Production

• Type: unsigned int - Default value: 0 The number of errors that will be ignored while choosing replicas (according to load_balancing algorithm). See also: - load_balancing - Table engine Distributed - distributed_replica_error_cap - distributed_replica_error_half_life

do_not_merge_across_partitions_select_final

Type: Bool
Default: 0
Tier: Production
Improve FINAL queries by avoiding merges across different partitions. When enabled, during SELECT FINAL queries, parts from different partitions will not be merged together. Instead, merging will only occur within each partition separately. This can significantly improve query performance when working with partitioned tables.

dynamic_disk_allow_from_env

Type: Bool
Default: 0
Tier: Production
Allow using from_env substitutions in the dynamic disk configuration (i.e. in the disk() function arguments). Disabled by default to prevent users from reading arbitrary environment variables when defining table storage.

dynamic_disk_allow_from_zk

Type: Bool
Default: 0
Tier: Production
Allow using from_zk substitutions in the dynamic disk configuration (i.e. in the disk() function arguments). Disabled by default.

dynamic_disk_allow_include

Type: Bool
Default: 0
Tier: Production
Allow using include in the dynamic disk configuration (i.e. in the disk() function arguments). Disabled by default.

dynamic_throw_on_type_mismatch

Type: Bool
Default: 0
Tier: Production
When applying a function to a Dynamic column using the default implementation, controls what happens for rows whose actual type is incompatible with the function: - true — throw an exception. - false (default) — return NULL for those rows (or the function's default result for incompatible types) instead.

empty_result_for_aggregation_by_constant_keys_on_empty_set

Type: Bool
Default: 1
Tier: Production
Return empty result when aggregating by constant keys on empty set.

empty_result_for_aggregation_by_empty_set

Type: Bool
Default: 0
Tier: Production
Return empty result when aggregating without keys on empty set.

enable_adaptive_aggregator

Type: Bool
Default: 1
Tier: Production
Enables the adaptive GROUP BY algorithm: every thread aggregates into its local hash table until it reaches adaptive_aggregator_freeze_threshold keys (or adaptive_aggregator_freeze_threshold_bytes of memory), then the table freezes, so that rows of already-seen (frequent) keys keep updating it in place, while new (rare) keys are routed by their hash into per-bucket backlogs and aggregated exactly once, inside the bucket-parallel merge. Frequent keys stay in small cache-resident tables, and rare keys are stored and processed once instead of once per thread. The external aggregation settings (max_bytes_before_external_group_by, max_bytes_ratio_before_external_group_by) are honored: past the threshold the backlogs are drained early into the shared table, and if that is not enough to get back under it, the shared table spills to disk through the ordinary external aggregation.

enable_adaptive_memory_spill_scheduler

Type: Bool
Default: 0
Tier: Experimental
Trigger processor to spill data into external storage adpatively. grace join is supported at present.

enable_add_distinct_to_in_subqueries

Type: Bool
Default: 0
Tier: Production
Enable DISTINCT in IN subqueries. This is a trade-off setting: enabling it can greatly reduce the size of temporary tables transferred for distributed IN subqueries and significantly speed up data transfer between shards, by ensuring only unique values are sent. However, enabling this setting adds extra merging effort on each node, as deduplication (DISTINCT) must be performed. Use this setting when network transfer is a bottleneck and the additional merging cost is acceptable.

enable_alp_codec

Type: Bool
Default: 0
Tier: Experimental
Allows using the experimental ALP compression codec.

enable_analyzer

Type: Bool
Default: 1
Tier: Production
Allow the analyzer.

enable_automatic_decision_for_merging_across_partitions_for_final

Type: Bool
Default: 1
Tier: Production
If set, RawTree will automatically enable this optimization when the partition key expression is deterministic and all columns used in the partition key expression are included in the primary key. This automatic derivation ensures that rows with the same primary key values will always belong to the same partition, making it safe to avoid cross-partition merges.

enable_blob_storage_log

Type: Bool
Default: 1
Tier: Production
Write information about blob storage operations to system.blob_storage_log table

enable_blob_storage_log_for_read_operations

Type: Bool
Default: 0
Tier: Production
Write information about blob storage read operations to system.blob_storage_log table. Requires enable_blob_storage_log to be enabled as well.

enable_cascades_optimizer

Type: Bool
Default: 0
Tier: Experimental
Enable the Cascades cost-based optimizer for distributed query plans. Takes effect only together with make_distributed_plan = 1: the setting alone does not change single-node query planning.

enable_early_constant_folding

Type: Bool
Default: 1
Tier: Production
Enable query optimization where we analyze function and subqueries results and rewrite query if there are constants there

enable_extended_results_for_datetime_functions

Type: Bool
Default: 0
Tier: Production
Enables or disables returning results of type Date32 with extended range (compared to type Date) or DateTime64 with extended range (compared to type DateTime). Possible values: - 0 — Functions return Date or DateTime for all types of arguments. - 1 — Functions return Date32 or DateTime64 for Date32 or DateTime64 arguments and Date or DateTime otherwise. The table below shows the behavior of this setting for various date-time functions. | Function | enable_extended_results_for_datetime_functions = 0 | enable_extended_results_for_datetime_functions = 1 | |----------|---------------------------------------------------|---------------------------------------------------| | toStartOfYear | Returns Date or DateTime | Returns Date/DateTime for Date/DateTime input
Returns Date32/DateTime64 for Date32/DateTime64 input | | toStartOfISOYear | Returns Date or DateTime | Returns Date/DateTime for Date/DateTime input
Returns Date32/DateTime64 for Date32/DateTime64 input | | toStartOfQuarter | Returns Date or DateTime | Returns Date/DateTime for Date/DateTime input
Returns Date32/DateTime64 for Date32/DateTime64 input | | toStartOfMonth | Returns Date or DateTime | Returns Date/DateTime for Date/DateTime input
Returns Date32/DateTime64 for Date32/DateTime64 input | | toStartOfWeek | Returns Date or DateTime | Returns Date/DateTime for Date/DateTime input
Returns Date32/DateTime64 for Date32/DateTime64 input | | toLastDayOfWeek | Returns Date or DateTime | Returns Date/DateTime for Date/DateTime input
Returns Date32/DateTime64 for Date32/DateTime64 input | | toLastDayOfMonth | Returns Date or DateTime | Returns Date/DateTime for Date/DateTime input
Returns Date32/DateTime64 for Date32/DateTime64 input | | toMonday | Returns Date or DateTime | Returns Date/DateTime for Date/DateTime input
Returns Date32/DateTime64 for Date32/DateTime64 input | | toStartOfDay | Returns DateTime
Note: Wrong results for values outside 1970-2149 range | Returns DateTime for Date/DateTime input
Returns DateTime64 for Date32/DateTime64 input | | toStartOfHour | Returns DateTime
Note: Wrong results for values outside 1970-2149 range | Returns DateTime for Date/DateTime input
Returns DateTime64 for Date32/DateTime64 input | | toStartOfFifteenMinutes | Returns DateTime
Note: Wrong results for values outside 1970-2149 range | Returns DateTime for Date/DateTime input
Returns DateTime64 for Date32/DateTime64 input | | toStartOfTenMinutes | Returns DateTime
Note: Wrong results for values outside 1970-2149 range | Returns DateTime for Date/DateTime input
Returns DateTime64 for Date32/DateTime64 input | | toStartOfFiveMinutes | Returns DateTime
Note: Wrong results for values outside 1970-2149 range | Returns DateTime for Date/DateTime input
Returns DateTime64 for Date32/DateTime64 input | | toStartOfMinute | Returns DateTime
Note: Wrong results for values outside 1970-2149 range | Returns DateTime for Date/DateTime input
Returns DateTime64 for Date32/DateTime64 input | | timeSlot | Returns DateTime
Note: Wrong results for values outside 1970-2149 range | Returns DateTime for Date/DateTime input
Returns DateTime64 for Date32/DateTime64 input |

enable_filesystem_cache

Type: Bool
Default: 1
Tier: Production
Use cache for remote filesystem. This setting does not turn on/off cache for disks (must be done via disk config), but allows to bypass cache for some queries if intended

enable_filesystem_cache_log

Type: Bool
Default: 0
Tier: Production
Allows to record the filesystem caching log for each query

enable_filesystem_cache_on_write_operations

Type: Bool
Default: 0
Tier: Production
Enables or disables write-through cache. If set to false, the write-through cache is disabled for write operations. If set to true, write-through cache is enabled as long as cache_on_write_operations is turned on in the server config's cache disk configuration section. See "Using local cache" for more details. Cloud default value: 1.

enable_filesystem_read_prefetches_log

Type: Bool
Default: 0
Tier: Production
Log to system.filesystem prefetch_log during query. Should be used only for testing or debugging, not recommended to be turned on by default

enable_full_text_index

Type: Bool
Default: 1
Tier: Production
If set to true, allow using the text index.

enable_function_early_short_circuit

Type: Bool
Default: 0
Tier: Production
Enable early short-circuit constant folding for and and or during query analysis. When enabled, eligible dead scalar-subquery branches are analyzed to preserve their types and validate query semantics, but they are not executed. The optimization falls back to normal analysis when scalar cardinality or runtime values are required.

enable_global_with_statement

Type: Bool
Default: 1
Tier: Production
Propagate WITH statements to UNION queries and all subqueries

enable_group_by_top_k_optimization

Type: Bool
Default: 1
Tier: Production
Enable TopK filtering optimization during aggregation in GROUP BY keys ORDER BY <prefix of keys> LIMIT K queries, and in GROUP BY keys LIMIT K queries without ORDER BY (any K groups are a valid result there, so a sort over all keys is synthesized). When enabled, the aggregator maintains a bounded heap of the top K keys seen so far and skips inserting new rows into the hash table when their grouping key cannot make it into the final result. This avoids aggregating rows that would be discarded by the subsequent ORDER BY ... LIMIT, and when the heap ranks the full GROUP BY key it also prunes evicted groups out of the intermediate hash table, bounding its size by the LIMIT instead of the number of distinct keys. When the ORDER BY covers only a proper prefix of the GROUP BY keys, the ranking cannot identify a full group, so only row skipping applies: the hash table keeps every admitted group and can still grow with the cardinality of the remaining key columns. The optimization is disabled when the requested LIMIT is higher than query_plan_max_limit_for_top_k_optimization or than the hard cap of 100000, because the memory and CPU cost of the heap grows with the requested LIMIT. The optimization is skipped for query shapes where pruning groups could change the result, including WITH TOTALS, HAVING, QUALIFY, window functions, ROLLUP/CUBE/GROUPING SETS, LIMIT WITH TIES, a COLLATE on any of the matched GROUP BY keys (a COLLATE on a later ORDER BY column past the full key prefix cannot affect which groups qualify, so it does not disable the optimization), ORDER BY on an aggregate or on anything that is not a leading prefix of the GROUP BY keys, and when max_rows_to_group_by or exact_rows_before_limit is set. Possible values: - 0 — Disabled. - 1 — Enabled.

enable_hdfs_pread

Type: Bool
Default: 1
Tier: Production
Enable or disables pread for HDFS files. By default, hdfsPread is used. If disabled, hdfsRead and hdfsSeek will be used to read hdfs files.

enable_http_compression

Type: Bool
Default: 1
Tier: Production
Enables or disables data compression in the response to an HTTP request. For more information, read the HTTP interface description. Possible values: - 0 — Disabled. - 1 — Enabled.

enable_identifier_resolve_cache

Type: Bool
Default: 1
Tier: Production
Enable the identifier resolution cache in the query analyzer. The cache shares resolved alias nodes to prevent AST explosion when the same alias is referenced multiple times. Set to false to disable caching if incorrect results are suspected.

enable_job_stack_trace

Type: Bool
Default: 0
Tier: Production
Output stack trace of a job creator when job results in exception. Disabled by default to avoid performance overhead.

enable_join_fixed_hash_table_conversion

Type: Bool
Default: 1
Tier: Production
Enable converting the hash table to a flat array for joins when the key is a single integer with a small value range.

enable_join_runtime_filters

Type: Bool
Default: 1
Tier: Beta
Filter left side by set of JOIN keys collected from the right side at runtime.

enable_join_runtime_filters_index_analysis

Type: Bool
Default: 0
Tier: Experimental
Run a second pass index analysis (via use_skip_indexes_on_data_read) to prune granules on LHS of a join.

enable_join_transitive_predicates

Type: Bool
Default: 1
Tier: Beta
Infer transitive equi-join predicates from existing join conditions. For example, given A.x = B.x and B.x = C.x, a synthetic A.x = C.x predicate is added so the join order optimizer can consider direct (A JOIN C) plans.

enable_json_ast_dialect

Type: Bool
Default: 0
Tier: Experimental
Enable the clickhouse_json value of the dialect setting. When dialect is set to clickhouse_json, queries are interpreted as JSON ASTs (the output of parseQueryToJSON) instead of SQL text. The SET query is still parsed as plain SQL so that the dialect can be switched back. Example: sql SET enable_json_ast_dialect = 1; SET dialect = 'clickhouse_json'; -- Subsequent queries are parsed as JSON ASTs: {"type":"SelectWithUnionQuery", ...}

enable_lazy_columns_replication

Type: Bool
Default: 1
Tier: Production
Enables lazy columns replication in JOIN, ARRAY JOIN and lambda captures of higher-order functions (e.g. arrayMap), it allows to avoid unnecessary copy of the same rows multiple times in memory.

enable_lightweight_delete

Type: Bool
Default: 1
Tier: Production
Enable lightweight DELETE mutations for mergetree tables.

enable_lightweight_update

Type: Bool
Default: 1
Tier: Beta
Allow to use lightweight updates.

enable_materialized_cte

Type: Bool
Default: 0
Tier: Experimental
Enable materialized common table expressions, it will be preferred over enable_global_with_statement

enable_memory_bound_merging_of_aggregation_results

Type: Bool
Default: 1
Tier: Production
Enable memory bound merging strategy for aggregation.

enable_multiple_prewhere_read_steps

Type: Bool
Default: 1
Tier: Production
Move more conditions from WHERE to PREWHERE and do reads from disk and filtering in multiple steps if there are multiple conditions combined with AND

enable_named_columns_in_function_tuple

Type: Bool
Default: 0
Tier: Production
Generate named tuples in function tuple() when all names are unique and can be treated as unquoted identifiers.

enable_nullable_tuple_type

Type: Bool
Default: 0
Tier: Beta
Allows creation of Nullable Tuple columns in tables. This setting does not control whether extracted tuple subcolumns can be Nullable (for example, from Dynamic, Variant, JSON, or Tuple columns). Use allow_nullable_tuple_in_extracted_subcolumns to control whether extracted tuple subcolumns can be Nullable.

enable_optimize_predicate_expression

Type: Bool
Default: 1
Tier: Production
Turns on predicate pushdown in SELECT queries. Predicate pushdown may significantly reduce network traffic for distributed queries. Possible values: - 0 — Disabled. - 1 — Enabled. Usage Consider the following queries: 1. SELECT count() FROM test_table WHERE date = '2018-10-10' 2. SELECT count() FROM (SELECT * FROM test_table) WHERE date = '2018-10-10' If enable_optimize_predicate_expression = 1, then the execution time of these queries is equal because RawTree applies WHERE to the subquery when processing it. If enable_optimize_predicate_expression = 0, then the execution time of the second query is much longer because the WHERE clause applies to all the data after the subquery finishes.

enable_optimize_predicate_expression_to_final_subquery

Type: Bool
Default: 1
Tier: Production
Allow push predicate to final subquery.

enable_order_by_all

Type: Bool
Default: 1
Tier: Production
Enables or disables sorting with ORDER BY ALL syntax, see ORDER BY. Possible values: - 0 — Disable ORDER BY ALL. - 1 — Enable ORDER BY ALL. Example Query: sql CREATE TABLE TAB(C1 Int, C2 Int, ALL Int) ENGINE=Memory(); INSERT INTO TAB VALUES (10, 20, 30), (20, 20, 10), (30, 10, 20); SELECT * FROM TAB ORDER BY ALL; -- returns an error that ALL is ambiguous SELECT * FROM TAB ORDER BY ALL SETTINGS enable_order_by_all = 0; Result: text ┌─C1─┬─C2─┬─ALL─┐ │ 20 │ 20 │ 10 │ │ 30 │ 10 │ 20 │ │ 10 │ 20 │ 30 │ └────┴────┴─────┘

enable_packed_string_keys_in_aggregation

Type: Bool
Default: 1
Tier: Production
Use a hash table keyed by 16-byte packed string references (PackedStringRef) for GROUP BY with a single non-nullable String key. Keys of up to 11 bytes are stored inline in the packed reference; longer keys are referenced in an arena. This is faster for most workloads, but can be slower than the legacy method for GROUP BY with very few distinct keys longer than 11 bytes (most noticeably 12..24 bytes), where the legacy hash table keeps keys inline in the cell while the packed one dereferences the arena pointer on every probe. When disabled, the legacy StringHashTable-based method (the default before 26.8) is used. All servers participating in a distributed query must agree on this value: with distributed_aggregation_memory_efficient, two-level bucket numbers depend on the key hash, which differs between the two methods, so servers disagreeing on this setting may split the same key into different buckets and produce an incorrectly merged result. To guarantee agreement, the initiator always sends its effective value with the secondary queries (even when it comes only from server/profile defaults), overriding the remote servers' own defaults.

enable_parallel_blocks_marshalling

Type: Bool
Default: 1
Tier: Production
Affects only distributed queries. If enabled, blocks will be (de)serialized and (de)compressed on pipeline threads (i.e. with higher parallelism that what we have by default) before/after sending to the initiator.

enable_parallel_replicas

Type: UInt64
Default: 0
Tier: Production
Use up to max_parallel_replicas the number of replicas from each shard for SELECT query execution. Reading is parallelized and coordinated dynamically. 0 - disabled, 1 - enabled, silently disable them in case of failure, 2 - enabled, throw an exception in case of failure

enable_parallel_single_level_merge

Type: Bool
Default: 1
Tier: Production
Parallelize the final merge of the per-thread single-level aggregation hash tables. The key space is split into disjoint partitions by key hash, and each partition is merged independently: the merging thread enumerates all per-thread tables and combines the keys that belong to its partition, so no two threads ever touch the same key. If the setting is turned off, the single-level tables are merged serially on one thread. Aggregation by 8- and 16-bit keys keeps its own range-partitioned parallel merge regardless of this setting.

enable_parsing_to_custom_serialization

Type: Bool
Default: 1
Tier: Production
If true then data can be parsed directly to columns with custom serialization (e.g. Sparse) according to hints for serialization got from the table.

enable_positional_arguments

Type: Bool
Default: 1
Tier: Production
Enables or disables supporting positional arguments for GROUP BY, LIMIT BY, ORDER BY statements. Possible values: - 0 — Positional arguments aren't supported. - 1 — Positional arguments are supported: column numbers can use instead of column names. Example Query: sql CREATE TABLE positional_arguments(one Int, two Int, three Int) ENGINE=Memory(); INSERT INTO positional_arguments VALUES (10, 20, 30), (20, 20, 10), (30, 10, 20); SELECT * FROM positional_arguments ORDER BY 2,3; Result: text ┌─one─┬─two─┬─three─┐ │ 30 │ 10 │ 20 │ │ 20 │ 20 │ 10 │ │ 10 │ 20 │ 30 │ └─────┴─────┴───────┘

enable_positional_arguments_for_projections

Type: Bool
Default: 0
Tier: Production
Enables or disables supporting positional arguments in PROJECTION definitions. See also enable_positional_arguments setting. :::note This is an expert-level setting, and you shouldn't change it if you're just getting started with RawTree. ::: Possible values: - 0 — Positional arguments aren't supported. - 1 — Positional arguments are supported: column numbers can use instead of column names.

enable_producing_buckets_out_of_order_in_aggregation

Type: Bool
Default: 1
Tier: Production
Allow memory-efficient aggregation (see distributed_aggregation_memory_efficient) to produce buckets out of order. It may improve performance when aggregation bucket sizes are skewed by letting a replica to send buckets with higher id-s to the initiator while it is still processing some heavy buckets with lower id-s. The downside is potentially higher memory usage.

enable_quantized_codec

Type: Bool
Default: 0
Tier: Experimental
Allows using the experimental Quantized compression codec.

enable_reads_from_query_cache

Type: Bool
Default: 1
Tier: Production
If turned on, results of SELECT queries are retrieved from the query cache. Possible values: - 0 - Disabled - 1 - Enabled

enable_s3_requests_logging

Type: Bool
Default: 0
Tier: Production
Enable very explicit logging of S3 requests. Makes sense for debug only.

enable_scalar_subquery_optimization

Type: Bool
Default: 1
Tier: Production
If it is set to true, prevent scalar subqueries from (de)serializing large scalar values and possibly avoid running the same subquery more than once.

enable_scopes_for_with_statement

Type: Bool
Default: 1
Tier: Production
If disabled, declarations in parent WITH cluases will behave the same scope as they declared in the current scope. Note that this is a compatibility setting for the analyzer to allow running some invalid queries that old analyzer could execute.

enable_sharding_aggregator

Type: Bool
Default: 0
Tier: Production
Enables sharded GROUP BY optimization that distributes rows across threads by hashing the grouping key, so each thread aggregates a disjoint subset of keys without a merge phase. This is efficient for high-cardinality keys with evenly distributed data, but may suffer from highly skewed key distributions or queries with very few distinct keys. Possible values: - 0 — Sharded aggregation optimization is disabled. - 1 — Sharded aggregation optimization is enabled.

enable_shared_storage_snapshot_in_query

Type: Bool
Default: 1
Tier: Production
If enabled, all subqueries within a single query will share the same StorageSnapshot for each table. This ensures a consistent view of the data across the entire query, even if the same table is accessed multiple times. This is required for queries where internal consistency of data parts is important. Example: sql SELECT count() FROM events WHERE (_part, _part_offset) IN ( SELECT _part, _part_offset FROM events WHERE user_id = 42 ) Without this setting, the outer and inner queries may operate on different data snapshots, leading to incorrect results. Possible values: - 0 - Disabled - 1 - Enabled

enable_sharing_sets_for_mutations

Type: Bool
Default: 1
Tier: Production
Allow sharing set objects build for IN subqueries between different tasks of the same mutation. This reduces memory usage and CPU consumption

enable_software_prefetch_in_aggregation

Type: Bool
Default: 1
Tier: Production
Enable use of software prefetch in aggregation

enable_software_prefetch_in_join

Type: Bool
Default: 1
Tier: Production
Enable use of software prefetch in hash join probe phase to hide memory access latency for large hash tables.

enable_streaming_queries

Type: Bool
Default: 0
Tier: Experimental
Allow SELECT ... FROM t STREAM [CURSOR '{...}'] continuous queries. When off, any table expression using the STREAM modifier is rejected at plan-build time. This is the umbrella gate for the streaming-queries feature; additional capabilities may be gated by their own settings.

enable_sz3_codec

Type: Bool
Default: 0
Tier: Experimental
Allows using the experimental SZ3 compression codec.

enable_time_time64_type

Type: Bool
Default: 1
Tier: Production
Allows creation of Time and Time64 data types.

enable_unaligned_array_join

Type: Bool
Default: 0
Tier: Production
Allow ARRAY JOIN with multiple arrays that have different sizes. When this settings is enabled, arrays will be resized to the longest one.

enable_url_encoding

Type: Bool
Default: 0
Tier: Production
Allows to enable/disable decoding/encoding path in uri in URL engine tables. Disabled by default.

enable_vertical_final

Type: Bool
Default: 1
Tier: Production
If enable, remove duplicated rows during FINAL by marking rows as deleted and filtering them later instead of merging rows

enable_writes_to_query_cache

Type: Bool
Default: 1
Tier: Production
If turned on, results of SELECT queries are stored in the query cache. Possible values: - 0 - Disabled - 1 - Enabled

enable_zxc_codec

Type: Bool
Default: 0
Tier: Experimental
Allows using the experimental ZXC compression codec.

enforce_strict_identifier_format

Type: Bool
Default: 0
Tier: Production
If enabled, only allow identifiers containing alphanumeric characters and underscores.

engine_file_allow_create_multiple_files

Type: Bool
Default: 0
Tier: Production
Enables or disables creating a new file on each insert in file engine tables if the format has the suffix (JSON, ORC, Parquet, etc.). If enabled, on each insert a new file will be created with a name following this pattern: data.Parquet -> data.1.Parquet -> data.2.Parquet, etc. Possible values: - 0 — INSERT query appends new data to the end of the file. - 1 — INSERT query creates a new file.

engine_file_empty_if_not_exists

Type: Bool
Default: 0
Tier: Production
Allows to select data from a file engine table without file. Possible values: - 0 — SELECT throws exception. - 1 — SELECT returns empty result.

engine_file_skip_empty_files

Type: Bool
Default: 0
Tier: Production
Enables or disables skipping empty files in File engine tables. Possible values: - 0 — SELECT throws an exception if empty file is not compatible with requested format. - 1 — SELECT returns empty result for empty file.

engine_file_truncate_on_insert

Type: Bool
Default: 0
Tier: Production
Enables or disables truncate before insert in File engine tables. Possible values: - 0 — INSERT query appends new data to the end of the file. - 1 — INSERT query replaces existing content of the file with the new data.

engine_url_skip_empty_files

Type: Bool
Default: 0
Tier: Production
Enables or disables skipping empty files in URL engine tables. Possible values: - 0 — SELECT throws an exception if empty file is not compatible with requested format. - 1 — SELECT returns empty result for empty file.

errors_output_format

Type: String
Default: CSV
Tier: Production
Method to write Errors to text output.

evaluation_time

Type: FloatAuto
Default: auto
Tier: Experimental
Sets the evaluation time to be used with promql dialect. 'auto' means the current time.

exact_rows_before_limit

Type: Bool
Default: 0
Tier: Production
When enabled, RawTree will provide exact value for rows_before_limit_at_least statistic, but with the cost that the data before limit will have to be read completely

except_default_mode

Type: SetOperationMode
Default: ALL
Tier: Production
Set default mode in EXCEPT query. Possible values: empty string, 'ALL', 'DISTINCT'. If empty, query without mode will throw exception.

exclude_materialize_skip_indexes_on_insert

Type: String
Default: ``
Tier: Production
Excludes specified skip indexes from being built and stored during INSERTs. The excluded skip indexes will still be built and stored during merges or by an explicit MATERIALIZE INDEX query. Has no effect if materialize_skip_indexes_on_insert is false. Example: sql CREATE TABLE tab ( a UInt64, b UInt64, INDEX idx_a a TYPE minmax, INDEX idx_b b TYPE set(3) ) ENGINE = MergeTree ORDER BY tuple(); SET exclude_materialize_skip_indexes_on_insert='idx_a'; -- idx_a will be not be updated upon insert --SET exclude_materialize_skip_indexes_on_insert='idx_a, idx_b'; -- neither index would be updated on insert INSERT INTO tab SELECT number, number / 50 FROM numbers(100); -- only idx_b is updated -- since it is a session setting it can be set on a per-query level INSERT INTO tab SELECT number, number / 50 FROM numbers(100, 100) SETTINGS exclude_materialize_skip_indexes_on_insert='idx_b'; ALTER TABLE tab MATERIALIZE INDEX idx_a; -- this query can be used to explicitly materialize the index SET exclude_materialize_skip_indexes_on_insert = DEFAULT; -- reset setting to default

execute_exists_as_scalar_subquery

Type: Bool
Default: 1
Tier: Production
Execute non-correlated EXISTS subqueries as scalar subqueries. As for scalar subqueries, the cache is used, and the constant folding applies to the result. Cloud default value: 0.

explain_query_plan_default

Type: ExplainQueryPlanDefault
Default: pretty
Tier: Production
Default format used by EXPLAIN PLAN. Possible values: - pretty (default since 26.7) — actions, compact, and pretty default to true, producing a compact, pretty, action-annotated plan. - legacy — pre-26.7 output. Specifying the actions, compact, or pretty options explicitly in the EXPLAIN statement (for example, EXPLAIN actions = 0, compact = 0, pretty = 0 SELECT ...) always overrides this setting. EXPLAIN PLAN with json = 1 or distributed = 1 keeps the legacy (pre-26.7) defaults regardless of this setting, unless actions, compact, or pretty are set explicitly. The pretty output cannot represent JSON results or per-shard distributed plans, so those modes are only rendered correctly in legacy form.

explain_syntax_single_record

Type: Bool
Default: 1
Tier: Production
Return EXPLAIN SYNTAX output as a single record (with embedded newlines) instead of one record per line, so the result is a single, recoverable row (for example, SELECT count() FROM (EXPLAIN SYNTAX ...) returns 1). Specifying the single_record option explicitly in the EXPLAIN SYNTAX statement (for example, EXPLAIN SYNTAX single_record = 0 SELECT ...) always overrides this setting. Set to false to restore the pre-26.8 one-record-per-line output, or set compatibility to any version older than 26.8.

external_storage_connect_timeout_sec

Type: UInt64
Default: 10
Tier: Production
Connect timeout in seconds. Now supported only for MySQL

external_storage_max_read_bytes

Type: UInt64
Default: 0
Tier: Production
Limit maximum number of bytes when table with external engine should flush history data. Now supported only for MySQL table engine, database engine, and dictionary. If equal to 0, this setting is disabled

external_storage_max_read_rows

Type: UInt64
Default: 0
Tier: Production
Limit maximum number of rows when table with external engine should flush history data. Now supported only for MySQL table engine, database engine, and dictionary. If equal to 0, this setting is disabled

external_storage_rw_timeout_sec

Type: UInt64
Default: 300
Tier: Production
Read/write timeout in seconds. Now supported only for MySQL

external_table_functions_use_nulls

Type: Bool
Default: 1
Tier: Production
Defines how mysql, postgresql and odbc table functions use Nullable columns. Possible values: - 0 — The table function explicitly uses Nullable columns. - 1 — The table function implicitly uses Nullable columns. Usage If the setting is set to 0, the table function does not make Nullable columns and inserts default values instead of NULL. This is also applicable for NULL values inside arrays.

external_table_strict_query

Type: Bool
Default: 0
Tier: Production
If it is set to true, transforming expression to local filter is forbidden for queries to external tables.

extract_key_value_pairs_max_pairs_per_row

Type: UInt64
Default: 1000
Tier: Production
Max number of pairs that can be produced by the extractKeyValuePairs function. Used as a safeguard against consuming too much memory.

extract_kvp_max_pairs_per_row

Type: UInt64
Default: 1000
Tier: Production
Max number of pairs that can be produced by the extractKeyValuePairs function. Used as a safeguard against consuming too much memory.

extremes

Type: Bool
Default: 0
Tier: Production
Whether to count extreme values (the minimums and maximums in columns of a query result). Accepts 0 or 1. By default, 0 (disabled). For more information, see the section "Extreme values".

fallback_to_stale_replicas_for_distributed_queries

Type: Bool
Default: 1
Tier: Production
Forces a query to an out-of-date replica if updated data is not available. See Replication. RawTree selects the most relevant from the outdated replicas of the table. Used when performing SELECT from a distributed table that points to replicated tables. By default, 1 (enabled).

file_like_engine_default_partition_strategy

Type: FileLikeEngineDefaultPartitionStrategy
Default: hive
Tier: Production
Default partition strategy for file like engines. Applied only to CREATE queries with a path that has no glob or {_partition_id} placeholder. A path with {_partition_id} always uses wildcard. A path with another glob uses no partition strategy and ignores PARTITION BY. If this setting is wildcard but the path has no {_partition_id}, no partition strategy is used; table engines that can not persist this decision in their engine arguments (e.g. HDFS) reject such a CREATE instead.

filesystem_cache_allow_background_download

Type: Bool
Default: 1
Tier: Production
Allow filesystem cache to enqueue background downloads for data read from remote storage. Disable to keep downloads in the foreground for the current query/session.

filesystem_cache_boundary_alignment

Type: UInt64
Default: 0
Tier: Production
Filesystem cache boundary alignment. For non-disk read (e.g. for cache of remote table engines / table functions) value 0 means no alignment. For disk read (e.g. for MergeTree tables on a disk with cache) value 0 means that boundary_alignment from the cache configuration is used.

filesystem_cache_enable_background_download_during_fetch

Type: Bool
Default: 1
Tier: Production
Only has an effect in RawTree Cloud. Wait time to lock cache for space reservation in filesystem cache

filesystem_cache_enable_background_download_for_metadata_files_in_packed_storage

Type: Bool
Default: 1
Tier: Production
Only has an effect in RawTree Cloud. Wait time to lock cache for space reservation in filesystem cache

filesystem_cache_max_download_size

Type: UInt64
Default: 137438953472
Tier: Production
Max remote filesystem cache size that can be downloaded by a single query

filesystem_cache_name

Type: String
Default: ``
Tier: Production
Filesystem cache name to use for stateless table engines or data lakes

filesystem_cache_prefer_bigger_buffer_size

Type: Bool
Default: 1
Tier: Production
Prefer bigger buffer size if filesystem cache is enabled to avoid writing small file segments which deteriorate cache performance. On the other hand, enabling this setting might increase memory usage.

filesystem_cache_reserve_space_wait_lock_timeout_milliseconds

Type: UInt64
Default: 1000
Tier: Production
Wait time to lock cache for space reservation in filesystem cache

filesystem_cache_segments_batch_size

Type: UInt64
Default: 20
Tier: Production
Limit on size of a single batch of file segments that a read buffer can request from cache. Too low value will lead to excessive requests to cache, too large may slow down eviction from cache

filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit

Type: Bool
Default: 1
Tier: Production
Skip download from remote filesystem if exceeds query cache size

filesystem_cache_verbose_logging

Type: Bool
Default: 0
Tier: Production
Emit TEST-level log messages for every filesystem cache buffer refill (state of the read, remaining size to read, bytes read). Only for debugging: the messages are formatted once per read, so enabling it on a query that does many small cached reads adds a large amount of logging overhead. The messages are only visible when the log level is test anyway (see send_logs_level).

filesystem_cache_wait_for_concurrent_download_timeout_milliseconds

Type: UInt64
Default: 1000
Tier: Production
Maximum time to wait for a file segment which is being downloaded to the filesystem cache by a concurrent query. When the timeout is reached, the read bypasses the filesystem cache for that range and reads directly from remote storage, while the concurrent download continues to fill the cache. Value 0 means do not wait at all: bypass the cache immediately if the needed range is not downloaded yet. Lowering this value bounds the tail latency of cache-hit reads which would otherwise wait for another query's download pace at the cost of additional requests to remote storage.

filesystem_prefetch_max_memory_usage

Type: NonZeroUInt64
Default: 1073741824
Tier: Production
Maximum memory usage for prefetches. Cloud default value: 10% of total memory.

filesystem_prefetch_min_bytes_for_single_read_task

Type: UInt64
Default: 2097152
Tier: Production
Min bytes to read per task.

filesystem_prefetch_step_bytes

Type: UInt64
Default: 0
Tier: Production
Prefetch step in bytes. Zero means auto - approximately the best prefetch step will be auto deduced, but might not be 100% the best. The actual value might be different because of setting filesystem_prefetch_min_bytes_for_single_read_task

filesystem_prefetch_step_marks

Type: UInt64
Default: 0
Tier: Production
Prefetch step in marks. Zero means auto - approximately the best prefetch step will be auto deduced, but might not be 100% the best. The actual value might be different because of setting filesystem_prefetch_min_bytes_for_single_read_task

filesystem_prefetches_limit

Type: UInt64
Default: 200
Tier: Production
Maximum number of prefetches. Zero means unlimited. A setting filesystem_prefetches_max_memory_usage is more recommended if you want to limit the number of prefetches

filter

Type: String
Default: ``
Tier: Production
Adds a WHERE clause to the query as a wrapping subquery. Multiple filters are combined with AND. The HTTP interface allows multiple filter URL parameters which are combined with AND in order, and with the value of this setting. This is a query-construction setting applied by the engine on the parsed query (wrapping it as a derived table), so it composes with the existing query and works on every protocol: it can be supplied via the HTTP URL parameter, an in-query SETTINGS clause, or a user profile. It shapes result-producing SELECT / UNION queries. For a write query (INSERT … SELECT, CREATE … AS SELECT) it takes effect only when the source SELECT carries it in its own SETTINGS clause; a value inherited from a profile or session, or set on the INSERT / CREATE statement itself, does not propagate into the source SELECT — the same non-propagation rule that applies to any other setting. :::danger filter is not an access-control mechanism and must not be used as a substitute for row-level security policies or the additional_table_filters setting. It only adds a WHERE over the wrapping subquery, so the underlying data is still read and processed before the filter is applied — a query can observe the filtered-out rows during processing (for example with throwIf to leak information through the error path). Use row-level security or additional_table_filters when the goal is to restrict which rows a user may access. :::

final

Type: Bool
Default: 0
Tier: Production
Automatically applies FINAL modifier to all tables in a query, to tables where FINAL is applicable, including joined tables and tables in sub-queries, and distributed tables. Possible values: - 0 - disabled - 1 - enabled Example: sql CREATE TABLE test ( key Int64, some String ) ENGINE = ReplacingMergeTree ORDER BY key; INSERT INTO test FORMAT Values (1, 'first'); INSERT INTO test FORMAT Values (1, 'second'); SELECT * FROM test; ┌─key─┬─some───┐ │ 1 │ second │ └─────┴────────┘ ┌─key─┬─some──┐ │ 1 │ first │ └─────┴───────┘ SELECT * FROM test SETTINGS final = 1; ┌─key─┬─some───┐ │ 1 │ second │ └─────┴────────┘ SET final = 1; SELECT * FROM test; ┌─key─┬─some───┐ │ 1 │ second │ └─────┴────────┘

finalize_projection_parts_synchronously

Type: Bool
Default: 0
Tier: Production
When enabled, projection parts are finalized synchronously during INSERT, reducing peak memory usage at the cost of reduced S3 upload parallelism. By default, each projection's output stream is kept alive until the entire part (including all projections) is finalized, which allows overlapping S3 uploads but increases peak memory proportional to the number of projections. This setting only affects the INSERT path; merge and mutation already finalize projections synchronously.

flatten_nested

Type: Bool
Default: 1
Tier: Production
Sets the data format of a nested columns. Possible values: - 1 — Nested column is flattened to separate arrays. - 0 — Nested column stays a single array of tuples. Usage If the setting is set to 0, it is possible to use an arbitrary level of nesting. Examples Query: sql SET flatten_nested = 1; CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple(); SHOW CREATE TABLE t_nest; Result: text ┌─statement───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ CREATE TABLE default.t_nest ( `n.a` Array(UInt32), `n.b` Array(UInt32) ) ENGINE = MergeTree ORDER BY tuple() SETTINGS index_granularity = 8192 │ └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ Query: sql SET flatten_nested = 0; CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple(); SHOW CREATE TABLE t_nest; Result: text ┌─statement──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ CREATE TABLE default.t_nest ( `n` Nested(a UInt32, b UInt32) ) ENGINE = MergeTree ORDER BY tuple() SETTINGS index_granularity = 8192 │ └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

force_aggregate_partitions_independently

Type: Bool
Default: 0
Tier: Production
Force the use of optimization when it is applicable, but heuristics decided not to use it

force_aggregation_in_order

Type: Bool
Default: 0
Tier: Production
The setting is used by the server itself to support distributed queries. Do not change it manually, because it will break normal operations. (Forces use of aggregation in order on remote nodes during distributed aggregation).

force_creating_set_partitions_independently

Type: Bool
Default: 0
Tier: Production
Force per-partition pre-deduplication for IN (subquery) set building when it is applicable, but the partition-skew check (largest partition more than twice the average) decided not to use it. Only bypasses the skew check of allow_creating_set_partitions_independently; the remaining conditions still apply.

force_data_skipping_indices

Type: String
Default: ``
Tier: Production
Disables query execution if passed data skipping indices wasn't used. Consider the following example: sql CREATE TABLE data ( key Int, d1 Int, d1_null Nullable(Int), INDEX d1_idx d1 TYPE minmax GRANULARITY 1, INDEX d1_null_idx assumeNotNull(d1_null) TYPE minmax GRANULARITY 1 ) Engine=MergeTree() ORDER BY key; SELECT * FROM data_01515; SELECT * FROM data_01515 SETTINGS force_data_skipping_indices=''; -- query will produce CANNOT_PARSE_TEXT error. SELECT * FROM data_01515 SETTINGS force_data_skipping_indices='d1_idx'; -- query will produce INDEX_NOT_USED error. SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='d1_idx'; -- Ok. SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`'; -- Ok (example of full featured parser). SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- query will produce INDEX_NOT_USED error, since d1_null_idx is not used. SELECT * FROM data_01515 WHERE d1 = 0 AND assumeNotNull(d1_null) = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- Ok.

force_distinct_partitions_independently

Type: Bool
Default: 0
Tier: Production
Force independent DISTINCT evaluation per partition when it is applicable, but the cost heuristic decided not to use it. Only bypasses the cost heuristic of allow_distinct_partitions_independently; the remaining conditions still apply.

force_grouping_standard_compatibility

Type: Bool
Default: 1
Tier: Production
Make GROUPING function to return 1 when argument is not used as an aggregation key

force_index_by_date

Type: Bool
Default: 0
Tier: Production
Disables query execution if the index can't be used by date. Works with tables in the MergeTree family. If force_index_by_date=1, RawTree checks whether the query has a date key condition that can be used for restricting data ranges. If there is no suitable condition, it throws an exception. However, it does not check whether the condition reduces the amount of data to read. For example, the condition Date != ' 2000-01-01 ' is acceptable even when it matches all the data in the table (i.e., running the query requires a full scan). For more information about ranges of data in MergeTree tables, see MergeTree.

force_optimize_projection

Type: Bool
Default: 0
Tier: Production
Enables or disables the obligatory use of projections in SELECT queries, when projection optimization is enabled (see optimize_use_projections setting). Possible values: - 0 — Projection optimization is not obligatory. - 1 — Projection optimization is obligatory.

force_optimize_projection_name

Type: String
Default: ``
Tier: Production
If it is set to a non-empty string, check that this projection is used in the query at least once. Possible values: - string: name of projection that used in a query

force_optimize_skip_unused_shards

Type: UInt64
Default: 0
Tier: Production
Enables or disables query execution if optimize_skip_unused_shards is enabled and skipping of unused shards is not possible. If the skipping is not possible and the setting is enabled, an exception will be thrown. Possible values: - 0 — Disabled. RawTree does not throw an exception. - 1 — Enabled. Query execution is disabled only if the table has a sharding key. - 2 — Enabled. Query execution is disabled regardless of whether a sharding key is defined for the table.

force_optimize_skip_unused_shards_nesting

Type: UInt64
Default: 0
Tier: Production
Controls force_optimize_skip_unused_shards (hence still requires force_optimize_skip_unused_shards) depends on the nesting level of the distributed query (case when you have Distributed table that look into another Distributed table). Possible values: - 0 - Disabled, force_optimize_skip_unused_shards works always. - 1 — Enables force_optimize_skip_unused_shards only for the first level. - 2 — Enables force_optimize_skip_unused_shards up to the second level.

force_primary_key

Type: Bool
Default: 0
Tier: Production
Disables query execution if indexing by the primary key is not possible. Works with tables in the MergeTree family. If force_primary_key=1, RawTree checks to see if the query has a primary key condition that can be used for restricting data ranges. If there is no suitable condition, it throws an exception. However, it does not check whether the condition reduces the amount of data to read. For more information about data ranges in MergeTree tables, see MergeTree.

force_read_through_distributed_cache

Type: BoolAuto
Default: auto
Tier: Production
Only has an effect in RawTree Cloud. Overrides the server setting enable_read_through_distributed_cache for a single query. auto (the default) means to follow the server setting.

force_remove_data_recursively_on_drop

Type: Bool
Default: 0
Tier: Production
Recursively remove data on DROP query. Avoids 'Directory not empty' error, but may silently remove detached data

force_window_partitions_independently

Type: Bool
Default: 0
Tier: Production
Force independent evaluation of window functions per partition when it is applicable, but the cost heuristic decided not to use it. Only bypasses the cost heuristic of allow_window_partitions_independently; the remaining conditions still apply.

force_write_through_distributed_cache

Type: BoolAuto
Default: auto
Tier: Production
Only has an effect in RawTree Cloud. Overrides the server setting enable_write_through_distributed_cache for a single query. auto (the default) means to follow the server setting.

format

Type: String
Default: ``
Tier: Production
Overrides the FORMAT of the query for both input and output. Wins over the format specified in the query and in the file extension. The more specific input_format and output_format settings take precedence over this generic format setting for their respective direction.

format_avro_schema_registry_connection_timeout

Type: UInt64
Default: 1
Tier: Production
For AvroConfluent format: connection timeout in seconds for the Confluent Schema Registry HTTP client. Used by both schema fetch and schema registration. Must be greater than 0 and less than 600 (10 minutes).

format_avro_schema_registry_max_retries

Type: UInt64
Default: 5
Tier: Production
For AvroConfluent format: maximum number of retries for transient failures when communicating with the Confluent Schema Registry (transport timeouts, connection refused, DNS errors, HTTP 5xx/408/429). Set to 0 to disable retries. The maximum allowed value is 20. Schema validation errors (HTTP 409, malformed Avro JSON) are not retried.

format_avro_schema_registry_receive_timeout

Type: UInt64
Default: 1
Tier: Production
For AvroConfluent format: receive timeout in seconds for the Confluent Schema Registry HTTP client. Used by both schema fetch and schema registration. Must be greater than 0 and less than 600 (10 minutes).

format_avro_schema_registry_retry_initial_backoff_ms

Type: UInt64
Default: 100
Tier: Production
For AvroConfluent format: initial backoff in milliseconds before retrying a failed Confluent Schema Registry request. The backoff doubles on each subsequent retry, capped at 10 seconds. Must be greater than 0 and less than or equal to 60000.

format_avro_schema_registry_send_timeout

Type: UInt64
Default: 1
Tier: Production
For AvroConfluent format: send timeout in seconds for the Confluent Schema Registry HTTP client. Used by both schema fetch and schema registration. Must be greater than 0 and less than 600 (10 minutes).

format_avro_schema_registry_url

Type: URI
Default: ``
Tier: Production
For AvroConfluent format: Confluent Schema Registry URL.

format_binary_max_array_size

Type: UInt64
Default: 1073741824
Tier: Production
The maximum allowed size for Array in RowBinary format. It prevents allocating large amount of memory in case of corrupted data. 0 means there is no limit

format_binary_max_object_size

Type: UInt64
Default: 100000
Tier: Production
The maximum allowed number of paths in a single Object for JSON type RowBinary format. It prevents allocating large amount of memory in case of corrupted data. 0 means there is no limit

format_binary_max_string_size

Type: UInt64
Default: 1073741824
Tier: Production
The maximum allowed size for String in RowBinary format. It prevents allocating large amount of memory in case of corrupted data. 0 means there is no limit

format_capn_proto_enum_comparising_mode

Type: CapnProtoEnumComparingMode
Default: by_values
Tier: Production
How to map RawTree Enum and CapnProto Enum

format_capn_proto_max_message_size

Type: UInt64
Default: 1073741824
Tier: Production
Maximum size of a single CapnProto message in bytes. This protects against malformed or corrupted data causing excessive memory allocation. Default is 1 GiB.

format_capn_proto_use_autogenerated_schema

Type: Bool
Default: 1
Tier: Production
Use autogenerated CapnProto schema when format_schema is not set

format_csv_allow_double_quotes

Type: Bool
Default: 1
Tier: Production
If it is set to true, allow strings in double quotes.

format_csv_allow_single_quotes

Type: Bool
Default: 0
Tier: Production
If it is set to true, allow strings in single quotes.

format_csv_delimiter

Type: Char
Default: ,
Tier: Production
The character to be considered as a delimiter in CSV data. If setting with a string, a string has to have a length of 1.

format_csv_null_representation

Type: String
Default: \N
Tier: Production
Custom NULL representation in CSV format

format_custom_escaping_rule

Type: EscapingRule
Default: Escaped
Tier: Production
Field escaping rule (for CustomSeparated format)

format_custom_field_delimiter

Type: String
Default: ``
Tier: Production
Delimiter between fields (for CustomSeparated format)

format_custom_result_after_delimiter

Type: String
Default: ``
Tier: Production
Suffix after result set (for CustomSeparated format)

format_custom_result_before_delimiter

Type: String
Default: ``
Tier: Production
Prefix before result set (for CustomSeparated format)

format_custom_row_after_delimiter

Type: String
Default: ``
Tier: Production
Delimiter after field of the last column (for CustomSeparated format)

format_custom_row_before_delimiter

Type: String
Default: ``
Tier: Production
Delimiter before field of the first column (for CustomSeparated format)

format_custom_row_between_delimiter

Type: String
Default: ``
Tier: Production
Delimiter between rows (for CustomSeparated format)

format_display_secrets_in_show_and_select

Type: Bool
Default: 0
Tier: Production
Enables or disables showing secrets in SHOW and SELECT queries for tables, databases, table functions, and dictionaries. It also controls whether secrets embedded in setting values (such as a password in format_avro_schema_registry_url) are shown in system.settings, system.processes, system.settings_profile_elements and in SHOW CREATE USER / SHOW CREATE SETTINGS PROFILE. User wishing to see secrets must also have display_secrets_in_show_and_select server setting turned on and a displaySecretsInShowAndSelect privilege. Possible values: - 0 — Disabled. - 1 — Enabled.

format_geojson_validate_geometry

Type: Bool
Default: 1
Tier: Production
Controls whether the GeoJSON format enforces RFC 7946 geometry validity, in both directions. When enabled (default), a geometry that violates the GeoJSON shape rules is rejected: a LineString (or a line of a MultiLineString) with fewer than two points; a Polygon or MultiPolygon ring with fewer than four points or whose first and last points differ (an unclosed ring); or an empty MultiLineString, Polygon, or MultiPolygon. This applies both when reading (such a document is rejected) and when writing (such a ClickHouse value is rejected instead of producing a document the input format would reject). When disabled, these shape rules are not enforced: such geometries are read as-is and written as-is, so degenerate geometries round-trip, but a written document may not be valid GeoJSON. The validation is structural only: it checks point counts and ring closure. It does not inspect the geometric correctness of a shape — ring orientation (the right-hand rule / winding order) is not enforced, and structurally valid but geometrically degenerate geometries are accepted, such as a zero-area polygon, a self-intersecting ring, or a polygon whose holes lie outside its outer ring. Non-finite coordinates (NaN, Inf) are always rejected regardless of this setting, because they cannot be represented as JSON numbers.

format_hive_text_rows_delimiter

Type: Char
Default: ``
Tier: Production
Delimiter at the end of each row in the Hive Text output format

format_json_object_each_row_column_for_object_name

Type: String
Default: ``
Tier: Production
The name of column that will be used for storing/writing object names in JSONObjectEachRow format. Column type should be String. If value is empty, default names row_{i}will be used for object names.

format_protobuf_use_autogenerated_schema

Type: Bool
Default: 1
Tier: Production
Use autogenerated Protobuf when format_schema is not set

format_regexp

Type: String
Default: ``
Tier: Production
Regular expression (for Regexp format)

format_regexp_escaping_rule

Type: EscapingRule
Default: Raw
Tier: Production
Field escaping rule (for Regexp format)

format_regexp_skip_unmatched

Type: Bool
Default: 0
Tier: Production
Skip lines unmatched by regular expression (for Regexp format)

format_schema

Type: String
Default: ``
Tier: Production
This parameter is useful when you are using formats that require a schema definition, such as Cap'n Proto or Protobuf. The value depends on the format.

format_schema_message_name

Type: String
Default: ``
Tier: Production
Define the name of the required message in the schema defined in format_schema. To maintain compatibility with the legacy format_schema format (file_name:message_name): - If format_schema_message_name is not specified, the message name is inferred from the message_name part of the legacy format_schema value. - If format_schema_message_name is specified while using the legacy format, an error will be raised.

format_schema_source

Type: String
Default: file
Tier: Production
Define the source of format_schema. Possible values: - 'file' (default): The format_schema is the name of a schema file located in the format_schemas directory. - 'string': The format_schema is the literal content of the schema. - 'query': The format_schema is a query to retrieve the schema. When format_schema_source is set to 'query', the following conditions apply: - The query must return exactly one value: a single row with a single string column. - The result of the query is treated as the schema content. - This result is cached locally in the format_schemas directory. - You can clear the local cache using the command: SYSTEM DROP FORMAT SCHEMA CACHE FOR Files. - Once cached, identical queries from the same user are not executed to fetch the schema again until the cache is explicitly cleared - In addition to local cache files, Protobuf messages are also cached in memory. Even after clearing the local cache files, the in-memory cache must be cleared using SYSTEM DROP FORMAT SCHEMA CACHE [FOR Protobuf] to fully refresh the schema. - Run the query SYSTEM DROP FORMAT SCHEMA CACHE to clear the cache for both cache files and Protobuf messages schemas at once. - The query is executed on behalf of the user running it, so it is subject to that user's access rights, and its cached result is reused only for the same user. It cannot be executed where there is no user: in a background task, such as a streaming engine consumer, or when INSERT data is parsed on the client side. Use format_schema_source set to file or string there.

format_template_resultset

Type: String
Default: ``
Tier: Production
Path to file which contains format string for result set (for Template format)

format_template_resultset_format

Type: String
Default: ``
Tier: Production
Format string for result set (for Template format)

format_template_row

Type: String
Default: ``
Tier: Production
Path to file which contains format string for rows (for Template format)

format_template_row_format

Type: String
Default: ``
Tier: Production
Format string for rows (for Template format)

format_template_rows_between_delimiter

Type: String
Default: ``
Tier: Production
Delimiter between rows (for Template format)

format_tsv_null_representation

Type: String
Default: \N
Tier: Production
Custom NULL representation in TSV format

formatdatetime_e_with_space_padding

Type: Bool
Default: 0
Tier: Production
Formatter '%e' in function 'formatDateTime' prints single-digit days with a leading space, e.g. ' 2' instead of '2'.

formatdatetime_f_prints_scale_number_of_digits

Type: Bool
Default: 0
Tier: Production
Formatter '%f' in function 'formatDateTime' prints only the scale amount of digits for a DateTime64 instead of fixed 6 digits.

formatdatetime_f_prints_single_zero

Type: Bool
Default: 0
Tier: Production
Formatter '%f' in function 'formatDateTime' prints a single zero instead of six zeros if the formatted value has no fractional seconds.

formatdatetime_format_without_leading_zeros

Type: Bool
Default: 0
Tier: Production
Formatters '%c', '%l' and '%k' in function 'formatDateTime' print months and hours without leading zeros.

formatdatetime_parsedatetime_m_is_month_name

Type: Bool
Default: 1
Tier: Production
Formatter '%M' in functions 'formatDateTime' and 'parseDateTime' print/parse the month name instead of minutes.

framing_output_format

Type: String
Default: None
Tier: Beta
Allows to multiplex different parts of the query response in a single stream: chunks of data, totals and extremes, progress packets, profile events (metrics), and server logs - everything that the native protocol supports. Framing formats are independent of output formats: they encapsulate bytes produced by any output format, by separating and potentially encoding these chunks of bytes. The concatenation of the payloads of all data, totals and extremes packets is exactly what the output format would have produced without framing. Auxiliary packets (progress, logs, profile events, exceptions) are represented as JSON. One deliberate exception: an output format that drops totals and extremes in its plain output because it cannot represent them (the JSONCompactEachRow family) does emit them under framing, into the totals and extremes packets. For such formats the concatenation of the data packets alone is exactly the unframed output, and the totals and extremes packets carry additional rows that the unframed output does not contain. Server logs are included if the send_logs_level setting is set, and profile events are included if the send_profile_events setting is enabled (they are sent at most once in interactive_delay microseconds, and progress packets are also throttled by interactive_delay). A successful stream ends with a final progress packet carrying the final counters (result_rows, result_bytes, memory_usage), written after the trailing log and profile_events packets emitted by the query-finish logging, like the final progress packet of the native protocol. On failure, the exception packet is the last packet instead - with one exception: when the failure happens after part of the packet stream has already been produced into the response and can no longer be discarded (a packet write fails partway through, the delivery of the exception packet itself fails, or the response stream fails while being flushed or closed), the framing fails closed - the stream is terminated without a terminal exception packet, and the client observes a truncated response and an aborted HTTP connection instead of a parseable terminal packet. Nothing is ever appended after a partial packet stream, so a plain HTTP error body is never mixed into it. Anything a query enables only through its own SETTINGS clause - a framing format, send_logs_level, or send_profile_events - is not known until the query has been parsed, so the corresponding logs and profile events are captured only from query execution onwards. The logs and profile events of the parse, plan, and analysis phase are captured only when the setting comes from the session or the URL. For example, a query that fails during analysis (such as a reference to an unknown table) and enables send_logs_level only in its SETTINGS clause delivers just the exception packet, not the analysis-phase logs; set send_logs_level on the session or the URL to capture those. The same late-discovery caveat applies to send_logs_source_regexp: the log queue filters entries by source at the moment each entry is captured, so a regexp set only in the query's own SETTINGS clause takes effect from query execution onwards. The log packets of the parse, plan, and analysis phase are filtered by the session or URL value of the setting (they are unfiltered when it is not set there), so they may include sources that do not match the query-level regexp; conversely, entries dropped by a narrower session or URL regexp are not recovered by a broader query-level one. Set send_logs_source_regexp on the session or the URL to filter the whole query lifecycle. The setting currently applies to the HTTP protocol and is ignored for other interfaces. Possible values: - None - transparently routes everything applicable (data, totals, extremes, progress) to the output format, and ignores everything that is not applicable (metrics, logs), so everything works as it is by default. - EventStream - frames packets as HTTP server-sent events (text/event-stream). Every packet is sent as an event with the corresponding name: data, totals, extremes, progress, log, profile_events, exception. Progress and other auxiliary packets are sent as JSON. Because server-sent events are a text protocol that treats line breaks (including carriage returns, \r) as delimiters, a block of formatted data is base64-encoded into a single data field of the event, which decodes to the fully formatted payload with all of its newlines; the Content-Type carries a payload=base64 parameter to say so. Any output format can be carried this way byte-exactly, text and binary alike. - JSONEachPacketBase64 - every packet is a JSON object on a separate line, and the formatted data is base64-encoded, e.g. {"packet":"data","data":"eyJ4IjoxfQo="}. Suitable for binary output formats. - JSONEachPacketString - every packet is a JSON object on a separate line, and the formatted data is put into a string, e.g. {"packet":"data","data":"{\"x\":1}\n"}. JSONEachPacketString puts the payload bytes into a JSON string without validating or re-encoding them. String and FixedString columns can hold arbitrary bytes, so text output formats (such as JSONEachRow, TSV, or CSV) may emit invalid UTF-8 for such values - just as RawTree's own JSONEachRow does with the default output_format_json_validate_utf8 = 0 - and then the resulting NDJSON stream is not guaranteed to be valid UTF-8. Use JSONEachPacketBase64 for byte-exact transport of arbitrary bytes. Example: bash curl "http://localhost:8123/?framing_output_format=JSONEachPacketString" -d "SELECT number FROM numbers(3) FORMAT JSONEachRow" Result: text {"packet":"data","data":"{\"number\":\"0\"}\n{\"number\":\"1\"}\n{\"number\":\"2\"}\n"} {"packet":"profile_events","profile_events":[{"host_name":"localhost","current_time":"2026-07-11 00:00:00","thread_id":"0","type":"increment","name":"SelectedRows","value":"3"}]} {"packet":"progress","progress":{"read_rows":"3","read_bytes":"24","total_rows_to_read":"3","result_rows":"3","result_bytes":"24","elapsed_ns":"1265958"}}

fsync_metadata

Type: Bool
Default: 1
Tier: Production
Enables or disables fsync when writing .sql files. Enabled by default. It makes sense to disable it if the server has millions of tiny tables that are constantly being created and destroyed.

function_base58_max_input_size

Type: UInt64
Default: 10000
Tier: Production
Maximum size, in bytes, of a single input value for the functions base58Encode, base58Decode and tryBase58Decode. The generic base58 conversion is quadratic in the input length, so a single large value can run for a very long time. base58 is meant for short data (keys, hashes, addresses), so the default of 10 KB is a generous safety threshold. base58Encode and base58Decode throw TOO_LARGE_STRING_SIZE for larger inputs, while tryBase58Decode returns an empty string. A value of 0 disables the limit (the behavior before this setting was introduced). The linear base32 and base64 functions are unaffected.

function_date_trunc_return_type_behavior

Type: UInt64
Default: 0
Tier: Production
Allows to change the behaviour of the result type of dateTrunc function. Possible values: - 0 - When the second argument is DateTime64/Date32 the return type will be DateTime64/Date32 regardless of the time unit in the first argument. - 1 - For Date32 the result is always Date. For DateTime64 the result is DateTime for time units second and higher.

function_implementation

Type: String
Default: ``
Tier: Production
Choose function implementation for specific target or variant (experimental). If empty enable all of them.

function_json_value_return_type_allow_complex

Type: Bool
Default: 0
Tier: Production
Control whether allow to return complex type (such as: struct, array, map) for json_value function. sql SELECT JSON_VALUE('{"hello":{"world":"!"}}', '$.hello') settings function_json_value_return_type_allow_complex=true ┌─JSON_VALUE('{"hello":{"world":"!"}}', '$.hello')─┐ │ {"world":"!"} │ └──────────────────────────────────────────────────┘ 1 row in set. Elapsed: 0.001 sec. Possible values: - true — Allow. - false — Disallow.

function_json_value_return_type_allow_nullable

Type: Bool
Default: 0
Tier: Production
Control whether allow to return NULL when value is not exist for JSON_VALUE function. sql SELECT JSON_VALUE('{"hello":"world"}', '$.b') settings function_json_value_return_type_allow_nullable=true; ┌─JSON_VALUE('{"hello":"world"}', '$.b')─┐ │ ᴺᵁᴸᴸ │ └────────────────────────────────────────┘ 1 row in set. Elapsed: 0.001 sec. Possible values: - true — Allow. - false — Disallow.

function_locate_has_mysql_compatible_argument_order

Type: Bool
Default: 1
Tier: Production
Controls the order of arguments in function locate. Possible values: - 0 — Function locate accepts arguments (haystack, needle[, start_pos]). - 1 — Function locate accepts arguments (needle, haystack, [, start_pos]) (MySQL-compatible behavior)

function_range_max_elements_in_block

Type: UInt64
Default: 500000000
Tier: Production
Sets the safety threshold for data volume generated by function range. Defines the maximum number of values generated by function per block of data (sum of array sizes for every row in a block). Possible values: - Positive integer. See Also - max_block_size - min_insert_block_size_rows

function_sleep_max_microseconds_per_block

Type: UInt64
Default: 3000000
Tier: Production
Maximum number of microseconds the function sleep is allowed to sleep for each block. If a user called it with a larger value, it throws an exception. It is a safety threshold.

function_visible_width_behavior

Type: UInt64
Default: 1
Tier: Production
The version of visibleWidth behavior. 0 - only count the number of code points; 1 - correctly count zero-width and combining characters, count full-width characters as two, estimate the tab width, count delete characters.

functions_h3_default_if_invalid

Type: Bool
Default: 0
Tier: Production
If false, h3 functions, e.g. h3CellAreaM2, throw an exception if input is invalid. If true, they return 0 or default value.

geo_distance_returns_float64_on_float64_arguments

Type: Bool
Default: 1
Tier: Production
If all four arguments to geoDistance, greatCircleDistance, greatCircleAngle functions are Float64, return Float64 and use double precision for internal calculations. In previous RawTree versions, the functions always returned Float32.

geotoh3_argument_order

Type: GeoToH3ArgumentOrder
Default: lat_lon
Tier: Beta
Function 'geoToH3' accepts (lon, lat) if set to 'lon_lat' and (lat, lon) if set to 'lat_lon'.

glob_expansion_max_elements

Type: UInt64
Default: 1000
Tier: Production
Maximum number of allowed addresses (For external storages, table functions, etc).

grace_hash_join_initial_buckets

Type: NonZeroUInt64
Default: 1
Tier: Experimental
Initial number of grace hash join buckets

grace_hash_join_max_buckets

Type: NonZeroUInt64
Default: 1024
Tier: Experimental
Limit on the number of grace hash join buckets

group_by_overflow_mode

Type: OverflowModeGroupBy
Default: throw
Tier: Production
Sets what happens when the number of unique keys for aggregation exceeds the limit: - throw: throw an exception - break: stop executing the query and return the partial result - any: continue aggregation for the keys that got into the set, but do not add new keys to the set. Using the 'any' value lets you run an approximation of GROUP BY. The quality of this approximation depends on the statistical nature of the data.

group_by_top_k_optimization_observation_rows

Type: UInt64
Default: 65536
Tier: Experimental
For enable_group_by_top_k_optimization: the number of rows each aggregation stream observes before freezing a full top-K heap that skipped less than 10% of input rows and evicted fewer keys than its capacity. A frozen heap means aggregation continues as if the optimization were disabled. The effective window is at least twice the heap's reserved size, so a heap always gets a chance to fill before being judged. 0 disables this freeze (the heap still freezes when a boundary tie-set overgrows it). This has no effect on GROUP BY keys LIMIT K queries without ORDER BY, where the freeze is always disabled: that shape's plan contains a synthesized sort that only pays off while the heap bounds the hash table, so freezing the heap would leave a plan slower than the un-optimized one.

group_by_two_level_threshold

Type: UInt64
Default: 100000
Tier: Production
From what number of keys, a two-level aggregation starts. 0 - the threshold is not set.

group_by_two_level_threshold_bytes

Type: UInt64
Default: 50000000
Tier: Production
From what size of the aggregation state in bytes, a two-level aggregation begins to be used. 0 - the threshold is not set. Two-level aggregation is used when at least one of the thresholds is triggered.

group_by_use_nulls

Type: Bool
Default: 0
Tier: Production
Changes the way the GROUP BY clause treats the types of aggregation keys. When the ROLLUP, CUBE, or GROUPING SETS specifiers are used, some aggregation keys may not be used to produce some result rows. Columns for these keys are filled with either default value or NULL in corresponding rows depending on this setting. Possible values: - 0 — The default value for the aggregation key type is used to produce missing values. - 1 — RawTree executes GROUP BY the same way as the SQL standard says. The types of aggregation keys are converted to Nullable. Columns for corresponding aggregation keys are filled with NULL for rows that didn't use it. See also: - GROUP BY clause

h3togeo_lon_lat_result_order

Type: Bool
Default: 0
Tier: Production
Function 'h3ToGeo' returns (lon, lat) if true, otherwise (lat, lon).

handshake_timeout_ms

Type: Milliseconds
Default: 10000
Tier: Production
Timeout in milliseconds for receiving Hello packet from replicas during handshake.

hdfs_create_new_file_on_insert

Type: Bool
Default: 0
Tier: Production
Enables or disables creating a new file on each insert in HDFS engine tables. If enabled, on each insert a new HDFS file will be created with the name, similar to this pattern: initial: data.Parquet.gz -> data.1.Parquet.gz -> data.2.Parquet.gz, etc. Possible values: - 0 — INSERT query appends new data to the end of the file. - 1 — INSERT query creates a new file.

hdfs_ignore_file_doesnt_exist

Type: Bool
Default: 0
Tier: Production
Ignore absence of file if it does not exist when reading certain keys. Possible values: - 1 — SELECT returns empty result. - 0 — SELECT throws an exception.

hdfs_replication

Type: UInt64
Default: 0
Tier: Production
The actual number of replications can be specified when the hdfs file is created.

hdfs_skip_empty_files

Type: Bool
Default: 0
Tier: Production
Enables or disables skipping empty files in HDFS engine tables. Possible values: - 0 — SELECT throws an exception if empty file is not compatible with requested format. - 1 — SELECT returns empty result for empty file.

hdfs_throw_on_zero_files_match

Type: Bool
Default: 0
Tier: Production
Throw an error if matched zero files according to glob expansion rules. Possible values: - 1 — SELECT throws an exception. - 0 — SELECT returns empty result.

hdfs_truncate_on_insert

Type: Bool
Default: 0
Tier: Production
Enables or disables truncation before an insert in hdfs engine tables. If disabled, an exception will be thrown on an attempt to insert if a file in HDFS already exists. Possible values: - 0 — INSERT query appends new data to the end of the file. - 1 — INSERT query replaces existing content of the file with the new data.

hedged_connection_timeout_ms

Type: Milliseconds
Default: 50
Tier: Production
Connection timeout for establishing connection with replica for Hedged requests

highlight_max_matches_per_row

Type: UInt64
Default: 10000
Tier: Production
Sets the maximum number of highlight matches per row in the highlight function. Use it to protect against excessive memory usage when highlighting highly repetitive patterns in large texts. Possible values: - Positive integer.

hnsw_candidate_list_size_for_search

Type: UInt64
Default: 256
Tier: Production
The size of the dynamic candidate list when searching the vector similarity index, also known as 'ef_search'.

hsts_max_age

Type: UInt64
Default: 0
Tier: Production
Expired time for HSTS. 0 means disable HSTS.

http_allow_database_as_path

Type: Bool
Default: 0
Tier: Production
If enabled, the HTTP interface recognizes a /database/ component in the URL path and uses it as the current database. This is a per-user setting that controls whether a routed path-style request is interpreted. Routing itself is gated globally by the server-level http_allow_path_requests configuration setting (off by default), which must be enabled for the HTTP interface to route a path-style request (such as /my_db/my_table.csv) to the query handler at all — that routing decision is made before the request is authenticated, so it cannot depend on a per-user setting. When http_allow_path_requests is off, unknown paths return a plain 404. After routing, this setting is re-checked against the authenticated user's effective settings, so it can be enabled selectively per user, role, or profile.

http_allow_filters_as_path

Type: Bool
Default: 0
Tier: Production
If enabled, the HTTP interface recognizes /name=value/ components in the path (hive partitioning style) and translates them to filters combined with AND. Operators >, <, >=, <=, !=, <> are also recognized. Like http_allow_database_as_path, this is a per-user setting; routing of path-style requests is gated globally by the server-level http_allow_path_requests configuration setting (routing happens before authentication).

http_allow_filters_as_unrecognized_url_parameters

Type: Bool
Default: 0
Tier: Production
If enabled, any URL parameter not recognized as a known parameter, setting, or param_* prefix is treated as a filter and combined with AND. Two forms are accepted: - A plain name=value becomes the equality `name` = 'value' (the identifier is back-quoted, the value is quoted as a string literal). - A comparison operator (!=, >, <, >=, <=, <>) makes it a comparison: either split across the parameter (?a!=2, ?a>=2) or written inline when the URL has no = to split on (?a<>2, ?f(x)>3), in which case the reassembled name[=value] is parsed as a full SQL expression.

http_allow_table_as_file

Type: Bool
Default: 0
Tier: Production
If enabled, the HTTP interface recognizes the last URL path component as a table name in the form table, table.format, or table.format.compression. The path is interpreted as SELECT * FROM table. Like http_allow_database_as_path, this is a per-user setting; routing of path-style requests is gated globally by the server-level http_allow_path_requests configuration setting (routing happens before authentication).

http_connection_timeout

Type: Seconds
Default: 1
Tier: Production
HTTP connection timeout (in seconds). Possible values: - Any positive integer. - 0 - Disabled (infinite timeout).

http_headers_progress_interval_ms

Type: UInt64
Default: 100
Tier: Production
Do not send HTTP headers X-RawTree-Progress / X-ClickHouse-Progress more frequently than at each specified interval.

http_headers_read_timeout

Type: Seconds
Default: 30
Tier: Production
Maximum time in seconds to read all HTTP request headers. This is a total deadline for the entire header parsing phase, not a per-read timeout. Protects against slowloris-style attacks where a client trickles header data slowly to hold connections open.

http_make_head_request

Type: Bool
Default: 1
Tier: Production
The http_make_head_request setting allows the execution of a HEAD request while reading data from HTTP to retrieve information about the file to be read, such as its size. Since it's enabled by default, it may be desirable to disable this setting in cases where the server does not support HEAD requests.

http_max_field_name_size

Type: UInt64
Default: 4096
Tier: Production
Maximum length of a field name in HTTP request headers, query parameters, and form data.

http_max_field_value_size

Type: UInt64
Default: 131072
Tier: Production
Maximum length of a field value in HTTP request headers, query parameters, and form data.

http_max_fields

Type: UInt64
Default: 1000
Tier: Production
Maximum number of fields in HTTP request headers, query parameters, and form data.

http_max_multipart_form_data_size

Type: UInt64
Default: 1073741824
Tier: Production
Limit on size of multipart/form-data content. This setting cannot be parsed from URL parameters and should be set in a user profile. Note that content is parsed and external tables are created in memory before the start of query execution. And this is the only limit that has an effect on that stage (limits on max memory usage and max execution time have no effect while reading HTTP form data).

http_max_request_header_size

Type: UInt64
Default: 10485760
Tier: Production
Maximum total size of all HTTP request headers (names and values combined) in bytes.

http_max_request_param_data_size

Type: UInt64
Default: 10485760
Tier: Production
Limit on size of request data used as a query parameter in predefined HTTP requests.

http_max_tries

Type: UInt64
Default: 10
Tier: Production
Max attempts to read via http.

http_max_uri_size

Type: UInt64
Default: 1048576
Tier: Production
Sets the maximum URI length of an HTTP request. Possible values: - Positive integer.

http_native_compression_disable_checksumming_on_decompress

Type: Bool
Default: 0
Tier: Production
Enables or disables checksum verification when decompressing the HTTP POST data from the client. Used only for RawTree native compression format (not used with gzip or deflate). For more information, read the HTTP interface description. Possible values: - 0 — Disabled. - 1 — Enabled.

http_receive_timeout

Type: Seconds
Default: 30
Tier: Production
HTTP receive timeout (in seconds). Possible values: - Any positive integer (seconds). 0 is not an infinite timeout and can cause connection setup failures (POSIX socket timeouts require a positive interval).

http_response_buffer_size

Type: UInt64
Default: 0
Tier: Production
The number of bytes to buffer in the server memory before sending a HTTP response to the client or flushing to disk (when http_wait_end_of_query is enabled).

http_response_headers

Type: Map
Default: {}
Tier: Production
Allows to add or override HTTP headers which the server will return in the response with a successful query result. This only affects the HTTP interface. If the header is already set by default, the provided value will override it. If the header was not set by default, it will be added to the list of headers. Headers that are set by the server by default and not overridden by this setting, will remain. The setting allows you to set a header to a constant value. Currently there is no way to set a header to a dynamically calculated value. Neither names nor values can contain ASCII control characters. If you implement a UI application which allows users to modify settings but at the same time makes decisions based on the returned headers, it is recommended to restrict this setting to readonly. Example: SET http_response_headers = $${'Content-Type': 'image/png'}$$

http_retry_initial_backoff_ms

Type: UInt64
Default: 100
Tier: Production
Min milliseconds for backoff, when retrying read via http

http_retry_max_backoff_ms

Type: UInt64
Default: 10000
Tier: Production
Max milliseconds for backoff, when retrying read via http

http_send_timeout

Type: Seconds
Default: 30
Tier: Production
HTTP send timeout (in seconds). Possible values: - Any positive integer (seconds). 0 is not an infinite timeout and can cause connection setup failures (POSIX socket timeouts require a positive interval). :::note It's applicable only to the default profile. A server reboot is required for the changes to take effect. :::

http_skip_not_found_url_for_globs

Type: Bool
Default: 1
Tier: Production
Skip URLs for globs with HTTP_NOT_FOUND error

http_wait_end_of_query

Type: Bool
Default: 0
Tier: Production
Enable HTTP response buffering on the server-side.

http_write_exception_in_output_format

Type: Bool
Default: 0
Tier: Production
Write exception in output format to produce valid output. Works with JSON and XML formats.

http_x_clickhouse_format_overrides_output_format

Type: Bool
Default: 1
Tier: Production
Controls which setting the X-RawTree-Format HTTP header (and its compatibility alias X-ClickHouse-Format) maps to. If enabled (the default), the header is an alias for the output_format setting: it is an explicit override of the response format that wins over the FORMAT clause in the query and over the file extension in the URL path. If disabled, the header is an alias for the default_format setting, as it was before version 26.8: it only selects the format used when the query has no FORMAT clause and no other format override is applied. In both cases the header overrides the URL parameter of the same name (output_format or default_format, respectively) and never changes how the request body of an INSERT is parsed. This is a compatibility setting for the HTTP interface: the header is consumed before the query is parsed, so it must be supplied via a URL parameter or a user profile, not via an in-query SETTINGS clause. Like output_format and default_format themselves, it can always be changed in read-only mode (readonly = 1), so a read-only user can pass it as a URL parameter.

http_x_rawtree_format_overrides_output_format

Type: Bool
Default: 1
Tier: Production
Controls which setting the X-RawTree-Format HTTP header (and its compatibility alias X-ClickHouse-Format) maps to. If enabled (the default), the header is an alias for the output_format setting: it is an explicit override of the response format that wins over the FORMAT clause in the query and over the file extension in the URL path. If disabled, the header is an alias for the default_format setting, as it was before version 26.8: it only selects the format used when the query has no FORMAT clause and no other format override is applied. In both cases the header overrides the URL parameter of the same name (output_format or default_format, respectively) and never changes how the request body of an INSERT is parsed. This is a compatibility setting for the HTTP interface: the header is consumed before the query is parsed, so it must be supplied via a URL parameter or a user profile, not via an in-query SETTINGS clause. Like output_format and default_format themselves, it can always be changed in read-only mode (readonly = 1), so a read-only user can pass it as a URL parameter.

http_zlib_compression_level

Type: Int64
Default: 3
Tier: Production
Sets the level of data compression in the response to an HTTP request if enable_http_compression = 1. The setting applies only to the zlib-based methods: gzip and deflate. The level for other methods (such as zstd, lz4, br, xz) is set by output_format_compression_level. Possible values: Numbers from 1 to 12. Levels above 9 require the default build with libdeflate; a build without libdeflate supports levels 1 to 9.

iceberg_compaction_commit_batch_size

Type: UInt64
Default: 100
Tier: Production
Number of merged data files that background Iceberg compaction accumulates before publishing them in a new snapshot. Compaction results are published in any case once there are no candidates left to compact, so this setting only bounds how long already merged files stay unpublished while compaction keeps finding new work. 0 restores the old behaviour of publishing only when compaction runs out of candidates - a state that is never reached while the table keeps receiving new data files, so every merged output is then written to object storage and never referenced by a snapshot.

iceberg_compaction_data_cleanup

Type: Seconds
Default: 10800
Tier: Production
The time after which the data will be deleted.

iceberg_compaction_delay_bias

Type: Seconds
Default: 10800
Tier: Production
Minimum time of delay between 2 background compaction operations.

iceberg_compaction_max_bytes_in_data_file

Type: UInt64
Default: 18446744073709551615
Tier: Production
Max bytes of an iceberg parquet data file produced by compaction. Defaults to the maximum so that compaction merges eligible files into as few output files as possible.

iceberg_compaction_max_rows_in_data_file

Type: UInt64
Default: 18446744073709551615
Tier: Production
Max rows of an iceberg parquet data file produced by compaction. Defaults to the maximum so that compaction merges eligible files into as few output files as possible. Keeping this above the size compaction can actually produce would make every output file stay below iceberg_data_file_size_lower_threshold_compaction and be re-selected forever.

iceberg_data_file_size_lower_threshold_compaction

Type: UInt64
Default: 10485760
Tier: Production
Threshold for compaction data files in iceberg.

iceberg_data_file_size_upper_threshold_compaction

Type: UInt64
Default: 10737418240
Tier: Production
Threshold for compaction data files in iceberg.

iceberg_delete_data_on_drop

Type: Bool
Default: 0
Tier: Production
Whether to delete all iceberg files on drop or not.

iceberg_delete_manifest_decode_concurrency

Type: NonZeroUInt64
Default: 4
Tier: Production
Maximum number of Iceberg manifest files decoded concurrently while reading a table. Delete manifests are all decoded before any data file is read; data manifests are decoded while the list of data files for the query is produced, and new ones are decoded only as the query consumes already decoded entries. Decoding several manifests at a time overlaps the object storage round-trips and the per-entry pruning work. Higher values raise peak memory when the Iceberg metadata files cache is disabled or full, since each in-flight manifest then holds its own decoded contents. Must be greater than zero; 1 decodes the manifests one at a time.

iceberg_expire_default_max_ref_age_ms

Type: Int64
Default: 9223372036854775807
Tier: Production
Default value for Iceberg table property history.expire.max-ref-age-ms used by expire_snapshots when that property is absent.

iceberg_expire_default_max_snapshot_age_ms

Type: Int64
Default: 432000000
Tier: Production
Default value for Iceberg table property history.expire.max-snapshot-age-ms used by expire_snapshots when that property is absent.

iceberg_expire_default_min_snapshots_to_keep

Type: Int64
Default: 1
Tier: Production
Default value for Iceberg table property history.expire.min-snapshots-to-keep used by expire_snapshots when that property is absent.

iceberg_file_entries_queue_size

Type: NonZeroUInt64
Default: 100
Tier: Production
Capacity of the queue between the Iceberg data manifest decode tasks and the query, in data file entries. The decode tasks pause once the queue is full and the query is not consuming, so this also bounds the read-ahead. Must be greater than zero.

iceberg_insert_max_bytes_in_data_file

Type: UInt64
Default: 1073741824
Tier: Production
Max bytes of iceberg parquet data file on insert operation.

iceberg_insert_max_partitions

Type: UInt64
Default: 100
Tier: Production
Max allowed partitions count per one insert operation for Iceberg table engine.

iceberg_insert_max_rows_in_data_file

Type: UInt64
Default: 1000000
Tier: Production
Max rows of iceberg parquet data file on insert operation.

iceberg_manifest_decode_concurrency

Type: NonZeroUInt64
Default: 4
Tier: Production
Maximum number of Iceberg manifest files decoded concurrently while reading a table. Delete manifests are all decoded before any data file is read; data manifests are decoded while the list of data files for the query is produced, and new ones are decoded only as the query consumes already decoded entries. Decoding several manifests at a time overlaps the object storage round-trips and the per-entry pruning work. Higher values raise peak memory when the Iceberg metadata files cache is disabled or full, since each in-flight manifest then holds its own decoded contents. Must be greater than zero; 1 decodes the manifests one at a time.

iceberg_manifest_min_count_to_compact

Type: UInt64
Default: 30
Tier: Experimental
Minimum number of manifest files required to trigger manifest-only compaction via OPTIMIZE TABLE ... MANIFEST. If the current number of manifest files is less than or equal to this threshold, compaction is skipped. Requires allow_experimental_iceberg_compaction to be enabled.

iceberg_max_number_datafiles_to_compact

Type: UInt64
Default: 1000
Tier: Production
Threshold for compaction data files in iceberg.

iceberg_metadata_compression_method

Type: String
Default: ``
Tier: Experimental
Method to compress .metadata.json file.

iceberg_metadata_log_level

Type: IcebergMetadataLogLevel
Default: none
Tier: Production
Controls the level of metadata logging for Iceberg tables to system.iceberg_metadata_log. Usually this setting can be modified for debugging purposes. Possible values: - none - No metadata log. - metadata - Root metadata.json file. - manifest_list_metadata - Everything above + metadata from avro manifest list which corresponds to a snapshot. - manifest_list_entry - Everything above + avro manifest list entries. - manifest_file_metadata - Everything above + metadata from traversed avro manifest files. - manifest_file_entry - Everything above + traversed avro manifest files entries.

iceberg_metadata_staleness_ms

Type: UInt64
Default: 0
Tier: Production
If non-zero, skip fetching iceberg metadata from remote catalog if there is a cached metadata snapshot, more recent than the given staleness window. Zero means to always fetch the latest metadata version from the remote catalog. Setting this a non-zero trades staleness to a lower latency of read operations.

iceberg_orphan_files_older_than_seconds

Type: UInt64
Default: 259200
Tier: Experimental
Default age threshold in seconds for orphan file removal in Iceberg tables. Files newer than this are not considered orphans. Used when the older_than argument is omitted from the remove_orphan_files() procedure call. Default is 259200 (3 days).

iceberg_snapshot_id

Type: Int64
Default: 0
Tier: Production
Query Iceberg table using the specific snapshot id.

iceberg_timestamp_ms

Type: Int64
Default: 0
Tier: Production
Query Iceberg table using the snapshot that was current at a specific timestamp.

iceberg_tolerate_conflicting_manifest_schemas

Type: Bool
Default: 1
Tier: Production
If enabled and the schema-id of an Iceberg manifest file is already registered from metadata.json, the metadata.json schema is used and the copy in the schema key of the manifest file header is ignored without being compared. If disabled, the manifest header copy is compared with the metadata.json schema, and a conflict fails the query with an ICEBERG_SPECIFICATION_VIOLATION error. The manifest header schema is only a copy of the table schema at the time the manifest was written, and some writers (e.g. AWS S3 Tables maintenance jobs) have been observed storing degraded copies there. Other query engines resolve schemas from metadata.json and ignore divergent header copies, so the default follows them. A conflict between two metadata.json schema definitions still always fails the query.

idle_connection_timeout

Type: UInt64
Default: 3600
Tier: Production
Timeout to close idle TCP connections after specified number of seconds. Possible values: - Positive integer (0 - close immediately, after 0 seconds).

ignore_cold_parts_seconds

Type: Int64
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. Exclude new data parts from SELECT queries until they're either pre-warmed (see cache_populated_by_fetch) or this many seconds old. Only for Replicated-/SharedMergeTree.

ignore_data_skipping_indices

Type: String
Default: ``
Tier: Production
Ignores the skipping indexes specified if used by the query. Consider the following example: sql CREATE TABLE data ( key Int, x Int, y Int, INDEX x_idx x TYPE minmax GRANULARITY 1, INDEX y_idx y TYPE minmax GRANULARITY 1, INDEX xy_idx (x,y) TYPE minmax GRANULARITY 1 ) Engine=MergeTree() ORDER BY key; INSERT INTO data VALUES (1, 2, 3); SELECT * FROM data; SELECT * FROM data SETTINGS ignore_data_skipping_indices=''; -- query will produce CANNOT_PARSE_TEXT error. SELECT * FROM data SETTINGS ignore_data_skipping_indices='x_idx'; -- Ok. SELECT * FROM data SETTINGS ignore_data_skipping_indices='na_idx'; -- Ok. SELECT * FROM data WHERE x = 1 AND y = 1 SETTINGS ignore_data_skipping_indices='xy_idx',force_data_skipping_indices='xy_idx' ; -- query will produce INDEX_NOT_USED error, since xy_idx is explicitly ignored. SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx'; The query without ignoring any indexes: sql EXPLAIN indexes = 1 SELECT * FROM data WHERE x = 1 AND y = 2; Expression ((Projection + Before ORDER BY)) Filter (WHERE) ReadFromMergeTree (default.data) Indexes: PrimaryKey Condition: true Parts: 1/1 Granules: 1/1 Skip Name: x_idx Description: minmax GRANULARITY 1 Parts: 0/1 Granules: 0/1 Skip Name: y_idx Description: minmax GRANULARITY 1 Parts: 0/0 Granules: 0/0 Skip Name: xy_idx Description: minmax GRANULARITY 1 Parts: 0/0 Granules: 0/0 Ignoring the xy_idx index: sql EXPLAIN indexes = 1 SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx'; Expression ((Projection + Before ORDER BY)) Filter (WHERE) ReadFromMergeTree (default.data) Indexes: PrimaryKey Condition: true Parts: 1/1 Granules: 1/1 Skip Name: x_idx Description: minmax GRANULARITY 1 Parts: 0/1 Granules: 0/1 Skip Name: y_idx Description: minmax GRANULARITY 1 Parts: 0/0 Granules: 0/0 Works with tables in the MergeTree family.

ignore_drop_queries_probability

Type: Float
Default: 0
Tier: Production
If enabled, server will ignore all DROP table queries with specified probability (for Memory and JOIN engines it will replace DROP to TRUNCATE). Used for testing purposes

ignore_format_null_for_explain

Type: Bool
Default: 1
Tier: Production
If enabled, FORMAT Null will be ignored for EXPLAIN queries and default output format will be used instead. When disabled, EXPLAIN queries with FORMAT Null will produce no output (backward compatible behavior).

ignore_materialized_views_with_dropped_target_table

Type: Bool
Default: 0
Tier: Production
Ignore MVs with dropped target table during pushing to views

ignore_on_cluster_for_replicated_access_entities_queries

Type: Bool
Default: 0
Tier: Production
Ignore ON CLUSTER clause for replicated access entities management queries.

ignore_on_cluster_for_replicated_database

Type: Bool
Default: 0
Tier: Production
Always ignore ON CLUSTER clause for DDL queries with replicated databases.

ignore_on_cluster_for_replicated_handler_queries

Type: Bool
Default: 0
Tier: Production
Ignore ON CLUSTER clause for replicated handler management queries.

ignore_on_cluster_for_replicated_named_collections_queries

Type: Bool
Default: 0
Tier: Production
Ignore ON CLUSTER clause for replicated named collections management queries.

ignore_on_cluster_for_replicated_udf_queries

Type: Bool
Default: 0
Tier: Production
Ignore ON CLUSTER clause for replicated UDF management queries.

implicit_select

Type: Bool
Default: 0
Tier: Production
Allow writing simple SELECT queries without the leading SELECT keyword, which makes it simple for calculator-style usage, e.g. 1 + 2 becomes a valid query. In rawtree-local it is enabled by default and can be explicitly disabled.

implicit_table_at_top_level

Type: String
Default: ``
Tier: Production
If not empty, queries without FROM at the top level will read from this table instead of system.one. This is used in rawtree-local for input data processing. The setting could be set explicitly by a user but is not intended for this type of usage. Subqueries are not affected by this setting (neither scalar, FROM, or IN subqueries). SELECTs at the top level of UNION, INTERSECT, EXCEPT chains are treated uniformly and affected by this setting, regardless of their grouping in parentheses. It is unspecified how this setting affects views and distributed queries. The setting accepts a table name (then the table is resolved from the current database) or a qualified name in the form of 'database.table'. Both database and table names have to be unquoted - only simple identifiers are allowed.

implicit_transaction

Type: Bool
Default: 0
Tier: Experimental
If enabled and not already inside a transaction, wraps the query inside a full transaction (begin + commit or rollback)

inject_random_order_for_select_without_order_by

Type: Bool
Default: 0
Tier: Production
If enabled, injects 'ORDER BY rand()' into SELECT queries without ORDER BY clause. Applied only for subquery depth = 0. Subqueries and INSERT INTO ... SELECT are not affected. If the top-level construct is UNION, 'ORDER BY rand()' is injected into all children independently. Only useful for testing and development (missing ORDER BY is a source of non-deterministic query results).

input_format

Type: String
Default: ``
Tier: Production
Overrides the input format of the query. Wins over the format specified in the query.

input_format_allow_errors_num

Type: UInt64
Default: 0
Tier: Production
Sets the maximum number of acceptable errors when reading from text formats (CSV, TSV, etc.). The default value is 0. Always pair it with input_format_allow_errors_ratio. If an error occurred while reading rows but the error counter is still less than input_format_allow_errors_num, RawTree ignores the row and moves on to the next one. If both input_format_allow_errors_num and input_format_allow_errors_ratio are exceeded, RawTree throws an exception.

input_format_allow_errors_ratio

Type: Float
Default: 0
Tier: Production
Sets the maximum percentage of errors allowed when reading from text formats (CSV, TSV, etc.). The percentage of errors is set as a floating-point number between 0 and 1. The default value is 0. Always pair it with input_format_allow_errors_num. If an error occurred while reading rows but the error counter is still less than input_format_allow_errors_ratio, RawTree ignores the row and moves on to the next one. If both input_format_allow_errors_num and input_format_allow_errors_ratio are exceeded, RawTree throws an exception.

input_format_allow_seeks

Type: Bool
Default: 1
Tier: Production
Allow seeks (or range reads) while reading ORC, Parquet, and Arrow input formats. When enabled and the source supports it (e.g. local file, S3, HTTP with range support and known size), ClickHouse can read only the needed byte ranges and use less memory. When disabled, or when the source does not support seeks (e.g. no file size, or stream not seekable), some readers may fall back to loading the full file into memory. Enabled by default.

input_format_arrow_allow_missing_columns

Type: Bool
Default: 1
Tier: Production
Allow missing columns while reading Arrow input formats

input_format_arrow_case_insensitive_column_matching

Type: Bool
Default: 0
Tier: Production
Ignore case when matching Arrow columns with CH columns.

input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference

Type: Bool
Default: 0
Tier: Production
Skip columns with unsupported types while schema inference for format Arrow

input_format_avro_allow_missing_fields

Type: Bool
Default: 0
Tier: Production
For Avro/AvroConfluent format: when field is not found in schema use default value instead of error

input_format_avro_null_as_default

Type: Bool
Default: 0
Tier: Production
For Avro/AvroConfluent format: insert default in case of null and non Nullable column

input_format_binary_decode_types_in_binary_format

Type: Bool
Default: 0
Tier: Production
Read data types in binary format instead of type names in RowBinaryWithNamesAndTypes input format

input_format_binary_max_type_complexity

Type: UInt64
Default: 1000
Tier: Production
Max type nodes when decoding binary types (not depth, but total count). Map(String, UInt32) = 3 nodes. Parameters of AggregateFunction types count as one node per value, including nested ones. Protects against malicious inputs. 0 = unlimited.

input_format_binary_read_json_as_string

Type: Bool
Default: 0
Tier: Production
Read values of JSON data type as JSON String values in RowBinary input format.

input_format_bson_skip_fields_with_unsupported_types_in_schema_inference

Type: Bool
Default: 0
Tier: Production
Skip fields with unsupported types while schema inference for format BSON.

input_format_capn_proto_skip_fields_with_unsupported_types_in_schema_inference

Type: Bool
Default: 0
Tier: Production
Skip columns with unsupported types while schema inference for format CapnProto

input_format_column_name_matching_mode

Type: InputFormatColumnMatchingCaseSensitivity
Default: auto
Tier: Production
Defines the column name matching mode when ingesting data through various formats (including but not limited to JSONEachRow, CSVWithNames, JSONColumns, BSONEachRow, RowBinaryWithNames). Supported modes: - match_case: match case-sensitively - ignore_case: match case-insensitively - auto: first tries to match case-sensitively, if fails, tries to match case-insensitively.

input_format_connection_handling

Type: Bool
Default: 0
Tier: Production
When this option is enabled, if the connection closes unexpectedly, any remaining data in the buffer will be parsed and processed instead of being treated as an error :::note Enabling this option disables parallel parsing and makes deduplication impossible :::

input_format_csv_allow_cr_end_of_line

Type: Bool
Default: 0
Tier: Production
If it is set true, \r will be allowed at end of line not followed by \n

input_format_csv_allow_variable_number_of_columns

Type: Bool
Default: 0
Tier: Production
Ignore extra columns in CSV input (if file has more columns than expected) and treat missing fields in CSV input as default values

input_format_csv_allow_whitespace_or_tab_as_delimiter

Type: Bool
Default: 0
Tier: Production
Allow to use spaces and tabs(\t) as field delimiter in the CSV strings

input_format_csv_arrays_as_nested_csv

Type: Bool
Default: 0
Tier: Production
When reading Array from CSV, expect that its elements were serialized in nested CSV and then put into string. Example: "[""Hello"", ""world"", ""42"""" TV""]". Braces around array can be omitted.

input_format_csv_deserialize_separate_columns_into_tuple

Type: Bool
Default: 1
Tier: Production
If it set to true, then separate columns written in CSV format can be deserialized to Tuple column. This applies only to bare Tuple. A Nullable(Tuple) is always written as a single CSV field (see output_format_csv_serialize_tuple_into_separate_columns) and is likewise read back from a single field, never from separate columns, regardless of this setting. Separate-columns parsing is not supported for Nullable(Tuple) because a leading \N field is ambiguous (it may be the outer NULL of the tuple or the NULL of its first element). Because a bare Tuple then occupies one field per element, a \N in the field of a direct top-level element is that element and not the whole column, so input_format_null_as_default applies to that element. A row that supplies a single field for the whole tuple is short by the remaining elements and is rejected instead of taking the column default. Set this setting to 0 to read such a field as the whole column again. A \N in the field of an element of a nested Tuple is still read as that whole nested element.

input_format_csv_detect_header

Type: Bool
Default: 1
Tier: Production
Automatically detect header with names and types in CSV format

input_format_csv_empty_as_default

Type: Bool
Default: 1
Tier: Production
Treat empty fields in CSV input as default values.

input_format_csv_enum_as_number

Type: Bool
Default: 0
Tier: Production
Treat inserted enum values in CSV formats as enum indices

input_format_csv_missing_nullable_as_empty_string

Type: Bool
Default: 0
Tier: Production
Controls how Nullable(String) is read from a missing value in CSV. A missing value is an empty space between/before/after commas, not surrounded by quotes. If this setting is enabled, regardless of the value of input_format_csv_empty_as_default, the missing value of Nullable(String) will be interpreted as an empty String, not as NULL.

input_format_csv_skip_first_lines

Type: UInt64
Default: 0
Tier: Production
Skip specified number of lines at the beginning of data in CSV format

input_format_csv_skip_trailing_empty_lines

Type: Bool
Default: 0
Tier: Production
Skip trailing empty lines in CSV format

input_format_csv_trim_whitespaces

Type: Bool
Default: 1
Tier: Production
Trims spaces and tabs (\t) characters at the beginning and end in CSV strings

input_format_csv_try_infer_numbers_from_strings

Type: Bool
Default: 0
Tier: Production
If enabled, during schema inference RawTree will try to infer numbers from string fields. It can be useful if CSV data contains quoted UInt64 numbers. Disabled by default.

input_format_csv_try_infer_strings_from_quoted_tuples

Type: Bool
Default: 1
Tier: Production
Interpret quoted tuples in the input data as a value of type String.

input_format_csv_use_best_effort_in_schema_inference

Type: Bool
Default: 1
Tier: Production
Use some tweaks and heuristics to infer schema in CSV format

input_format_csv_use_default_on_bad_values

Type: Bool
Default: 0
Tier: Production
Allow to set default value to column when CSV field deserialization failed on bad value

input_format_custom_allow_variable_number_of_columns

Type: Bool
Default: 0
Tier: Production
Ignore extra columns in CustomSeparated input (if file has more columns than expected) and treat missing fields in CustomSeparated input as default values

input_format_custom_detect_header

Type: Bool
Default: 1
Tier: Production
Automatically detect header with names and types in CustomSeparated format

input_format_custom_skip_trailing_empty_lines

Type: Bool
Default: 0
Tier: Production
Skip trailing empty lines in CustomSeparated format

input_format_defaults_for_omitted_fields

Type: Bool
Default: 1
Tier: Production
When performing INSERT queries, replace omitted input column values with default values of the respective columns. This option applies to JSONEachRow (and other JSON formats), CSV, TabSeparated, TSKV, Parquet, Arrow, Avro, ORC, Native formats and formats with WithNames/WithNamesAndTypes suffixes. :::note When this option is enabled, extended table metadata are sent from server to client. It consumes additional computing resources on the server and can reduce performance. ::: Possible values: - 0 — Disabled. - 1 — Enabled.

input_format_force_null_for_omitted_fields

Type: Bool
Default: 0
Tier: Production
Force initialize omitted fields with null values

input_format_geojson_unsupported_geometry_handling

Type: GeoJSONUnsupportedGeometryHandling
Default: throw
Tier: Production
Controls what happens when a valid GeoJSON geometry type that cannot be represented in RawTree's Geometry type (such as GeometryCollection) must be stored in the geometry column while reading GeoJSON input. Possible values: - 'throw' (default) — throw an exception. - 'null' — insert a NULL value for the geometry column and continue parsing. This applies only when the geometry column is materialized. When it is not a requested output column, such a geometry is validated for well-formedness but does not trigger the handling.

input_format_hive_text_allow_variable_number_of_columns

Type: Bool
Default: 1
Tier: Production
Ignore extra columns in Hive Text input (if file has more columns than expected) and treat missing fields in Hive Text input as default values

input_format_hive_text_collection_items_delimiter

Type: Char
Default: 
Tier: Production
Delimiter between collection(array or map) items in Hive Text File

input_format_hive_text_fields_delimiter

Type: Char
Default:

Tier: Production
Delimiter between fields in Hive Text File

input_format_hive_text_map_keys_delimiter

Type: Char
Default: 
Tier: Production
Delimiter between a pair of map key/values in Hive Text File

input_format_import_nested_json

Type: Bool
Default: 0
Tier: Production
Enables or disables the insertion of JSON data with nested objects. Supported formats: - JSONEachRow Possible values: - 0 — Disabled. - 1 — Enabled. See also: - Usage of Nested Structures with the JSONEachRow format.

input_format_ipv4_default_on_conversion_error

Type: Bool
Default: 0
Tier: Production
Deserialization of IPv4 will use default values instead of throwing exception on conversion error. Disabled by default.

input_format_ipv6_default_on_conversion_error

Type: Bool
Default: 0
Tier: Production
Deserialization of IPV6 will use default values instead of throwing exception on conversion error. Disabled by default.

input_format_json_compact_allow_variable_number_of_columns

Type: Bool
Default: 0
Tier: Production
Allow variable number of columns in rows in JSONCompact/JSONCompactEachRow input formats. Ignore extra columns in rows with more columns than expected and treat missing columns as default values. Disabled by default.

input_format_json_defaults_for_missing_elements_in_named_tuple

Type: Bool
Default: 1
Tier: Production
Insert default values for missing elements in JSON object while parsing named tuple. This setting works only when setting input_format_json_named_tuples_as_objects is enabled. Enabled by default.

input_format_json_empty_as_default

Type: Bool
Default: 0
Tier: Production
When enabled, replace empty input fields in JSON with default values. For complex default expressions input_format_defaults_for_omitted_fields must be enabled too. Possible values: + 0 — Disable. + 1 — Enable.

input_format_json_ignore_unknown_keys_in_named_tuple

Type: Bool
Default: 1
Tier: Production
Ignore unknown keys in json object for named tuples. Enabled by default.

input_format_json_ignore_unnecessary_fields

Type: Bool
Default: 1
Tier: Production
Ignore unnecessary fields and not parse them. Enabling this may not throw exceptions on json strings of invalid format or with duplicated fields

input_format_json_infer_array_of_dynamic_from_array_of_different_types

Type: Bool
Default: 1
Tier: Production
If enabled, during schema inference RawTree will use Array(Dynamic) type for JSON arrays with values of different data types. Example: sql SET input_format_json_infer_array_of_dynamic_from_array_of_different_types=1; DESC format(JSONEachRow, '{"a" : [42, "hello", [1, 2, 3]]}'); response ┌─name─┬─type───────────┐ │ a │ Array(Dynamic) │ └──────┴────────────────┘ sql SET input_format_json_infer_array_of_dynamic_from_array_of_different_types=0; DESC format(JSONEachRow, '{"a" : [42, "hello", [1, 2, 3]]}'); response ┌─name─┬─type─────────────────────────────────────────────────────────────┐ │ a │ Tuple(Nullable(Int64), Nullable(String), Array(Nullable(Int64))) │ └──────┴──────────────────────────────────────────────────────────────────┘ Enabled by default.

input_format_json_infer_incomplete_types_as_strings

Type: Bool
Default: 1
Tier: Production
Allow to use String type for JSON keys that contain only Null/{}/[] in data sample during schema inference. In JSON formats any value can be read as String, and we can avoid errors like Cannot determine type for column 'column_name' by first 25000 rows of data, most likely this column contains only Nulls or empty Arrays/Maps during schema inference by using String type for keys with unknown types. Example: sql SET input_format_json_infer_incomplete_types_as_strings = 1, input_format_json_try_infer_named_tuples_from_objects = 1; DESCRIBE format(JSONEachRow, '{"obj" : {"a" : [1,2,3], "b" : "hello", "c" : null, "d" : {}, "e" : []}}'); SELECT * FROM format(JSONEachRow, '{"obj" : {"a" : [1,2,3], "b" : "hello", "c" : null, "d" : {}, "e" : []}}'); Result: ┌─name─┬─type───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ obj │ Tuple(a Array(Nullable(Int64)), b Nullable(String), c Nullable(String), d Nullable(String), e Array(Nullable(String))) │ │ │ │ │ │ └──────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ┌─obj────────────────────────────┐ │ ([1,2,3],'hello',NULL,'{}',[]) │ └────────────────────────────────┘ Enabled by default.

input_format_json_map_as_array_of_tuples

Type: Bool
Default: 0
Tier: Production
Deserialize maps columns as JSON arrays of tuples. Disabled by default.

input_format_json_max_depth

Type: UInt64
Default: 1000
Tier: Production
Maximum depth of a field in JSON. This is not a strict limit, it does not have to be applied precisely.

input_format_json_max_object_size

Type: UInt64
Default: 536870912
Tier: Production
Maximum allowed size of a single JSON object in bytes. Objects exceeding this limit are rejected as likely malformed. This protects against memory exhaustion when a malformed JSON document is parsed as a single object. The same limit is applied in both parallel and non-parallel parsing paths. Set to 0 to disable the check.

input_format_json_max_string_column_growth_step

Type: UInt64
Default: 0
Tier: Production
When building the JSON column's internal String buffers while parsing JSON from string, cap the power-of-two growth at this many bytes: once the reserved size reaches this value, the buffer grows by increments of this size instead of doubling. This bounds over-allocation for large JSON columns. 0 means unlimited (pure doubling).

input_format_json_named_tuples_as_objects

Type: Bool
Default: 1
Tier: Production
Parse named tuple columns as JSON objects. Enabled by default.

input_format_json_read_arrays_as_strings

Type: Bool
Default: 1
Tier: Production
Allow parsing JSON arrays as strings in JSON input formats. Example: sql SET input_format_json_read_arrays_as_strings = 1; SELECT arr, toTypeName(arr), JSONExtractArrayRaw(arr)[3] from format(JSONEachRow, 'arr String', '{"arr" : [1, "Hello", [1,2,3]]}'); Result: ┌─arr───────────────────┬─toTypeName(arr)─┬─arrayElement(JSONExtractArrayRaw(arr), 3)─┐ │ [1, "Hello", [1,2,3]] │ String │ [1,2,3] │ └───────────────────────┴─────────────────┴───────────────────────────────────────────┘ Enabled by default.

input_format_json_read_bools_as_numbers

Type: Bool
Default: 1
Tier: Production
Allow parsing bools as numbers in JSON input formats. Enabled by default.

input_format_json_read_bools_as_strings

Type: Bool
Default: 1
Tier: Production
Allow parsing bools as strings in JSON input formats. Enabled by default.

input_format_json_read_numbers_as_strings

Type: Bool
Default: 1
Tier: Production
Allow parsing numbers as strings in JSON input formats. Enabled by default.

input_format_json_read_objects_as_strings

Type: Bool
Default: 1
Tier: Production
Allow parsing JSON objects as strings in JSON input formats. Example: sql SET input_format_json_read_objects_as_strings = 1; CREATE TABLE test (id UInt64, obj String, date Date) ENGINE=Memory(); INSERT INTO test FORMAT JSONEachRow {"id" : 1, "obj" : {"a" : 1, "b" : "Hello"}, "date" : "2020-01-01"}; SELECT * FROM test; Result: ┌─id─┬─obj──────────────────────┬───────date─┐ │ 1 │ {"a" : 1, "b" : "Hello"} │ 2020-01-01 │ └────┴──────────────────────────┴────────────┘ Enabled by default.

input_format_json_throw_on_bad_escape_sequence

Type: Bool
Default: 1
Tier: Production
Throw an exception if JSON string contains bad escape sequence in JSON input formats. If disabled, bad escape sequences will remain as is in the data. Enabled by default.

input_format_json_try_infer_named_tuples_from_objects

Type: Bool
Default: 1
Tier: Production
If enabled, during schema inference RawTree will try to infer named Tuple from JSON objects. The resulting named Tuple will contain all elements from all corresponding JSON objects from sample data. Example: sql SET input_format_json_try_infer_named_tuples_from_objects = 1; DESC format(JSONEachRow, '{"obj" : {"a" : 42, "b" : "Hello"}}, {"obj" : {"a" : 43, "c" : [1, 2, 3]}}, {"obj" : {"d" : {"e" : 42}}}') Result: ┌─name─┬─type───────────────────────────────────────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ obj │ Tuple(a Nullable(Int64), b Nullable(String), c Array(Nullable(Int64)), d Tuple(e Nullable(Int64))) │ │ │ │ │ │ └──────┴────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ Enabled by default.

input_format_json_try_infer_numbers_from_strings

Type: Bool
Default: 0
Tier: Production
If enabled, during schema inference RawTree will try to infer numbers from string fields. It can be useful if JSON data contains quoted UInt64 numbers. Disabled by default.

input_format_json_use_string_type_for_ambiguous_paths_in_named_tuples_inference_from_objects

Type: Bool
Default: 0
Tier: Production
Use String type instead of an exception in case of ambiguous paths in JSON objects during named tuples inference

input_format_json_validate_types_from_metadata

Type: Bool
Default: 1
Tier: Production
For JSON/JSONCompact/JSONColumnsWithMetadata input formats, if this setting is set to 1, the types from metadata in input data will be compared with the types of the corresponding columns from the table. Enabled by default.

input_format_max_block_size_bytes

Type: UInt64
Default: 0
Tier: Production
Limits the size of the blocks formed during data parsing in input formats in bytes. Used in row based input formats when block is formed on RawTree side. 0 means no limit in bytes.

input_format_max_block_wait_ms

Type: UInt64
Default: 0
Tier: Production
Limits the maximum time in milliseconds to wait before emitting a block during parsing in row-based input formats. 0 means no limit. :::note This option only works if input_format_connection_handling is enabled. Setting a value also disables parallel parsing and makes deduplication impossible. ::: :::note For streaming inserts, you must also set min_insert_block_size_rows=0 and min_insert_block_size_bytes=0. Otherwise, parsed blocks may still be accumulated in memory by the block squashing stage until those thresholds are reached, preventing timely inserts. ::: Example: streaming Wikipedia recent changes into ClickHouse bash clickhouse-client --query 'CREATE TABLE wikipedia_edits (data JSON)' curl -sS --globoff -H 'Accept: application/json' --no-buffer \ 'https://stream.wikimedia.org/v2/stream/recentchange' \ | clickhouse-client \ --query 'INSERT INTO wikipedia_edits FORMAT JSONAsObject' \ --input_format_max_block_wait_ms 1000 \ --input_format_connection_handling 1 \ --min_insert_block_size_rows 0 \ --min_insert_block_size_bytes 0

input_format_max_bytes_to_read_for_schema_inference

Type: UInt64
Default: 33554432
Tier: Production
The maximum amount of data in bytes to read for automatic schema inference.

input_format_max_rows_to_read_for_schema_inference

Type: UInt64
Default: 25000
Tier: Production
The maximum rows of data to read for automatic schema inference.

input_format_msgpack_number_of_columns

Type: UInt64
Default: 0
Tier: Production
The number of columns in inserted MsgPack data. Used for automatic schema inference from data.

input_format_mysql_dump_map_column_names

Type: Bool
Default: 1
Tier: Production
Match columns from table in MySQL dump and columns from RawTree table by names

input_format_mysql_dump_table_name

Type: String
Default: ``
Tier: Production
Name of the table in MySQL dump from which to read data

input_format_native_allow_types_conversion

Type: Bool
Default: 1
Tier: Production
Allow data types conversion in Native input format

input_format_native_decode_types_in_binary_format

Type: Bool
Default: 0
Tier: Production
Read data types in binary format instead of type names in Native input format

input_format_null_as_default

Type: Bool
Default: 1
Tier: Production
Enables or disables the initialization of NULL fields with default values, if data type of these fields is not nullable. If column type is not nullable and this setting is disabled, then inserting NULL causes an exception. If column type is nullable, then NULL values are inserted as is, regardless of this setting. This setting is applicable for most input formats. For complex default expressions input_format_defaults_for_omitted_fields must be enabled too. Possible values: - 0 — Inserting NULL into a not nullable column causes an exception. - 1 — NULL fields are initialized with default column values.

input_format_orc_allow_missing_columns

Type: Bool
Default: 1
Tier: Production
Allow missing columns while reading ORC input formats

input_format_orc_case_insensitive_column_matching

Type: Bool
Default: 0
Tier: Production
Ignore case when matching ORC columns with CH columns.

input_format_orc_dictionary_as_low_cardinality

Type: Bool
Default: 1
Tier: Production
Treat ORC dictionary encoded columns as LowCardinality columns while reading ORC files.

input_format_orc_filter_push_down

Type: Bool
Default: 1
Tier: Production
When reading ORC files, skip whole stripes or row groups based on the WHERE/PREWHERE expressions, min/max statistics or bloom filter in the ORC metadata.

input_format_orc_reader_time_zone_name

Type: String
Default: GMT
Tier: Production
The time zone name for ORC row reader, the default ORC row reader's time zone is GMT.

input_format_orc_row_batch_size

Type: Int64
Default: 100000
Tier: Production
Batch size when reading ORC stripes.

input_format_orc_skip_columns_with_unsupported_types_in_schema_inference

Type: Bool
Default: 0
Tier: Production
Skip columns with unsupported types while schema inference for format ORC

input_format_parallel_parsing

Type: Bool
Default: 1
Tier: Production
Enables or disables order-preserving parallel parsing of data formats. Supported only for TabSeparated (TSV), TSKV, CSV and JSONEachRow formats. Possible values: - 1 — Enabled. - 0 — Disabled.

input_format_parquet_allow_geoparquet_parser

Type: Bool
Default: 1
Tier: Production
Use geo column parser to convert Array(UInt8) into Point/MultiPoint/Linestring/Polygon/MultiLineString/MultiPolygon types

input_format_parquet_allow_missing_columns

Type: Bool
Default: 1
Tier: Production
Allow missing columns while reading Parquet input formats

input_format_parquet_bloom_filter_push_down

Type: Bool
Default: 1
Tier: Production
When reading Parquet files, skip whole row groups based on the WHERE expressions and bloom filter in the Parquet metadata.

input_format_parquet_case_insensitive_column_matching

Type: Bool
Default: 0
Tier: Production
Ignore case when matching Parquet columns with CH columns.

input_format_parquet_dictionary_filter_push_down

Type: UInt64
Default: 1048576
Tier: Production
When reading Parquet files (with reader v3), skip whole row groups based on the WHERE/PREWHERE expressions and the dictionary page contents, when all data pages of a column chunk are dictionary-encoded. The value is the maximum dictionary page size (in bytes) for which this optimization is applied; set to 0 to disable. This takes precedence over the bloom filter when both are available.

input_format_parquet_enable_json_parsing

Type: Bool
Default: 1
Tier: Production
When reading Parquet files, parse JSON columns as RawTree JSON Column.

input_format_parquet_enable_row_group_prefetch

Type: Bool
Default: 1
Tier: Production
Enable row group prefetching during parquet parsing. Currently, only single-threaded parsing can prefetch.

input_format_parquet_filter_push_down

Type: Bool
Default: 1
Tier: Production
When reading Parquet files, skip whole row groups based on the WHERE/PREWHERE expressions and min/max statistics in the Parquet metadata.

input_format_parquet_local_file_min_bytes_for_seek

Type: UInt64
Default: 8192
Tier: Production
Min bytes required for local read (file) to do seek, instead of read with ignore in Parquet input format

input_format_parquet_local_time_as_utc

Type: Bool
Default: 1
Tier: Production
Determines the data type used by schema inference for Parquet timestamps with isAdjustedToUTC=false. If true: DateTime64(..., 'UTC'), if false: DateTime64(...). Neither behavior is fully correct as RawTree doesn't have a data type for local wall-clock time. Counterintuitively, 'true' is probably the less incorrect option, because formatting the 'UTC' timestamp as String will produce representation of the correct local time.

input_format_parquet_max_block_size

Type: NonZeroUInt64
Default: 65409
Tier: Production
Max block size for parquet reader.

input_format_parquet_memory_high_watermark

Type: UInt64
Default: 4294967296
Tier: Production
Approximate memory limit for Parquet reader v3. Limits how many row groups or columns can be read in parallel. When reading multiple files in one query, the limit is on total memory usage across those files.

input_format_parquet_memory_low_watermark

Type: UInt64
Default: 2097152
Tier: Production
Schedule prefetches more aggressively if memory usage is below than threshold. Potentially useful e.g. if there are many small bloom filters to read over network.

input_format_parquet_page_filter_push_down

Type: Bool
Default: 1
Tier: Production
Skip pages using min/max values from column index.

input_format_parquet_prefer_block_bytes

Type: UInt64
Default: 16744704
Tier: Production
Average block bytes output by parquet reader

input_format_parquet_preserve_order

Type: Bool
Default: 0
Tier: Production
Avoid reordering rows when reading from Parquet files. Not recommended as row ordering is generally not guaranteed, and other parts of query pipeline may break it. Use ORDER BY _row_number instead.

input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference

Type: Bool
Default: 0
Tier: Production
Skip columns with unsupported types while schema inference for format Parquet

input_format_parquet_spatial_filter_push_down

Type: Bool
Default: 1
Tier: Production
When reading GeoParquet files, skip whole row groups and, together with input_format_parquet_page_filter_push_down, individual pages based on spatial predicates in the WHERE clause and the geometry bounding box statistics (geospatial_statistics.bbox or covering.bbox columns) in the Parquet metadata.

input_format_parquet_use_offset_index

Type: Bool
Default: 1
Tier: Production
Minor tweak to how pages are read from parquet file when no page filtering is used.

input_format_parquet_verify_checksums

Type: Bool
Default: 1
Tier: Production
Verify page checksums when reading parquet files.

input_format_protobuf_flatten_google_wrappers

Type: Bool
Default: 0
Tier: Production
Enable Google wrappers for regular non-nested columns, e.g. google.protobuf.StringValue 'str' for String column 'str'. For Nullable columns empty wrappers are recognized as defaults, and missing as nulls

input_format_protobuf_oneof_presence

Type: Bool
Default: 0
Tier: Production
Indicate which field of protobuf oneof was found by means of setting enum value in a special column

input_format_protobuf_skip_fields_with_unsupported_types_in_schema_inference

Type: Bool
Default: 0
Tier: Production
Skip fields with unsupported types while schema inference for format Protobuf

input_format_read_datetime_number_as_raw_value

Type: Bool
Default: 0
Tier: Production
Read a bare unquoted integer for a DateTime/DateTime64 column as the raw underlying value — seconds for DateTime, ticks at the column precision for DateTime64 — instead of a Unix timestamp in seconds. Disabled by default: an unquoted number is a Unix timestamp in seconds (with optional sub-second precision), consistent with the Values format, CAST and toDateTime64. Enable it (or SET compatibility = '26.7') to restore the behavior of versions up to and including 26.7, where a bare unquoted integer fed to a DateTime64 column was interpreted as the raw scaled value (ticks). The legacy path accepts only such a bare integer: with the setting enabled, a number with a fractional or exponent part is rejected by the row input paths (as before 26.8), while in JSONExtract and the typed JSON type a fractional number is still read as seconds for DateTime64 and rejected for DateTime (also as before 26.8). In the Values format itself, a number the streaming parser rejects then falls back to SQL expression evaluation and is read as seconds, both before 26.8 and with this setting enabled — so the Values behavior for a fractional number is the same in every configuration. This setting governs only the JSON, Values/Quoted and JSONExtract/typed JSON paths (the Quoted path covers every format parsing fields with the Quoted escaping rule: Values, MySQLDump, and Template/CustomSeparated/Regexp configured with Quoted field escaping). The tab-separated, CSV and other escaped/whole-text formats are unaffected: there a large unquoted DateTime64 number is still read as ticks.

input_format_record_errors_file_path

Type: String
Default: ``
Tier: Production
Path of the file used to record errors while reading text formats (CSV, TSV).

input_format_skip_unknown_fields

Type: Bool
Default: 1
Tier: Production
Enables or disables skipping insertion of extra data. When writing data, RawTree throws an exception if input data contain columns that do not exist in the target table. If skipping is enabled, RawTree does not insert extra data and does not throw an exception. Supported formats: - JSONEachRow (and other JSON formats) - BSONEachRow (and other JSON formats) - TSKV - All formats with suffixes WithNames/WithNamesAndTypes - MySQLDump - Native Possible values: - 0 — Disabled. - 1 — Enabled.

input_format_try_infer_dates

Type: Bool
Default: 1
Tier: Production
If enabled, RawTree will try to infer type Date from string fields in schema inference for text formats. If all fields from a column in input data were successfully parsed as dates, the result type will be Date, if at least one field was not parsed as date, the result type will be String. Enabled by default.

input_format_try_infer_datetimes

Type: Bool
Default: 1
Tier: Production
If enabled, RawTree will try to infer type DateTime64 from string fields in schema inference for text formats. If all fields from a column in input data were successfully parsed as datetimes, the result type will be DateTime64, if at least one field was not parsed as datetime, the result type will be String. Enabled by default.

input_format_try_infer_datetimes_only_datetime64

Type: Bool
Default: 0
Tier: Production
When input_format_try_infer_datetimes is enabled, infer only DateTime64 but not DateTime types

input_format_try_infer_exponent_floats

Type: Bool
Default: 0
Tier: Production
Try to infer floats in exponential notation while schema inference in text formats (except JSON, where exponent numbers are always inferred)

input_format_try_infer_integers

Type: Bool
Default: 1
Tier: Production
If enabled, RawTree will try to infer integers instead of floats in schema inference for text formats. If all numbers in the column from input data are integers, the result type will be Int64, if at least one number is float, the result type will be Float64. Enabled by default.

input_format_try_infer_variants

Type: Bool
Default: 0
Tier: Production
If enabled, RawTree will try to infer type Variant in schema inference for text formats when there is more than one possible type for column/array elements. Possible values: - 0 — Disabled. - 1 — Enabled.

input_format_tsv_allow_variable_number_of_columns

Type: Bool
Default: 0
Tier: Production
Ignore extra columns in TSV input (if file has more columns than expected) and treat missing fields in TSV input as default values

input_format_tsv_crlf_end_of_line

Type: Bool
Default: 0
Tier: Production
If it is set true, file function will read TSV format with \r\n instead of \n.

input_format_tsv_detect_header

Type: Bool
Default: 1
Tier: Production
Automatically detect header with names and types in TSV format

input_format_tsv_empty_as_default

Type: Bool
Default: 0
Tier: Production
Treat empty fields in TSV input as default values.

input_format_tsv_enum_as_number

Type: Bool
Default: 0
Tier: Production
Treat inserted enum values in TSV formats as enum indices.

input_format_tsv_skip_first_lines

Type: UInt64
Default: 0
Tier: Production
Skip specified number of lines at the beginning of data in TSV format

input_format_tsv_skip_trailing_empty_lines

Type: Bool
Default: 0
Tier: Production
Skip trailing empty lines in TSV format

input_format_tsv_use_best_effort_in_schema_inference

Type: Bool
Default: 1
Tier: Production
Use some tweaks and heuristics to infer schema in TSV format

input_format_values_accurate_types_of_literals

Type: Bool
Default: 1
Tier: Production
For Values format: when parsing and interpreting expressions using template, check actual type of literal to avoid possible overflow and precision issues.

input_format_values_deduce_templates_of_expressions

Type: Bool
Default: 1
Tier: Production
For Values format: if the field could not be parsed by streaming parser, run SQL parser, deduce template of the SQL expression, try to parse all rows using template and then interpret expression for all rows.

input_format_values_interpret_expressions

Type: Bool
Default: 1
Tier: Production
For Values format: if the field could not be parsed by streaming parser, run SQL parser and try to interpret it as SQL expression.

input_format_with_names_use_header

Type: Bool
Default: 1
Tier: Production
Enables or disables checking the column order when inserting data. To improve insert performance, we recommend disabling this check if you are sure that the column order of the input data is the same as in the target table. Supported formats: - CSVWithNames - CSVWithNamesAndTypes - TabSeparatedWithNames - TabSeparatedWithNamesAndTypes - JSONCompactEachRowWithNames - JSONCompactEachRowWithNamesAndTypes - JSONCompactStringsEachRowWithNames - JSONCompactStringsEachRowWithNamesAndTypes - RowBinaryWithNames - RowBinaryWithNamesAndTypes - CustomSeparatedWithNames - CustomSeparatedWithNamesAndTypes Possible values: - 0 — Disabled. - 1 — Enabled.

input_format_with_types_use_header

Type: Bool
Default: 1
Tier: Production
Controls whether format parser should check if data types from the input data match data types from the target table. Supported formats: - CSVWithNamesAndTypes - TabSeparatedWithNamesAndTypes - JSONCompactEachRowWithNamesAndTypes - JSONCompactStringsEachRowWithNamesAndTypes - RowBinaryWithNamesAndTypes - CustomSeparatedWithNamesAndTypes Possible values: - 0 — Disabled. - 1 — Enabled.

insert_allow_materialized_columns

Type: Bool
Default: 0
Tier: Production
If setting is enabled, Allow materialized columns in INSERT.

insert_deduplicate

Type: Bool
Default: 1
Tier: Production
Enables or disables block deduplication of INSERT (for Replicated* tables). This setting only takes effect when deduplicate_insert is set to backward_compatible_choice. Possible values: - 0 — Disabled. - 1 — Enabled. By default, blocks inserted into replicated tables by the INSERT statement are deduplicated (see Data Replication). For the replicated tables by default the only 100 of the most recent blocks for each partition are deduplicated (see replicated_deduplication_window, replicated_deduplication_window_seconds). For not replicated tables see non_replicated_deduplication_window.

insert_deduplication_token

Type: String
Default: ``
Tier: Production
The setting allows a user to provide own deduplication semantic in MergeTree/ReplicatedMergeTree For example, by providing a unique value for the setting in each INSERT statement, user can avoid the same inserted data being deduplicated. Possible values: - Any string insert_deduplication_token is used for deduplication only when not empty. For the replicated tables by default the only 100 of the most recent inserts for each partition are deduplicated (see replicated_deduplication_window, replicated_deduplication_window_seconds). For not replicated tables see non_replicated_deduplication_window. :::note insert_deduplication_token is tracked per partition, so multiple partitions written by one insert can carry the same token. Without a token, the default content checksum is computed over the whole inserted block, so an insert is deduplicated only when its entire data matches a previous insert (a retry), not when a single partition's rows happen to coincide with a different insert. ::: Example: sql CREATE TABLE test_table ( A Int64 ) ENGINE = MergeTree ORDER BY A SETTINGS non_replicated_deduplication_window = 100; INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (1); -- the next insert won't be deduplicated because insert_deduplication_token is different INSERT INTO test_table SETTINGS insert_deduplication_token = 'test1' VALUES (1); -- the next insert will be deduplicated because insert_deduplication_token -- is the same as one of the previous INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (2); SELECT * FROM test_table ┌─A─┐ │ 1 │ └───┘ ┌─A─┐ │ 1 │ └───┘

insert_distributed_one_random_shard

Type: Bool
Default: 0
Tier: Production
Enables or disables random shard insertion into a Distributed table when there is no distributed key. By default, when inserting data into a Distributed table with more than one shard, the RawTree server will reject any insertion request if there is no distributed key. When insert_distributed_one_random_shard = 1, insertions are allowed and data is forwarded randomly among all shards. Possible values: - 0 — Insertion is rejected if there are multiple shards and no distributed key is given. - 1 — Insertion is done randomly among all available shards when no distributed key is given.

insert_distributed_sync

Type: Bool
Default: 0
Tier: Production
Enables or disables synchronous data insertion into a Distributed table. By default, when inserting data into a Distributed table, the RawTree server sends data to cluster nodes in background mode. When distributed_foreground_insert=1, the data is processed synchronously, and the INSERT operation succeeds only after all the data is saved on all shards (at least one replica for each shard if internal_replication is true). Possible values: - 0 — Data is inserted in background mode. - 1 — Data is inserted in synchronous mode. Cloud default value: 1. See Also - Distributed Table Engine - Managing Distributed Tables

insert_distributed_timeout

Type: UInt64
Default: 0
Tier: Production
Timeout for insert query into distributed. Setting is used only with insert_distributed_sync enabled. Zero value means no timeout.

insert_keeper_fault_injection_probability

Type: Float
Default: 0
Tier: Production
Approximate probability of failure for a keeper request during insert. Valid value is in interval [0.0f, 1.0f]

insert_keeper_fault_injection_seed

Type: UInt64
Default: 0
Tier: Production
0 - random seed, otherwise the setting value

insert_keeper_max_retries

Type: UInt64
Default: 20
Tier: Production
The setting sets the maximum number of retries for RawTree Keeper (or ZooKeeper) requests during insert into replicated MergeTree. Only Keeper requests which failed due to network error, Keeper session timeout, or request timeout are considered for retries. Possible values: - Positive integer. - 0 — Retries are disabled Keeper request retries are done after some timeout. The timeout is controlled by the following settings: insert_keeper_retry_initial_backoff_ms, insert_keeper_retry_max_backoff_ms. The first retry is done after insert_keeper_retry_initial_backoff_ms timeout. The consequent timeouts will be calculated as follows: timeout = min(insert_keeper_retry_max_backoff_ms, latest_timeout * 2) For example, if insert_keeper_retry_initial_backoff_ms=100, insert_keeper_retry_max_backoff_ms=10000 and insert_keeper_max_retries=8 then timeouts will be 100, 200, 400, 800, 1600, 3200, 6400, 10000. Apart from fault tolerance, the retries aim to provide a better user experience - they allow to avoid returning an error during INSERT execution if Keeper is restarted, for example, due to an upgrade.

insert_keeper_retry_initial_backoff_ms

Type: UInt64
Default: 100
Tier: Production
Initial timeout(in milliseconds) to retry a failed Keeper request during INSERT query execution Possible values: - Positive integer. - 0 — No timeout

insert_keeper_retry_max_backoff_ms

Type: UInt64
Default: 10000
Tier: Production
Maximum timeout (in milliseconds) to retry a failed Keeper request during INSERT query execution Possible values: - Positive integer. - 0 — Maximum timeout is not limited

insert_null_as_default

Type: Bool
Default: 1
Tier: Production
Enables or disables the insertion of default values instead of NULL into columns with not nullable data type. If column type is not nullable and this setting is disabled, then inserting NULL causes an exception. If column type is nullable, then NULL values are inserted as is, regardless of this setting. This setting is applicable to INSERT ... SELECT queries. Note that SELECT subqueries may be concatenated with UNION ALL clause. Possible values: - 0 — Inserting NULL into a not nullable column causes an exception. - 1 — Default column value is inserted instead of NULL.

insert_quorum

Type: UInt64Auto
Default: 0
Tier: Production
:::note This setting is not applicable to SharedMergeTree, see SharedMergeTree consistency for more information. ::: Enables the quorum writes. - If insert_quorum < 2, the quorum writes are disabled. - If insert_quorum >= 2, the quorum writes are enabled. - If insert_quorum = 'auto', use majority number (number_of_replicas / 2 + 1) as quorum number. Quorum writes INSERT succeeds only when RawTree manages to correctly write data to the insert_quorum of replicas during the insert_quorum_timeout. If for any reason the number of replicas with successful writes does not reach the insert_quorum, the write is considered failed and RawTree will delete the inserted block from all the replicas where data has already been written. When insert_quorum_parallel is disabled, all replicas in the quorum are consistent, i.e. they contain data from all previous INSERT queries (the INSERT sequence is linearized). When reading data written using insert_quorum and insert_quorum_parallel is disabled, you can turn on sequential consistency for SELECT queries using select_sequential_consistency. RawTree generates an exception: - If the number of available replicas at the time of the query is less than the insert_quorum. - When insert_quorum_parallel is disabled and an attempt to write data is made when the previous block has not yet been inserted in insert_quorum of replicas. This situation may occur if the user tries to perform another INSERT query to the same table before the previous one with insert_quorum is completed. See also: - insert_quorum_timeout - insert_quorum_parallel - select_sequential_consistency

insert_quorum_parallel

Type: Bool
Default: 1
Tier: Production
:::note This setting is not applicable to SharedMergeTree, see SharedMergeTree consistency for more information. ::: Enables or disables parallelism for quorum INSERT queries. If enabled, additional INSERT queries can be sent while previous queries have not yet finished. If disabled, additional writes to the same table will be rejected. Possible values: - 0 — Disabled. - 1 — Enabled. See also: - insert_quorum - insert_quorum_timeout - select_sequential_consistency

insert_quorum_timeout

Type: Milliseconds
Default: 600000
Tier: Production
Write to a quorum timeout in milliseconds. If the timeout has passed and no write has taken place yet, RawTree will generate an exception and the client must repeat the query to write the same block to the same or any other replica. See also: - insert_quorum - insert_quorum_parallel - select_sequential_consistency

insert_shard_id

Type: UInt64
Default: 0
Tier: Production
If not 0, specifies the shard of Distributed table into which the data will be inserted synchronously. If insert_shard_id value is incorrect, the server will throw an exception. To get the number of shards on requested_cluster, you can check server config or use this query: sql SELECT uniq(shard_num) FROM system.clusters WHERE cluster = 'requested_cluster'; Possible values: - 0 — Disabled. - Any number from 1 to shards_num of corresponding Distributed table. Example Query: sql CREATE TABLE x AS system.numbers ENGINE = MergeTree ORDER BY number; CREATE TABLE x_dist AS x ENGINE = Distributed('test_cluster_two_shards_localhost', currentDatabase(), x); INSERT INTO x_dist SELECT * FROM numbers(5) SETTINGS insert_shard_id = 1; SELECT * FROM x_dist ORDER BY number ASC; Result: text ┌─number─┐ │ 0 │ │ 0 │ │ 1 │ │ 1 │ │ 2 │ │ 2 │ │ 3 │ │ 3 │ │ 4 │ │ 4 │ └────────┘

interactive_delay

Type: UInt64
Default: 100000
Tier: Production
The interval in microseconds for checking whether request execution has been canceled and sending the progress.

intersect_default_mode

Type: SetOperationMode
Default: ALL
Tier: Production
Set default mode in INTERSECT query. Possible values: empty string, 'ALL', 'DISTINCT'. If empty, query without mode will throw exception.

interval_output_format

Type: IntervalOutputFormat
Default: numeric
Tier: Production
Allows choosing different output formats of the text representation of interval types. Possible values: - kusto - KQL-style output format. RawTree outputs intervals in KQL format. For example, toIntervalDay(2) would be formatted as 2.00:00:00. Please note that for interval types of varying length (ie. IntervalMonth and IntervalYear) the average number of seconds per interval is taken into account. - numeric - Numeric output format. RawTree outputs intervals as their underlying numeric representation. For example, toIntervalDay(2) would be formatted as 2. See also: - Interval

into_outfile_create_parent_directories

Type: Bool
Default: 0
Tier: Production
Automatically create parent directories when using INTO OUTFILE if they do not already exists.

jemalloc_collect_profile_samples_in_trace_log

Type: Bool
Default: 0
Tier: Production
Collect jemalloc allocation and deallocation samples in trace log.

jemalloc_enable_profiler

Type: Bool
Default: 0
Tier: Production
Enable jemalloc profiler for the query. Jemalloc will sample allocations and all deallocations for sampled allocations. Profiles can be flushed using SYSTEM JEMALLOC FLUSH PROFILE which can be used for allocation analysis. Samples can also be stored in system.trace_log using config jemalloc_collect_global_profile_samples_in_trace_log or with query setting jemalloc_collect_profile_samples_in_trace_log. See Allocation Profiling

jemalloc_profile_text_collapsed_use_count

Type: Bool
Default: 0
Tier: Production
When using the 'collapsed' output format for jemalloc heap profile, aggregate by allocation count instead of bytes. When false (default), each stack is weighted by live bytes; when true, by live allocation count.

jemalloc_profile_text_output_format

Type: JemallocProfileFormat
Default: collapsed
Tier: Production
Output format for jemalloc heap profile in system.jemalloc_profile_text table. Can be: 'raw' (raw profile), 'symbolized' (jeprof format with symbols), or 'collapsed' (FlameGraph format).

jemalloc_profile_text_symbolize_with_inline

Type: Bool
Default: 1
Tier: Production
Whether to include inline frames when symbolizing jemalloc heap profile. When enabled, inline frames are included which can slow down symbolization process drastically; when disabled, they are skipped. Only affects 'symbolized' and 'collapsed' output formats.

join_algorithm

Type: JoinAlgorithm
Default: direct,parallel_hash,hash,ie_join
Tier: Production
Specifies which JOIN algorithm is used. Several algorithms can be specified, and an available one would be chosen for a particular query based on kind/strictness and table engine. Most algorithms affect a query only when they are the one selected for it. Some, however, change planning merely by being listed — even as a lower-priority fallback that is not ultimately selected — because the decision is made before the algorithm is picked. There are two such effects: - Join-key type inference becomes stricter (a merge join cannot join keys of different types, for example String and Nullable(String)). This can change the result types of USING columns, and can make a join into a Join-engine table fail with TYPE_MISMATCH. Triggered by full_sorting_merge and parallel_full_sorting_merge. - ORDER BY ... LIMIT on the preserved side of a join gets an explicit sort instead of a read in primary-key order, because the join is assumed to break the ordered read (a merge join inserts its own pre-join sort; a partial merge join re-sorts the left blocks; a join that can produce delayed blocks does not propagate the ordered read either). The result is the same, the plan is less efficient. Triggered by full_sorting_merge, parallel_full_sorting_merge, partial_merge, prefer_partial_merge, grace_hash and auto, and also by a non-zero max_bytes_before_external_join / max_bytes_ratio_before_external_join. Both apply even when the query eventually runs with hash or another algorithm. If this is undesirable, do not list the algorithms above in join_algorithm for the affected queries. Possible values: - grace_hash Grace hash join is used. Grace hash provides an algorithm option that provides performant complex joins while limiting memory use. The first phase of a grace join reads the right table and splits it into N buckets depending on the hash value of key columns (initially, N is grace_hash_join_initial_buckets). This is done in a way to ensure that each bucket can be processed independently. Rows from the first bucket are added to an in-memory hash table while the others are saved to disk. If the hash table grows beyond the memory limit (e.g., as set by max_bytes_in_join, the number of buckets is increased and the assigned bucket for each row. Any rows which don't belong to the current bucket are flushed and reassigned. Supports INNER/LEFT/RIGHT/FULL ALL/ANY JOIN. - hash Hash join algorithm is used. The most generic implementation that supports all combinations of kind and strictness and multiple join keys that are combined with OR in the JOIN ON section. When using the hash algorithm, the right part of JOIN is uploaded into RAM. - parallel_hash A variation of hash join that splits the data into buckets and builds several hashtables instead of one concurrently to speed up this process. When using the parallel_hash algorithm, the right part of JOIN is uploaded into RAM. - partial_merge A variation of the sort-merge algorithm, where only the right table is fully sorted. The RIGHT JOIN and FULL JOIN are supported only with ALL strictness (SEMI, ANTI, ANY, and ASOF are not supported). When using the partial_merge algorithm, RawTree sorts the data and dumps it to the disk. The partial_merge algorithm in RawTree differs slightly from the classic realization. First, RawTree sorts the right table by joining keys in blocks and creates a min-max index for sorted blocks. Then it sorts parts of the left table by the join key and joins them over the right table. The min-max index is also used to skip unneeded right table blocks. - direct The direct (also known as nested loop) algorithm performs a lookup in the right table using rows from the left table as keys. It's supported by special storages such as Dictionary, EmbeddedRocksDB, and MergeTree tables. For MergeTree tables, the algorithm pushes join key filters directly to the storage layer. This can be more efficient when the key can use the table's primary key index for lookups, otherwise it performs full scans of the right table for each left table block. Supports INNER and LEFT joins and only single-column equality join keys without other conditions. - auto When set to auto, hash join is tried first, and the algorithm is switched on the fly to another algorithm if the memory limit is violated. - full_sorting_merge Sort-merge algorithm with full sorting of joined tables before joining. - ie_join The sort-based IEJoin algorithm for a JOIN whose ON section has two inequality comparisons (<, <=, >, >=) between expressions of the joined tables. Supports ALL INNER/LEFT/RIGHT/FULL JOIN and SEMI/ANTI LEFT/RIGHT JOIN. The position in the list sets the priority: listed after other algorithms, as in the default value, IEJoin is used only when they do not apply (the ON section has no equality conditions); listed first, it is used whenever the ON section has two inequality conditions. The remaining conditions (including equalities) are applied as a filter over the join result for ALL INNER JOIN, and evaluated inside the operator as a residual condition affecting matching for the other kinds. Without ie_join in the list, an INNER JOIN with only inequality conditions is executed as a CROSS JOIN with a filter, and the other kinds are not supported. Both inputs are accumulated in memory before joining: max_rows_in_join and max_bytes_in_join limit the accumulated input of both sides together (not just the right side), with the action on overflow set by join_overflow_mode; the sort indexes the operator builds on top of the accumulated input are not counted against the limit. The join operator itself runs in a single thread; only the pre-join sorts of the inputs are parallelized. - parallel_full_sorting_merge Same as full_sorting_merge, but hash-compatible equality joins are sharded by the hash of the join keys into independent per-shard merge joins that run in parallel (up to max_threads), instead of a single merge join. This keeps the low, streaming memory usage of a merge join while using all threads, and the result is not ordered. Hash-sharding by the join keys is applied only to plain equality joins on key types whose hash agrees with the merge-join comparison, and only when neither side is already sorted. It is skipped in these cases: - ASOF joins, and floating-point / JSON / Object / Dynamic key types: their hashes are not consistent with the merge-join comparison, so equal keys could land in different shards. - Sides that are already sorted (a MergeTree read in order, or any pre-sorted input): an order-preserving scatter into the per-shard merges can deadlock the pipeline. The in-order read and its read_in_order_use_virtual_row optimization are kept instead. - While the initiator builds a distributed plan (make_distributed_plan), because the scattered sort is not serializable for remote execution. The local single-fragment plan and the per-worker fragments re-optimize with that setting disabled, so they can still be sharded. Skipping it disables only this rewrite, not parallelism in general: the join runs as a single full_sorting_merge, and MergeTree sides read in order can still be sharded at the source by primary-key ranges (which order by the same comparison the join uses, so equal keys stay together) when query_plan_join_shard_by_pk_ranges is enabled. - prefer_partial_merge RawTree always tries to use partial_merge join if possible, otherwise, it uses hash. Deprecated, same as partial_merge,hash. - default (deprecated) Legacy value, please don't use anymore. Same as direct,hash, i.e. try to use direct join and hash join (in this order).

join_any_take_last_row

Type: Bool
Default: 0
Tier: Production
Changes the behaviour of join operations with ANY strictness when the right table has more than one matching row for a key. :::note This setting applies to Join engine tables and hash-based join algorithms. If a join is built in parallel, the order of rows can be non-deterministic. This means that join_any_take_last_row = 1 can return a non-deterministic row for ANY JOIN queries. ::: Possible values: - 0 — If the right table has more than one matching row, only the first one found is joined. - 1 — If the right table has more than one matching row, only the last one found is joined. See also: - JOIN clause - Join table engine - join_default_strictness

join_default_strictness

Type: JoinStrictness
Default: ALL
Tier: Production
Sets default strictness for JOIN clauses. Possible values: - ALL — If the right table has several matching rows, RawTree creates a Cartesian product from matching rows. This is the normal JOIN behaviour from standard SQL. - ANY — If the right table has several matching rows, only the first one found is joined. If the right table has only one matching row, the results of ANY and ALL are the same. - ASOF — For joining sequences with an uncertain match. - Empty string — If ALL or ANY is not specified in the query, RawTree throws an exception.

join_on_disk_max_files_to_merge

Type: UInt64
Default: 64
Tier: Production
Limits the number of files allowed for parallel sorting in MergeJoin operations when they are executed on disk. The bigger the value of the setting, the more RAM is used and the less disk I/O is needed. Possible values: - Any positive integer, starting from 2.

join_output_by_rowlist_perkey_rows_threshold

Type: UInt64
Default: 5
Tier: Production
The lower limit of per-key average rows in the right table to determine whether to output by row list in hash join.

join_overflow_mode

Type: OverflowMode
Default: throw
Tier: Production
Defines what action RawTree performs when a join reaches any of the following limits: - max_bytes_in_join - max_rows_in_join This setting is honored only by the hash, parallel_hash, and ie_join join_algorithm values. Other algorithms (for example, partial_merge, grace_hash, auto) handle the limits differently — by spilling to disk, re-partitioning, or switching strategy — see join_algorithm. Possible values: - THROW — RawTree throws an exception and stops the query. - BREAK — RawTree stops the query and does not throw an exception. Default value: THROW. See Also - JOIN clause - Join table engine

join_runtime_bloom_filter_bytes

Type: UInt64
Default: 524288
Tier: Experimental
Size in bytes of a bloom filter used as JOIN runtime filter (see enable_join_runtime_filters setting).

join_runtime_bloom_filter_hash_functions

Type: UInt64
Default: 3
Tier: Experimental
Number of hash functions in a bloom filter used as JOIN runtime filter (see enable_join_runtime_filters setting).

join_runtime_bloom_filter_max_ratio_of_set_bits

Type: Double
Default: 0.7
Tier: Experimental
If the number of set bits in a runtime bloom filter exceeds this ratio the filter is completely disabled to reduce the overhead.

join_runtime_filter_blocks_to_skip_before_reenabling

Type: UInt64
Default: 30
Tier: Experimental
Number of blocks that are skipped before trying to dynamically re-enable a runtime filter that previously was disabled due to poor filtering ratio.

join_runtime_filter_exact_values_limit

Type: UInt64
Default: 10000
Tier: Experimental
Maximum number of elements in runtime filter that are stored as is in a set, when this threshold is exceeded it switches to bloom filter.

join_runtime_filter_from_fixed_hash_table

Type: Bool
Default: 1
Tier: Production
When the hash join build side was converted to a FixedHashMap (see enable_join_fixed_hash_table_conversion), use that hash map directly as the runtime filter.

join_runtime_filter_min_probe_rows

Type: UInt64
Default: 1000
Tier: Experimental
If, at query planning time, the probe side of a JOIN is estimated to produce no more than this number of rows, the JOIN runtime filter is not created. Building and applying a runtime filter for a tiny probe side costs more than it saves. Set to 0 to always create the runtime filter regardless of the estimated probe size.

join_runtime_filter_pass_ratio_threshold_for_disabling

Type: Double
Default: 0.7
Tier: Experimental
If ratio of passed rows to checked rows is greater than this threshold the runtime filter is considered as poorly performing and is disabled for the next join_runtime_filter_blocks_to_skip_before_reenabling blocks to reduce the overhead.

join_runtime_filter_size_from_hash_table_stats

Type: Bool
Default: 1
Tier: Production
Use hash table size statistics collected from previous executions to size the JOIN runtime filter. When disabled, fall back to the fixed join_runtime_bloom_filter_bytes.

join_to_sort_maximum_table_rows

Type: UInt64
Default: 10000
Tier: Experimental
The maximum number of rows in the right table to determine whether to rerange the right table by key in left or inner join.

join_to_sort_minimum_perkey_rows

Type: UInt64
Default: 40
Tier: Experimental
The lower limit of per-key average rows in the right table to determine whether to rerange the right table by key in left or inner join. This setting ensures that the optimization is not applied for sparse table keys

join_use_nulls

Type: Bool
Default: 0
Tier: Production
Sets the type of JOIN behaviour. When merging tables, empty cells may appear. RawTree fills them differently based on this setting. Possible values: - 0 — The empty cells are filled with the default value of the corresponding field type. - 1 — JOIN behaves the same way as in standard SQL. The type of the corresponding field is converted to Nullable, and empty cells are filled with NULL.

joined_block_split_single_row

Type: Bool
Default: 0
Tier: Production
Allow to chunk hash join result by rows corresponding to single row from left table. This may reduce memory usage in case of row with many matches in right table, but may increase CPU usage. Note that max_joined_block_size_rows != 0 is mandatory for this setting to have effect. The max_joined_block_size_bytes combined with this setting is helpful to avoid excessive memory usage in case of skewed data with some large rows having many matches in right table.

joined_subquery_requires_alias

Type: Bool
Default: 1
Tier: Production
Force joined subqueries and table functions to have aliases for correct name qualification.

json_type_escape_dots_in_keys

Type: Bool
Default: 0
Tier: Production
When enabled, dots in JSON keys will be escaped during parsing.

kafka_disable_num_consumers_limit

Type: Bool
Default: 0
Tier: Production
Disable limit on kafka_num_consumers that depends on the number of available CPU cores.

kafka_max_wait_ms

Type: Milliseconds
Default: 5000
Tier: Production
The wait time in milliseconds for reading messages from Kafka before retry. Possible values: - Positive integer. - 0 — Infinite timeout. See also: - Apache Kafka

keeper_map_strict_mode

Type: Bool
Default: 0
Tier: Production
Enforce additional checks during operations on KeeperMap. E.g. throw an exception on an insert for already existing key

keeper_max_retries

Type: UInt64
Default: 10
Tier: Production
Max retries for general keeper operations

keeper_retry_initial_backoff_ms

Type: UInt64
Default: 100
Tier: Production
Initial backoff timeout for general keeper operations

keeper_retry_max_backoff_ms

Type: UInt64
Default: 5000
Tier: Production
Max backoff timeout for general keeper operations

least_greatest_legacy_null_behavior

Type: Bool
Default: 0
Tier: Production
If enabled, functions 'least' and 'greatest' return NULL if one of their arguments is NULL.

legacy_column_name_of_tuple_literal

Type: Bool
Default: 0
Tier: Production
List all names of element of large tuple literals in their column names instead of hash. This settings exists only for compatibility reasons. It makes sense to set to 'true', while doing rolling update of cluster from version lower than 21.7 to higher.

lightweight_delete_mode

Type: LightweightDeleteMode
Default: alter_update
Tier: Production
A mode of internal update query that is executed as a part of lightweight delete. Possible values: - alter_update - run ALTER UPDATE query that creates a heavyweight mutation. - lightweight_update - run lightweight update if possible, run ALTER UPDATE otherwise. - lightweight_update_force - run lightweight update if possible, throw otherwise.

lightweight_deletes_sync

Type: UInt64
Default: 2
Tier: Production
The same as mutations_sync, but controls only execution of lightweight deletes. Possible values: | Value | Description | |-------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | 0 | Mutations execute asynchronously. | | 1 | The query waits for the lightweight deletes to complete on the current server. | | 2 | The query waits for the lightweight deletes to complete on all replicas (if they exist). | | 3 | The query waits only for active replicas. Supported only for SharedMergeTree. For ReplicatedMergeTree it behaves the same as mutations_sync = 2.| See Also - Synchronicity of ALTER Queries - Mutations Cloud default value: 1.

limit

Type: Double
Default: 0
Tier: Production
Sets the maximum number of rows to get from the query result. It adjusts the value set by the LIMIT clause. The value is passed through to LIMIT and accepts everything that LIMIT accepts, including negative values (count from the end of the result) and fractions in (0, 1) (interpreted as a share of the result). Possible values: - 0 — The number of rows is not limited. - Positive integer — exact number of rows. - Negative integer — return the last N rows. - A real number in the open range (0, 1) — return that fraction of the result. This setting shapes result-producing SELECT / UNION queries. For a write query (INSERT … SELECT, CREATE … AS SELECT) it takes effect only when the source SELECT carries it in its own SETTINGS clause; a value inherited from a profile or session, or set on the INSERT / CREATE statement itself, does not propagate into the source SELECT — the same non-propagation rule that applies to any other setting.

load_balancing

Type: LoadBalancing
Default: random
Tier: Production
Specifies the algorithm of replicas selection that is used for distributed query processing. RawTree supports the following algorithms of choosing replicas: - Random (by default) - Nearest hostname - Hostname levenshtein distance - Hostname longest common prefix - Hostname longest common suffix - In order - First or random - Round robin See also: - distributed_replica_max_ignored_errors ### Random (by Default) sql load_balancing = random The number of errors is counted for each replica. The query is sent to the replica with the fewest errors, and if there are several of these, to anyone of them. Disadvantages: Server proximity is not accounted for; if the replicas have different data, you will also get different data. ### Nearest Hostname sql load_balancing = nearest_hostname The number of errors is counted for each replica. Every 5 minutes, the number of errors is integrally divided by 2. Thus, the number of errors is calculated for a recent time with exponential smoothing. If there is one replica with a minimal number of errors (i.e. errors occurred recently on the other replicas), the query is sent to it. If there are multiple replicas with the same minimal number of errors, the query is sent to the replica with a hostname that is most similar to the server's hostname in the config file (for the number of different characters in identical positions, up to the minimum length of both hostnames). For instance, example01-01-1 and example01-01-2 are different in one position, while example01-01-1 and example01-02-2 differ in two places. This method might seem primitive, but it does not require external data about network topology, and it does not compare IP addresses, which would be complicated for our IPv6 addresses. Thus, if there are equivalent replicas, the closest one by name is preferred. We can also assume that when sending a query to the same server, in the absence of failures, a distributed query will also go to the same servers. So even if different data is placed on the replicas, the query will return mostly the same results. ### Hostname levenshtein distance sql load_balancing = hostname_levenshtein_distance Just like nearest_hostname, but it compares hostname in a levenshtein distance manner. For example: text example-clickhouse-0-0 ample-clickhouse-0-0 1 example-clickhouse-0-0 example-clickhouse-1-10 2 example-clickhouse-0-0 example-clickhouse-12-0 3 ### Hostname longest common prefix sql load_balancing = hostname_longest_common_prefix Just like nearest_hostname, but the replica whose hostname shares the longest common prefix with the local hostname is preferred (the longer the common prefix, the higher the priority). Unlike nearest_hostname, which counts differing characters position by position, this strategy is not confused by hostnames whose numeric segments have different lengths. For example, for the local hostname sfe301: text sfe301 sde301 1 sfe301 sfe10101 3 sfe301 sde505 1 Here sfe10101 is preferred because it shares the longest common prefix (sfe, length 3) with sfe301. Replicas with equal common prefix length are chosen at random. In particular, when no replica shares any prefix with the local hostname (all common prefix lengths are zero), this strategy behaves exactly like random. ### Hostname longest common suffix sql load_balancing = hostname_longest_common_suffix Just like hostname_longest_common_prefix, but the longest common suffix is compared instead of the prefix. This is useful when the data center identity is encoded as a suffix of the hostname. For example, for the local hostname et46gtghn.qc.localdomain: text et46gtghn.qc.localdomain tr676ddgh.td.localdomain 12 et46gtghn.qc.localdomain ab999.qc.localdomain 15 Here ab999.qc.localdomain is preferred because it shares the longest common suffix (.qc.localdomain, length 15) with et46gtghn.qc.localdomain. Replicas with equal common suffix length are chosen at random. In particular, when no replica shares any suffix with the local hostname (all common suffix lengths are zero), this strategy behaves exactly like random. ### In Order sql load_balancing = in_order Replicas with the same number of errors are accessed in the same order as they are specified in the configuration. This method is appropriate when you know exactly which replica is preferable. ### First or Random sql load_balancing = first_or_random This algorithm chooses the first replica in the set or a random replica if the first is unavailable. It's effective in cross-replication topology setups, but useless in other configurations. The first_or_random algorithm solves the problem of the in_order algorithm. With in_order, if one replica goes down, the next one gets a double load while the remaining replicas handle the usual amount of traffic. When using the first_or_random algorithm, the load is evenly distributed among replicas that are still available. It's possible to explicitly define what the first replica is by using the setting load_balancing_first_offset. This gives more control to rebalance query workloads among replicas. ### Round Robin sql load_balancing = round_robin This algorithm uses a round-robin policy across replicas with the same number of errors (only the queries with round_robin policy is accounted).

load_balancing_first_offset

Type: UInt64
Default: 0
Tier: Production
Which replica to preferably send a query when FIRST_OR_RANDOM load balancing strategy is used.

load_marks_asynchronously

Type: Bool
Default: 0
Tier: Production
Load MergeTree marks asynchronously Cloud default value: 1.

local_filesystem_read_method

Type: String
Default: pread_threadpool
Tier: Production
Method of reading data from local filesystem, one of: read, pread, mmap, io_uring, pread_threadpool. The 'pread_threadpool' method hands a read off to a thread pool, unless the data is already in the page cache, which is checked with the preadv2 system call and the RWF_NOWAIT flag. That check needs Linux 5.11 or newer, and the system call must not be rejected by a seccomp profile of a container runtime. It is checked on startup whether the system call can be used, and if it cannot, the default value of this setting is switched to 'pread', because a thread pool hand-off for every read, including the reads that are served from the page cache, is expensive; the reason is reported in the server log. A seccomp profile is detected only if it rejects the system call with an error code, which is what container runtimes do; a profile that terminates the process instead cannot be detected. A value set explicitly, in the configuration or with SET, is not switched. The 'io_uring' method is experimental and does not work for Log, TinyLog, StripeLog, File, Set and Join, and other tables with append-able files in presence of concurrent reads and writes. If you read various articles about 'io_uring' on the Internet, don't be blinded by them. It is not a better method of reading files, unless the case of a large amount of small IO requests, which is not the case in RawTree. There are no reasons to enable 'io_uring'.

local_filesystem_read_prefetch

Type: Bool
Default: 0
Tier: Production
Should use prefetching when reading data from local filesystem.

lock_acquire_timeout

Type: Seconds
Default: 120
Tier: Production
Defines how many seconds a locking request waits before failing. Locking timeout is used to protect from deadlocks while executing read/write operations with tables. When the timeout expires and the locking request fails, the RawTree server throws an exception "Locking attempt timed out! Possible deadlock avoided. Client should retry." with error code DEADLOCK_AVOIDED. Possible values: - Positive integer (in seconds). - 0 — No locking timeout.

log_comment

Type: String
Default: ``
Tier: Production
Specifies the value for the log_comment field of the system.query_log table and comment text for the server log. It can be used to improve the readability of server logs. Additionally, it helps to select queries related to the test from the system.query_log after running rawtree-test. Possible values: - Any string no longer than max_query_size. If the max_query_size is exceeded, the server throws an exception. Example Query: sql SET log_comment = 'log_comment test', log_queries = 1; SELECT 1; SYSTEM FLUSH LOGS; SELECT type, query FROM system.query_log WHERE log_comment = 'log_comment test' AND event_date >= yesterday() ORDER BY event_time DESC LIMIT 2; Result: text ┌─type────────┬─query─────┐ │ QueryStart │ SELECT 1; │ │ QueryFinish │ SELECT 1; │ └─────────────┴───────────┘

log_formatted_queries

Type: Bool
Default: 0
Tier: Production
Allows to log formatted queries to the system.query_log system table (populates formatted_query column in the system.query_log). Possible values: - 0 — Formatted queries are not logged in the system table. - 1 — Formatted queries are logged in the system table.

log_processors_profiles

Type: Bool
Default: 1
Tier: Production
Write time that processor spent during execution/waiting for data to system.processors_profile_log table. See also: - system.processors_profile_log - EXPLAIN PIPELINE

log_profile_events

Type: Bool
Default: 1
Tier: Production
Log query performance statistics into the query_log, query_thread_log and query_views_log.

log_queries

Type: Bool
Default: 1
Tier: Production
Setting up query logging. Queries sent to RawTree with this setup are logged according to the rules in the query_log server configuration parameter. Example: text log_queries=1

log_queries_cut_to_length

Type: UInt64
Default: 100000
Tier: Production
If query length is greater than a specified threshold (in bytes), then cut query when writing to query log. Also limit the length of printed query in ordinary text log.

log_queries_min_query_duration_ms

Type: Milliseconds
Default: 0
Tier: Production
If enabled (non-zero), queries faster than the value of this setting will not be logged (you can think about this as a long_query_time for MySQL Slow Query Log), and this basically means that you will not find them in the following tables: - system.query_log - system.query_thread_log Only the queries with the following type will get to the log: - QUERY_FINISH - EXCEPTION_WHILE_PROCESSING - Type: milliseconds - Default value: 0 (any query)

log_queries_min_type

Type: LogQueriesType
Default: QUERY_START
Tier: Production
query_log minimal type to log. Possible values: - QUERY_START (=1) - QUERY_FINISH (=2) - EXCEPTION_BEFORE_START (=3) - EXCEPTION_WHILE_PROCESSING (=4) Can be used to limit which entities will go to query_log, say you are interested only in errors, then you can use EXCEPTION_WHILE_PROCESSING: text log_queries_min_type='EXCEPTION_WHILE_PROCESSING'

log_queries_probability

Type: Float
Default: 1
Tier: Production
Allows a user to write to query_log, query_thread_log, and query_views_log system tables only a sample of queries selected randomly with the specified probability. It helps to reduce the load with a large volume of queries in a second. Possible values: - 0 — Queries are not logged in the system tables. - Positive floating-point number in the range [0..1]. For example, if the setting value is 0.5, about half of the queries are logged in the system tables. - 1 — All queries are logged in the system tables.

log_query_settings

Type: Bool
Default: 1
Tier: Production
Log query settings into the query_log and OpenTelemetry span log.

log_query_threads

Type: Bool
Default: 0
Tier: Production
Setting up query threads logging. Query threads log into the system.query_thread_log table. This setting has effect only when log_queries is true. Queries' threads run by RawTree with this setup are logged according to the rules in the query_thread_log server configuration parameter. Possible values: - 0 — Disabled. - 1 — Enabled. Example text log_query_threads=1

log_query_views

Type: Bool
Default: 1
Tier: Production
Setting up query views logging. When a query run by RawTree with this setting enabled has associated views (materialized or live views), they are logged in the query_views_log server configuration parameter. Example: text log_query_views=1

low_cardinality_allow_in_native_format

Type: Bool
Default: 1
Tier: Production
Allows or restricts using the LowCardinality data type with the Native format. If usage of LowCardinality is restricted, RawTree server converts LowCardinality-columns to ordinary ones for SELECT queries, and convert ordinary columns to LowCardinality-columns for INSERT queries. This setting is required mainly for third-party clients which do not support LowCardinality data type. Possible values: - 1 — Usage of LowCardinality is not restricted. - 0 — Usage of LowCardinality is restricted.

low_cardinality_max_dictionary_size

Type: UInt64
Default: 8192
Tier: Production
Sets a maximum size in rows of a shared global dictionary for the LowCardinality data type that can be written to a storage file system. This setting prevents issues with RAM in case of unlimited dictionary growth. All the data that can't be encoded due to maximum dictionary size limitation RawTree writes in an ordinary method. Possible values: - Any positive integer.

low_cardinality_use_single_dictionary_for_part

Type: Bool
Default: 0
Tier: Production
Turns on or turns off using of single dictionary for the data part. By default, the RawTree server monitors the size of dictionaries and if a dictionary overflows then the server starts to write the next one. To prohibit creating several dictionaries set low_cardinality_use_single_dictionary_for_part = 1. Possible values: - 1 — Creating several dictionaries for the data part is prohibited. - 0 — Creating several dictionaries for the data part is not prohibited.

low_priority_query_wait_time_ms

Type: Milliseconds
Default: 1000
Tier: Beta
When the query prioritization mechanism is employed (see setting priority), low-priority queries wait for higher-priority queries to finish. This setting specifies the duration of waiting.

make_distributed_plan

Type: Bool
Default: 0
Tier: Experimental
Make distributed query plan. Enabling it automatically adjusts settings that control features not supported by distributed query plans yet: - enable_parallel_replicas = 0 and automatic_parallel_replicas_mode = 0 — the distributed plan does its own work distribution; - correlated_subqueries_use_in_memory_buffer = 0; - use_skip_indexes_on_data_read = 0; - compile_expressions = 0; - query_plan_direct_read_from_text_index = 0.

materialize_skip_indexes_on_insert

Type: Bool
Default: 1
Tier: Production
If INSERTs build and store skip indexes. If disabled, skip indexes will only be built and stored during merges or by explicit MATERIALIZE INDEX. See also exclude_materialize_skip_indexes_on_insert.

materialize_statistics_on_insert

Type: Bool
Default: 1
Tier: Production
If statistics are build and materialized for newly inserted parts. Even if disabled, statistics are still be build and stored during merges or by explicit MATERIALIZE STATISTICS. Only tables whose current size plus the size of the block being written, does not exceed materialize_statistics_on_insert_max_table_size are affected.

materialize_statistics_on_insert_max_table_size

Type: UInt64
Default: 26843545600
Tier: Production
Only build and store column statistics for newly inserted parts (see materialize_statistics_on_insert) for tables whose current size plus the block being written, does not exceed this value. 0 means no size limit.

materialize_ttl_after_modify

Type: Bool
Default: 1
Tier: Production
Apply TTL for old data, after ALTER MODIFY TTL query

materialized_views_ignore_errors

Type: Bool
Default: 0
Tier: Production
If enabled, exceptions thrown while pushing data to a dependent materialized view (in its SELECT or in the inner table sink) are logged as a warning and the INSERT statement succeeds. If disabled (default), such an exception propagates and the INSERT statement fails. This setting controls only error reporting. It does not roll back a write to the source table, and it does not guarantee whether the original block has already been committed to the source table when an error occurs in a dependent view's pipeline. When disabled (default), the INSERT fails on a view error — retry it with insert deduplication (insert_deduplicate, deduplicate_blocks_in_dependent_materialized_views) for exactly-once delivery to the source table and all dependent views. When enabled, the INSERT reports success despite partial delivery to failing views and their downstream chains; use this only when source-table writes must not be blocked by view-side problems (for example, system.*_log tables). See the CREATE VIEW docs for full semantics.

materialized_views_populate_atomically

Type: Bool
Default: 1
Tier: Production
Make CREATE MATERIALIZED VIEW ... POPULATE atomic: the view is subscribed to new inserts of the source table and a snapshot of the existing data is taken together, under a brief exclusive lock on the source table, so that every row inserted concurrently with the population is delivered to the view exactly once (neither missed nor duplicated). The (possibly long-running) population then reads the pinned snapshot without holding any lock. This is local insert-path atomicity: the exclusive lock only serializes with inserts that acquire this source table's storage lock on the same server, so the exactly-once guarantee covers inserts arriving through this server. It is not a cluster-wide guarantee - rows inserted on another replica of a ReplicatedMergeTree source, or through a distributed write path (for example, into a Distributed table or via ON CLUSTER), concurrently with the population can still be missed or duplicated. This requires the source table to support reading a pinned point-in-time snapshot (the MergeTree family and Memory). For any other source (a view, Distributed, Merge, the Log family, or a table not in an Atomic database) the population falls back to the legacy, non-atomic behavior (recorded in the server log): existing data is read with a separate, non-coordinated snapshot, so rows inserted during the population can be missed or duplicated. Set this setting to false to force the legacy behavior for all sources. Applies to plain CREATE MATERIALIZED VIEW only; CREATE OR REPLACE / REPLACE always use the legacy non-atomic population, and so does a view created in a Replicated database (where POPULATE requires database_replicated_allow_heavy_create), because a failed population could not be rolled back consistently on all replicas there.

materialized_views_squash_parallel_inserts

Type: Bool
Default: 1
Tier: Production
Squash inserts to materialized views destination table of a single INSERT query from parallel inserts to reduce amount of generated parts. If set to false and parallel_view_processing is enabled, INSERT query will generate part in the destination table for each max_insert_thread.

max_analyze_depth

Type: UInt64
Default: 5000
Tier: Production
Maximum number of analyses performed by interpreter.

max_ast_depth

Type: UInt64
Default: 1000
Tier: Production
The maximum nesting depth of a query syntactic tree. If exceeded, an exception is thrown. :::note At this time, it isn't checked during parsing, but only after parsing the query. This means that a syntactic tree that is too deep can be created during parsing, but the query will fail. :::

max_ast_elements

Type: UInt64
Default: 50000
Tier: Production
The maximum number of elements in a query syntactic tree. If exceeded, an exception is thrown. :::note At this time, it isn't checked during parsing, but only after parsing the query. This means that a syntactic tree that is too deep can be created during parsing, but the query will fail. :::

max_autoincrement_series

Type: UInt64
Default: 1000
Tier: Production
The limit on the number of series created by the generateSerialID function. As each series represents a node in Keeper, it is recommended to have no more than a couple of millions of them.

max_backup_bandwidth

Type: UInt64
Default: 0
Tier: Production
The maximum read speed in bytes per second for particular backup on server. Zero means unlimited.

max_block_size

Type: NonZeroUInt64
Default: 65409
Tier: Production
In RawTree, data is processed by blocks, which are sets of column parts. The internal processing cycles for a single block are efficient but there are noticeable costs when processing each block. The max_block_size setting indicates the recommended maximum number of rows to include in a single block when loading data from tables. Blocks the size of max_block_size are not always loaded from the table: if RawTree determines that less data needs to be retrieved, a smaller block is processed. The block size should not be too small to avoid noticeable costs when processing each block. It should also not be too large to ensure that queries with a LIMIT clause execute quickly after processing the first block. When setting max_block_size, the goal should be to avoid consuming too much memory when extracting a large number of columns in multiple threads and to preserve at least some cache locality.

max_bytes_before_external_group_by

Type: UInt64
Default: 0
Tier: Production
Cloud default value: half the memory amount per replica. Enables or disables execution of GROUP BY clauses in external memory. (See GROUP BY in external memory) Possible values: - Maximum volume of RAM (in bytes) that can be used by the single GROUP BY operation. - 0 — GROUP BY in external memory disabled. :::note If memory usage during GROUP BY operations is exceeding this threshold in bytes, activate the 'external aggregation' mode (spill data to disk). The recommended value is half of the available system memory. :::

max_bytes_before_external_join

Type: UInt64
Default: 0
Tier: Production
If set to a non-zero value and join_algorithm is hash, parallel_hash, default, or auto, the hash join will automatically be converted to grace hash join to enable spilling to disk when the right-side data exceeds this many bytes. When set to 0 (default), this absolute byte threshold is disabled, but automatic spilling may still occur via max_bytes_ratio_before_external_join (which defaults to 0.5); set both to 0 to fully disable automatic spilling. It prevents read in order through join optimization.

max_bytes_before_external_sort

Type: UInt64
Default: 0
Tier: Production
Cloud default value: half the memory amount per replica. Enables or disables execution of ORDER BY clauses in external memory. See ORDER BY Implementation Details If memory usage during ORDER BY operation exceeds this threshold in bytes, the 'external sorting' mode (spill data to disk) is activated. Possible values: - Maximum volume of RAM (in bytes) that can be used by the single ORDER BY operation. The recommended value is half of available system memory - 0 — ORDER BY in external memory disabled.

max_bytes_before_remerge_sort

Type: UInt64
Default: 1000000000
Tier: Production
In case of ORDER BY with LIMIT, when memory usage is higher than specified threshold, perform additional steps of merging blocks before final merge to keep just top LIMIT rows.

max_bytes_for_lazy_final

Type: UInt64
Default: 256000000
Tier: Production
Maximum number of bytes in the set for lazy FINAL optimization. If exceeded, falls back to normal FINAL.

max_bytes_in_distinct

Type: UInt64
Default: 0
Tier: Production
The maximum number of bytes of the state (in uncompressed bytes) in memory, which is used by a hash table when using DISTINCT.

max_bytes_in_join

Type: UInt64
Default: 0
Tier: Production
The maximum size in bytes of the right-side data structure (typically a hash table) used when joining tables. This setting applies to SELECT ... JOIN operations and the Join table engine. If a query contains multiple joins, RawTree checks this setting for every intermediate result. When the limit is reached, the action depends on the chosen join_algorithm — see that setting for the per-algorithm behavior (spill, re-partition, switch, or throw/break per join_overflow_mode). Possible values: - Positive integer. - 0 — Memory control is disabled.

max_bytes_in_set

Type: UInt64
Default: 0
Tier: Production
The maximum number of bytes (of uncompressed data) used by a set in the IN clause created from a subquery.

max_bytes_ratio_before_external_group_by

Type: Double
Default: 0.5
Tier: Production
The ratio of available memory that is allowed for GROUP BY. Once reached, external memory is used for aggregation. For example, if set to 0.6, GROUP BY will allow using 60% of the available memory (to server/user/merges) at the beginning of the execution, after that, it will start using external aggregation.

max_bytes_ratio_before_external_join

Type: Double
Default: 0.5
Tier: Production
The ratio of available memory that is allowed for JOIN. Once reached, the hash join will be converted to grace hash join to spill the right-side data to disk. For example, if set to 0.6, JOIN will allow using 60% of the available memory (to server/user/merges) for the right-side hash table at the beginning of the execution; after that, it starts spilling to disk. If both max_bytes_before_external_join and max_bytes_ratio_before_external_join are set, the smaller resulting threshold is used. If the ratio is 0, only the absolute setting applies. Has effect only when join_algorithm is hash, parallel_hash, default, or auto and a temporary data path is configured.

max_bytes_ratio_before_external_sort

Type: Double
Default: 0.5
Tier: Production
The ratio of available memory that is allowed for ORDER BY. Once reached, external sort is used. For example, if set to 0.6, ORDER BY will allow using 60% of available memory (to server/user/merges) at the beginning of the execution, after that, it will start using external sort. Note, that max_bytes_before_external_sort is still respected, spilling to disk will be done only if the sorting block is bigger then max_bytes_before_external_sort.

max_bytes_to_read

Type: UInt64
Default: 0
Tier: Production
The maximum number of bytes (of uncompressed data) that can be read from a table when running a query. The restriction is checked for each processed chunk of data, applied only to the deepest table expression and when reading from a remote server, checked only on the remote server.

max_bytes_to_read_leaf

Type: UInt64
Default: 0
Tier: Production
The maximum number of bytes (of uncompressed data) that can be read from a local table on a leaf node when running a distributed query. While distributed queries can issue a multiple sub-queries to each shard (leaf) - this limit will be checked only on the read stage on the leaf nodes and will be ignored on the merging of results stage on the root node. For example, a cluster consists of 2 shards and each shard contains a table with 100 bytes of data. A distributed query which is supposed to read all the data from both tables with setting max_bytes_to_read=150 will fail as in total it will be 200 bytes. A query with max_bytes_to_read_leaf=150 will succeed since leaf nodes will read 100 bytes at max. The restriction is checked for each processed chunk of data. :::note This setting is unstable with prefer_localhost_replica=1. :::

max_bytes_to_sort

Type: UInt64
Default: 0
Tier: Production
The maximum number of bytes before sorting. If more than the specified amount of uncompressed bytes have to be processed for ORDER BY operation, the behavior will be determined by the sort_overflow_mode which by default is set to throw.

max_bytes_to_transfer

Type: UInt64
Default: 0
Tier: Production
The maximum number of bytes (uncompressed data) that can be passed to a remote server or saved in a temporary table when the GLOBAL IN/JOIN section is executed.

max_columns_to_read

Type: UInt64
Default: 0
Tier: Production
The maximum number of columns that can be read from a table in a single query. If a query requires reading more than the specified number of columns, an exception is thrown. :::tip This setting is useful for preventing overly complex queries. ::: 0 value means unlimited.

max_compress_block_size

Type: UInt64
Default: 1048576
Tier: Production
The maximum size of blocks of uncompressed data before compressing for writing to a table. By default, 1,048,576 (1 MiB). Specifying a smaller block size generally leads to slightly reduced compression ratio, the compression and decompression speed increases slightly due to cache locality, and memory consumption is reduced. :::note This is an expert-level setting, and you shouldn't change it if you're just getting started with RawTree. ::: Don't confuse blocks for compression (a chunk of memory consisting of bytes) with blocks for query processing (a set of rows from a table).

max_concurrent_queries_for_all_users

Type: UInt64
Default: 0
Tier: Production
Throw exception if the value of this setting is less or equal than the current number of simultaneously processed queries. Example: max_concurrent_queries_for_all_users can be set to 99 for all users and database administrator can set it to 100 for itself to run queries for investigation even when the server is overloaded. Modifying the setting for one query or user does not affect other queries. Possible values: - Positive integer. - 0 — No limit. Example xml <max_concurrent_queries_for_all_users>99</max_concurrent_queries_for_all_users> See Also - max_concurrent_queries Cloud default value: 1000.

max_concurrent_queries_for_user

Type: UInt64
Default: 0
Tier: Production
The maximum number of simultaneously processed queries per user. Possible values: - Positive integer. - 0 — No limit. Example xml <max_concurrent_queries_for_user>5</max_concurrent_queries_for_user>

max_consume_snapshots

Type: UInt64
Default: 0
Tier: Experimental
Maximum number of Paimon snapshots to consume per incremental read. 0 means no limit.

max_distributed_connections

Type: UInt64
Default: 1024
Tier: Production
The maximum number of simultaneous connections with remote servers for distributed processing of a single query to a single Distributed table. We recommend setting a value no less than the number of servers in the cluster. The following parameters are only used when creating Distributed tables (and when launching a server), so there is no reason to change them at runtime.

max_distributed_depth

Type: UInt64
Default: 5
Tier: Production
Limits the maximum depth of recursive queries for Distributed tables. If the value is exceeded, the server throws an exception. Possible values: - Positive integer. - 0 — Unlimited depth.

max_download_buffer_size

Type: UInt64
Default: 10485760
Tier: Production
The maximal size of buffer for parallel downloading (e.g. for URL engine) per each thread.

max_download_threads

Type: MaxThreads
Default: 4
Tier: Production
The maximum number of threads to download data (e.g. for URL engine).

max_dynamic_subcolumns_in_json_type_parsing

Type: UInt64Auto
Default: auto
Tier: Production
The maximum number of dynamic subcolumns that can be created in every column during parsing of JSON column. It allows to control the number of dynamic subcolumns during parsing regardless of dynamic parameters specified in the data type.

max_estimated_execution_time

Type: Seconds
Default: 0
Tier: Production
Maximum query estimate execution time in seconds. Checked on every data block when timeout_before_checking_execution_speed expires.

max_execution_speed

Type: UInt64
Default: 0
Tier: Production
The maximum number of execution rows per second. Checked on every data block when timeout_before_checking_execution_speed expires. If the execution speed is high, the execution speed will be reduced.

max_execution_speed_bytes

Type: UInt64
Default: 0
Tier: Production
The maximum number of execution bytes per second. Checked on every data block when timeout_before_checking_execution_speed expires. If the execution speed is high, the execution speed will be reduced.

max_execution_time

Type: Seconds
Default: 0
Tier: Production
The maximum query execution time in seconds. The max_execution_time parameter can be a bit tricky to understand. It operates based on interpolation relative to the current query execution speed (this behaviour is controlled by timeout_before_checking_execution_speed). RawTree will interrupt a query if the projected execution time exceeds the specified max_execution_time. By default, the timeout_before_checking_execution_speed is set to 10 seconds. This means that after 10 seconds of query execution, RawTree will begin estimating the total execution time. If, for example, max_execution_time is set to 3600 seconds (1 hour), RawTree will terminate the query if the estimated time exceeds this 3600-second limit. If you set timeout_before_checking_execution_speed to 0, RawTree will use the clock time as the basis for max_execution_time. If query runtime exceeds the specified number of seconds, the behavior will be determined by the 'timeout_overflow_mode', which by default is set to throw. :::note The timeout is checked and the query can stop only in designated places during data processing. It currently cannot stop during merging of aggregation states, nor during most of query analysis (establishing a connection to a remote replica is one place where it can), and the actual run time will be higher than the value of this setting. :::

max_execution_time_leaf

Type: Seconds
Default: 0
Tier: Production
Similar semantically to max_execution_time but only applied on leaf nodes for distributed or remote queries. For example, if we want to limit the execution time on a leaf node to 10s but have no limit on the initial node, instead of having max_execution_time in the nested subquery settings: sql SELECT count() FROM cluster(cluster, view(SELECT * FROM t SETTINGS max_execution_time = 10)); We can use max_execution_time_leaf as the query settings: sql SELECT count() FROM cluster(cluster, view(SELECT * FROM t)) SETTINGS max_execution_time_leaf = 10;

max_expanded_ast_elements

Type: UInt64
Default: 500000
Tier: Production
Maximum size of query syntax tree in number of nodes after expansion of aliases and the asterisk.

max_fetch_partition_retries_count

Type: UInt64
Default: 5
Tier: Production
Amount of retries while fetching partition from another host.

max_final_threads

Type: MaxThreads
Default: auto(4)
Tier: Production
Sets the maximum number of parallel threads for the SELECT query data read phase with the FINAL modifier. Possible values: - Positive integer. - 0 or 1 — Disabled. SELECT queries are executed in a single thread.

max_http_get_redirects

Type: UInt64
Default: 0
Tier: Production
Max number of HTTP GET redirects hops allowed. Ensures additional security measures are in place to prevent a malicious server from redirecting your requests to unexpected services.\n\nIt is the case when an external server redirects to another address, but that address appears to be internal to the company's infrastructure, and by sending an HTTP request to an internal server, you could request an internal API from the internal network, bypassing the auth, or even query other services, such as Redis or Memcached. When you don't have an internal infrastructure (including something running on your localhost), or you trust the server, it is safe to allow redirects. Although keep in mind, that if the URL uses HTTP instead of HTTPS, and you will have to trust not only the remote server but also your ISP and every network in the middle. Cloud default value: 10.

max_hyperscan_regexp_length

Type: UInt64
Default: 0
Tier: Production
Defines the maximum length for each regular expression in the hyperscan multi-match functions. Possible values: - Positive integer. - 0 - The length is not limited. Example Query: sql SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 3; Result: text ┌─multiMatchAny('abcd', ['ab', 'bcd', 'c', 'd'])─┐ │ 1 │ └────────────────────────────────────────────────┘ Query: sql SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 2; Result: text Exception: Regexp length too large. See Also - max_hyperscan_regexp_total_length

max_hyperscan_regexp_total_length

Type: UInt64
Default: 0
Tier: Production
Sets the maximum length total of all regular expressions in each hyperscan multi-match function. Possible values: - Positive integer. - 0 - The length is not limited. Example Query: sql SELECT multiMatchAny('abcd', ['a','b','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5; Result: text ┌─multiMatchAny('abcd', ['a', 'b', 'c', 'd'])─┐ │ 1 │ └─────────────────────────────────────────────┘ Query: sql SELECT multiMatchAny('abcd', ['ab','bc','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5; Result: text Exception: Total regexp lengths too large. See Also - max_hyperscan_regexp_length

max_insert_block_size

Type: NonZeroUInt64
Default: 1048449
Tier: Production
The maximum size of blocks (in a count of rows) to form for insertion into a table. This setting controls block formation in two contexts: 1. Format parsing: When the server parses row-based input formats (CSV, TSV, JSONEachRow, etc.) from any interface (HTTP, clickhouse-client with inline data, gRPC, PostgreSQL wire protocol), blocks are emitted when: - Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached, OR - Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached Note: When using clickhouse-client or clickhouse-local to read from a file, the client itself parses the data and this setting applies on the client side. 2. INSERT operations: During INSERT queries and when data flows through materialized views, this setting's behavior depends on use_strict_insert_block_limits: - When enabled: Blocks are emitted when: - Min thresholds (AND): Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached - Max thresholds (OR): Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached - When disabled: Blocks are emitted when min_insert_block_size_rows OR min_insert_block_size_bytes is reached. The max_insert_block_size settings are not enforced. Possible values: - Positive integer.

max_insert_block_size_bytes

Type: UInt64
Default: 0
Tier: Production
The maximum size of blocks (in bytes) to form for insertion into a table. This setting works together with max_insert_block_size_rows and controls block formation in the same context. See max_insert_block_size_rows for detailed information about when and how these settings are applied. Possible values: - Positive integer. - 0 — setting does not participate in block formation.

max_insert_block_size_rows

Type: NonZeroUInt64
Default: 1048449
Tier: Production
The maximum size of blocks (in a count of rows) to form for insertion into a table. This setting controls block formation in two contexts: 1. Format parsing: When the server parses row-based input formats (CSV, TSV, JSONEachRow, etc.) from any interface (HTTP, clickhouse-client with inline data, gRPC, PostgreSQL wire protocol), blocks are emitted when: - Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached, OR - Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached Note: When using clickhouse-client or clickhouse-local to read from a file, the client itself parses the data and this setting applies on the client side. 2. INSERT operations: During INSERT queries and when data flows through materialized views, this setting's behavior depends on use_strict_insert_block_limits: - When enabled: Blocks are emitted when: - Min thresholds (AND): Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached - Max thresholds (OR): Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached - When disabled: Blocks are emitted when min_insert_block_size_rows OR min_insert_block_size_bytes is reached. The max_insert_block_size settings are not enforced. Possible values: - Positive integer.

max_insert_delayed_streams_for_parallel_write

Type: UInt64
Default: 0
Tier: Production
The maximum number of streams (columns) to delay final part flush. Default - auto (100 in case of underlying storage supports parallel write, for example S3 and disabled otherwise) Cloud default value: 50.

max_insert_threads

Type: MaxThreads
Default: auto(4)
Tier: Production
The maximum number of threads to execute the INSERT query. This applies both to INSERT SELECT and to a plain INSERT whose data is sent from rawtree-client or over the HTTP interface. The writing side of the pipeline (squashing the blocks and writing them to the destination table) is parallelized across up to this many threads. Possible values: - 0 — Auto. Uses the number of CPU cores available to the server (the same auto value as max_threads), reduced under memory pressure by max_insert_threads_min_free_memory_per_thread. - 1 — the INSERT is executed in a single thread (no parallel execution). Use this to preserve the insertion order of INSERT ... SELECT. - Positive integer bigger than 1 — Parallel execution with the specified number of threads. Before version 26.8 the default was 1 (no parallel execution). Since 26.8 the default (0) resolves to the number of CPU cores, so INSERT is parallelized by default. Set max_insert_threads to 1 (or use the compatibility setting) to restore the previous behavior. Cloud default value: - 1 for nodes with 8 GiB memory - 2 for nodes with 16 GiB memory - 4 for larger nodes Parallel INSERT SELECT has effect only if the SELECT part is executed in parallel, see max_threads setting. For a plain INSERT, the input data is read and parsed as a single stream, and the pipeline is then resized to this many streams for writing. The write-side parallelization applies only to synchronous plain INSERTs: asynchronous inserts (async_insert = 1) are stored in a queue and flushed in the background, so they are unaffected by this setting and always stay single-stream. The writing side is parallelized only when it is safe to do so; otherwise it stays single-stream and this setting has no effect on it. In particular, the write is kept single-stream when use_strict_insert_block_limits is enabled, a destination table (or a table it forwards to) deduplicates inserted blocks, and insert deduplication is enabled for the query (see deduplicate_insert), when the destination has dependent materialized views — including views of a table the destination forwards to, e.g. behind an Alias — (unless parallel_view_processing is enabled and the dependent view chains are free of deduplication hazards — deduplication in the views is disabled (deduplicate_blocks_in_dependent_materialized_views) or no dependent view path can deduplicate), and always for Buffer and Distributed destinations. A Buffer flushes in its own context and a Distributed forwards the write to a remote shard (which may itself buffer the data), so this query's deduplication settings do not govern the final write and it is kept single-stream regardless of them. A non-parallel quorum insert (insert_quorum is 2 or greater, or 'auto', and insert_quorum_parallel is disabled) also stays single-stream, because it permits only one in-flight quorum part per table. Higher values will lead to higher memory usage.

max_insert_threads_min_free_memory_per_thread

Type: UInt64
Default: 4294967296
Tier: Production
Same as max_threads_min_free_memory_per_thread, but applied to max_insert_threads instead of max_threads. The default is higher because insert pipelines typically hold larger per-thread buffers (merge tree parts, compression blocks) than read pipelines. If the amount of free memory is less than max_insert_threads multiplied by this value, max_insert_threads is reduced to fit, down to a minimum of 1. Set to 0 to disable this limit.

max_joined_block_size_bytes

Type: UInt64
Default: 4194304
Tier: Production
Maximum block size in bytes for JOIN result (if join algorithm supports it). 0 means unlimited.

max_joined_block_size_rows

Type: UInt64
Default: 65409
Tier: Production
Maximum block size for JOIN result (if join algorithm supports it). 0 means unlimited.

max_limit_for_vector_search_queries

Type: UInt64
Default: 1000
Tier: Production
SELECT queries with LIMIT bigger than this setting cannot use vector similarity indices. Helps to prevent memory overflows in vector similarity indices.

max_local_read_bandwidth

Type: UInt64
Default: 0
Tier: Production
The maximum speed of local reads in bytes per second.

max_local_write_bandwidth

Type: UInt64
Default: 0
Tier: Production
The maximum speed of local writes in bytes per second.

max_memory_usage

Type: UInt64
Default: 0
Tier: Production
Cloud default value: depends on the amount of RAM on the replica. The maximum amount of RAM to use for running a query on a single server. A value of 0 means unlimited. This setting does not consider the volume of available memory or the total volume of memory on the machine. The restriction applies to a single query within a single server. You can use SHOW PROCESSLIST to see the current memory consumption for each query. Peak memory consumption is tracked for each query and written to the log. Memory usage is not fully tracked for states of the following aggregate functions from String and Array arguments: - min - max - any - anyLast - argMin - argMax Memory consumption is also restricted by the parameters max_memory_usage_for_user and max_server_memory_usage.

max_memory_usage_for_user

Type: UInt64
Default: 0
Tier: Production
The maximum amount of RAM to use for running a user's queries on a single server. Zero means unlimited. By default, the amount is not restricted (max_memory_usage_for_user = 0). Also see the description of max_memory_usage. For example if you want to set max_memory_usage_for_user to 1000 bytes for a user named clickhouse_read, you can use the statement sql ALTER USER clickhouse_read SETTINGS max_memory_usage_for_user = 1000; You can verify it worked by logging out of your client, logging back in, then use the getSetting function: sql SELECT getSetting('max_memory_usage_for_user');

max_network_bandwidth

Type: UInt64
Default: 0
Tier: Production
Limits the speed of the data exchange over the network in bytes per second. This setting applies to every query. Possible values: - Positive integer. - 0 — Bandwidth control is disabled.

max_network_bandwidth_for_all_users

Type: UInt64
Default: 0
Tier: Production
Limits the speed that data is exchanged at over the network in bytes per second. This setting applies to all concurrently running queries on the server. Possible values: - Positive integer. - 0 — Control of the data speed is disabled.

max_network_bandwidth_for_user

Type: UInt64
Default: 0
Tier: Production
Limits the speed of the data exchange over the network in bytes per second. This setting applies to all concurrently running queries performed by a single user. Possible values: - Positive integer. - 0 — Control of the data speed is disabled.

max_network_bytes

Type: UInt64
Default: 0
Tier: Production
Limits the data volume (in bytes) that is received or transmitted over the network when executing a query. This setting applies to every individual query. Possible values: - Positive integer. - 0 — Data volume control is disabled.

max_number_of_partitions_for_independent_aggregation

Type: UInt64
Default: 128
Tier: Production
Maximal number of partitions in table to apply independent aggregation per partition. Part of the cost heuristic of allow_aggregate_partitions_independently.

max_number_of_partitions_for_independent_distinct

Type: UInt64
Default: 128
Tier: Production
Maximal number of partitions in table to apply independent DISTINCT per partition. Part of the cost heuristic of allow_distinct_partitions_independently.

max_number_of_partitions_for_independent_window

Type: UInt64
Default: 128
Tier: Production
Maximal number of partitions in table to apply independent evaluation of window functions per partition. Part of the cost heuristic of allow_window_partitions_independently.

max_os_cpu_wait_time_ratio_to_throw

Type: Float
Default: 0
Tier: Production
Max ratio between OS CPU wait (OSCPUWaitMicroseconds metric) and busy (OSCPUVirtualTimeMicroseconds metric) times to consider rejecting queries. Linear interpolation between min and max ratio is used to calculate the probability, the probability is 1 at this point.

max_parallel_replicas

Type: NonZeroUInt64
Default: 1000
Tier: Production
The maximum number of replicas for each shard when executing a query. Possible values: - Positive integer. Additional Info This options will produce different results depending on the settings used. ### Parallel processing using SAMPLE key A query may be processed faster if it is executed on several servers in parallel. But the query performance may degrade in the following cases: - The position of the sampling key in the partitioning key does not allow efficient range scans. - Adding a sampling key to the table makes filtering by other columns less efficient. - The sampling key is an expression that is expensive to calculate. - The cluster latency distribution has a long tail, so that querying more servers increases the query overall latency. ### Parallel processing using parallel_replicas_custom_key This setting is useful for any replicated table.

max_parser_backtracks

Type: UInt64
Default: 1000000
Tier: Production
Maximum parser backtracking (how many times it tries different alternatives in the recursive descend parsing process).

max_parser_depth

Type: UInt64
Default: 1000
Tier: Production
Limits maximum recursion depth in the recursive descent parser. Allows controlling the stack size. Possible values: - Positive integer. - 0 — Recursion depth is unlimited.

max_parsing_threads

Type: MaxThreads
Default: auto(4)
Tier: Production
The maximum number of threads to parse data in input formats that support parallel parsing. By default, it is determined automatically.

max_partition_size_to_drop

Type: UInt64
Default: 50000000000
Tier: Production
Restriction on dropping partitions in query time. The value 0 means that you can drop partitions without any restrictions. Cloud default value: 1 TB. :::note This query setting overwrites its server setting equivalent, see max_partition_size_to_drop :::

max_partitions_per_insert_block

Type: UInt64
Default: 100
Tier: Production
Limits the maximum number of partitions in a single inserted block and an exception is thrown if the block contains too many partitions. - Positive integer. - 0 — Unlimited number of partitions. Details When inserting data, RawTree calculates the number of partitions in the inserted block. If the number of partitions is more than max_partitions_per_insert_block, RawTree either logs a warning or throws an exception based on throw_on_max_partitions_per_insert_block. Exceptions have the following text: > "Too many partitions for a single INSERT block (partitions_count partitions, limit is " + toString(max_partitions) + "). The limit is controlled by the 'max_partitions_per_insert_block' setting. A large number of partitions is a common misconception. It will lead to severe negative performance impact, including slow server startup, slow INSERT queries and slow SELECT queries. Recommended total number of partitions for a table is under 1000..10000. Please note, that partitioning is not intended to speed up SELECT queries (ORDER BY key is sufficient to make range queries fast). Partitions are intended for data manipulation (DROP PARTITION, etc)." :::note This setting is a safety threshold because using a large number of partitions is a common misconception. :::

max_partitions_to_read

Type: Int64
Default: -1
Tier: Production
Limits the maximum number of partitions that can be accessed in a single query. The setting value specified when the table is created can be overridden via query-level setting. Possible values: - Positive integer - -1 - unlimited (default) :::note You can also specify the MergeTree setting max_partitions_to_read in tables' setting. :::

max_parts_to_move

Type: UInt64
Default: 1000
Tier: Production
Limit the number of parts that can be moved in one query. Zero means unlimited.

max_projection_rows_to_use_projection_index

Type: UInt64
Default: 1000000
Tier: Production
If the number of rows to read from the projection index is less than or equal to this threshold, RawTree will try to apply the projection index during query execution.

max_query_size

Type: UInt64
Default: 262144
Tier: Production
The maximum number of bytes of a query string parsed by the SQL parser. Data in the VALUES clause of INSERT queries is processed by a separate stream parser (that consumes O(1) RAM) and not affected by this restriction. :::note max_query_size cannot be set within an SQL query (e.g., SELECT now() SETTINGS max_query_size=10000) because RawTree needs to allocate a buffer to parse the query, and this buffer size is determined by the max_query_size setting, which must be configured before the query is executed. :::

max_rand_distribution_parameter

Type: Float
Default: 1000000
Tier: Production
Maximum value for distribution shape parameters in random distribution functions such as randChiSquared, randStudentT, and randFisherF. This prevents extremely long computation times with extreme parameter values. 0 disables the limit; values for which the sampler does not terminate at all are still rejected.

max_rand_distribution_trials

Type: UInt64
Default: 1000000000
Tier: Production
Maximum number of trials allowed for random distribution functions such as randBinomial and randNegativeBinomial. This prevents extremely long computation times with large trial counts. 0 disables the limit, and the setting may be raised above its default, except for randBinomial with a probability strictly between 0 and 1, which always rejects more than 10^9 trials because the cost of a single sample is proportional to the number of trials in the worst case, with a probability that grows with it. The probabilities 0 and 1 are exempt from that hard cap, because a sample costs constant time for them.

max_read_buffer_size

Type: NonZeroUInt64
Default: 1048576
Tier: Production
The maximum size of the buffer to read from the filesystem. Values above 256 MiB are clamped to 256 MiB, as a read buffer never needs to be larger.

max_read_buffer_size_local_fs

Type: UInt64
Default: 131072
Tier: Production
The maximum size of the buffer to read from local filesystem. If set to 0 then max_read_buffer_size will be used. Values above 256 MiB are clamped to 256 MiB, as a read buffer never needs to be larger.

max_read_buffer_size_remote_fs

Type: UInt64
Default: 0
Tier: Production
The maximum size of the buffer to read from remote filesystem. If set to 0 then max_read_buffer_size will be used. Values above 256 MiB are clamped to 256 MiB, as a read buffer never needs to be larger.

max_recursive_cte_evaluation_depth

Type: UInt64
Default: 1000
Tier: Production
Maximum limit on recursive CTE evaluation depth

max_remote_read_network_bandwidth

Type: UInt64
Default: 0
Tier: Production
The maximum speed of data exchange over the network in bytes per second for read.

max_remote_write_network_bandwidth

Type: UInt64
Default: 0
Tier: Production
The maximum speed of data exchange over the network in bytes per second for write.

max_replica_delay_for_distributed_queries

Type: UInt64
Default: 300
Tier: Production
Disables lagging replicas for distributed queries. See Replication. Sets the time in seconds. If a replica's lag is greater than or equal to the set value, this replica is not used. Possible values: - Positive integer. - 0 — Replica lags are not checked. To prevent the use of any replica with a non-zero lag, set this parameter to 1. Used when performing SELECT from a distributed table that points to replicated tables.

max_result_bytes

Type: UInt64
Default: 0
Tier: Production
Limits the result size in bytes (uncompressed). The query will stop after processing a block of data if the threshold is met, but it will not cut the last block of the result, therefore the result size can be larger than the threshold. Caveats The result size in memory is taken into account for this threshold. Even if the result size is small, it can reference larger data structures in memory, representing dictionaries of LowCardinality columns, and Arenas of AggregateFunction columns, so the threshold can be exceeded despite the small result size. :::warning The setting is fairly low level and should be used with caution :::

max_result_rows

Type: UInt64
Default: 0
Tier: Production
Limits the number of rows in the result. Also checked for subqueries, and on remote servers when running parts of a distributed query. No limit is applied when the value is 0. The query will stop after processing a block of data if the threshold is met, but it will not cut the last block of the result, therefore the result size can be larger than the threshold.

max_reverse_dictionary_lookup_cache_size_bytes

Type: UInt64
Default: 104857600
Tier: Production
Maximum size in bytes of the per-query reverse dictionary lookup cache used by the function dictGetKeys. The cache stores serialized key tuples per attribute value to avoid re-scanning the dictionary within the same query. When the limit is reached, entries are evicted using LRU. Set to 0 to disable caching.

max_rows_for_lazy_final

Type: UInt64
Default: 10000000
Tier: Production
Maximum number of rows in the set for lazy FINAL optimization. If exceeded, falls back to normal FINAL.

max_rows_in_distinct

Type: UInt64
Default: 0
Tier: Production
The maximum number of different rows when using DISTINCT.

max_rows_in_join

Type: UInt64
Default: 0
Tier: Production
Limits the number of rows in the right-side data structure (typically a hash table) used when joining tables. This setting applies to SELECT ... JOIN operations and the Join table engine. If a query contains multiple joins, RawTree checks this setting for every intermediate result. When the limit is reached, the action depends on the chosen join_algorithm — see that setting for the per-algorithm behavior (spill, re-partition, switch, or throw/break per join_overflow_mode). Possible values: - Positive integer. - 0 — Unlimited number of rows.

max_rows_in_set

Type: UInt64
Default: 0
Tier: Production
The maximum number of rows for a data set in the IN clause created from a subquery.

max_rows_in_set_to_optimize_join

Type: UInt64
Default: 0
Tier: Production
Maximal size of the set to filter joined tables by each other's row sets before joining. Possible values: - 0 — Disable. - Any positive integer.

max_rows_to_group_by

Type: UInt64
Default: 0
Tier: Production
The maximum number of unique keys received from aggregation. This setting lets you limit memory consumption when aggregating. If aggregation during GROUP BY is generating more than the specified number of rows (unique GROUP BY keys), the behavior will be determined by the 'group_by_overflow_mode' which by default is throw, but can be also switched to an approximate GROUP BY mode.

max_rows_to_read

Type: UInt64
Default: 0
Tier: Production
The maximum number of rows that can be read from a table when running a query. The restriction is checked for each processed chunk of data, applied only to the deepest table expression and when reading from a remote server, checked only on the remote server.

max_rows_to_read_leaf

Type: UInt64
Default: 0
Tier: Production
The maximum number of rows that can be read from a local table on a leaf node when running a distributed query. While distributed queries can issue multiple sub-queries to each shard (leaf) - this limit will be checked only on the read stage on the leaf nodes and ignored on the merging of results stage on the root node. For example, a cluster consists of 2 shards and each shard contains a table with 100 rows. The distributed query which is supposed to read all the data from both tables with setting max_rows_to_read=150 will fail, as in total there will be 200 rows. A query with max_rows_to_read_leaf=150 will succeed, since leaf nodes will read at max 100 rows. The restriction is checked for each processed chunk of data. :::note This setting is unstable with prefer_localhost_replica=1. :::

max_rows_to_sort

Type: UInt64
Default: 0
Tier: Production
The maximum number of rows before sorting. This allows you to limit memory consumption when sorting. If more than the specified amount of records have to be processed for the ORDER BY operation, the behavior will be determined by the sort_overflow_mode which by default is set to throw.

max_rows_to_transfer

Type: UInt64
Default: 0
Tier: Production
Maximum size (in rows) that can be passed to a remote server or saved in a temporary table when the GLOBAL IN/JOIN section is executed.

max_sessions_for_user

Type: UInt64
Default: 0
Tier: Production
Maximum number of simultaneous sessions per authenticated user to the RawTree server. Example: xml <profiles> <single_session_profile> <max_sessions_for_user>1</max_sessions_for_user> </single_session_profile> <two_sessions_profile> <max_sessions_for_user>2</max_sessions_for_user> </two_sessions_profile> <unlimited_sessions_profile> <max_sessions_for_user>0</max_sessions_for_user> </unlimited_sessions_profile> </profiles> <users> <Alice> <profile>single_session_user</profile> </Alice> <Bob> <profile>two_sessions_profile</profile> </Bob> <Charles> <profile>unlimited_sessions_profile</profile> </Charles> </users> Possible values: - Positive integer - 0 - infinite count of simultaneous sessions (default)

max_size_to_preallocate_for_aggregation

Type: UInt64
Default: 1000000000000
Tier: Production
For how many elements it is allowed to preallocate space in all hash tables in total before aggregation

max_size_to_preallocate_for_joins

Type: UInt64
Default: 1000000000000
Tier: Production
For how many elements it is allowed to preallocate space in all hash tables in total before join

max_skip_unavailable_shards_num

Type: UInt64
Default: 0
Tier: Production
When skip_unavailable_shards is enabled, limits the maximum number of shards that can be silently skipped. If the number of unavailable shards exceeds this value, an exception is thrown instead of silently skipping. A value of 0 means no limit (default behavior — all unavailable shards can be skipped).

max_skip_unavailable_shards_ratio

Type: Float
Default: 0
Tier: Production
When skip_unavailable_shards is enabled, limits the maximum ratio (0 to 1) of shards that can be silently skipped. If the ratio of unavailable shards to total shards exceeds this value, an exception is thrown instead of silently skipping. A value of 0 means no limit (default behavior — all unavailable shards can be skipped).

max_streams_for_files_processing_in_cluster_functions

Type: UInt64
Default: 0
Tier: Production
If is not zero, limit the number of threads reading data from files in *Cluster table functions.

max_streams_for_merge_tree_reading

Type: UInt64
Default: 0
Tier: Production
If is not zero, limit the number of reading streams for MergeTree table.

max_streams_for_union_step

Type: UInt64
Default: 0
Tier: Production
Limits the number of simultaneously active data streams in a UNION step (applies to both UNION ALL and UNION DISTINCT, because UNION DISTINCT is implemented via a UNION ALL step followed by a DISTINCT step). When a UNION query has many subqueries, all of them open their read buffers at the same time, leading to memory usage proportional to the number of subqueries. This setting inserts Concat processors to narrow the pipeline so that at most this many streams are active at once, drastically reducing peak memory. The actual limit is the minimum of this value and max_threads * max_streams_for_union_step_to_max_threads_ratio (either one being 0 means it is ignored). When both are 0, no narrowing is applied. The limit is also not applied when the query plan requires each output stream of the UNION to stay individually sorted (for example, when the read-in-order optimization is applied across the UNION); in that case correctness of the ordering takes precedence and narrowing is skipped.

max_streams_for_union_step_to_max_threads_ratio

Type: Float
Default: 8
Tier: Production
This ratio multiplied by max_threads determines a limit on simultaneously active streams in a UNION step (applies to both UNION ALL and UNION DISTINCT). The actual limit is the minimum of this computed value and max_streams_for_union_step (either one being 0 means it is ignored). For example, with max_threads = 8 and this ratio set to 1, at most 8 streams will be active. Set to 0 to disable this ratio-based limit. Like max_streams_for_union_step, the limit is not applied when the query plan requires each output stream of the UNION to stay individually sorted.

max_streams_multiplier_for_merge_tables

Type: Float
Default: 5
Tier: Production
Ask more streams when reading from Merge table. Streams will be spread across tables that Merge table will use. This allows more even distribution of work across threads and is especially helpful when merged tables differ in size.

max_streams_to_max_threads_ratio

Type: Float
Default: 1
Tier: Production
Allows you to use more sources than the number of threads - to more evenly distribute work across threads. It is assumed that this is a temporary solution since it will be possible in the future to make the number of sources equal to the number of threads, but for each source to dynamically select available work for itself.

max_subquery_depth

Type: UInt64
Default: 100
Tier: Production
If a query has more than the specified number of nested subqueries, throws an exception. :::tip This allows you to have a sanity check to protect against the users of your cluster from writing overly complex queries. :::

max_table_size_to_drop

Type: UInt64
Default: 50000000000
Tier: Production
Restriction on deleting tables in query time. The value 0 means that you can delete all tables without any restrictions. Cloud default value: 1 TB. :::note This query setting overwrites its server setting equivalent, see max_table_size_to_drop :::

max_temporary_columns

Type: UInt64
Default: 0
Tier: Production
The maximum number of temporary columns that must be kept in RAM simultaneously when running a query, including constant columns. If a query generates more than the specified number of temporary columns in memory as a result of intermediate calculation, then an exception is thrown. :::tip This setting is useful for preventing overly complex queries. ::: 0 value means unlimited.

max_temporary_data_on_disk_size_for_query

Type: UInt64
Default: 0
Tier: Production
The maximum amount of data consumed by temporary files on disk in bytes for all concurrently running queries. Possible values: - Positive integer. - 0 — unlimited (default)

max_temporary_data_on_disk_size_for_user

Type: UInt64
Default: 0
Tier: Production
The maximum amount of data consumed by temporary files on disk in bytes for all concurrently running user queries. Possible values: - Positive integer. - 0 — unlimited (default)

max_temporary_non_const_columns

Type: UInt64
Default: 0
Tier: Production
Like max_temporary_columns, the maximum number of temporary columns that must be kept in RAM simultaneously when running a query, but without counting constant columns. :::note Constant columns are formed fairly often when running a query, but they require approximately zero computing resources. :::

max_threads

Type: MaxThreads
Default: auto(4)
Tier: Production
The maximum number of query processing threads, excluding threads for retrieving data from remote servers (see the 'max_distributed_connections' parameter). This parameter applies to threads that perform the same stages of the query processing pipeline in parallel. For example, when reading from a table, if it is possible to evaluate expressions with functions, filter with WHERE and pre-aggregate for GROUP BY in parallel using at least 'max_threads' number of threads, then 'max_threads' are used. For queries that are completed quickly because of a LIMIT, you can set a lower 'max_threads'. For example, if the necessary number of entries are located in every block and max_threads = 8, then 8 blocks are retrieved, although it would have been enough to read just one. The smaller the max_threads value, the less memory is consumed. The max_threads setting by default matches the number of hardware threads (number of CPU cores) available to RawTree. As a special case, for x86 processors with less than 32 CPU cores and SMT (e.g. Intel HyperThreading), RawTree uses the number of logical cores (= 2 x physical core count) by default. Without SMT (e.g. Intel HyperThreading), this corresponds to the number of CPU cores. For RawTree Cloud users, the default value will display as auto(N) where N matches the vCPU size of your service e.g. 2vCPU/8GiB, 4vCPU/16GiB etc. See the settings tab in the Cloud console for a list of all service sizes.

max_threads_for_indexes

Type: UInt64
Default: 0
Tier: Production
The maximum number of threads process indices.

max_threads_min_free_memory_per_thread

Type: UInt64
Default: 1073741824
Tier: Production
Lowers max_threads when the server is under memory pressure, to avoid starting highly-parallel queries that are likely to hit the memory limit. Free memory is computed as the server's max_server_memory_usage minus the memory currently tracked by the global memory tracker. If that free memory is less than max_threads multiplied by this value, max_threads is reduced to the largest N such that N * value <= free_memory, with a minimum of 1. Set to 0 to disable this limit. For example, with the default of 1 GiB and 32 GiB of free memory, max_threads is capped at 32; with 1 GiB of free memory it falls back to 1. This setting applies to read-side parallelism (SELECT, UNION, INTERSECT/EXCEPT, and the SELECT side of INSERT ... SELECT). For the write side, see max_insert_threads_min_free_memory_per_thread.

max_untracked_memory

Type: UInt64
Default: 4194304
Tier: Production
Small allocations and deallocations are grouped in thread local variable and tracked or profiled only when an amount (in absolute value) becomes larger than the specified value. If the value is higher than 'memory_profiler_step' it will be effectively lowered to 'memory_profiler_step'.

max_wkb_geometry_elements

Type: UInt64
Default: 1000000
Tier: Production
Maximum number of points, rings, or polygons allowed in a single WKB geometry element during parsing by readWKB and related functions. This protects against excessive memory allocations from malformed WKB data. Set to 0 to use the hard-coded limit (100 million).

memory_overcommit_ratio_denominator

Type: UInt64
Default: 1073741824
Tier: Production
It represents the soft memory limit when the hard limit is reached on the global level. This value is used to compute the overcommit ratio for the query. Zero means skip the query. Read more about memory overcommit.

memory_overcommit_ratio_denominator_for_user

Type: UInt64
Default: 1073741824
Tier: Production
It represents the soft memory limit when the hard limit is reached on the user level. This value is used to compute the overcommit ratio for the query. Zero means skip the query. Read more about memory overcommit.

memory_profiler_sample_max_allocation_size

Type: UInt64
Default: 0
Tier: Production
Collect random allocations of size less or equal than the specified value with probability equal to memory_profiler_sample_probability. 0 means disabled. You may want to set 'max_untracked_memory' to 0 to make this threshold work as expected.

memory_profiler_sample_min_allocation_size

Type: UInt64
Default: 0
Tier: Production
Collect random allocations of size greater or equal than the specified value with probability equal to memory_profiler_sample_probability. 0 means disabled. You may want to set 'max_untracked_memory' to 0 to make this threshold work as expected.

memory_profiler_sample_probability

Type: Float
Default: 0
Tier: Production
Collect random allocations and deallocations and write them into system.trace_log with 'MemorySample' trace_type. The probability is for every alloc/free regardless of the size of the allocation (can be changed with memory_profiler_sample_min_allocation_size and memory_profiler_sample_max_allocation_size). Note that sampling happens only when the amount of untracked memory exceeds 'max_untracked_memory'. You may want to set 'max_untracked_memory' to 0 for extra fine-grained sampling.

memory_profiler_step

Type: UInt64
Default: 4194304
Tier: Production
Sets the step of memory profiler. Whenever query memory usage becomes larger than every next step in number of bytes the memory profiler will collect the allocating stacktrace and will write it into trace_log. Possible values: - A positive integer number of bytes. - 0 for turning off the memory profiler.

memory_tracker_fault_probability

Type: Float
Default: 0
Tier: Production
For testing of exception safety - throw an exception every time you allocate memory with the specified probability.

memory_usage_overcommit_max_wait_microseconds

Type: UInt64
Default: 5000000
Tier: Production
Maximum time thread will wait for memory to be freed in the case of memory overcommit on a user level. If the timeout is reached and memory is not freed, an exception is thrown. Read more about memory overcommit.

merge_table_max_tables_to_look_for_schema_inference

Type: UInt64
Default: 1000
Tier: Production
When creating a Merge table without an explicit schema or when using the merge table function, infer schema as a union of not more than the specified number of matching tables. If there is a larger number of tables, the schema will be inferred from the first specified number of tables.

merge_tree_coarse_index_granularity

Type: UInt64
Default: 8
Tier: Production
When searching for data, RawTree checks the data marks in the index file. If RawTree finds that required keys are in some range, it divides this range into merge_tree_coarse_index_granularity subranges and searches the required keys there recursively. Possible values: - Any positive even integer.

merge_tree_compact_parts_min_granules_to_multibuffer_read

Type: UInt64
Default: 16
Tier: Production
Only has an effect in RawTree Cloud. Number of granules in stripe of compact part of MergeTree tables to use multibuffer reader, which supports parallel reading and prefetch. In case of reading from remote fs using of multibuffer reader increases number of read request. A part is read with a single buffer when it contains both fewer granules than this threshold and fewer granules than the number of columns being read, because in that case the single buffer reader issues fewer read requests than the multibuffer reader.

merge_tree_determine_task_size_by_prewhere_columns

Type: Bool
Default: 1
Tier: Production
Whether to use only prewhere columns size to determine reading task size.

merge_tree_generic_exclusion_search_max_steps

Type: UInt64
Default: 0
Tier: Production
When a filter cannot be evaluated as a single continuous range of the primary key, for example when it uses key columns other than the first one, ClickHouse runs an iterative generic exclusion search algorithm over the index marks. The same algorithm is used for the analysis of the text index. This setting limits the number of steps (index checks) the algorithm spends on each data part. The budget is spent on the largest remaining mark ranges first. When it is exhausted, the ranges that were not fully analyzed are accepted as a whole, so the query stays correct but may read more granules than an unlimited search would select. A lower budget speeds up index analysis at the cost of reading more data. The limit is approximate rather than a strict cap on the analysis cost: the search can exceed it by roughly one round of splitting, and when the part is already divided into many ranges (for example, by the query condition cache), each of them is checked at least once regardless of the limit. The number of steps the search made for each data part is reported in the trace level log messages of the query, and the IndexGenericExclusionSearchStepLimitReached and TextIndexGenericExclusionSearchStepLimitReached profile events count how many times the budget was exhausted. The (default) value 0 means unlimited steps. Possible values: - 0 for unlimited steps, or any positive integer.

merge_tree_max_bytes_to_use_cache

Type: UInt64
Default: 2013265920
Tier: Production
If RawTree should read more than merge_tree_max_bytes_to_use_cache bytes in one query, it does not use the cache of uncompressed blocks. The cache of uncompressed blocks stores data extracted for queries. RawTree uses this cache to speed up responses to repeated small queries. This setting protects the cache from trashing by queries that read a large amount of data. The uncompressed_cache_size server setting defines the size of the cache of uncompressed blocks. Possible values: - Any positive integer.

merge_tree_max_rows_to_use_cache

Type: UInt64
Default: 1048576
Tier: Production
If RawTree should read more than merge_tree_max_rows_to_use_cache rows in one query, it does not use the cache of uncompressed blocks. The cache of uncompressed blocks stores data extracted for queries. RawTree uses this cache to speed up responses to repeated small queries. This setting protects the cache from trashing by queries that read a large amount of data. The uncompressed_cache_size server setting defines the size of the cache of uncompressed blocks. Possible values: - Any positive integer.

merge_tree_min_bytes_for_concurrent_read

Type: UInt64
Default: 251658240
Tier: Production
If the number of bytes to read from one file of a MergeTree-engine table exceeds merge_tree_min_bytes_for_concurrent_read, then RawTree tries to concurrently read from this file in several threads. Possible value: - Positive integer.

merge_tree_min_bytes_for_concurrent_read_for_remote_filesystem

Type: UInt64
Default: 0
Tier: Production
The minimum number of bytes to read from one file before MergeTree engine can parallelize reading, when reading from remote filesystem. We do not recommend using this setting. Possible values: - Positive integer.

merge_tree_min_bytes_for_seek

Type: UInt64
Default: 0
Tier: Production
If the distance between two data blocks to be read in one file is less than merge_tree_min_bytes_for_seek bytes, then RawTree sequentially reads a range of file that contains both blocks, thus avoiding extra seek. Possible values: - Any positive integer.

merge_tree_min_bytes_per_read_stream

Type: UInt64
Default: 65536
Tier: Production
Per-stream overhead cost expressed as byte-equivalent. Controls the maximum number of read streams created for ordinary local unordered MergeTree scans. Ordered, FINAL, layered, and parallel-replica reads are not changed. The volume-based cap is ceil(sqrt(estimated_read_bytes / this_setting)). RawTree also preserves at least 16 streams and at least one quarter of the streams requested before this cap, so the effective stream count is min(requested_streams, max(volume_based_cap, 16, floor(requested_streams / 4))). These lower bounds preserve downstream parallelism for CPU-heavy expressions and aggregations, whose cost is not represented by estimated_read_bytes. estimated_read_bytes is the uncompressed size of the columns being read over the mark ranges left after index and partition pruning. Uncompressed size is used because per-stream overhead is traded against the work done per stream, which scales with the number of values processed rather than with how well they compress. The cap is not applied when the read volume cannot be estimated conservatively, for example when an old part needs other physical columns to evaluate a newly added DEFAULT column, or when a selected range reads only part of a variable-width column. The default of 64 KB is derived from the cost model T(N) = W/N + F + V·N, where W is useful work, F is fixed pipeline overhead, and V is per-stream variable cost. The optimal stream count is sqrt(W/V). Expressing W in bytes via throughput gives C = throughput · V ≈ 400 MB/s · 0.17 ms ≈ 64 KB. Increasing this value reduces the number of streams (more conservative); decreasing it allows more streams. Set to 0 to disable this optimization. Possible values: - Non-negative integer.

merge_tree_min_bytes_per_task_for_remote_reading

Type: UInt64
Default: 2097152
Tier: Production
Min bytes to read per task.

merge_tree_min_read_task_size

Type: NonZeroUInt64
Default: 8
Tier: Production
Hard lower limit on the task size (even when the number of granules is low and the number of available threads is high we won't allocate smaller tasks

merge_tree_min_rows_for_concurrent_read

Type: UInt64
Default: 163840
Tier: Production
If the number of rows to be read from a file of a MergeTree table exceeds merge_tree_min_rows_for_concurrent_read then RawTree tries to perform a concurrent reading from this file on several threads. Possible values: - Positive integer.

merge_tree_min_rows_for_concurrent_read_for_remote_filesystem

Type: UInt64
Default: 0
Tier: Production
The minimum number of lines to read from one file before the MergeTree engine can parallelize reading, when reading from remote filesystem. We do not recommend using this setting. Possible values: - Positive integer.

merge_tree_min_rows_for_seek

Type: UInt64
Default: 0
Tier: Production
If the distance between two data blocks to be read in one file is less than merge_tree_min_rows_for_seek rows, then RawTree does not seek through the file but reads the data sequentially. Possible values: - Any positive integer.

merge_tree_prefetch_json_shared_data_substreams

Type: Bool
Default: 1
Tier: Production
Enables prefetching of JSON shared data substreams in Wide parts that are read by seeking to a mark. Such a prefetch reads from the beginning of the granule, which is usually not the position the substream is read from, so it can be wasted. Disable to skip these prefetches.

merge_tree_read_split_ranges_into_intersecting_and_non_intersecting_injection_probability

Type: Float
Default: 0
Tier: Production
For testing of PartsSplitter - split read ranges into intersecting and non intersecting every time you read from MergeTree with the specified probability.

merge_tree_storage_snapshot_sleep_ms

Type: UInt64
Default: 0
Tier: Production
Inject artificial delay (in milliseconds) when creating a storage snapshot for MergeTree tables. Used for testing and debugging purposes only. Possible values: - 0 - No delay (default) - N - Delay in milliseconds

merge_tree_use_const_size_tasks_for_remote_reading

Type: Bool
Default: 1
Tier: Production
Whether to use constant size tasks for reading from a remote table.

merge_tree_use_deserialization_prefixes_cache

Type: Bool
Default: 1
Tier: Production
Enables caching of columns metadata from the file prefixes during reading from remote disks in MergeTree.

merge_tree_use_prefixes_deserialization_thread_pool

Type: Bool
Default: 1
Tier: Production
Enables usage of the thread pool for parallel prefixes reading in Wide parts in MergeTree. Size of that thread pool is controlled by server setting max_prefixes_deserialization_thread_pool_size.

merge_tree_use_v1_object_and_dynamic_serialization

Type: Bool
Default: 0
Tier: Production
When enabled, V1 serialization version of JSON and Dynamic types will be used in MergeTree instead of V2. Changing this setting takes affect only after server restart.

metrics_perf_events_enabled

Type: Bool
Default: 0
Tier: Production
If enabled, some of the perf events will be measured throughout queries' execution.

metrics_perf_events_list

Type: String
Default: ``
Tier: Production
Comma separated list of perf metrics that will be measured throughout queries' execution. Empty means all events. See PerfEventInfo in sources for the available events.

min_bytes_to_use_direct_io

Type: UInt64
Default: 0
Tier: Production
The minimum data volume required for using direct I/O access to the storage disk. RawTree uses this setting when reading data from tables. If the total storage volume of all the data to be read exceeds min_bytes_to_use_direct_io bytes, then RawTree reads the data from the storage disk with the O_DIRECT option. Possible values: - 0 — Direct I/O is disabled. - Positive integer.

min_bytes_to_use_mmap_io

Type: UInt64
Default: 0
Tier: Production
This is an experimental setting. Sets the minimum amount of memory for reading large files without copying data from the kernel to userspace. Recommended threshold is about 64 MB, because mmap/munmap is slow. It makes sense only for large files and helps only if data reside in the page cache. Possible values: - Positive integer. - 0 — Big files read with only copying data from kernel to userspace.

min_chunk_bytes_for_parallel_parsing

Type: NonZeroUInt64
Default: 10485760
Tier: Production

• Type: unsigned int - Default value: 1 MiB The minimum chunk size in bytes, which each thread will parse in parallel.

min_compress_block_size

Type: UInt64
Default: 65536
Tier: Production
For MergeTree tables. In order to reduce latency when processing queries, a block is compressed when writing the next mark if its size is at least min_compress_block_size. By default, 65,536. The actual size of the block, if the uncompressed data is less than max_compress_block_size, is no less than this value and no less than the volume of data for one mark. Let's look at an example. Assume that index_granularity was set to 8192 during table creation. We are writing a UInt32-type column (4 bytes per value). When writing 8192 rows, the total will be 32 KB of data. Since min_compress_block_size = 65,536, a compressed block will be formed for every two marks. We are writing a URL column with the String type (average size of 60 bytes per value). When writing 8192 rows, the average will be slightly less than 500 KB of data. Since this is more than 65,536, a compressed block will be formed for each mark. In this case, when reading data from the disk in the range of a single mark, extra data won't be decompressed. :::note This is an expert-level setting, and you shouldn't change it if you're just getting started with RawTree. :::

min_count_to_compile_aggregate_expression

Type: UInt64
Default: 3
Tier: Production
The minimum number of identical aggregate expressions to start JIT-compilation. Works only if the compile_aggregate_expressions setting is enabled. Possible values: - Positive integer. - 0 — Identical aggregate expressions are always JIT-compiled.

min_count_to_compile_expression

Type: UInt64
Default: 3
Tier: Production
Minimum count of executing same expression before it is get compiled.

min_count_to_compile_regular_expression

Type: UInt64
Default: 3
Tier: Production
Minimum count of executing same regular expression before it is get compiled.

min_count_to_compile_sort_description

Type: UInt64
Default: 3
Tier: Production
The number of identical sort descriptions before they are JIT-compiled

min_execution_speed

Type: UInt64
Default: 0
Tier: Production
Minimal execution speed in rows per second. Checked on every data block when timeout_before_checking_execution_speed expires. If the execution speed is lower, an exception is thrown.

min_execution_speed_bytes

Type: UInt64
Default: 0
Tier: Production
The minimum number of execution bytes per second. Checked on every data block when timeout_before_checking_execution_speed expires. If the execution speed is lower, an exception is thrown.

min_external_table_block_size_bytes

Type: UInt64
Default: 268402944
Tier: Production
Squash blocks passed to the external table to a specified size in bytes, if blocks are not big enough.

min_external_table_block_size_rows

Type: UInt64
Default: 1048449
Tier: Production
Squash blocks passed to external table to specified size in rows, if blocks are not big enough.

min_filtered_ratio_for_lazy_final

Type: Float
Default: 0.5
Tier: Production
Minimum ratio of marks filtered by index analysis for lazy FINAL optimization. If less than this fraction of marks is filtered, falls back to normal FINAL. Value 0 disables this check.

min_free_disk_bytes_to_perform_insert

Type: UInt64
Default: 0
Tier: Production
Minimum free disk space bytes to perform an insert.

min_free_disk_ratio_to_perform_insert

Type: Float
Default: 0
Tier: Production
Minimum free disk space ratio to perform an insert.

min_free_disk_space_for_temporary_data

Type: UInt64
Default: 0
Tier: Production
The minimum disk space to keep while writing temporary data used in external sorting and aggregation.

min_hit_rate_to_use_consecutive_keys_optimization

Type: Float
Default: 0.5
Tier: Production
Minimal hit rate of a cache which is used for consecutive keys optimization in aggregation to keep it enabled

min_insert_block_size_bytes

Type: UInt64
Default: 268402944
Tier: Production
The minimum size of blocks (in bytes) to form for insertion into a table. This setting works together with min_insert_block_size_rows and controls block formation in the same contexts (format parsing and INSERT operations). See min_insert_block_size_rows for detailed information about when and how these settings are applied. Possible values: - Positive integer. - 0 — setting does not participate in block formation.

min_insert_block_size_bytes_for_materialized_views

Type: UInt64
Default: 0
Tier: Production
Sets the minimum number of bytes in the block which can be inserted into a table by an INSERT query. Smaller-sized blocks are squashed into bigger ones. This setting is applied only for blocks inserted into materialized view. By adjusting this setting, you control blocks squashing while pushing to materialized view and avoid excessive memory usage. Possible values: - Any positive integer. - 0 — Squashing disabled. See also - min_insert_block_size_bytes

min_insert_block_size_rows

Type: UInt64
Default: 1048449
Tier: Production
The minimum size of blocks (in rows) to form for insertion into a table. This setting controls block formation in two contexts: 1. Format parsing: When the server parses row-based input formats (CSV, TSV, JSONEachRow, etc.) from any interface (HTTP, rawtree-client with inline data, gRPC, PostgreSQL wire protocol), blocks are emitted when: - Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached, OR - Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached Note: When using rawtree-client or rawtree-local to read from a file, the client itself parses the data and this setting applies on the client side. 2. INSERT operations: During INSERT queries and when data flows through materialized views, this setting's behavior depends on use_strict_insert_block_limits: - When enabled: Blocks are emitted when: - Min thresholds (AND): Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached - Max thresholds (OR): Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached - When disabled (default): Blocks are emitted when min_insert_block_size_rows OR min_insert_block_size_bytes is reached. The max_insert_block_size settings are not enforced. Possible values: - Positive integer. - 0 — setting does not participate in block formation.

min_insert_block_size_rows_for_materialized_views

Type: UInt64
Default: 0
Tier: Production
Sets the minimum number of rows in the block which can be inserted into a table by an INSERT query. Smaller-sized blocks are squashed into bigger ones. This setting is applied only for blocks inserted into materialized view. By adjusting this setting, you control blocks squashing while pushing to materialized view and avoid excessive memory usage. Possible values: - Any positive integer. - 0 — Squashing disabled. See Also - min_insert_block_size_rows

min_joined_block_size_bytes

Type: UInt64
Default: 524288
Tier: Production
Minimum block size in bytes for JOIN input and output blocks (if join algorithm supports it). Small blocks will be squashed. 0 means unlimited.

min_joined_block_size_rows

Type: UInt64
Default: 65409
Tier: Production
Minimum block size in rows for JOIN input and output blocks (if join algorithm supports it). Small blocks will be squashed. 0 means unlimited.

min_os_cpu_wait_time_ratio_to_throw

Type: Float
Default: 0
Tier: Production
Min ratio between OS CPU wait (OSCPUWaitMicroseconds metric) and busy (OSCPUVirtualTimeMicroseconds metric) times to consider rejecting queries. Linear interpolation between min and max ratio is used to calculate the probability, the probability is 0 at this point.

min_outstreams_per_resize_after_split

Type: UInt64
Default: 24
Tier: Production
Specifies the minimum number of output streams of a Resize or StrictResize processor after the split is performed during pipeline generation. If the resulting number of streams is less than this value, the split operation will not occur. ### What is a Resize Node A Resize node is a processor in the query pipeline that adjusts the number of data streams flowing through the pipeline. It can either increase or decrease the number of streams to balance the workload across multiple threads or processors. For example, if a query requires more parallelism, the Resize node can split a single stream into multiple streams. Conversely, it can merge multiple streams into fewer streams to consolidate data processing. The Resize node ensures that data is evenly distributed across streams, maintaining the structure of the data blocks. This helps optimize resource utilization and improve query performance. ### Why the Resize Node Needs to Be Split During pipeline execution, ExecutingGraph::Node::status_mutex of the centrally-hubbed Resize node is heavily contended especially in high-core-count environments, and this contention leads to: 1. Increased latency for ExecutingGraph::updateNode, directly impacting query performance. 2. Excessive CPU cycles are wasted in spin-lock contention (native_queued_spin_lock_slowpath), degrading efficiency. 3. Reduced CPU utilization, limiting parallelism and throughput. ### How the Resize Node Gets Split 1. The number of output streams is checked to ensure the split could be performed: the output streams of each split processor meet or exceed the min_outstreams_per_resize_after_split threshold. 2. The Resize node is divided into smaller Resize nodes with equal count of ports, each handling a subset of input and output streams. 3. Each group is processed independently, reducing the lock contention. ### Splitting Resize Node with Arbitrary Inputs/Outputs In some cases, where the inputs/outputs are indivisible by the number of split Resize nodes, some inputs are connected to NullSources and some outputs are connected to NullSinks. This allows the split to occur without affecting the overall data flow. ### Purpose of the Setting The min_outstreams_per_resize_after_split setting ensures that the splitting of Resize nodes is meaningful and avoids creating too few streams, which could lead to inefficient parallel processing. By enforcing a minimum number of output streams, this setting helps maintain a balance between parallelism and overhead, optimizing query execution in scenarios involving stream splitting and merging. ### Disabling the Setting To disable the split of Resize nodes, set this setting to 0. This will prevent the splitting of Resize nodes during pipeline generation, allowing them to retain their original structure without division into smaller nodes.

min_table_rows_to_use_projection_index

Type: UInt64
Default: 1000000
Tier: Production
If the estimated number of rows to read from the table is greater than or equal to this threshold, RawTree will try to use the projection index during query execution.

mongodb_throw_on_unsupported_query

Type: Bool
Default: 1
Tier: Production
If enabled, MongoDB tables will return an error when a MongoDB query cannot be built. Otherwise, RawTree reads the full table and processes it locally. This option does not apply when 'allow_experimental_analyzer=0'.

move_all_conditions_to_prewhere

Type: Bool
Default: 1
Tier: Production
Move all viable conditions from WHERE to PREWHERE

move_primary_key_columns_to_end_of_prewhere

Type: Bool
Default: 1
Tier: Production
Move PREWHERE conditions containing primary key columns to the end of AND chain. It is likely that these conditions are taken into account during primary key analysis and thus will not contribute a lot to PREWHERE filtering.

multiple_joins_try_to_keep_original_names

Type: Bool
Default: 0
Tier: Production
Do not add aliases to top level expression list on multiple joins rewrite

mutations_execute_nondeterministic_on_initiator

Type: Bool
Default: 0
Tier: Production
If true constant nondeterministic functions (e.g. function now()) are executed on initiator and replaced to literals in UPDATE and DELETE queries. It helps to keep data in sync on replicas while executing mutations with constant nondeterministic functions. Default value: false.

mutations_execute_subqueries_on_initiator

Type: Bool
Default: 0
Tier: Production
If true scalar subqueries are executed on initiator and replaced to literals in UPDATE and DELETE queries. Default value: false.

mutations_max_literal_size_to_replace

Type: UInt64
Default: 16384
Tier: Production
The maximum size of serialized literal in bytes to replace in UPDATE and DELETE queries. Takes effect only if at least one the two settings above is enabled. Default value: 16384 (16 KiB).

mutations_sync

Type: UInt64
Default: 0
Tier: Production
Allows to execute ALTER TABLE ... UPDATE|DELETE|MATERIALIZE INDEX|MATERIALIZE PROJECTION|MATERIALIZE COLUMN|MATERIALIZE STATISTICS queries (mutations) synchronously. Possible values: | Value | Description | |-------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | 0 | Mutations execute asynchronously. | | 1 | The query waits for all mutations to complete on the current server. | | 2 | The query waits for all mutations to complete on all replicas (if they exist). | | 3 | The query waits only for active replicas. Supported only for SharedMergeTree. For ReplicatedMergeTree it behaves the same as mutations_sync = 2.|

mysql_datatypes_support_level

Type: MySQLDataTypesSupport
Default: decimal,datetime64,date2Date32,geometry
Tier: Production
Defines how MySQL types are converted to corresponding RawTree types. A comma separated list in any combination of decimal, datetime64, date2Date32, date2String or geometry. All modern mappings (decimal, datetime64, date2Date32, geometry) are enabled by default. - decimal: convert NUMERIC and DECIMAL types to Decimal when precision allows it. - datetime64: convert DATETIME and TIMESTAMP types to DateTime64 instead of DateTime when precision is not 0. - date2Date32: convert DATE to Date32 instead of Date. Takes precedence over date2String. - date2String: convert DATE to String instead of Date. Overridden by datetime64. - geometry: convert MySQL's spatial types (LINESTRING, POLYGON, MULTILINESTRING, MULTIPOLYGON, MULTIPOINT) to the corresponding RawTree geometric types, and the generic GEOMETRY type to the umbrella Geometry type. POINT is always converted to Point regardless of this option. Because a generic GEOMETRY column can hold any subtype, reading a value whose subtype has no RawTree counterpart (GEOMETRYCOLLECTION) throws an exception at read time; columns declared as GEOMETRYCOLLECTION map to String. A nullable spatial column other than POINT also maps to Nullable(String), since Point is the only geometric type that can be nested inside Nullable. Every such string is a 4-byte SRID prefix followed by the WKB payload, as returned by MySQL. All of the above applies when the schema is inferred from the column types of a MySQL table; when the source is a query (the query(...) argument of the mysql table function or the MySQL table engine), MySQL reports every spatial result column as the generic GEOMETRY without the concrete subtype, so such columns — including POINT — map to String (Nullable(String) if nullable).

mysql_map_fixed_string_to_text_in_show_columns

Type: Bool
Default: 1
Tier: Production
When enabled, FixedString RawTree data type will be displayed as TEXT in SHOW COLUMNS. Has an effect only when the connection is made through the MySQL wire protocol. - 0 - Use BLOB. - 1 - Use TEXT.

mysql_map_string_to_text_in_show_columns

Type: Bool
Default: 1
Tier: Production
When enabled, String RawTree data type will be displayed as TEXT in SHOW COLUMNS. Has an effect only when the connection is made through the MySQL wire protocol. - 0 - Use BLOB. - 1 - Use TEXT.

mysql_max_rows_to_insert

Type: UInt64
Default: 65536
Tier: Production
The maximum number of rows in MySQL batch insertion of the MySQL storage engine

network_compression_method

Type: String
Default: LZ4
Tier: Production
The codec for compressing the client/server and server/server communication. Possible values: - NONE — no compression. - LZ4 — use the LZ4 codec. - LZ4HC — use the LZ4HC codec. - ZSTD — use the ZSTD codec. See Also - network_zstd_compression_level

network_zstd_compression_level

Type: Int64
Default: 1
Tier: Production
Adjusts the level of ZSTD compression. Used only when network_compression_method is set to ZSTD. Possible values: - Positive integer from 1 to 15.

normalize_function_names

Type: Bool
Default: 1
Tier: Production
Normalize function names to their canonical names

number_of_mutations_to_delay

Type: UInt64
Default: 0
Tier: Production
If the mutated table contains at least that many unfinished mutations, artificially slow down mutations of table. 0 - disabled

number_of_mutations_to_throw

Type: UInt64
Default: 0
Tier: Production
If the mutated table contains at least that many unfinished mutations, throw 'Too many mutations ...' exception. 0 - disabled

odbc_bridge_connection_pool_size

Type: UInt64
Default: 16
Tier: Production
Connection pool size for each connection settings string in ODBC bridge.

odbc_bridge_use_connection_pooling

Type: Bool
Default: 1
Tier: Production
Use connection pooling in ODBC bridge. If set to false, a new connection is created every time.

offset

Type: Double
Default: 0
Tier: Production
Sets the number of rows to skip before starting to return rows from the query. It adjusts the offset set by the OFFSET clause. The value is passed through to OFFSET and accepts everything that OFFSET accepts, including negative values and fractions in (0, 1). Possible values: - 0 — No rows are skipped. - Positive integer. - Negative integer. - A real number in the open range (0, 1) — skip that fraction of the result. Example Input table: sql CREATE TABLE test (i UInt64) ENGINE = MergeTree() ORDER BY i; INSERT INTO test SELECT number FROM numbers(500); Query: sql SET limit = 5; SET offset = 7; SELECT * FROM test LIMIT 10 OFFSET 100; Result: text ┌───i─┐ │ 107 │ │ 108 │ │ 109 │ └─────┘ This setting shapes result-producing SELECT / UNION queries. For a write query (INSERT … SELECT, CREATE … AS SELECT) it takes effect only when the source SELECT carries it in its own SETTINGS clause; a value inherited from a profile or session, or set on the INSERT / CREATE statement itself, does not propagate into the source SELECT — the same non-propagation rule that applies to any other setting.

opentelemetry_start_keeper_trace_probability

Type: FloatAuto
Default: auto
Tier: Production
Probability to start a trace for ZooKeeper request - whether there is a parent trace or not. Possible values: - 'auto' - Equals the opentelemetry_start_trace_probability setting - 0 — Tracing is disabled - 0 to 1 — Probability (e.g., 1.0 = always enable)

opentelemetry_start_trace_probability

Type: Float
Default: 0
Tier: Production
Sets the probability that the RawTree can start a trace for executed queries (if no parent trace context is supplied). Possible values: - 0 — The trace for all executed queries is disabled (if no parent trace context is supplied). - Positive floating-point number in the range [0..1]. For example, if the setting value is 0,5, RawTree can start a trace on average for half of the queries. - 1 — The trace for all executed queries is enabled.

opentelemetry_trace_cpu_scheduling

Type: Bool
Default: 0
Tier: Production
Collect OpenTelemetry spans for workload preemptive CPU scheduling.

opentelemetry_trace_processors

Type: Bool
Default: 0
Tier: Production
Collect OpenTelemetry spans for processors.

optimize_aggregation_in_order

Type: Bool
Default: 0
Tier: Production
Enables GROUP BY optimization in SELECT queries for aggregating data in corresponding order in MergeTree tables. Possible values: - 0 — GROUP BY optimization is disabled. - 1 — GROUP BY optimization is enabled. See Also - GROUP BY optimization

optimize_aggregation_in_order_limit

Type: Bool
Default: 1
Tier: Production
When enabled and aggregation in order is active, pushes LIMIT into the aggregation step to enable early termination after producing enough groups. This reduces the amount of data read when ORDER BY matches the GROUP BY key prefix. May reduce the value reported by rows_before_limit_at_least; use exact_rows_before_limit if exact counts are needed.

optimize_aggregators_of_group_by_keys

Type: Bool
Default: 1
Tier: Production
Eliminates min/max/any/anyLast aggregators of GROUP BY keys in SELECT section

optimize_and_compare_chain

Type: Bool
Default: 1
Tier: Production
Populate constant comparison in AND chains to enhance filtering ability. Support operators <, <=, >, >=, = and mix of them. For example, (a < b) AND (b < c) AND (c < 5) would be (a < b) AND (b < c) AND (c < 5) AND indexHint(b < 5) AND indexHint(a < 5). The derived comparisons are wrapped in indexHint: they participate in index analysis (primary key, partition key, skipping indexes) and prune the read set, but cost nothing per row and do not affect PREWHERE. A comparison derived through expressions of different tables stays executable ((t1.a < t2.b) AND (t2.b < 5) derives plain t1.a < 5): it is the only condition that can be pushed below the join, where it filters a join input the original chain cannot reach. Derived comparisons that contradict an existing condition are also added as plain conditions, so the AND folds to false.

optimize_and_compare_chain_max_hash_work

Type: UInt64
Default: 5000000
Tier: Production
Work budget for the optimize_and_compare_chain optimization during query analysis, measured in the number of query-tree nodes hashed by getTreeHash (the dominant cost of this optimization). Once a query has hashed more than this many nodes while applying the optimization, it stops applying it for the rest of the query. This bounds analysis time for queries with very many or very large AND-chains of comparisons, where the optimization can otherwise dominate analysis while folding nothing. Stopping early is always safe: it only forgoes an optimization and never changes results. Set to 0 to disable the budget (unlimited).

optimize_append_index

Type: Bool
Default: 0
Tier: Production
Use constraints in order to append index condition. The default is false. Possible values: - true, false

optimize_arithmetic_operations_in_aggregate_functions

Type: Bool
Default: 1
Tier: Production
Move arithmetic operations out of aggregation functions

optimize_const_name_size

Type: Int64
Default: 256
Tier: Production
Replace with scalar and use hash as a name for large constants (size is estimated by the name length). Possible values: - positive integer - max length of the name, - 0 — always, - negative integer - never.

optimize_count_from_files

Type: Bool
Default: 1
Tier: Production
Enables or disables the optimization of counting number of rows from files in different input formats. It applies to table functions/engines file/s3/url/hdfs/azureBlobStorage. Possible values: - 0 — Optimization disabled. - 1 — Optimization enabled.

optimize_dictget_tuple_element

Type: Bool
Default: 1
Tier: Production
Rewrite tupleElement(dictGet('dict', ('a', 'b', 'c'), key), 2) into dictGet('dict', 'b', key) to avoid fetching unnecessary dictionary attributes. Supports positional (.1, .2, ...) and named (.b) access, and also applies to dictGetOrDefault when the default argument is a constant tuple or a tuple(...) of constants.

optimize_distinct_in_order

Type: Bool
Default: 1
Tier: Production
Enable DISTINCT optimization if some columns in DISTINCT form a prefix of sorting. For example, prefix of sorting key in merge tree or ORDER BY statement

optimize_distributed_group_by_sharding_key

Type: Bool
Default: 1
Tier: Production
Optimize GROUP BY sharding_key queries, by avoiding costly aggregation on the initiator server (which will reduce memory usage for the query on the initiator server). The following types of queries are supported (and all combinations of them): - SELECT DISTINCT [..., ]sharding_key[, ...] FROM dist - SELECT ... FROM dist GROUP BY sharding_key[, ...] - SELECT ... FROM dist GROUP BY sharding_key[, ...] ORDER BY x - SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1 - SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1 BY x The following types of queries are not supported (support for some of them may be added later): - SELECT ... GROUP BY sharding_key[, ...] WITH TOTALS - SELECT ... GROUP BY sharding_key[, ...] WITH ROLLUP - SELECT ... GROUP BY sharding_key[, ...] WITH CUBE - SELECT ... GROUP BY sharding_key[, ...] SETTINGS extremes=1 Possible values: - 0 — Disabled. - 1 — Enabled. See also: - distributed_group_by_no_merge - distributed_push_down_limit - optimize_skip_unused_shards :::note Right now it requires optimize_skip_unused_shards (the reason behind this is that one day it may be enabled by default, and it will work correctly only if data was inserted via Distributed table, i.e. data is distributed according to sharding_key). :::

optimize_dry_run_check_part

Type: Bool
Default: 1
Tier: Production
When enabled, OPTIMIZE ... DRY RUN validates the resulting merged part using checkDataPart. If the check fails, an exception is thrown.

optimize_dynamic_types_distribution_query

Type: Bool
Default: 1
Tier: Production
Serve SELECT dynamicType(d), count() FROM t GROUP BY dynamicType(d) (where d is a Dynamic column) from the per-part variant statistics persisted in the Dynamic structure stream instead of reading the column data. Each part is processed by its own source during query execution. Parts whose statistics are not exact (Compact parts, parts with more distinct types in the shared variant than the shared variant statistics can hold) are read in full and counted by their source, so the result is always exact. The optimization is not applied with WHERE/PREWHERE, FINAL, SAMPLE, row policies, transactions, lightweight deletes, patch parts or pending mutations. Possible values: - 0 — Optimization disabled. - 1 — Optimization enabled.

optimize_empty_string_comparisons

Type: Bool
Default: 1
Tier: Production
Convert expressions like col = '' or '' = col into empty(col), and col != '' or '' != col into notEmpty(col), only when col is of String or FixedString type.

optimize_extract_common_expressions

Type: Bool
Default: 1
Tier: Production
Allow extracting common expressions from disjunctions in WHERE, PREWHERE, ON, HAVING and QUALIFY expressions. A logical expression like (A AND B) OR (A AND C) can be rewritten to A AND (B OR C), which might help to utilize: - indices in simple filtering expressions - cross to inner join optimization

optimize_functions_to_subcolumns

Type: Bool
Default: 1
Tier: Production
Enables or disables optimization by transforming some functions to reading subcolumns. This reduces the amount of data to read. These functions can be transformed: - length to read the size0 subcolumn. - empty to read the size0 subcolumn. - notEmpty to read the size0 subcolumn. - isNull to read the null subcolumn. - isNotNull to read the null subcolumn. - count to read the null subcolumn. - mapKeys to read the keys subcolumn. - mapValues to read the values subcolumn. Possible values: - 0 — Optimization disabled. - 1 — Optimization enabled.

optimize_group_by_constant_keys

Type: Bool
Default: 1
Tier: Production
Optimize GROUP BY when all keys in block are constant

optimize_group_by_function_keys

Type: Bool
Default: 1
Tier: Production
Eliminates functions of other keys in GROUP BY section

optimize_if_chain_to_multiif

Type: Bool
Default: 0
Tier: Production
Replace if(cond1, then1, if(cond2, ...)) chains to multiIf. Currently it's not beneficial for numeric types.

optimize_if_transform_strings_to_enum

Type: Bool
Default: 0
Tier: Production
Replaces string-type arguments in If and Transform to enum. Disabled by default cause it could make inconsistent change in distributed query that would lead to its fail.

optimize_injective_functions_in_group_by

Type: Bool
Default: 1
Tier: Production
Replaces injective functions by it's arguments in GROUP BY section

optimize_injective_functions_in_limit_by

Type: Bool
Default: 1
Tier: Production
Replaces injective functions by their arguments in LIMIT BY section. Example: LIMIT 5 BY toString(x) becomes LIMIT 5 BY x.

optimize_injective_functions_inside_uniq

Type: Bool
Default: 1
Tier: Production
Delete injective functions of one argument inside uniq*() functions.

optimize_inverse_dictionary_lookup

Type: Bool
Default: 1
Tier: Production
Avoid repeated inverse dictionary lookup by doing faster lookups into a precomputed set of possible key values.

optimize_limit_by_function_keys

Type: Bool
Default: 1
Tier: Production
Eliminates functions of other keys in LIMIT BY section. Example: LIMIT 5 BY x, f(x) becomes LIMIT 5 BY x.

optimize_limit_by_in_order

Type: Bool
Default: 1
Tier: Production
Optimize SELECT ... LIMIT N BY <cols> queries when <cols> (in any order) form a prefix of the table's sorting key, or become one after WHERE col = const fixes leading columns. With this enabled the source reads data in primary-key order, so rows with equal values of the BY columns arrive adjacent to each other within each stream. When the data arrives in a single sorted stream, LIMIT BY filters it in streaming mode with O(1) memory, instead of building a hash table of every distinct combination of BY columns seen. When the sorted data arrives in multiple streams and the same BY values can appear in more than one of them, each stream is first prefiltered in streaming mode down to at most LIMIT + OFFSET rows per group, then the streams are combined and a final hash-based LIMIT BY deduplicates groups that span several streams. That final pass still keeps an entry for every distinct combination of BY columns, but it only processes the prefiltered rows.

optimize_min_equality_disjunction_chain_length

Type: UInt64
Default: 3
Tier: Production
The minimum length of the expression expr = x1 OR ... expr = xN for optimization

optimize_min_inequality_conjunction_chain_length

Type: UInt64
Default: 3
Tier: Production
The minimum length of the expression expr <> x1 AND ... expr <> xN for optimization

optimize_move_to_prewhere

Type: Bool
Default: 1
Tier: Production
Enables or disables automatic PREWHERE optimization in SELECT queries. Works only for *MergeTree tables. Possible values: - 0 — Automatic PREWHERE optimization is disabled. - 1 — Automatic PREWHERE optimization is enabled.

optimize_move_to_prewhere_if_final

Type: Bool
Default: 0
Tier: Production
Enables or disables automatic PREWHERE optimization in SELECT queries with FINAL modifier. Works only for *MergeTree tables. Possible values: - 0 — Automatic PREWHERE optimization in SELECT queries with FINAL modifier is disabled. - 1 — Automatic PREWHERE optimization in SELECT queries with FINAL modifier is enabled. See Also - optimize_move_to_prewhere setting

optimize_multiif_to_if

Type: Bool
Default: 1
Tier: Production
Replace 'multiIf' with only one condition to 'if'.

optimize_normalize_count_variants

Type: Bool
Default: 1
Tier: Production
Rewrite aggregate functions that semantically equals to count() as count().

optimize_on_insert

Type: Bool
Default: 1
Tier: Production
Enables or disables data transformation before the insertion, as if merge was done on this block (according to table engine). Possible values: - 0 — Disabled. - 1 — Enabled. Example The difference between enabled and disabled: Query: sql SET optimize_on_insert = 1; CREATE TABLE test1 (`FirstTable` UInt32) ENGINE = ReplacingMergeTree ORDER BY FirstTable; INSERT INTO test1 SELECT number % 2 FROM numbers(5); SELECT * FROM test1; SET optimize_on_insert = 0; CREATE TABLE test2 (`SecondTable` UInt32) ENGINE = ReplacingMergeTree ORDER BY SecondTable; INSERT INTO test2 SELECT number % 2 FROM numbers(5); SELECT * FROM test2; Result: text ┌─FirstTable─┐ │ 0 │ │ 1 │ └────────────┘ ┌─SecondTable─┐ │ 0 │ │ 0 │ │ 0 │ │ 1 │ │ 1 │ └─────────────┘ Note that this setting influences Materialized view behaviour.

optimize_or_like_chain

Type: Bool
Default: 1
Tier: Production
Optimize multiple OR LIKE/ILIKE/match predicates on the same expression into a single multiSearchAny/multiSearchAnyCaseInsensitiveUTF8 (for pure-substring %needle% patterns) or multiMatchAny (for other patterns, when Hyperscan/Vectorscan is permitted). When neither fast path is applicable — for example when Hyperscan is disabled or unavailable, or the patterns are raw match regexps, not valid UTF-8, contain an embedded NUL, are end-anchored (do not end in an unescaped %; Vectorscan matches $ before a final newline, so the rewrite would widen the filter), or the haystack is FixedString/Enum — the original OR chain is kept unchanged, because a combined match alternation over RE2 is consistently slower than the original short-circuit OR. The optimization is applied only with the analyzer (enable_analyzer = 1, the default); with the old analyzer (enable_analyzer = 0) the OR chain is left unchanged. For pure LIKE/ILIKE/match OR chains the original expressions are preserved in indexHint() to allow index analysis; mixed OR chains that include non-LIKE branches intentionally skip indexHint() wrapping so that ranges matching only the non-LIKE branch are not pruned. The multiMatchAny rewrite honors allow_hyperscan, max_hyperscan_regexp_length, max_hyperscan_regexp_total_length and reject_expensive_hyperscan_regexps. A chain is rewritten only when it has enough branches sharing the same left-hand-side expression to make the rewrite reliably faster than short-circuit OR evaluation: at least optimize_or_like_chain_min_substrings branches for the multiSearchAny path, and at least optimize_or_like_chain_min_patterns branches for the multiMatchAny path.

optimize_or_like_chain_min_patterns

Type: UInt64
Default: 10
Tier: Production
Minimum number of non-pure-substring LIKE/ILIKE/match branches (prefix/suffix/regexp patterns), sharing the same left-hand-side expression, required for optimize_or_like_chain to rewrite a chain into multiMatchAny. Calibrated on the hits dataset (see tests/performance/optimize_or_like_chain_hits.xml): a multiMatchAny (Hyperscan) rewrite of prefix/regexp LIKE chains only becomes faster than short-circuit OR evaluation from about nine branches, so shorter chains are kept as-is to avoid regressing them. A value of 0 or 1 disables the threshold. Has no effect when optimize_or_like_chain is disabled. See also optimize_or_like_chain_min_substrings for the pure-substring (multiSearchAny) path.

optimize_or_like_chain_min_substrings

Type: UInt64
Default: 4
Tier: Production
Minimum number of pure-substring (%needle%) LIKE/ILIKE branches, sharing the same left-hand-side expression, required for optimize_or_like_chain to rewrite a chain into multiSearchAny/multiSearchAnyCaseInsensitiveUTF8. Calibrated on the hits dataset (see tests/performance/optimize_or_like_chain_hits.xml): the multiSearchAny rewrite becomes faster than short-circuit OR evaluation from about four branches. A value of 0 or 1 disables the threshold. Has no effect when optimize_or_like_chain is disabled. See also optimize_or_like_chain_min_patterns for the regexp (multiMatchAny) path.

optimize_prewhere_after_pushdown

Type: Bool
Default: 0
Tier: Production
Run a second PREWHERE promotion pass after later query plan optimizations may have deposited additional filters above a MergeTree read step (e.g. predicate pushdown through JOIN, projection rewrites). When an existing PREWHERE is already present, the new filter is AND-merged into it instead of staying as a separate filter step.

optimize_qbit_distance_function_reads

Type: Bool
Default: 1
Tier: Production
Replace distance functions on QBit data type with equivalent ones that only read the columns necessary for the calculation from the storage.

optimize_read_in_order

Type: Bool
Default: 1
Tier: Production
Enables ORDER BY optimization in SELECT queries for reading data from MergeTree tables. Possible values: - 0 — ORDER BY optimization is disabled. - 1 — ORDER BY optimization is enabled. See Also - ORDER BY Clause

optimize_read_in_window_order

Type: Bool
Default: 0
Tier: Production
Toggles a query-plan-level optimization which uses storage sorting when sorting for window functions. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

optimize_redundant_comparisons

Type: Bool
Default: 1
Tier: Production
Detect conflicting and redundant comparison conditions on the same expression within AND chains. For example, a < 1 AND a > 5 would be rewritten to false. A contradiction between two equals on the same expression (for example, a = 1 AND a = 2) is detected independently of this setting.

optimize_redundant_functions_in_order_by

Type: Bool
Default: 1
Tier: Production
Remove functions from ORDER BY if its argument is also in ORDER BY

optimize_respect_aliases

Type: Bool
Default: 1
Tier: Production
If it is set to true, it will respect aliases in WHERE/GROUP BY/ORDER BY, that will help with partition pruning/secondary indexes/optimize_aggregation_in_order/optimize_read_in_order/optimize_trivial_count

optimize_rewrite_aggregate_function_with_if

Type: Bool
Default: 1
Tier: Production
Rewrite aggregate functions with if expression as argument when logically equivalent. For example, avg(if(cond, col, null)) can be rewritten to avgOrNullIf(cond, col). It may improve performance. :::note Supported only with the analyzer (enable_analyzer = 1). :::

optimize_rewrite_array_exists_to_has

Type: Bool
Default: 1
Tier: Production
Rewrite arrayExists() functions to has() when logically equivalent. For example, arrayExists(x -> x = 1, arr) can be rewritten to has(arr, 1)

optimize_rewrite_has_to_in

Type: Bool
Default: 1
Tier: Production
Rewrite has functions to IN when the first argument is a constant array. For example, has([1, 2, 3], x) can be rewritten to x IN [1, 2, 3] for better performance with constant arrays

optimize_rewrite_like_perfect_affix

Type: Bool
Default: 1
Tier: Production
Rewrite LIKE expressions with perfect prefix or suffix (e.g. col LIKE 'ClickHouse%') to startsWith or endsWith functions (e.g. startsWith(col, 'ClickHouse')).

optimize_rewrite_regexp_functions

Type: Bool
Default: 1
Tier: Production
Rewrite regular expression related functions into simpler and more efficient forms

optimize_rewrite_sum_if_to_count_if

Type: Bool
Default: 1
Tier: Production
Rewrite sumIf() and sum(if()) function countIf() function when logically equivalent

optimize_skip_merged_partitions

Type: Bool
Default: 0
Tier: Production
Enables or disables optimization for OPTIMIZE TABLE ... FINAL query if there is only one part with level > 0 and it doesn't have expired TTL. - OPTIMIZE TABLE ... FINAL SETTINGS optimize_skip_merged_partitions=1 By default, OPTIMIZE TABLE ... FINAL query rewrites the one part even if there is only a single part. Possible values: - 1 - Enable optimization. - 0 - Disable optimization.

optimize_skip_unused_shards

Type: Bool
Default: 0
Tier: Production
Enables or disables skipping of unused shards for SELECT queries that have sharding key condition in WHERE/PREWHERE, and activates related optimizations for distributed queries (e.g. aggregation by sharding key). :::note Assumes that the data is distributed by sharding key, otherwise a query yields incorrect result. ::: Possible values: - 0 — Disabled. - 1 — Enabled.

optimize_skip_unused_shards_limit

Type: UInt64
Default: 1000
Tier: Production
Limit for number of sharding key values, turns off optimize_skip_unused_shards if the limit is reached. Too many values may require significant amount for processing, while the benefit is doubtful, since if you have huge number of values in IN (...), then most likely the query will be sent to all shards anyway.

optimize_skip_unused_shards_nesting

Type: UInt64
Default: 0
Tier: Production
Controls optimize_skip_unused_shards (hence still requires optimize_skip_unused_shards) depends on the nesting level of the distributed query (case when you have Distributed table that look into another Distributed table). Possible values: - 0 — Disabled, optimize_skip_unused_shards works always. - 1 — Enables optimize_skip_unused_shards only for the first level. - 2 — Enables optimize_skip_unused_shards up to the second level.

optimize_skip_unused_shards_rewrite_in

Type: Bool
Default: 1
Tier: Production
Rewrite IN in query for remote shards to exclude values that does not belong to the shard (requires optimize_skip_unused_shards). Possible values: - 0 — Disabled. - 1 — Enabled.

optimize_sorting_by_input_stream_properties

Type: Bool
Default: 1
Tier: Production
Optimize sorting by sorting properties of input stream

optimize_substitute_columns

Type: Bool
Default: 0
Tier: Production
Use constraints for column substitution. The default is false. Possible values: - true, false

optimize_syntax_fuse_functions

Type: Bool
Default: 1
Tier: Production
Enables to fuse aggregate functions with identical argument. It rewrites query contains at least two aggregate functions from sum, count or avg with identical argument to sumCount. Possible values: - 0 — Functions with identical argument are not fused. - 1 — Functions with identical argument are fused. Example Query: sql CREATE TABLE fuse_tbl(a Int8, b Int8) Engine = Log; SET optimize_syntax_fuse_functions = 1; EXPLAIN SYNTAX run_query_tree_passes = 1 SELECT sum(a), sum(b), count(b), avg(b) from fuse_tbl FORMAT TSVRaw; Result: text SELECT sum(__table1.a) AS `sum(a)`, tupleElement(sumCount(__table1.b), 1) AS `sum(b)`, tupleElement(sumCount(__table1.b), 2) AS `count(b)`, divide(tupleElement(sumCount(__table1.b), 1), toFloat64(tupleElement(sumCount(__table1.b), 2))) AS `avg(b)` FROM default.fuse_tbl AS __table1

optimize_throw_if_noop

Type: Bool
Default: 0
Tier: Production
Enables or disables throwing an exception if an OPTIMIZE query didn't perform a merge. By default, OPTIMIZE returns successfully even if it didn't do anything. This setting lets you differentiate these situations and get the reason in an exception message. Possible values: - 1 — Throwing an exception is enabled. - 0 — Throwing an exception is disabled.

optimize_time_filter_with_preimage

Type: Bool
Default: 1
Tier: Production
Optimize Date and DateTime predicates by converting functions into equivalent comparisons without conversions (e.g. toYear(col) = 2023 -> col >= '2023-01-01' AND col <= '2023-12-31')

optimize_trivial_approximate_count_query

Type: Bool
Default: 0
Tier: Production
Use an approximate value for trivial count optimization of storages that support such estimation, for example, EmbeddedRocksDB. Possible values: - 0 — Optimization disabled. - 1 — Optimization enabled.

optimize_trivial_count_query

Type: Bool
Default: 1
Tier: Production
Enables or disables the optimization to trivial query SELECT count() FROM table using metadata from MergeTree. If you need to use row-level security, disable this setting. Possible values: - 0 — Optimization disabled. - 1 — Optimization enabled. See also: - optimize_functions_to_subcolumns

optimize_trivial_count_with_sparsity_filter

Type: Bool
Default: 1
Tier: Beta
Extends the optimize_trivial_count_query optimization to queries of the form SELECT count() FROM t WHERE col <op> const, where <op> const exactly partitions rows into defaults and non-defaults of col. The count is then served from the per-column num_defaults / num_rows counters that MergeTree already keeps in serialization.json, with no data scan. Patterns recognised: - col = default(col) / col != default(col) for Int* / UInt*, String / FixedString, Date / DateTime / DateTime64, Decimal*, UUID, IPv4 / IPv6. - IS NULL / IS NOT NULL on Nullable columns. - empty(col) / notEmpty(col) on String columns. - col = true / col != true on Bool columns. - col > 0, col >= 1, col < 1, col <= 0 on unsigned integer columns. - Bare col / NOT col on Int*, UInt*, Bool columns (truthy test). The equality patterns are not applied to Float*, Enum*, Date32, Nullable, LowCardinality, or composite types (Tuple, Array, Map, ...) — for these the count is served from the regular scan path. To take effect, the per-part num_defaults counter must be exact. Enable the MergeTree table setting compute_exact_num_defaults_for_sparse_columns on the target table before inserts and merges. Parts written without it are silently opted out of the rewrite, so enabling optimize_trivial_count_with_sparsity_filter alone is not enough. For the IS NULL / IS NOT NULL patterns on Nullable columns, the column must also have a num_defaults entry in serialization.json, which only happens when the MergeTree table setting nullable_serialization_version is set to allow_sparse at insert / merge time. With the default value basic Nullable columns get no per-column entry, so the optimization silently does not apply. Possible values: - 0 — Optimization disabled. - 1 — Optimization enabled. See also: - optimize_trivial_count_query

optimize_trivial_group_by_limit_query

Type: Bool
Default: 1
Tier: Production
Enables or disables the optimization of a trivial query SELECT key_expr FROM table GROUP BY key_expr LIMIT n (with no aggregate functions, window functions or arrayJoin in the projection, no HAVING/ORDER BY/QUALIFY/LIMIT BY/DISTINCT/window clauses, and no GROUP BY modifiers) by setting max_rows_to_group_by = n + offset with group_by_overflow_mode = 'any'. The aggregation stops once n + offset distinct keys are produced. The optimization is suppressed when the user has explicitly set group_by_overflow_mode to a non-any value (to preserve their explicit throw/break contract), and when the user has already set a tighter max_rows_to_group_by (the optimization would be a no-op). Possible values: - 0 — Optimization disabled. - 1 — Optimization enabled.

optimize_trivial_insert_select

Type: Bool
Default: 0
Tier: Production
Optimize trivial 'INSERT INTO table SELECT ... FROM TABLES' query

optimize_trivial_limit_query

Type: Bool
Default: 1
Tier: Production
Enables an optimization for trivial LIMIT queries on MergeTree tables. A query is a trivial LIMIT query when it has a LIMIT but no WHERE, PREWHERE, GROUP BY, HAVING, ORDER BY, DISTINCT, LIMIT BY, JOIN, aggregate or window functions. Such a query may return any limit + offset rows of the table. When this setting is enabled and a subset of the parts already contains enough rows to satisfy the limit, the remaining parts are pruned before reading, which avoids opening their data files. The optimization is automatically skipped for queries with FINAL, SAMPLE, lightweight deletes, on-the-fly mutations, parallel replicas and other cases where the number of rows stored in a part does not match the number of rows the query would read from it. Note that, like any LIMIT without ORDER BY, the set of rows returned is not deterministic; this optimization can change which rows are returned, but not their count. Possible values: - 0 — Optimization disabled. - 1 — Optimization enabled.

optimize_trivial_view_pushdown_to_distributed

Type: Bool
Default: 1
Tier: Production
When enabled, for views over Distributed tables whose SELECT list contains only column references, *, or expressions (but no window functions or scalar subqueries), and that have no aggregation, grouping, ordering, or joins, the full outer query is pushed to each shard. This allows the shard to apply the view's filters and expressions locally, reducing the amount of data transferred over the network. Possible values: - 0 — The optimization is disabled; views over Distributed tables are always executed on the coordinator. - 1 — The optimization is enabled.

optimize_truncate_order_by_after_group_by_keys

Type: Bool
Default: 1
Tier: Production
Remove trailing ORDER BY elements once all GROUP BY keys are covered in the ORDER BY prefix.

optimize_uniq_to_count

Type: Bool
Default: 1
Tier: Production
Rewrite uniq and its variants(except uniqUpTo) to count if subquery has distinct or group by clause.

optimize_use_implicit_projections

Type: Bool
Default: 1
Tier: Production
Automatically choose implicit projections to perform SELECT query

optimize_use_projection_filtering

Type: Bool
Default: 1
Tier: Production
Enables using projections to filter part ranges even when projections are not selected to perform SELECT query.

optimize_use_projections

Type: Bool
Default: 1
Tier: Production
Enables or disables projection optimization when processing SELECT queries. Possible values: - 0 — Projection optimization disabled. - 1 — Projection optimization enabled.

optimize_using_constraints

Type: Bool
Default: 0
Tier: Production
Use constraints for query optimization. The default is false. Possible values: - true, false

order

Type: String
Default: ``
Tier: Production
Adds an ORDER BY clause to the query as a wrapping subquery. Accepts an arbitrary expression list. This is a query-construction setting applied by the engine on the parsed query (wrapping it as a derived table), so it composes with the existing query and works on every protocol: it can be supplied via the HTTP URL parameter, an in-query SETTINGS clause, or a user profile. It shapes result-producing SELECT / UNION queries. For a write query (INSERT … SELECT, CREATE … AS SELECT) it takes effect only when the source SELECT carries it in its own SETTINGS clause; a value inherited from a profile or session, or set on the INSERT / CREATE statement itself, does not propagate into the source SELECT — the same non-propagation rule that applies to any other setting.

os_thread_priority

Type: Int32
Default: 0
Tier: Production
Linux nice value for query processing threads. Lower values mean higher CPU priority. Requires CAP_SYS_NICE capability, otherwise no-op. Possible values: -20 to 19.

os_threads_nice_value_materialized_view

Type: Int32
Default: 0
Tier: Production
Linux nice value for materialized view threads. Lower values mean higher CPU priority. Requires CAP_SYS_NICE capability, otherwise no-op. Possible values: -20 to 19.

os_threads_nice_value_query

Type: Int32
Default: 0
Tier: Production
Linux nice value for query processing threads. Lower values mean higher CPU priority. Requires CAP_SYS_NICE capability, otherwise no-op. Possible values: -20 to 19.

output_format

Type: String
Default: ``
Tier: Production
Overrides the output format of the query. Wins over the format specified in the query, in the file extension, or via default_format.

output_format_always_write_decimal_point_in_float_and_decimal

Type: Bool
Default: 0
Tier: Production
Always print a decimal point for floating-point and Decimal numbers in text formats, even when the value is a whole number. For example, output 1. instead of 1. Disabled by default.

output_format_arrow_compression_method

Type: ArrowCompression
Default: lz4_frame
Tier: Production
Compression method for Arrow output format. Supported codecs: lz4_frame, zstd, none (uncompressed)

output_format_arrow_date_as_uint16

Type: Bool
Default: 0
Tier: Production
Write Date values as plain 16-bit numbers (read back as UInt16), instead of converting to a 32-bit Arrow DATE32 type (read back as Date32).

output_format_arrow_fixed_string_as_fixed_byte_array

Type: Bool
Default: 1
Tier: Production
Use Arrow FIXED_SIZE_BINARY type instead of Binary for FixedString columns.

output_format_arrow_low_cardinality_as_dictionary

Type: Bool
Default: 0
Tier: Production
Enable output LowCardinality type as Dictionary Arrow type

output_format_arrow_record_batch_size

Type: UInt64
Default: 0
Tier: Production
Target number of rows per record batch for the Arrow and ArrowStream output formats. Combining small blocks reduces metadata and buffer-padding overhead, particularly for queries with selective filters. Blocks accumulate until this target or output_format_arrow_record_batch_size_bytes is reached. A block that already meets the row or byte target is written separately, without splitting. If you set a row target, combined batches contain fewer than twice that many rows, but a single input block can be larger. Buffering blocks can increase memory use and delay output. If the result never reaches either target, ArrowStream writes the first record batch only when the query finishes, though it can write the schema earlier. Leave both targets at 0 to write record batches as blocks arrive. 0 (the default) disables the row target. Try 65409 as a starting value.

output_format_arrow_record_batch_size_bytes

Type: UInt64
Default: 0
Tier: Production
Target record batch size for the Arrow and ArrowStream output formats, measured in bytes of accumulated block data. This uses the same measure as min_insert_block_size_bytes. A batch is written when either this target or output_format_arrow_record_batch_size is reached. Note that LowCardinality columns can produce Arrow batches much larger or smaller than this byte target. Repeated values expand in the output unless output_format_arrow_low_cardinality_as_dictionary is enabled. Filtered blocks can also retain large dictionaries, so even a block with very few rows can reach the target and be written separately. For these columns, use output_format_arrow_record_batch_size to control the row count and set the byte target to 0. Buffering blocks can increase memory use and delay the first record batch until the query finishes. Leave both targets at 0 to write record batches as blocks arrive. 0 (the default) disables the byte target. Try 1048576 (1 MiB) as a starting value.

output_format_arrow_string_as_string

Type: Bool
Default: 1
Tier: Production
Use Arrow String type instead of Binary for String columns

output_format_arrow_unsupported_types_as_binary

Type: Bool
Default: 1
Tier: Production
Output types having no conversion as raw binary data. If false - such types would raise UNKNOWN_TYPE exception.

output_format_arrow_use_64_bit_indexes_for_dictionary

Type: Bool
Default: 0
Tier: Production
Always use 64 bit integers for dictionary indexes in Arrow format

output_format_arrow_use_signed_indexes_for_dictionary

Type: Bool
Default: 1
Tier: Production
Use signed integers for dictionary indexes in Arrow format

output_format_avro_codec

Type: String
Default: ``
Tier: Production
Compression codec used for output. Possible values: 'null', 'deflate', 'snappy', 'zstd'.

output_format_avro_confluent_subject

Type: String
Default: ``
Tier: Production
For AvroConfluent output format: the subject name under which the schema is registered in the Confluent Schema Registry. Required when writing AvroConfluent output.

output_format_avro_rows_in_file

Type: UInt64
Default: 1
Tier: Production
Max rows in a file (if permitted by storage)

output_format_avro_string_column_pattern

Type: String
Default: ``
Tier: Production
For Avro format: regexp of String columns to select as AVRO string.

output_format_avro_sync_interval

Type: UInt64
Default: 16384
Tier: Production
Sync interval in bytes.

output_format_binary_encode_types_in_binary_format

Type: Bool
Default: 0
Tier: Production
Write data types in binary format instead of type names in RowBinaryWithNamesAndTypes output format

output_format_binary_write_json_as_string

Type: Bool
Default: 0
Tier: Production
Write values of JSON data type as JSON String values in RowBinary output format.

output_format_bson_string_as_string

Type: Bool
Default: 0
Tier: Production
Use BSON String type instead of Binary for String columns.

output_format_compression_level

Type: UInt64
Default: 3
Tier: Production
Default compression level if query output is compressed. The setting is applied when SELECT query has INTO OUTFILE or when writing to table functions file, url, hdfs, s3, or azureBlobStorage. It is also applied to the compressed response to an HTTP request with a method other than gzip and deflate, for which http_zlib_compression_level is used. Possible values: from 1 to 22

output_format_compression_zstd_window_log

Type: UInt64
Default: 0
Tier: Production
Can be used when the output compression method is zstd. If greater than 0, this setting explicitly sets compression window size (power of 2) and enables a long-range mode for zstd compression. This can help to achieve a better compression ratio. Possible values: non-negative numbers. Note that if the value is too small or too big, zstdlib will throw an exception. Typical values are from 20 (window size = 1MB) to 30 (window size = 1GB).

output_format_csv_crlf_end_of_line

Type: Bool
Default: 0
Tier: Production
If it is set true, end of line in CSV format will be \r\n instead of \n.

output_format_csv_header_serialize_tuple_into_separate_columns

Type: Bool
Default: 1
Tier: Production
When output_format_csv_serialize_tuple_into_separate_columns is enabled, the header rows of CSVWithNames and CSVWithNamesAndTypes flatten each bare Tuple column into its leaf fields (dotted names like t.a, t.b, and the leaf type names), so the header has the same number of columns as the data. A Nullable(Tuple) column is never flattened (its data stays a single CSV field), so its header keeps the single top-level column name and type. For CustomSeparated* this flattening applies only when format_custom_escaping_rule = 'CSV' and format_custom_field_delimiter is a single character equal to format_csv_delimiter; otherwise (for example the default tab delimiter or format_custom_field_delimiter = '|') the header stays unflattened so it still matches the data. Set it to 0 to keep the previous behavior where the header keeps the single top-level Tuple name and type. Note: a flattened header is not read back into a Tuple by name when input_format_with_names_use_header = 1. To read such data back into a Tuple, either set this setting to 0 on output, or read with input_format_with_names_use_header = 0 (and, for the *WithNamesAndTypes formats CSVWithNamesAndTypes and CustomSeparatedWithNamesAndTypes, also input_format_with_types_use_header = 0, since the flattened types row is otherwise validated against the single top-level Tuple input field and rejected).

output_format_csv_serialize_tuple_into_separate_columns

Type: Bool
Default: 1
Tier: Production
If it set to true, then bare Tuple columns in CSV format are serialized as separate columns (that is, their nesting in the tuple is lost). This flattening applies only to bare Tuple. A Nullable(Tuple) is always serialized as a single CSV field (so that NULL and non-null rows occupy the same number of fields), regardless of this setting.

output_format_decimal_trailing_zeros

Type: Bool
Default: 0
Tier: Production
Output trailing zeros when printing Decimal values. E.g. 1.230000 instead of 1.23. Disabled by default.

output_format_float_precision

Type: UInt64
Default: 0
Tier: Production
When non-zero, format floating-point output (Float32, Float64, BFloat16) with at most this many digits after the decimal point (trailing zeros are removed). When 0 (the default), use the shortest round-trip representation. Values too large for fixed notation, and values whose magnitude is so small that rounding to the requested precision would lose all significant digits (the mantissa would become ±0), are emitted in scientific notation instead. In these fallback cases the mantissa may carry more than the requested number of fractional digits. Valid range: 0 to 100.

output_format_image_height

Type: UInt64
Default: 1024
Tier: Production
The height of the output image in pixels for image output formats such as PNG. Default value: 1024.

output_format_image_streaming_animation

Type: Bool
Default: 0
Tier: Production
For image output formats such as PNG, write each frame of an animation as soon as the next value of the t column is seen, instead of buffering all the frames in memory until the end of the query. Only one frame is kept in memory, and the frames reach the output while the query is still running. In exchange, the values of t must be non-decreasing, otherwise the query throws an exception, and the number of frames is not known when the header of the animation has to be written, so the declared frame count is an upper bound rather than the exact value. Browsers play such a file, but decoders that trust the declared count report an error after the last real frame. Default value: false.

output_format_image_terminal_mode

Type: String
Default: **Tier:** Production For image output formats such as `PNG`, output the image directly to the terminal using an inline image protocol instead of writing the raw image bytes. Possible values: - (empty) — write the raw image bytes (the default). - iterm — use the iTerm2 inline image protocol. - kitty — use the Kitty graphics protocol. - sixel — use the Sixel protocol. - auto — if the output is a terminal, detect its capabilities and use iterm, kitty, or sixel (in this order); otherwise write the raw image bytes. Default value: `` (empty).

output_format_image_time_divisor_seconds

Type: UInt64
Default: 60
Tier: Production
The denominator of the time unit of the t column, in seconds, for image output formats such as PNG. See output_format_image_time_multiplier_seconds. Default value: 60.

output_format_image_time_multiplier_seconds

Type: UInt64
Default: 1
Tier: Production
The numerator of the time unit of the t column, in seconds, for image output formats such as PNG. The presence of a t column makes the format produce an animation, in which t is the relative time offset of the frame. One unit of t corresponds to output_format_image_time_multiplier_seconds / output_format_image_time_divisor_seconds seconds. With the default values (1 and 60), one unit of t is 1/60 of a second. Default value: 1.

output_format_image_width

Type: UInt64
Default: 1024
Tier: Production
The width of the output image in pixels for image output formats such as PNG. Default value: 1024.

output_format_json_array_of_rows

Type: Bool
Default: 0
Tier: Production
Enables the ability to output all rows as a JSON array in the JSONEachRow format. Possible values: - 1 — RawTree outputs all rows as an array, each row in the JSONEachRow format. - 0 — RawTree outputs each row separately in the JSONEachRow format. Example of a query with the enabled setting Query: sql SET output_format_json_array_of_rows = 1; SELECT number FROM numbers(3) FORMAT JSONEachRow; Result: text [ {"number":"0"}, {"number":"1"}, {"number":"2"} ] Example of a query with the disabled setting Query: sql SET output_format_json_array_of_rows = 0; SELECT number FROM numbers(3) FORMAT JSONEachRow; Result: text {"number":"0"} {"number":"1"} {"number":"2"}

output_format_json_escape_forward_slashes

Type: Bool
Default: 1
Tier: Production
Controls escaping forward slashes for string outputs in JSON output format. This is intended for compatibility with JavaScript. Don't confuse with backslashes that are always escaped. Enabled by default.

output_format_json_map_as_array_of_tuples

Type: Bool
Default: 0
Tier: Production
Serialize maps columns as JSON arrays of tuples. Disabled by default.

output_format_json_named_tuples_as_objects

Type: Bool
Default: 1
Tier: Production
Serialize named tuple columns as JSON objects. Enabled by default.

output_format_json_pretty_print

Type: Bool
Default: 1
Tier: Production
This setting determines how nested structures such as Tuples, Maps, and Arrays are displayed within the data array when using the JSON output format. For example, instead of output: json "data": [ { "tuple": {"a":1,"b":2,"c":3}, "array": [1,2,3], "map": {"a":1,"b":2,"c":3} } ], The output will be formatted as: json "data": [ { "tuple": { "a": 1, "b": 2, "c": 3 }, "array": [ 1, 2, 3 ], "map": { "a": 1, "b": 2, "c": 3 } } ], Enabled by default.

output_format_json_quote_64bit_floats

Type: Bool
Default: 0
Tier: Production
Controls quoting of 64-bit floats when they are output in JSON* formats. Disabled by default.

output_format_json_quote_64bit_integers

Type: Bool
Default: 0
Tier: Production
Controls quoting of 64-bit or bigger integers (like UInt64 or Int128) when they are output in a JSON format. Such integers are enclosed in quotes by default. This behavior is compatible with most JavaScript implementations. Possible values: - 0 — Integers are output without quotes. - 1 — Integers are enclosed in quotes.

output_format_json_quote_decimals

Type: Bool
Default: 0
Tier: Production
Controls quoting of decimals in JSON output formats. Disabled by default.

output_format_json_quote_denormals

Type: Bool
Default: 0
Tier: Production
Enables +nan, -nan, +inf, -inf outputs in JSON output format. Possible values: - 0 — Disabled. - 1 — Enabled. Example Consider the following table account_orders: text ┌─id─┬─name───┬─duration─┬─period─┬─area─┐ │ 1 │ Andrew │ 20 │ 0 │ 400 │ │ 2 │ John │ 40 │ 0 │ 0 │ │ 3 │ Bob │ 15 │ 0 │ -100 │ └────┴────────┴──────────┴────────┴──────┘ When output_format_json_quote_denormals = 0, the query returns null values in output: sql SELECT area/period FROM account_orders FORMAT JSON; json { "meta": [ { "name": "divide(area, period)", "type": "Float64" } ], "data": [ { "divide(area, period)": null }, { "divide(area, period)": null }, { "divide(area, period)": null } ], "rows": 3, "statistics": { "elapsed": 0.003648093, "rows_read": 3, "bytes_read": 24 } } When output_format_json_quote_denormals = 1, the query returns: json { "meta": [ { "name": "divide(area, period)", "type": "Float64" } ], "data": [ { "divide(area, period)": "inf" }, { "divide(area, period)": "-nan" }, { "divide(area, period)": "-inf" } ], "rows": 3, "statistics": { "elapsed": 0.000070241, "rows_read": 3, "bytes_read": 24 } }

output_format_json_skip_null_value_in_named_tuples

Type: Bool
Default: 0
Tier: Production
Skip key value pairs with null value when serialize named tuple columns as JSON objects. It is only valid when output_format_json_named_tuples_as_objects is true.

output_format_json_validate_utf8

Type: Bool
Default: 0
Tier: Production
Controls validation of UTF-8 sequences in JSON output formats, doesn't impact formats JSON/JSONCompact/JSONColumnsWithMetadata, they always validate UTF-8. Disabled by default.

output_format_markdown_escape_special_characters

Type: Bool
Default: 0
Tier: Production
When enabled, escape special characters in Markdown. Common Mark defines the following special characters that can be escaped by : ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` \{ | \} ~ Possible values: + 0 — Disable. + 1 — Enable.

output_format_msgpack_uuid_representation

Type: MsgPackUUIDRepresentation
Default: ext
Tier: Production
The way how to output UUID in MsgPack format.

output_format_native_encode_types_in_binary_format

Type: Bool
Default: 0
Tier: Production
Write data types in binary format instead of type names in Native output format

output_format_native_use_flattened_dynamic_and_json_serialization

Type: Bool
Default: 0
Tier: Production
Write data of JSON and Dynamic columns in a flattened format (all types/paths as separate subcolumns).

output_format_native_write_json_as_string

Type: Bool
Default: 0
Tier: Production
Write data of JSON column as String column containing JSON strings instead of default native JSON serialization.

output_format_orc_compression_block_size

Type: UInt64
Default: 262144
Tier: Production
The size of the compression block in bytes for ORC output format.

output_format_orc_compression_method

Type: ORCCompression
Default: zstd
Tier: Production
Compression method for ORC output format. Supported codecs: lz4, snappy, zlib, zstd, none (uncompressed)

output_format_orc_dictionary_key_size_threshold

Type: Double
Default: 0
Tier: Production
For a string column in ORC output format, if the number of distinct values is greater than this fraction of the total number of non-null rows, turn off dictionary encoding. Otherwise dictionary encoding is enabled

output_format_orc_row_index_stride

Type: UInt64
Default: 10000
Tier: Production
Target row index stride in ORC output format

output_format_orc_string_as_string

Type: Bool
Default: 1
Tier: Production
Use ORC String type instead of Binary for String columns

output_format_orc_writer_time_zone_name

Type: String
Default: GMT
Tier: Production
The time zone name for ORC writer, the default ORC writer's time zone is GMT.

output_format_parallel_formatting

Type: Bool
Default: 1
Tier: Production
Enables or disables parallel formatting of data formats. Supported only for TSV, TSKV, CSV and JSONEachRow formats. Possible values: - 1 — Enabled. - 0 — Disabled.

output_format_parquet_batch_size

Type: NonZeroUInt64
Default: 1024
Tier: Production
Check page size every this many rows. Consider decreasing if you have columns with average values size above a few KBs.

output_format_parquet_bloom_filter_bits_per_value

Type: Double
Default: 10.5
Tier: Production
Approximate number of bits to use for each distinct value in parquet bloom filters. Estimated false positive rates: * 6 bits - 10% * 10.5 bits - 1% * 16.9 bits - 0.1% * 26.4 bits - 0.01% * 41 bits - 0.001%

output_format_parquet_bloom_filter_flush_threshold_bytes

Type: UInt64
Default: 134217728
Tier: Production
Where in the parquet file to place the bloom filters. Bloom filters will be written in groups of approximately this size. In particular: * if 0, each row group's bloom filters are written immediately after the row group, * if greater than the total size of all bloom filters, bloom filters for all row groups will be accumulated in memory, then written together near the end of the file, * otherwise, bloom filters will be accumulated in memory and written out whenever their total size goes above this value.

output_format_parquet_compression_method

Type: ParquetCompression
Default: zstd
Tier: Production
Compression method for Parquet output format. Supported codecs: snappy, lz4, brotli, zstd, gzip, none (uncompressed)

output_format_parquet_data_page_size

Type: UInt64
Default: 1048576
Tier: Production
Target page size in bytes, before compression.

output_format_parquet_date_as_uint16

Type: Bool
Default: 0
Tier: Production
Write Date values as plain 16-bit numbers (read back as UInt16), instead of converting to a 32-bit parquet DATE type (read back as Date32).

output_format_parquet_datetime_as_uint32

Type: Bool
Default: 0
Tier: Production
Write DateTime values as raw unix timestamp (read back as UInt32), instead of converting to milliseconds (read back as DateTime64(3)).

output_format_parquet_enum_as_byte_array

Type: Bool
Default: 1
Tier: Production
Write enum using parquet physical type: BYTE_ARRAY and logical type: ENUM

output_format_parquet_fixed_string_as_fixed_byte_array

Type: Bool
Default: 1
Tier: Production
Use Parquet FIXED_LEN_BYTE_ARRAY type instead of Binary for FixedString columns.

output_format_parquet_geometadata

Type: Bool
Default: 1
Tier: Production
Allow to write information about geo columns in parquet metadata and encode columns in WKB format.

output_format_parquet_max_dictionary_size

Type: UInt64
Default: 1048576
Tier: Production
If dictionary size grows bigger than this many bytes, switch to encoding without dictionary. Set to 0 to disable dictionary encoding.

output_format_parquet_parallel_encoding

Type: Bool
Default: 1
Tier: Production
Do Parquet encoding in multiple threads.

output_format_parquet_row_group_size

Type: UInt64
Default: 1000000
Tier: Production
Target row group size in rows.

output_format_parquet_row_group_size_bytes

Type: UInt64
Default: 536870912
Tier: Production
Target row group size in bytes, before compression.

output_format_parquet_string_as_string

Type: Bool
Default: 1
Tier: Production
Use Parquet String type instead of Binary for String columns.

output_format_parquet_wide_integer_as_decimal

Type: Bool
Default: 0
Tier: Production
Write Int128, UInt128, Int256, and UInt256 values as standards-compliant Parquet DECIMAL values in big-endian byte order. The default keeps the legacy unannotated little-endian FIXED_LEN_BYTE_ARRAY representation for compatibility with older RawTree versions. The decimal representation enables interoperable numeric statistics, but some Parquet readers do not support precisions above 38 or 76.

output_format_parquet_write_bloom_filter

Type: Bool
Default: 1
Tier: Production
Write bloom filters in parquet files.

output_format_parquet_write_checksums

Type: Bool
Default: 1
Tier: Production
Put crc32 checksums in parquet page headers.

output_format_parquet_write_page_index

Type: Bool
Default: 1
Tier: Production
Write column index and offset index (i.e. statistics about each data page, which may be used for filter pushdown on read) into parquet files.

output_format_pretty_color

Type: UInt64Auto
Default: auto
Tier: Production
Use ANSI escape sequences in Pretty formats. 0 - disabled, 1 - enabled, 'auto' - enabled if a terminal.

output_format_pretty_display_footer_column_names

Type: UInt64
Default: 1
Tier: Production
Display column names in the footer if there are many table rows. Possible values: - 0 — No column names are displayed in the footer. - 1 — Column names are displayed in the footer if row count is greater than or equal to the threshold value set by output_format_pretty_display_footer_column_names_min_rows (50 by default). Example Query: sql SELECT *, toTypeName(*) FROM (SELECT * FROM system.numbers LIMIT 1000); Result: response ┌─number─┬─toTypeName(number)─┐ 1. │ 0 │ UInt64 │ 2. │ 1 │ UInt64 │ 3. │ 2 │ UInt64 │ ... 999. │ 998 │ UInt64 │ 1000. │ 999 │ UInt64 │ └─number─┴─toTypeName(number)─┘

output_format_pretty_display_footer_column_names_min_rows

Type: UInt64
Default: 50
Tier: Production
Sets the minimum number of rows for which a footer with column names will be displayed if setting output_format_pretty_display_footer_column_names is enabled.

output_format_pretty_fallback_to_vertical

Type: Bool
Default: 1
Tier: Production
If enabled, and the table is wide but short, the Pretty format will output it as the Vertical format does. See output_format_pretty_fallback_to_vertical_max_rows_per_chunk and output_format_pretty_fallback_to_vertical_min_table_width for detailed tuning of this behavior.

output_format_pretty_fallback_to_vertical_max_rows_per_chunk

Type: UInt64
Default: 10
Tier: Production
The fallback to Vertical format (see output_format_pretty_fallback_to_vertical) will be activated only if the number of records in a chunk is not more than the specified value.

output_format_pretty_fallback_to_vertical_min_columns

Type: UInt64
Default: 5
Tier: Production
The fallback to Vertical format (see output_format_pretty_fallback_to_vertical) will be activated only if the number of columns is greater than the specified value.

output_format_pretty_fallback_to_vertical_min_table_width

Type: UInt64
Default: 250
Tier: Production
The fallback to Vertical format (see output_format_pretty_fallback_to_vertical) will be activated only if the sum of lengths of columns in a table is at least the specified value, or if at least one value contains a newline character.

output_format_pretty_glue_chunks

Type: UInt64Auto
Default: auto
Tier: Production
If the data rendered in Pretty formats arrived in multiple chunks, even after a delay, but the next chunk has the same column widths as the previous, use ANSI escape sequences to move back to the previous line and overwrite the footer of the previous chunk to continue it with the data of the new chunk. This makes the result more visually pleasant. 0 - disabled, 1 - enabled, 'auto' - enabled if a terminal.

output_format_pretty_grid_charset

Type: String
Default: UTF-8
Tier: Production
Charset for printing grid borders. Available charsets: ASCII, UTF-8 (default). In interactive mode, clickhouse-client automatically switches to ASCII when the terminal does not support UTF-8 (as determined by the LC_ALL, LC_CTYPE and LANG environment variables), unless this setting is specified explicitly.

output_format_pretty_highlight_digit_groups

Type: Bool
Default: 1
Tier: Production
If enabled and if output is a terminal, highlight every digit corresponding to the number of thousands, millions, etc. with underline.

output_format_pretty_highlight_trailing_spaces

Type: Bool
Default: 1
Tier: Production
If enabled and if output is a terminal, highlight trailing spaces with a gray color and underline.

output_format_pretty_max_column_name_width_cut_to

Type: UInt64
Default: 24
Tier: Production
If the column name is too long, cut it to this length. The column will be cut if it is longer than output_format_pretty_max_column_name_width_cut_to plus output_format_pretty_max_column_name_width_min_chars_to_cut.

output_format_pretty_max_column_name_width_min_chars_to_cut

Type: UInt64
Default: 4
Tier: Production
Minimum characters to cut if the column name is too long. The column will be cut if it is longer than output_format_pretty_max_column_name_width_cut_to plus output_format_pretty_max_column_name_width_min_chars_to_cut.

output_format_pretty_max_column_pad_width

Type: UInt64
Default: 250
Tier: Production
Maximum width to pad all values in a column in Pretty formats.

output_format_pretty_max_rows

Type: UInt64
Default: 1000
Tier: Production
Rows limit for Pretty formats.

output_format_pretty_max_value_width

Type: UInt64
Default: 10000
Tier: Production
Maximum width of value to display in Pretty formats. If greater - it will be cut. The value 0 means - never cut.

output_format_pretty_max_value_width_apply_for_single_value

Type: UInt64
Default: 0
Tier: Production
Only cut values (see the output_format_pretty_max_value_width setting) when it is not a single value in a block. Otherwise output it entirely, which is useful for the SHOW CREATE TABLE query.

output_format_pretty_multiline_fields

Type: Bool
Default: 1
Tier: Production
If enabled, Pretty formats will render multi-line fields inside table cell, so the table's outline will be preserved. If not, they will be rendered as is, potentially deforming the table (one upside of keeping it off is that copy-pasting multi-line values will be easier).

output_format_pretty_named_tuples_as_json

Type: Bool
Default: 1
Tier: Production
Controls whether named tuples in Pretty format are output as pretty-printed JSON objects.

output_format_pretty_row_numbers

Type: Bool
Default: 1
Tier: Production
Add row numbers before each row for pretty output format

output_format_pretty_single_large_number_tip_threshold

Type: UInt64
Default: 1000000
Tier: Production
Print a readable number tip on the right side of the table if the block consists of a single number which exceeds this value (except 0)

output_format_pretty_squash_consecutive_ms

Type: UInt64
Default: 50
Tier: Production
Wait for the next block for up to specified number of milliseconds and squash it to the previous before writing. This avoids frequent output of too small blocks, but still allows to display data in a streaming fashion.

output_format_pretty_squash_max_wait_ms

Type: UInt64
Default: 1000
Tier: Production
Output the pending block in pretty formats if more than the specified number of milliseconds has passed since the previous output.

output_format_pretty_use_nbsp_for_padding

Type: Bool
Default: 0
Tier: Production
If enabled, padding in Pretty output formats is rendered with U+00A0 instead of an ASCII space. The output remains visually identical in monospace, but the padding survives tools that compress or trim runs of regular spaces. Only takes effect when output_format_pretty_grid_charset is UTF-8.

output_format_protobuf_nullables_with_google_wrappers

Type: Bool
Default: 0
Tier: Production
When serializing Nullable columns with Google wrappers, serialize default values as empty wrappers. If turned off, default and null values are not serialized

output_format_schema

Type: String
Default: ``
Tier: Production
The path to the file where the automatically generated schema will be saved in Cap'n Proto or Protobuf formats.

output_format_sql_insert_include_column_names

Type: Bool
Default: 1
Tier: Production
Include column names in INSERT query

output_format_sql_insert_max_batch_size

Type: UInt64
Default: 65409
Tier: Production
The maximum number of rows in one INSERT statement.

output_format_sql_insert_quote_names

Type: Bool
Default: 1
Tier: Production
Quote column names with '`' characters

output_format_sql_insert_table_name

Type: String
Default: table
Tier: Production
The name of table in the output INSERT query

output_format_sql_insert_use_replace

Type: Bool
Default: 0
Tier: Production
Use REPLACE statement instead of INSERT

output_format_trim_fixed_string

Type: Bool
Default: 0
Tier: Production
Trim trailing null bytes from FixedString values in text output formats. E.g. toFixedString('John', 8) is printed as John instead of John\0\0\0\0.

output_format_tsv_crlf_end_of_line

Type: Bool
Default: 0
Tier: Production
If it is set true, end of line in TSV format will be \r\n instead of \n.

output_format_values_escape_quote_with_quote

Type: Bool
Default: 0
Tier: Production
If true escape ' with '', otherwise quoted with \'

output_format_write_statistics

Type: Bool
Default: 1
Tier: Production
Write statistics about read rows, bytes, time elapsed in suitable output formats. Enabled by default

page

Type: Double
Default: 0
Tier: Production
Sets the page number for paginated results. Equivalent to offset = limit * (page - 1). Can only be specified when limit is set and offset is not. Pages are 1-based. Inherits the same negative/fractional support as limit and offset. This is a query-construction setting applied by the engine on the parsed query (wrapping it as a derived table), so it composes with the existing query and works on every protocol: it can be supplied via the HTTP URL parameter, an in-query SETTINGS clause, or a user profile. It shapes result-producing SELECT / UNION queries. For a write query (INSERT … SELECT, CREATE … AS SELECT) it takes effect only when the source SELECT carries it in its own SETTINGS clause; a value inherited from a profile or session, or set on the INSERT / CREATE statement itself, does not propagate into the source SELECT — the same non-propagation rule that applies to any other setting.

page_cache_block_size

Type: UInt64
Default: 1048576
Tier: Production
Size of file chunks to store in the userspace page cache, in bytes. All reads that go through the cache will be rounded up to a multiple of this size. This setting can be adjusted on a per-query level basis, but cache entries with different block sizes cannot be reused. Changing this setting effectively invalidates existing entries in the cache. A higher value, like 1 MiB is good for high-throughput queries, and a lower value, like 64 KiB is good for low-latency point queries.

page_cache_inject_eviction

Type: Bool
Default: 0
Tier: Production
Userspace page cache will sometimes invalidate some pages at random. Intended for testing.

page_cache_lookahead_blocks

Type: UInt64
Default: 16
Tier: Production
On userspace page cache miss, read up to this many consecutive blocks at once from the underlying storage, if they're also not in the cache. Each block is page_cache_block_size bytes. A higher value is good for high-throughput queries, while low-latency point queries will work better without readahead.

page_cache_max_coalesced_bytes

Type: UInt64
Default: 16777216
Tier: Production
When readBigAt populates the userspace page cache, consecutive cache misses are coalesced into a single read from the underlying storage. This setting bounds the size of one coalesced read in bytes; longer miss runs are split into multiple reads. It limits transient memory usage of the temporary buffer under parallel cold reads. A higher value reduces the number of HTTP requests for cold scans on object storage; a lower value reduces peak transient memory.

paimon_target_snapshot_id

Type: Int64
Default: -1
Tier: Experimental
Query-level targeted snapshot read for Paimon incremental mode. When >0, the reader will only fetch the delta for the specified snapshot_id without advancing the committed watermark. Default: -1 (disabled)

parallel_distributed_insert_select

Type: UInt64
Default: 2
Tier: Production
Enables parallel distributed INSERT ... SELECT query. If we execute INSERT INTO distributed_table_a SELECT ... FROM distributed_table_b queries and both tables use the same cluster, and both tables are either replicated or non-replicated, then this query is processed locally on every shard. Possible values: - 0 — Disabled. - 1 — SELECT will be executed on each shard from the underlying table of the distributed engine. - 2 — SELECT and INSERT will be executed on each shard from/to the underlying table of the distributed engine. Since v25.4, INSERT ... SELECT from a ReplicatedMergeTree or SharedMergeTree source can also be parallelized across replicas. To enable it: - parallel_distributed_insert_select = 2 - enable_parallel_replicas = 1

parallel_hash_join_threshold

Type: UInt64
Default: 100000
Tier: Production
When hash-based join algorithm is applied, this threshold helps to decide between using hash and parallel_hash (only if estimation of the right table size is available). The former is used when we know that the right table size is below the threshold.

parallel_non_joined_rows_processing

Type: Bool
Default: 1
Tier: Production
Allow multiple threads to process non-joined rows from the right table in parallel during RIGHT and FULL JOINs. This can speed up the non-joined phase when using the parallel_hash join algorithm with large tables. When disabled, non-joined rows are processed by a single thread.

parallel_replica_offset

Type: UInt64
Default: 0
Tier: Beta
This is internal setting that should not be used directly and represents an implementation detail of the 'parallel replicas' mode. This setting will be automatically set up by the initiator server for distributed queries to the index of the replica participating in query processing among parallel replicas.

parallel_replicas_allow_in_with_subquery

Type: Bool
Default: 1
Tier: Production
If true, subquery for IN will be executed on every follower replica.

parallel_replicas_allow_materialized_views

Type: Bool
Default: 1
Tier: Production
Allow usage of materialized views with parallel replicas

parallel_replicas_allow_view_over_mergetree

Type: Bool
Default: 0
Tier: Beta
Allow parallel replicas to execute the outer query of a simple view over MergeTree tables (instead of the view's inner query), improving parallelization across nodes. Also applies to UNION ALL views whose branches all read from different MergeTree tables.

parallel_replicas_connect_timeout_ms

Type: Milliseconds
Default: 300
Tier: Production
The timeout in milliseconds for connecting to a remote replica during query execution with parallel replicas. If the timeout is expired, the corresponding replicas is not used for query execution

parallel_replicas_count

Type: UInt64
Default: 0
Tier: Beta
This is internal setting that should not be used directly and represents an implementation detail of the 'parallel replicas' mode. This setting will be automatically set up by the initiator server for distributed queries to the number of parallel replicas participating in query processing.

parallel_replicas_custom_key

Type: String
Default: ``
Tier: Beta
An arbitrary integer expression that can be used to split work between replicas for a specific table. The value can be any integer expression. Simple expressions using primary keys are preferred. If the setting is used on a cluster that consists of a single shard with multiple replicas, those replicas will be converted into virtual shards. Otherwise, it will behave same as for SAMPLE key, it will use multiple replicas of each shard. The expression is checked against the column-level SELECT grants of the user. For a view with SQL SECURITY DEFINER or NONE it is applied to the columns of the view; the body of the view is read without it.

parallel_replicas_custom_key_range_lower

Type: UInt64
Default: 0
Tier: Beta
Allows the filter type range to split the work evenly between replicas based on the custom range [parallel_replicas_custom_key_range_lower, INT_MAX]. When used in conjunction with parallel_replicas_custom_key_range_upper, it lets the filter evenly split the work over replicas for the range [parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]. Note: This setting will not cause any additional data to be filtered during query processing, rather it changes the points at which the range filter breaks up the range [0, INT_MAX] for parallel processing.

parallel_replicas_custom_key_range_upper

Type: UInt64
Default: 0
Tier: Beta
Allows the filter type range to split the work evenly between replicas based on the custom range [0, parallel_replicas_custom_key_range_upper]. A value of 0 disables the upper bound, setting it the max value of the custom key expression. When used in conjunction with parallel_replicas_custom_key_range_lower, it lets the filter evenly split the work over replicas for the range [parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]. Note: This setting will not cause any additional data to be filtered during query processing, rather it changes the points at which the range filter breaks up the range [0, INT_MAX] for parallel processing

parallel_replicas_filter_pushdown

Type: Bool
Default: 0
Tier: Beta
Allow pushing down filters to part of query which parallel replicas choose to execute

parallel_replicas_for_cluster_engines

Type: Bool
Default: 1
Tier: Production
Replace table function engines with their -Cluster alternatives

parallel_replicas_for_non_replicated_merge_tree

Type: Bool
Default: 0
Tier: Production
If true, RawTree will use parallel replicas algorithm also for non-replicated MergeTree tables

parallel_replicas_index_analysis_only_on_coordinator

Type: Bool
Default: 1
Tier: Production
Index analysis done only on replica-coordinator and skipped on other replicas. Effective only with enabled parallel_replicas_local_plan

parallel_replicas_insert_select_local_pipeline

Type: Bool
Default: 1
Tier: Production
Use local pipeline during distributed INSERT SELECT with parallel replicas

parallel_replicas_local_plan

Type: Bool
Default: 1
Tier: Production
Build local plan for local replica

parallel_replicas_mark_segment_size

Type: UInt64
Default: 0
Tier: Production
Parts virtually divided into segments to be distributed between replicas for parallel reading. This setting controls the size of these segments. Not recommended to change until you're absolutely sure in what you're doing. Value should be in range [128; 16384]

parallel_replicas_min_number_of_rows_per_replica

Type: UInt64
Default: 0
Tier: Production
Limit the number of replicas used in a query to (estimated rows to read / min_number_of_rows_per_replica). The max is still limited by 'max_parallel_replicas'

parallel_replicas_mode

Type: ParallelReplicasMode
Default: read_tasks
Tier: Production
Type of filter to use with custom key for parallel replicas. default - use modulo operation on the custom key, range - use range filter on custom key using all possible values for the value type of custom key.

parallel_replicas_only_with_analyzer

Type: Bool
Default: 1
Tier: Production
The analyzer should be enabled to use parallel replicas. With disabled analyzer query execution fallbacks to local execution, even if parallel reading from replicas is enabled. Using parallel replicas without the analyzer enabled is not supported

parallel_replicas_plan_based

Type: Bool
Default: 0
Tier: Experimental
Decide whether and where to use parallel replicas by analyzing the query plan, as opposed to the query-tree-based analysis. As a result, a plan fragment is sent to the remote replicas instead of a SQL query. Experimental.

parallel_replicas_prefer_local_join

Type: Bool
Default: 1
Tier: Production
If true, and JOIN can be executed with parallel replicas algorithm, and every storage of the JOIN part that would otherwise be materialized into a temporary table can be read by each replica on its own, local JOIN will be used instead of GLOBAL JOIN. That part is the right one, except for a RIGHT JOIN, where it is the left one and where every storage has to be eligible for parallel replicas rather than merely *MergeTree. A storage under the materialized side of a nested GLOBAL JOIN, or under a GLOBAL IN, does not count, because the initiator materializes those itself.

parallel_replicas_prefer_local_replica

Type: Bool
Default: 1
Tier: Production
When enabled (default), the local replica is always included in the set of replicas used for parallel reading. When disabled, the local replica is not given any preference and replicas are selected purely by the load balancing algorithm. This allows queries with max_parallel_replicas = 1 to be directed to another host, which can improve cache locality when many short queries are distributed across a cluster.

parallel_replicas_support_projection

Type: Bool
Default: 1
Tier: Production
Optimization of projections can be applied in parallel replicas. Effective only with enabled parallel_replicas_local_plan and aggregation_in_order is inactive.

parallel_view_processing

Type: Bool
Default: 0
Tier: Production
Enables pushing to attached views concurrently instead of sequentially.

parallelize_output_from_storages

Type: Bool
Default: 1
Tier: Production
Parallelize output for reading step from storage. It allows parallelization of query processing right after reading from storage if possible

parsedatetime_e_requires_space_padding

Type: Bool
Default: 0
Tier: Production
Formatter '%e' in function 'parseDateTime' expects that single-digit days are space-padded, e.g., ' 2' is accepted but '2' raises an error.

parsedatetime_parse_without_leading_zeros

Type: Bool
Default: 1
Tier: Production
Formatters '%c', '%l' and '%k' in function 'parseDateTime' parse months and hours without leading zeros.

partial_merge_join_left_table_buffer_bytes

Type: UInt64
Default: 0
Tier: Production
If not 0 group left table blocks in bigger ones for left-side table in partial merge join. It uses up to 2x of specified memory per joining thread.

partial_merge_join_rows_in_right_blocks

Type: UInt64
Default: 65536
Tier: Production
Limits sizes of right-hand join data blocks in partial merge join algorithm for JOIN queries. RawTree server: 1. Splits right-hand join data into blocks with up to the specified number of rows. 2. Indexes each block with its minimum and maximum values. 3. Unloads prepared blocks to disk if it is possible. Possible values: - Any positive integer. Recommended range of values: [1000, 100000].

partial_result_on_first_cancel

Type: Bool
Default: 0
Tier: Production
Allows query to return a partial result after cancel.

parts_to_delay_insert

Type: UInt64
Default: 0
Tier: Production
If the destination table contains at least that many active parts in a single partition, artificially slow down insert into table.

parts_to_throw_insert

Type: UInt64
Default: 0
Tier: Production
If more than this number active parts in a single partition of the destination table, throw 'Too many parts ...' exception.

per_part_index_stats

Type: Bool
Default: 0
Tier: Production
Logs index statistics per part

poll_interval

Type: UInt64
Default: 10
Tier: Production
Block at the query wait loop on the server for the specified number of seconds.

polyglot_dialect

Type: String
Default: ``
Tier: Experimental
Source SQL dialect for the polyglot transpiler (e.g. 'sqlite', 'mysql', 'postgresql', 'snowflake', 'duckdb').

postgresql_connection_attempt_timeout

Type: UInt64
Default: 2
Tier: Production
Connection timeout in seconds of a single attempt to connect PostgreSQL end-point. The value is passed as a connect_timeout parameter of the connection URL.

postgresql_connection_pool_auto_close_connection

Type: Bool
Default: 0
Tier: Production
Close connection before returning connection to the pool.

postgresql_connection_pool_retries

Type: UInt64
Default: 2
Tier: Production
Connection pool push/pop retries number for PostgreSQL table engine and database engine.

postgresql_connection_pool_size

Type: UInt64
Default: 16
Tier: Production
Connection pool size for PostgreSQL table engine and database engine.

postgresql_connection_pool_wait_timeout

Type: UInt64
Default: 5000
Tier: Production
Connection pool push/pop timeout on empty pool for PostgreSQL table engine and database engine. By default it will block on empty pool.

postgresql_fault_injection_probability

Type: Float
Default: 0
Tier: Production
Approximate probability of failing internal (for replication) PostgreSQL queries. Valid value is in interval [0.0f, 1.0f]

precise_float_parsing

Type: Bool
Default: 1
Tier: Production
Use the precise float parsing algorithm, which always returns the closest representable value to the input. When disabled, a faster but less accurate algorithm is used that may differ from the precise result by the least significant bits.

predicate_statistics_sample_rate

Type: UInt64
Default: 0
Tier: Production
Collect predicate selectivity statistics into system.predicate_statistics_log. When set to N > 0, approximately 1/N of queries are sampled (by the query ID). 0 means disabled.

prefer_column_name_to_alias

Type: Bool
Default: 0
Tier: Production
Enables or disables using the original column names instead of aliases in query expressions and clauses. It especially matters when alias is the same as the column name, see Expression Aliases. Enable this setting to make aliases syntax rules in RawTree more compatible with most other database engines. Possible values: - 0 — The column name is substituted with the alias. - 1 — The column name is not substituted with the alias. Example The difference between enabled and disabled: Query: sql SET prefer_column_name_to_alias = 0; SELECT avg(number) AS number, max(number) FROM numbers(10); Result: text Received exception from server (version 21.5.1): Code: 184. DB::Exception: Received from localhost:9000. DB::Exception: Aggregate function avg(number) is found inside another aggregate function in query: While processing avg(number) AS number. Query: sql SET prefer_column_name_to_alias = 1; SELECT avg(number) AS number, max(number) FROM numbers(10); Result: text ┌─number─┬─max(number)─┐ │ 4.5 │ 9 │ └────────┴─────────────┘

prefer_external_sort_block_bytes

Type: UInt64
Default: 16744704
Tier: Production
Prefer maximum block bytes for external sort, reduce the memory usage during merging.

prefer_global_in_and_join

Type: Bool
Default: 0
Tier: Production
Enables the replacement of IN/JOIN operators with GLOBAL IN/GLOBAL JOIN. Possible values: - 0 — Disabled. IN/JOIN operators are not replaced with GLOBAL IN/GLOBAL JOIN. - 1 — Enabled. IN/JOIN operators are replaced with GLOBAL IN/GLOBAL JOIN. Usage Although SET distributed_product_mode=global can change the queries behavior for the distributed tables, it's not suitable for local tables or tables from external resources. Here is when the prefer_global_in_and_join setting comes into play. For example, we have query serving nodes that contain local tables, which are not suitable for distribution. We need to scatter their data on the fly during distributed processing with the GLOBAL keyword — GLOBAL IN/GLOBAL JOIN. Another use case of prefer_global_in_and_join is accessing tables created by external engines. This setting helps to reduce the number of calls to external sources while joining such tables: only one call per query. See also: - Distributed subqueries for more information on how to use GLOBAL IN/GLOBAL JOIN

prefer_localhost_replica

Type: Bool
Default: 1
Tier: Production
Enables/disables preferable using the localhost replica when processing distributed queries. Possible values: - 1 — RawTree always sends a query to the localhost replica if it exists. - 0 — RawTree uses the balancing strategy specified by the load_balancing setting. :::note Disable this setting if you use max_parallel_replicas without parallel_replicas_custom_key. If parallel_replicas_custom_key is set, disable this setting only if it's used on a cluster with multiple shards containing multiple replicas. If it's used on a cluster with a single shard and multiple replicas, disabling this setting will have negative effects. :::

prefer_warmed_unmerged_parts_seconds

Type: Int64
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. If a merged part is less than this many seconds old and is not pre-warmed (see cache_populated_by_fetch), but all its source parts are available and pre-warmed, SELECT queries will read from those parts instead. Only for Replicated-/SharedMergeTree. Note that this only checks whether CacheWarmer processed the part; if the part was fetched into cache by something else, it'll still be considered cold until CacheWarmer gets to it; if it was warmed, then evicted from cache, it'll still be considered warm.

preferred_block_size_bytes

Type: UInt64
Default: 1000000
Tier: Production
This setting adjusts the data block size for query processing and represents additional fine-tuning to the more rough 'max_block_size' setting. If the columns are large and with 'max_block_size' rows the block size is likely to be larger than the specified amount of bytes, its size will be lowered for better CPU cache locality.

preferred_max_column_in_block_size_bytes

Type: UInt64
Default: 0
Tier: Production
Limit on max column size in block while reading. Helps to decrease cache misses count. Should be close to L2 cache size.

preferred_optimize_projection_name

Type: String
Default: ``
Tier: Production
If it is set to a non-empty string, RawTree will try to apply specified projection in query. Possible values: - string: name of preferred projection

prefetch_buffer_size

Type: UInt64
Default: 1048576
Tier: Production
The maximum size of the prefetch buffer to read from the filesystem. Values above 256 MiB are clamped to 256 MiB, as a read buffer never needs to be larger.

print_pretty_type_names

Type: Bool
Default: 1
Tier: Production
Allows to print deep-nested type names in a pretty way with indents in DESCRIBE query and in toTypeName() function. Example: sql CREATE TABLE test (a Tuple(b String, c Tuple(d Nullable(UInt64), e Array(UInt32), f Array(Tuple(g String, h Map(String, Array(Tuple(i String, j UInt64))))), k Date), l Nullable(String))) ENGINE=Memory; DESCRIBE TABLE test FORMAT TSVRaw SETTINGS print_pretty_type_names=1; a Tuple( b String, c Tuple( d Nullable(UInt64), e Array(UInt32), f Array(Tuple( g String, h Map( String, Array(Tuple( i String, j UInt64 )) ) )), k Date ), l Nullable(String) )

priority

Type: UInt64
Default: 0
Tier: Production
Priority of the query. 1 - the highest, higher value - lower priority; 0 - do not use priorities.

promql_database

Type: String
Default: ``
Tier: Experimental
Specifies the database name used by the 'promql' dialect. Empty string means the current database.

promql_evaluation_time

Type: FloatAuto
Default: auto
Tier: Experimental
Sets the evaluation time to be used with promql dialect. 'auto' means the current time.

promql_table

Type: String
Default: ``
Tier: Experimental
Specifies the name of a TimeSeries table used by the 'promql' dialect.

push_external_roles_in_interserver_queries

Type: Bool
Default: 1
Tier: Production
Enable pushing user roles from originator to other nodes while performing a query.

query_cache_compress_entries

Type: Bool
Default: 1
Tier: Production
Compress entries in the query cache. Lessens the memory consumption of the query cache at the cost of slower inserts into / reads from it. Possible values: - 0 - Disabled - 1 - Enabled

query_cache_for_subqueries

Type: Bool
Default: 0
Tier: Production
If turned on, subquery results may be written to and read from the query cache. This enables propagation of use_query_cache into all subqueries. Possible values: - 0 - Disabled - 1 - Enabled

query_cache_max_entries

Type: UInt64
Default: 0
Tier: Production
The maximum number of query results the current user may store in the query cache. 0 means unlimited. Possible values: - Positive integer >= 0.

query_cache_max_size_in_bytes

Type: UInt64
Default: 0
Tier: Production
The maximum amount of memory (in bytes) the current user may allocate in the query cache. 0 means unlimited. Possible values: - Positive integer >= 0.

query_cache_min_query_duration

Type: Milliseconds
Default: 0
Tier: Production
Minimum duration in milliseconds a query needs to run for its result to be stored in the query cache. Possible values: - Positive integer >= 0.

query_cache_min_query_runs

Type: UInt64
Default: 0
Tier: Production
Minimum number of times a SELECT query must run before its result is stored in the query cache. Possible values: - Positive integer >= 0.

query_cache_nondeterministic_function_handling

Type: QueryResultCacheNondeterministicFunctionHandling
Default: throw
Tier: Production
Controls how the query cache handles SELECT queries with non-deterministic functions like rand() or now(). Possible values: - 'throw' - Throw an exception and don't cache the query result. - 'save' - Cache the query result. - 'ignore' - Don't cache the query result and don't throw an exception.

query_cache_share_between_users

Type: Bool
Default: 0
Tier: Production
If turned on, the result of SELECT queries cached in the query cache can be read by other users. It is not recommended to enable this setting due to security reasons. Possible values: - 0 - Disabled - 1 - Enabled

query_cache_squash_partial_results

Type: Bool
Default: 1
Tier: Production
Squash partial result blocks to blocks of size max_block_size. Reduces performance of inserts into the query cache but improves the compressability of cache entries (see query_cache_compress-entries). Possible values: - 0 - Disabled - 1 - Enabled

query_cache_system_table_handling

Type: QueryResultCacheSystemTableHandling
Default: throw
Tier: Production
Controls how the query cache handles SELECT queries against system tables, i.e. tables in databases system.* and information_schema.*. Possible values: - 'throw' - Throw an exception and don't cache the query result. - 'save' - Cache the query result. - 'ignore' - Don't cache the query result and don't throw an exception.

query_cache_tag

Type: String
Default: ``
Tier: Production
A string which acts as a label for query cache entries. The same queries with different tags are considered different by the query cache. Possible values: - Any string

query_cache_ttl

Type: Seconds
Default: 60
Tier: Production
After this time in seconds entries in the query cache become stale. Possible values: - Positive integer >= 0.

query_cache_views_default_ttl

Type: Seconds
Default: 3600
Tier: Experimental
The TTL of the view of a query with the CACHE clause without TTL: the view is created with TTL ... SECOND FROM LAST READ of this time in seconds, so it is dropped when its result was not read for this time. Possible values: - Positive integer — the time in seconds. - 0 — the views of the queries without TTL are not dropped, and a query with CACHE without EVERY, AFTER and TTL fails.

query_cache_views_max_failed_refreshes

Type: UInt64
Default: 3
Tier: Experimental
A query with the CACHE clause fails with the error of the refresh when this many latest refreshes of its view failed, instead of returning the result of an older refresh. A refresh fails when all its attempts (see the refresh setting refresh_retries) fail. Possible values: - Positive integer. - 0 — the result of the latest successful refresh is returned however many refreshes failed after it.

query_metric_log_interval

Type: Int64
Default: -1
Tier: Production
The interval in milliseconds at which the query_metric_log for individual queries is collected. If set to any negative value, it will take the value collect_interval_milliseconds from the query_metric_log setting or default to 1000 if not present. To disable the collection of a single query, set query_metric_log_interval to 0. Default value: -1

query_plan_aggregation_bucket_top_k

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which, when a final aggregation feeds ORDER BY over the aggregation's outputs with LIMIT n and the plan proves the per-bucket selection exact, materializes only each two-level bucket's best n groups in that order during the aggregation's final conversion. The result is exact: a group outside its own bucket's best n has at least n groups ahead of it globally, so it cannot be in the global top n. Only takes effect if setting query_plan_enable_optimizations is 1. Possible values: - 0 - Disable - 1 - Enable

query_plan_aggregation_in_order

Type: Bool
Default: 1
Tier: Production
Toggles the aggregation in-order query-plan-level optimization. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_convert_any_join_to_semi_or_anti_join

Type: Bool
Default: 1
Tier: Production
Allow to convert ANY JOIN to SEMI or ANTI JOIN if filter after JOIN always evaluates to false for not-matched or matched rows

query_plan_convert_join_to_in

Type: Bool
Default: 0
Tier: Production
Allow to convert JOIN to subquery with IN if output columns tied to only left table. May cause wrong results with non-ANY JOINs (e.g. ALL JOINs which is the default).

query_plan_convert_outer_join_to_inner_join

Type: Bool
Default: 1
Tier: Production
Allow to convert OUTER JOIN to INNER JOIN if filter after JOIN always filters default values

query_plan_direct_read_from_text_index

Type: Bool
Default: 1
Tier: Production
Allow to perform full text search filtering using only the inverted text index in query plan.

query_plan_display_internal_aliases

Type: Bool
Default: 0
Tier: Production
Show internal aliases (such as __table1) in EXPLAIN PLAN instead of those specified in the original query.

query_plan_enable_multithreading_after_window_functions

Type: Bool
Default: 1
Tier: Production
Enable multithreading after evaluating window functions to allow parallel stream processing

query_plan_enable_optimizations

Type: Bool
Default: 1
Tier: Production
Toggles query optimization at the query plan level. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable all optimizations at the query plan level - 1 - Enable optimizations at the query plan level (but individual optimizations may still be disabled via their individual settings)

query_plan_execute_functions_after_sorting

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which moves expressions after sorting steps. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_filter_push_down

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which moves filters down in the execution plan. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_filter_push_down_below_limit_by

Type: Bool
Default: 1
Tier: Production
Toggles pushing filters on LIMIT BY key columns below the LIMIT BY step. Only takes effect if setting query_plan_enable_optimizations is 1. It is read independently of query_plan_filter_push_down: the push-down pass also runs, with that setting off, once a JOIN runtime filter has been added. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_join_shard_by_pk_ranges

Type: Bool
Default: 0
Tier: Production
Apply sharding for JOIN if join keys contain a prefix of PRIMARY KEY for both tables. Supported for hash, parallel_hash, full_sorting_merge and parallel_full_sorting_merge algorithms. Usually does not speed up queries but may lower memory consumption.

query_plan_join_swap_table

Type: BoolAuto
Default: auto
Tier: Production
Determine which side of the join should be the build table (also called inner, the one inserted into the hash table for a hash join) in the query plan. This setting is supported only for ALL join strictness with the JOIN ON clause. Possible values are: - 'auto': Let the planner decide which table to use as the build table. - 'false': Never swap tables (the right table is the build table). - 'true': Always swap tables (the left table is the build table).

query_plan_lift_up_array_join

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which moves ARRAY JOINs up in the execution plan. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_lift_up_union

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which moves larger subtrees of the query plan into union to enable further optimizations. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_max_limit_for_join_lazy_indexing

Type: UInt64
Default: 1000
Tier: Production
Control maximum limit value that allows to use query plan for lazy indexing optimization in JOIN. If zero, there is no limit.

query_plan_max_limit_for_lazy_materialization

Type: UInt64
Default: 10000
Tier: Production
Control maximum limit value that allows to use query plan for lazy materialization optimization. If zero, there is no limit.

query_plan_max_limit_for_top_k_optimization

Type: UInt64
Default: 1000
Tier: Production
Control maximum limit value that allows to evaluate query plan for TopK optimization by using minmax skip index and dynamic threshold filtering. If zero, there is no limit. This setting also controls the behavior of enable_group_by_top_k_optimization.

query_plan_max_optimizations_to_apply

Type: UInt64
Default: 10000
Tier: Production
Limits the total number of optimizations applied to query plan, see setting query_plan_enable_optimizations. Useful to avoid long optimization times for complex queries. In the EXPLAIN PLAN query, stop applying optimizations after this limit is reached and return the plan as is. For regular query execution if the actual number of optimizations exceeds this setting, an exception is thrown. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. :::

query_plan_max_set_size_for_projection_match

Type: UInt64
Default: 10000
Tier: Production
Maximum number of rows in an IN-clause set for which the projection matcher computes and compares content hashes when deciding whether two sets are equal. Sets larger than this are treated as non-matching and skip the projection. Zero disables content-hash comparison entirely: a projection match never succeeds for nodes containing IN-clause sets. Used by the aggregate projection matcher (and any future projection matcher that needs to compare IN-clause sets). Computing the content hash is O(N log N) in the number of set elements; this setting bounds the cost paid during planning when many IN-clauses appear in the query or the projection.

query_plan_max_step_description_length

Type: UInt64
Default: 500
Tier: Production
Maximum length of step description in EXPLAIN PLAN.

query_plan_merge_expression_into_join

Type: Bool
Default: 1
Tier: Production
Allow to merge expressions into JOIN step during join reordering optimization.

query_plan_merge_expressions

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which merges consecutive filters. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_merge_filter_into_join_condition

Type: Bool
Default: 1
Tier: Production
Allow to merge filter into JOIN condition and convert CROSS JOIN to INNER.

query_plan_merge_filters

Type: Bool
Default: 1
Tier: Production
Allow to merge filters in the query plan.

query_plan_min_columns_for_join_lazy_indexing

Type: UInt64
Default: 3
Tier: Production
Control the minimum number of payload columns from the left side required for enabling lazy indexing optimization in JOIN. 0 means the optimization is disabled.

query_plan_optimize_count_from_text_index

Type: Bool
Default: 1
Tier: Production
Allow to answer SELECT count() ... WHERE <text search predicate> directly from the text index posting-list cardinalities, without materializing the matching rows. Only takes effect when query_plan_direct_read_from_text_index is enabled.

query_plan_optimize_join_order_algorithm

Type: JoinOrderAlgorithm
Default: greedy
Tier: Experimental
Specifies which JOIN order algorithms to attempt during query plan optimization. The following algorithms are available: - 'greedy' - basic greedy algorithm - works fast but might not produce the best join order - 'dpsize' - implements DPsize algorithm currently only for Inner joins - considers all possible join orders and finds the most optimal one but might be slow for queries with many tables and join predicates. - 'dpsub' - implements DPsub algorithm which supports both inner and non-inner joins - considers all possible join orders and finds the most optimal one but might be slow for queries with many tables and join predicates. - 'dphyp' - implements DPhyp (Dynamic Programming via Hypergraph Partitioning) algorithm currently only for inner joins - explores the same search space as dpsize but enumerates only connected subgraph pairs, which generates fewer intermediate joins on sparse join graphs, at the cost of not considering cross products Multiple algorithms can be specified as a comma-separated list, e.g. dphyp,greedy. They are tried in order; if an algorithm cannot handle the query (e.g. due to outer joins or disconnected components), the next one is used as a fallback.

query_plan_optimize_join_order_limit

Type: UInt64
Default: 10
Tier: Production
Optimize the order of joins within the same subquery. Currently only supported for very limited cases. Value is the maximum number of tables to optimize.

query_plan_optimize_join_order_max_searched_plans

Type: UInt64
Default: 100000
Tier: Experimental
Maximum number of partial plans the join order optimizer may enumerate before giving up and falling back to the next algorithm in query_plan_optimize_join_order_algorithm. This bounds optimization time deterministically (independent of wall-clock) on dense join graphs such as cliques or stars, where the search space grows exponentially. Set to 0 to disable the limit. Has no effect on the default query_plan_optimize_join_order_limit, where the search always stays well below this bound.

query_plan_optimize_join_order_randomize

Type: UInt64
Default: 0
Tier: Experimental
When non-zero, the join order optimizer uses randomly generated cardinalities and NDVs instead of real statistics. When set to 1, a random seed is generated, when set to a value > 1, that value is used as the seed directly. This is intended for testing to find errors caused by different join orderings.

query_plan_optimize_lazy_final

Type: Bool
Default: 0
Tier: Production
Optimize reading with FINAL from ReplacingMergeTree by building a set of primary keys and using it for index analysis.

query_plan_optimize_lazy_materialization

Type: Bool
Default: 1
Tier: Production
Use query plan for lazy materialization optimization.

query_plan_optimize_lazy_materialization_for_file

Type: Bool
Default: 1
Tier: Production
Use lazy materialization optimization for reading local Parquet files with the file table function and the File table engine: for ORDER BY ... LIMIT n queries, the columns that are not needed for sorting and filtering are read only for the n rows that survive the LIMIT. Takes effect only if query_plan_optimize_lazy_materialization is enabled.

query_plan_optimize_lazy_materialization_for_object_storage

Type: Bool
Default: 1
Tier: Production
Use lazy materialization optimization for reading Parquet files from object storage (including Iceberg tables): for ORDER BY ... LIMIT n queries, the columns that are not needed for sorting and filtering are read only for the n rows that survive the LIMIT. Takes effect only if query_plan_optimize_lazy_materialization is enabled.

query_plan_optimize_prewhere

Type: Bool
Default: 1
Tier: Production
Allow to push down filter to PREWHERE expression for supported storages

query_plan_push_down_limit

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which moves LIMITs down in the execution plan. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_push_down_volume_reducing_functions

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which moves volume-reducing functions (length, lengthUTF8, empty, notEmpty) down in the execution plan, below Sorting and Filter steps. The fixed-size result replaces the wide String / FixedString argument, so the argument is no longer carried through those steps. The rewrite is only applied when the argument column is not needed above the step it is pushed below. Only takes effect if setting query_plan_enable_optimizations is 1. Possible values: - 0 - Disable - 1 - Enable

query_plan_push_limit_by_into_sort

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization for ORDER BY ... LIMIT BY queries. When LIMIT BY columns are a prefix of the ORDER BY clause, each parallel sorted stream applies LIMIT BY before the streams are merged into one, reducing rows processed by the final merge and later pipeline stages. Speeds up queries where LIMIT BY discards a large fraction of rows. Only takes effect if setting query_plan_enable_optimizations is 1. Possible values: - 0 - Disable - 1 - Enable

query_plan_read_in_order

Type: Bool
Default: 1
Tier: Production
Toggles the read in-order optimization query-plan-level optimization. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_read_in_order_through_join

Type: Bool
Default: 1
Tier: Production
Keep reading in order from the left table in JOIN operations, which can be utilized by subsequent steps.

query_plan_remove_redundant_distinct

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which removes redundant DISTINCT steps. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_remove_redundant_sorting

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which removes redundant sorting steps, e.g. in subqueries. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_remove_unused_columns

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which tries to remove unused columns (both input and output columns) from query plan steps. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_reuse_storage_ordering_for_window_functions

Type: Bool
Default: 0
Tier: Production
Toggles a query-plan-level optimization which uses storage sorting when sorting for window functions. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_plan_short_circuit_constant_false_join

Type: Bool
Default: 1
Tier: Production
Short-circuit a JOIN whose ON condition folds to a constant false by replacing each input side that cannot contribute a row (both sides for INNER/CROSS/SEMI, the non-preserved side for LEFT/RIGHT) with an empty source, so the non-contributing side is not read. Applies to the analyzer (enable_analyzer = 1) and to non-distributed plans.

query_plan_split_filter

Type: Bool
Default: 1
Tier: Production
:::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Toggles a query-plan-level optimization which splits filters into expressions. Only takes effect if setting query_plan_enable_optimizations is 1. Possible values: - 0 - Disable - 1 - Enable

query_plan_text_index_add_hint

Type: Bool
Default: 1
Tier: Production
Allow to add hint (additional predicate) for filtering built from the inverted text index in query plan.

query_plan_top_k_through_join

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which pushes ORDER BY ... LIMIT n down through a join when the sort key only references columns from the side preserved by the join (LEFT/RIGHT). Restricts how many rows the preserved-side input must produce before joining. Only takes effect if setting query_plan_enable_optimizations is 1. Possible values: - 0 - Disable - 1 - Enable

query_plan_try_use_vector_search

Type: Bool
Default: 1
Tier: Production
Toggles a query-plan-level optimization which tries to use the vector similarity index. Only takes effect if setting query_plan_enable_optimizations is 1. :::note This is an expert-level setting which should only be used for debugging by developers. The setting may change in future in backward-incompatible ways or be removed. ::: Possible values: - 0 - Disable - 1 - Enable

query_profiler_cpu_time_period_ns

Type: UInt64
Default: 1000000000
Tier: Production
Sets the period for a CPU clock timer of the query profiler. This timer counts only CPU time. Possible values: - A positive integer number of nanoseconds. Recommended values: - 10000000 (100 times a second) nanoseconds and more for single queries. - 1000000000 (once a second) for cluster-wide profiling. - 0 for turning off the timer. See also: - System table trace_log

query_profiler_real_time_period_ns

Type: UInt64
Default: 1000000000
Tier: Production
Sets the period for a real clock timer of the query profiler. Real clock timer counts wall-clock time. Possible values: - Positive integer number, in nanoseconds. Recommended values: - 10000000 (100 times a second) nanoseconds and less for single queries. - 1000000000 (once a second) for cluster-wide profiling. - 0 for turning off the timer. See also: - System table trace_log Cloud default value: 3000000000.

queue_max_wait_ms

Type: Milliseconds
Default: 0
Tier: Production
The wait time in the request queue, if the number of concurrent requests exceeds the maximum.

rabbitmq_max_wait_ms

Type: Milliseconds
Default: 5000
Tier: Production
The wait time for reading from RabbitMQ before retry.

read_backoff_max_throughput

Type: UInt64
Default: 1048576
Tier: Production
Settings to reduce the number of threads in case of slow reads. Count events when the read bandwidth is less than that many bytes per second.

read_backoff_min_concurrency

Type: UInt64
Default: 1
Tier: Production
Settings to try keeping the minimal number of threads in case of slow reads.

read_backoff_min_events

Type: UInt64
Default: 2
Tier: Production
Settings to reduce the number of threads in case of slow reads. The number of events after which the number of threads will be reduced.

read_backoff_min_interval_between_events_ms

Type: Milliseconds
Default: 1000
Tier: Production
Settings to reduce the number of threads in case of slow reads. Do not pay attention to the event, if the previous one has passed less than a certain amount of time.

read_backoff_min_latency_ms

Type: Milliseconds
Default: 1000
Tier: Production
Setting to reduce the number of threads in case of slow reads. Pay attention only to reads that took at least that much time.

read_from_distributed_cache_if_exists_otherwise_bypass_cache

Type: Bool
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. Same as read_from_filesystem_cache_if_exists_otherwise_bypass_cache, but for distributed cache.

read_from_filesystem_cache_if_exists_otherwise_bypass_cache

Type: Bool
Default: 0
Tier: Production
Allow to use the filesystem cache in passive mode - benefit from the existing cache entries, but don't put more entries into the cache. If you set this setting for heavy ad-hoc queries and leave it disabled for short real-time queries, this will allows to avoid cache threshing by too heavy queries and to improve the overall system efficiency.

read_from_page_cache_if_exists_otherwise_bypass_cache

Type: Bool
Default: 0
Tier: Production
Use userspace page cache in passive mode, similar to read_from_filesystem_cache_if_exists_otherwise_bypass_cache.

read_in_order_two_level_merge_threshold

Type: UInt64
Default: 100
Tier: Production
Minimal number of parts to read to run preliminary merge step during multithread reading in order of primary key.

read_in_order_use_buffering

Type: Bool
Default: 1
Tier: Production
Use buffering before merging while reading in order of primary key. It increases the parallelism of query execution

read_in_order_use_virtual_row

Type: Bool
Default: 1
Tier: Production
Use virtual row while reading in order of primary key or its monotonic function fashion. It is useful when searching over multiple parts as only the parts that can actually contribute to the result are read, plus a bounded read-ahead window of at most max_threads parts that keeps reads parallel.

read_in_order_use_virtual_row_per_block

Type: Bool
Default: 0
Tier: Production
When enabled together with read_in_order_use_virtual_row, emit a virtual row after each block read (not only at the beginning of each part). This allows MergingSortedTransform to reprioritize sources more frequently, which is useful when downstream filters discard many rows and data is distributed unevenly across parts. Note that it disables read_in_order_use_buffering optimization and preliminary merge (read_in_order_two_level_merge_threshold) for reading.

read_overflow_mode

Type: OverflowMode
Default: throw
Tier: Production
What to do when the limit is exceeded.

read_overflow_mode_leaf

Type: OverflowMode
Default: throw
Tier: Production
Sets what happens when the volume of data read exceeds one of the leaf limits. Possible options: - throw: throw an exception (default). - break: stop executing the query and return the partial result.

read_priority

Type: Int64
Default: 0
Tier: Production
Priority to read data from local filesystem or remote filesystem. Only supported for 'pread_threadpool' method for local filesystem and for threadpool method for remote filesystem.

reader_executor_block_size

Type: UInt64
Default: 1048576
Tier: Experimental
Buffer chunk size for the experimental ReaderExecutor: source reads fill nodes of at most this size. Must be at least 4 KiB.

reader_executor_max_tail_for_drain

Type: UInt64
Default: 1048576
Tier: Experimental
Drain bound for the experimental ReaderExecutor: a long source connection dropped within this many bytes of its right bound is read out to the bound first, so it completes and returns to the connection pool reusable instead of counting as an incomplete connection.

reader_executor_min_bytes_for_seek

Type: UInt64
Default: 2097152
Tier: Experimental
Forward-gap bound for the experimental ReaderExecutor: a gap up to this is skipped on the open source connection (bridged / read through) instead of issuing a separate source read or reopening. Set near the bandwidth/request cost breakeven so bridging stays cost-positive.

reader_executor_use_long_connections

Type: Bool
Default: 0
Tier: Experimental
Reuse a bounded long source connection across windows in the experimental ReaderExecutor. A long connection is one whose range exceeds the current read window; when disabled, the executor takes no connection-pool budget and every window opens a short-lived one-shot connection (the stateless path).

reader_executor_window_size

Type: UInt64
Default: 4194304
Tier: Experimental
Bytes served per read window by the experimental ReaderExecutor (the unit a read returns). Must be at least 4 KiB.

readonly

Type: UInt64
Default: 0
Tier: Production
0 - no read-only restrictions. 1 - only read requests, as well as changing explicitly allowed settings. 2 - only read requests, as well as changing settings, except for the 'readonly' setting.

receive_data_timeout_ms

Type: Milliseconds
Default: 2000
Tier: Production
Connection timeout for receiving first packet of data or packet with positive progress from replica

receive_timeout

Type: Seconds
Default: 300
Tier: Production
Timeout for receiving data from the network, in seconds. If no bytes were received in this interval, the exception is thrown. If you set this setting on the client, the 'send_timeout' for the socket will also be set on the corresponding connection end on the server.

recursive_cte_max_steps_in_type_inference

Type: UInt64
Default: 10
Tier: Production
Maximum number of iterations for inferring column types in recursive CTEs. Column types are determined by iteratively applying getLeastSupertype across the non-recursive and recursive sides of the UNION ALL until convergence. Set to 0 to disable type widening and use the types from the non-recursive part only.

regexp_dict_allow_hyperscan

Type: Bool
Default: 1
Tier: Production
Allow regexp_tree dictionary using Hyperscan library.

regexp_dict_flag_case_insensitive

Type: Bool
Default: 0
Tier: Production
Use case-insensitive matching for a regexp_tree dictionary. Can be overridden in individual expressions with (?i) and (?-i).

regexp_dict_flag_dotall

Type: Bool
Default: 0
Tier: Production
Allow '.' to match newline characters for a regexp_tree dictionary.

regexp_max_matches_per_row

Type: UInt64
Default: 1000
Tier: Production
Sets the maximum number of matches for a single regular expression per row. Use it to protect against memory overload when using greedy regular expression in the extractAllGroupsHorizontal function. Possible values: - Positive integer.

reject_expensive_hyperscan_regexps

Type: Bool
Default: 1
Tier: Production
Reject patterns which will likely be expensive to evaluate with hyperscan (due to NFA state explosion)

remerge_sort_lowered_memory_bytes_ratio

Type: Float
Default: 2
Tier: Production
If memory usage after remerge does not reduced by this ratio, remerge will be disabled.

remote_filesystem_read_method

Type: String
Default: threadpool
Tier: Production
Method of reading data from remote filesystem, one of: read, threadpool.

remote_filesystem_read_prefetch

Type: Bool
Default: 1
Tier: Production
Should use prefetching when reading data from remote filesystem.

remote_fs_read_backoff_max_tries

Type: UInt64
Default: 5
Tier: Production
Max attempts to read with backoff

remote_fs_read_max_backoff_ms

Type: UInt64
Default: 10000
Tier: Production
Max wait time when trying to read data for remote disk

remote_read_min_bytes_for_seek

Type: UInt64
Default: 4194304
Tier: Production
Min bytes required for remote read (url, s3) to do seek, instead of read with ignore.

rename_files_after_processing

Type: String
Default: ``
Tier: Production

• Type: String - Default value: Empty string This setting allows to specify renaming pattern for files processed by file table function. When option is set, all files read by file table function will be renamed according to specified pattern with placeholders, only if files processing was successful. Renaming is a write to the source, so a query that reads the files with this option set requires the WRITE ON FILE grant in addition to READ ON FILE. DESCRIBE does not build the data-reading pipeline that renames, and so requires only READ ON FILE. ### Placeholders - %a — Full original filename (e.g., "sample.csv"). - %f — Original filename without extension (e.g., "sample"). - %e — Original file extension with dot (e.g., ".csv"). - %t — Timestamp (in microseconds). - %% — Percentage sign ("%"). ### Example - Option: --rename_files_after_processing="processed_%f_%t%e" - Query: SELECT * FROM file('sample.csv') If reading sample.csv is successful, file will be renamed to processed_sample_1683473210851438.csv

replace_running_query

Type: Bool
Default: 0
Tier: Production
When using the HTTP interface, the 'query_id' parameter can be passed. This is any string that serves as the query identifier. If a query from the same user with the same 'query_id' already exists at this time, the behaviour depends on the 'replace_running_query' parameter. 0 (default) – Throw an exception (do not allow the query to run if a query with the same 'query_id' is already running). 1 – Cancel the old query and start running the new one. Set this parameter to 1 for implementing suggestions for segmentation conditions. After entering the next character, if the old query hasn't finished yet, it should be cancelled.

replace_running_query_max_wait_ms

Type: Milliseconds
Default: 5000
Tier: Production
The wait time for running the query with the same query_id to finish, when the replace_running_query setting is active. Possible values: - Positive integer. - 0 — Throwing an exception that does not allow to run a new query if the server already executes a query with the same query_id.

replication_alter_partitions_sync

Type: UInt64
Default: 1
Tier: Production
Allows you to specify the wait behavior for actions that are to be executed on replicas by ALTER, OPTIMIZE or TRUNCATE queries. Possible values: - 0 — Do not wait. - 1 — Wait for own execution. - 2 — Wait for everyone. - 3 - Only wait for active replicas. Cloud default value: 0. :::note alter_sync is applicable to Replicated and SharedMergeTree tables only, it does nothing to alter non Replicated or Shared tables. :::

replication_wait_for_inactive_replica_timeout

Type: Int64
Default: 120
Tier: Production
Specifies how long (in seconds) to wait for inactive replicas to execute ALTER, OPTIMIZE or TRUNCATE queries. Possible values: - 0 — Do not wait. - Negative integer — Wait for unlimited time. - Positive integer — The number of seconds to wait.

reserve_memory

Type: UInt64
Default: 0
Tier: Experimental
Used in workload scheduling. The minimum amount of RAM reserved to be used for running a query on a single server. Reservation is made through the WORKLOAD hierarchy using the value of a workload query setting. If not enough memory is available to the workload, a query is prevented from starting and waits in pending state until the reservation can be fulfilled. A value of 0 means no reservation. This setting takes effect only if MEMORY RESERVATION resource is created.

restore_replace_external_dictionary_source_to_null

Type: Bool
Default: 0
Tier: Production
Replace external dictionary sources to Null on restore. Useful for testing purposes

restore_replace_external_engines_to_null

Type: Bool
Default: 0
Tier: Production
For testing purposes. Replaces all external engines to Null to not initiate external connections.

restore_replace_external_table_functions_to_null

Type: Bool
Default: 0
Tier: Production
For testing purposes. Replaces all external table functions to Null to not initiate external connections.

restore_replicated_merge_tree_to_shared_merge_tree

Type: Bool
Default: 0
Tier: Production
Replace table engine from ReplicatedMergeTree -> SharedMergeTree during RESTORE. Cloud default value: 1.

result_overflow_mode

Type: OverflowMode
Default: throw
Tier: Production
Sets what to do if the volume of the result exceeds one of the limits. Possible values: - throw: throw an exception (default). - break: stop executing the query and return the partial result, as if the source data ran out. Using 'break' is similar to using LIMIT. Break interrupts execution only at the block level. This means that amount of returned rows is greater than max_result_rows, multiple of max_block_size and depends on max_threads. Example sql title="Query" SET max_threads = 3, max_block_size = 3333; SET max_result_rows = 3334, result_overflow_mode = 'break'; SELECT * FROM numbers_mt(100000) FORMAT Null; text title="Result" 6666 rows in set. ...

resumable_backup_from_snapshot

Type: Bool
Default: 0
Tier: Experimental

RawTree only

Enables resumable BACKUP FROM SNAPSHOT: a failed attempt can be rerun without recopying the entries of batches that already completed. Cloud, for directory-style S3 and AzureBlobStorage destinations. Enabling it in RawTree open-source builds, where BACKUP FROM SNAPSHOT itself is unavailable, makes BACKUP fail with WRONG_BACKUP_SETTINGS.

rewrite_count_distinct_if_with_count_distinct_implementation

Type: Bool
Default: 0
Tier: Production
Allows you to rewrite countDistcintIf with count_distinct_implementation setting. Possible values: - true — Allow. - false — Disallow.

rewrite_in_to_join

Type: Bool
Default: 0
Tier: Experimental
Rewrite expressions like 'x IN subquery' to JOIN. This might be useful for optimizing the whole query with join reordering.

rows_before_aggregation

Type: Bool
Default: 0
Tier: Production
When enabled, RawTree will provide exact value for rows_before_aggregation statistic, represents the number of rows read before aggregation

run_query_in_background

Type: Bool
Default: 0
Tier: Production
If enabled, the server schedules the query in the background, immediately returns an empty successful result, and runs the query to completion regardless of what happens to the connection. A background query does not survive a server restart. On shutdown it obeys the same server settings as a foreground query: shutdown_wait_unfinished_queries chooses between cancelling it and waiting for it (queued entries are discarded either way, without a system.query_log entry), and shutdown_wait_unfinished limits how long the server waits. Track the query by its query_id: in system.processes while it is running and in system.query_log after it finishes and the query log entry is flushed. Applies to queries received over the native TCP and HTTP protocols. Over HTTP, pass the setting as a URL parameter. It cannot be changed with SET; enable it per query, or at the user or profile level. The main use case is a long INSERT ... SELECT that must not be lost when the client connection drops.

runtime_projections_max_aggregation_memory

Type: UInt64
Default: 1073741824
Tier: Production
Parts are aggregated separately for the runtime projections cache only when an earlier run of the same aggregation took at most this much memory for its hash tables and states.

runtime_projections_max_entry_bytes

Type: UInt64
Default: 67108864
Tier: Production
The maximum size of one entry of the runtime projections cache, i.e. of the compressed states of one part. A part whose states turn out bigger is read as usual by later queries.

runtime_projections_max_entry_rows_ratio

Type: Float
Default: 0.1
Tier: Production
A part is aggregated separately only when the aggregation is expected to produce at most this fraction of the selected rows, which is known from the hash table statistics of an earlier run of the same aggregation.

runtime_projections_max_parts_to_compute

Type: UInt64
Default: 16
Tier: Production
The maximum number of parts without a cached entry that a query aggregates separately to fill the runtime projections cache. The rest is read as usual.

runtime_projections_min_part_rows

Type: UInt64
Default: 262144
Tier: Production
The minimum number of rows a query selects from a part for the part to be aggregated separately and its states to be cached.

s3_allow_multipart_copy

Type: Bool
Default: 1
Tier: Production
Allow multipart copy in S3.

s3_allow_parallel_part_upload

Type: Bool
Default: 1
Tier: Production
Use multiple threads for s3 multipart upload. It may lead to slightly higher memory usage

s3_allow_server_credentials_in_user_queries

Type: Bool
Default: 0
Tier: Production
Allow S3 access that originates from user SQL to use server-managed credentials. When disabled (the default), the s3/s3Cluster table functions, the S3/S3Queue engines, S3 named collections, dynamic disk(type=s3, ...) definitions, BACKUP/RESTORE TO S3, DataLake table-data reads, and DataLakeCatalog databases (Glue, BigLake) may not resolve credentials from the environment, instance metadata (IMDS), IRSA, ECS, instance profile, SSO, AWS config/credentials files, or the GCP OAuth metadata service. A request that asks for one of those server-managed sources (for example use_environment_credentials = 1 or http_client = gcp_oauth) without supplying usable explicit credentials is rejected with ACCESS_DENIED. A request that asks for none of them is sent unsigned (anonymous), the same as if NOSIGN had been given. role_arn-based STS assume-role (extra_credentials(role_arn = '...')) stays allowed even when this setting is disabled: the target role must explicitly trust the identity the server runs under, and only the assumed role's credentials ever sign the query's S3 requests, so the server's own credentials are not exposed to the query. This is the documented way to grant RawTree Cloud access to a private bucket. The role is assumed with the query's own base keys when the query supplies a complete pair; otherwise the STS AssumeRole call is signed by the server's ambient identity. Static keys from the server <s3>/endpoint config or from a named collection are never used as the STS base for a query-supplied role, and a role_arn configured in the server <s3> config is not applied to user queries at all. Dynamic disk(type=s3, role_arn=...) definitions remain covered by the restriction. Whether a credential-less request asks for environment credentials is decided by use_environment_credentials. Named collections default it to 0, so a collection that only specifies a URL reads anonymously. The s3/s3Cluster table functions and S3/S3Queue engines use the built-in default (1) unless the server <s3> config sets it otherwise; set <s3><use_environment_credentials>0</use_environment_credentials></s3> to make their credential-less reads anonymous by default too (otherwise such a request is refused and must use NOSIGN). Disks defined in the server configuration are unaffected and keep using environment credentials by default; user-created dynamic disk(type = s3, ...) definitions are covered by the restriction (see above) and are rejected when they rely on default/environment credentials. This prevents an authenticated user from making the server access S3 with its own (ambient) credentials. Credentials supplied explicitly are not affected: keys passed in the query, static keys in a named collection (created via SQL or defined in config), and keys in the server <s3> config all keep working. The recommended way to give user queries S3 access is a named collection with explicit credentials (or NOSIGN for public buckets): the keys stay out of the query text, and use of each collection is controlled with RBAC (GRANT NAMED COLLECTION ON <name> TO <user>), so you grant specific users specific buckets instead of exposing the server's own identity. Scope (out of scope on purpose): this setting blocks only the server's ambient credential sources listed above. It does not block operator-provisioned static access_key_id/secret_access_key from the server <s3> config or from a config-defined named collection: those are treated as explicit credentials and keep working. Note, however, that config request material such as access_header or server-side-encryption keys is not by itself treated as a credential here: a request that carries only such material but no explicit key pair (and the default use_environment_credentials = 1) is still refused, because it would otherwise fall back to the server's ambient credentials. Such an endpoint must also provide explicit keys, NOSIGN, use_environment_credentials = 0, or the escape hatch below. A trusted administrative client may need server-managed credentials for legitimate operations (for example, attaching system tables on an s3_plain_rewritable disk via SQL). Enable this setting in that client's session or settings profile to permit it. For BACKUP/RESTORE ... ON CLUSTER the initiator's value of this setting is propagated to the other hosts and used there as-is. Those hosts run the per-host continuation of the operation through the distributed DDL queue, by default without the initiator's user, so they would otherwise evaluate the restriction against their own default profile; the initiator's value is preserved instead, because it has already opened the same backup destination under its own, constrained, settings. A readonly constraint on the initiator still applies (an untrusted initiator cannot enable the setting for its own on-cluster backup), so this does not weaken the restriction. Durability for persistent S3 and S3Queue tables: enabling this only per session or profile is not durable across a restart. When the server reloads such a table from its stored definition (startup or RESTORE) it rebuilds the S3 client and re-applies the restriction with the startup context, so a table that relied on server-managed credentials and was created only under a session/profile s3_allow_server_credentials_in_user_queries = 1 is created successfully but becomes inaccessible after a restart (the table is left in place; queries against it fail until its credentials resolve to a permitted source again). The server itself still starts. Give such tables explicit credentials for durable access; alternatively, enabling the setting server-wide keeps them loading across restarts, at the cost of relaxing the restriction for all reloads. To keep it disabled for untrusted users, pin it in their profile by both setting the value explicitly to 0 and marking it readonly: xml <profiles> <untrusted> <s3_allow_server_credentials_in_user_queries>0</s3_allow_server_credentials_in_user_queries> <constraints> <s3_allow_server_credentials_in_user_queries> <readonly/> </s3_allow_server_credentials_in_user_queries> </constraints> </untrusted> </profiles> This setting has no effect in clickhouse-local, where the user is the operator. DataLakeCatalog databases (Glue, BigLake) are also covered, with one difference. A catalog object is created once and shared by every user of the database, so the value cannot be read per query; it is captured from the session that runs CREATE DATABASE (or a user ATTACH DATABASE). A database created while this setting is enabled (for example in a trusted session or profile) may use the server's ambient credentials for its catalog, and every user able to query that database then shares them; created under the default, the catalog is restricted for everyone regardless of who queries it. When the server loads an already-created database from its own metadata (startup, RESTORE) the restriction is re-applied with the startup context, the same as for persistent S3/S3Queue tables: a catalog that resolves server-managed credentials is left unavailable and the database becomes inaccessible after a restart (the server still starts; the database loads with an unavailable catalog per s3_load_table_anonymously_if_credentials_restricted, and queries report the restriction). A catalog given explicit credentials (Glue: aws_access_key_id and aws_secret_access_key; BigLake: a complete Google ADC triple) works regardless and is durable across restart.

s3_base

Type: String
Default: ``
Tier: Production
The base URL used to resolve relative URLs in the s3 table function and the S3 table engine, as well as in the table functions that share their configuration (s3Cluster, gcs, oss). When set, a URL without a scheme is resolved against s3_base per RFC 3986, using the same rules as url_base. URLs that already contain a scheme are used as-is. For example, if s3_base is s3://clickhouse-public-datasets/, then s3('hits_compatible/hits.csv') reads s3://clickhouse-public-datasets/hits_compatible/hits.csv. The base URL can use any form accepted by the s3 table function, e.g. s3://bucket/, https://bucket.s3.amazonaws.com/ or https://endpoint/bucket/. When the relative URL comes from a named collection, resolving it counts as an override of the url key of the collection and requires the SHOW NAMED COLLECTIONS SECRETS privilege on that collection.

s3_check_objects_after_upload

Type: Bool
Default: 0
Tier: Production
Check each uploaded object to s3 with head request to be sure that upload was successful

s3_connect_timeout_ms

Type: UInt64
Default: 1000
Tier: Production
Connection timeout for host from s3 disks.

s3_create_new_file_on_insert

Type: Bool
Default: 0
Tier: Production
Enables or disables creating a new file on each insert in s3 engine tables. If enabled, on each insert a new S3 object will be created with the key, similar to this pattern: initial: data.Parquet.gz -> data.1.Parquet.gz -> data.2.Parquet.gz, etc. Possible values: - 0 — INSERT query creates a new file or fail if file exists and s3_truncate_on_insert is not set. - 1 — INSERT query creates a new file on each insert using suffix (from the second one) if s3_truncate_on_insert is not set. See more details here.

s3_disable_checksum

Type: Bool
Default: 0
Tier: Production
Do not calculate a checksum when sending a file to S3. This speeds up writes by avoiding excessive processing passes on a file. It is mostly safe as the data of MergeTree tables is checksummed by RawTree anyway, and when S3 is accessed with HTTPS, the TLS layer already provides integrity while transferring through the network. While additional checksums on S3 give defense in depth.

s3_ignore_file_doesnt_exist

Type: Bool
Default: 0
Tier: Production
Ignore absence of file if it does not exist when reading certain keys. Possible values: - 1 — SELECT returns empty result. - 0 — SELECT throws an exception.

s3_list_object_keys_size

Type: UInt64
Default: 1000
Tier: Production
Maximum number of files that could be returned in batch by ListObject request

s3_max_connections

Type: UInt64
Default: 1024
Tier: Production
The maximum number of connections per server.

s3_max_get_burst

Type: UInt64
Default: 0
Tier: Production
Max number of requests that can be issued simultaneously before hitting request per second limit. By default (0) equals to s3_max_get_rps

s3_max_get_rps

Type: UInt64
Default: 0
Tier: Production
Limit on S3 GET request per second rate before throttling. Zero means unlimited.

s3_max_inflight_parts_for_one_file

Type: UInt64
Default: 20
Tier: Production
The maximum number of a concurrent loaded parts in multipart upload request. 0 means unlimited.

s3_max_part_number

Type: UInt64
Default: 10000
Tier: Production
Maximum part number number for s3 upload part.

s3_max_put_burst

Type: UInt64
Default: 0
Tier: Production
Max number of requests that can be issued simultaneously before hitting request per second limit. By default (0) equals to s3_max_put_rps

s3_max_put_rps

Type: UInt64
Default: 0
Tier: Production
Limit on S3 PUT request per second rate before throttling. Zero means unlimited.

s3_max_single_operation_copy_size

Type: UInt64
Default: 33554432
Tier: Production
Maximum size for single-operation copy in s3. This setting is used only if s3_allow_multipart_copy is true.

s3_max_single_part_upload_size

Type: UInt64
Default: 33554432
Tier: Production
The maximum size of object to upload using singlepart upload to S3.

s3_max_single_read_retries

Type: UInt64
Default: 4
Tier: Production
The maximum number of retries during single S3 read.

s3_max_unexpected_write_error_retries

Type: UInt64
Default: 4
Tier: Production
The maximum number of retries in case of unexpected errors during S3 write.

s3_max_upload_part_size

Type: UInt64
Default: 5368709120
Tier: Production
The maximum size of part to upload during multipart upload to S3.

s3_min_upload_part_size

Type: UInt64
Default: 16777216
Tier: Production
The minimum size of part to upload during multipart upload to S3.

s3_path_filter_limit

Type: UInt64
Default: 1000
Tier: Production
Maximum number of _path values that can be extracted from query filters to use for file iteration instead of glob listing. 0 means disabled.

s3_request_timeout_ms

Type: UInt64
Default: 30000
Tier: Production
Idleness timeout for sending and receiving data to/from S3. Fail if a single TCP read or write call blocks for this long.

s3_skip_empty_files

Type: Bool
Default: 1
Tier: Production
Enables or disables skipping empty files in S3 engine tables. Possible values: - 0 — SELECT throws an exception if empty file is not compatible with requested format. - 1 — SELECT returns empty result for empty file.

s3_slow_all_threads_after_network_error

Type: Bool
Default: 1
Tier: Production
When set to true, all threads executing S3 requests to the same backup endpoint are slowed down after any single s3 request encounters a retryable network error, such as socket timeout. When set to false, each thread handles S3 request backoff independently of the others.

s3_strict_upload_part_size

Type: UInt64
Default: 0
Tier: Production
The exact size of part to upload during multipart upload to S3 (some implementations does not supports variable size parts).

s3_throw_on_zero_files_match

Type: Bool
Default: 0
Tier: Production
Throw an error, when ListObjects request cannot match any files

s3_truncate_on_insert

Type: Bool
Default: 0
Tier: Production
Enables or disables truncate before inserts in s3 engine tables. If disabled, an exception will be thrown on insert attempts if an S3 object already exists. Possible values: - 0 — INSERT query creates a new file or fail if file exists and s3_create_new_file_on_insert is not set. - 1 — INSERT query replaces existing content of the file with the new data. See more details here.

s3_upload_part_size_multiply_factor

Type: UInt64
Default: 2
Tier: Production
Multiply s3_min_upload_part_size by this factor each time s3_multiply_parts_count_threshold parts were uploaded from a single write to S3.

s3_upload_part_size_multiply_parts_count_threshold

Type: UInt64
Default: 500
Tier: Production
Each time this number of parts was uploaded to S3, s3_min_upload_part_size is multiplied by s3_upload_part_size_multiply_factor.

s3_uri_style

Type: S3UriStyle
Default: auto
Tier: Production
Force the s3 endpoint style. Possible values: auto, virtual_hosted, path.

s3_use_adaptive_timeouts

Type: Bool
Default: 1
Tier: Production
When set to true than for all s3 requests first two attempts are made with low send and receive timeouts. When set to false than all attempts are made with identical timeouts.

s3_validate_etag_on_read

Type: Bool
Default: 1
Tier: Production
When reading an object from S3 (or an S3-compatible store such as GCS), check that every GET request returns the same ETag that was observed when the object was listed. A single file read issues many ranged GET requests; if the object is overwritten in place between them (for example by an external writer rewriting a fixed key), the reads can otherwise be stitched together from two different object generations and surface as a corrupted checksum or parse error. When a mismatch is detected the read fails with S3_OBJECT_CHANGED_DURING_READ instead of returning inconsistent data. Disable only for workloads that intentionally read objects that are being overwritten and can tolerate inconsistent reads.

s3_validate_request_settings

Type: Bool
Default: 1
Tier: Production
Enables s3 request settings validation. Possible values: - 1 — validate settings. - 0 — do not validate settings.

s3queue_default_zookeeper_path

Type: String
Default: /rawtree/s3queue/
Tier: Production
Default zookeeper path prefix for S3Queue engine

s3queue_enable_logging_to_s3queue_log

Type: Bool
Default: 0
Tier: Production
Enable writing to system.s3queue_log. The value can be overwritten per table with table settings

s3queue_keeper_fault_injection_probability

Type: Float
Default: 0
Tier: Production
Keeper fault injection probability for S3Queue.

s3queue_migrate_old_metadata_to_buckets

Type: Bool
Default: 0
Tier: Production
Migrate old metadata structure of S3Queue table to a new one

schema_inference_cache_require_modification_time_for_url

Type: Bool
Default: 1
Tier: Production
Use schema from cache for URL with last modification time validation (for URLs with Last-Modified header)

schema_inference_hints

Type: String
Default: ``
Tier: Production
The list of column names and types to use as hints in schema inference for formats without schema. Example: Query: sql desc format(JSONEachRow, '{"x" : 1, "y" : "String", "z" : "0.0.0.0" }') settings schema_inference_hints='x UInt8, z IPv4'; Result: sql x UInt8 y Nullable(String) z IPv4 :::note If the schema_inference_hints is not formatted properly, or if there is a typo or a wrong datatype, etc... the whole schema_inference_hints will be ignored. :::

schema_inference_make_columns_nullable

Type: UInt64Auto
Default: 3
Tier: Production
Controls making inferred types Nullable in schema inference. Possible values: * 0 - the inferred type will never be Nullable (use input_format_null_as_default to control what do do with null values in this case), * 1 - all inferred types will be Nullable, * 2 or auto - the inferred type will be Nullable only if the column contains NULL in a sample that is parsed during schema inference or file metadata contains information about column nullability, * 3 - the inferred type nullability will match file metadata if the format has it (e.g. Parquet), always Nullable otherwise (e.g. CSV).

schema_inference_make_json_columns_nullable

Type: Bool
Default: 0
Tier: Production
Controls making inferred JSON types Nullable in schema inference. If this setting is enabled together with schema_inference_make_columns_nullable, inferred JSON type will be Nullable.

schema_inference_mode

Type: SchemaInferenceMode
Default: default
Tier: Production
Mode of schema inference. 'default' - assume that all files have the same schema and schema can be inferred from any file, 'union' - files can have different schemas and the resulting schema should be the a union of schemas of all files

schema_inference_use_cache_for_azure

Type: Bool
Default: 1
Tier: Production
Use cache in schema inference while using azure table function

schema_inference_use_cache_for_file

Type: Bool
Default: 1
Tier: Production
Use cache in schema inference while using file table function

schema_inference_use_cache_for_hdfs

Type: Bool
Default: 1
Tier: Production
Use cache in schema inference while using hdfs table function

schema_inference_use_cache_for_s3

Type: Bool
Default: 1
Tier: Production
Use cache in schema inference while using s3 table function

schema_inference_use_cache_for_url

Type: Bool
Default: 1
Tier: Production
Use cache in schema inference while using url table function

secondary_indices_enable_bulk_filtering

Type: Bool
Default: 1
Tier: Production
Enable the bulk filtering algorithm for indices. It is expected to be always better, but we have this setting for compatibility and control.

select

Type: String
Default: ``
Tier: Production
Wraps the query as a subquery with an explicit SELECT expression list. When non-empty, the result-producing query is wrapped as SELECT <expr_list> FROM (<query>). This is a query-construction setting applied by the engine on the parsed query (wrapping it as a derived table), so it composes with the existing query and works on every protocol: it can be supplied via the HTTP URL parameter, an in-query SETTINGS clause, or a user profile. It shapes result-producing SELECT / UNION queries. For a write query (INSERT … SELECT, CREATE … AS SELECT) it takes effect only when the source SELECT carries it in its own SETTINGS clause; a value inherited from a profile or session, or set on the INSERT / CREATE statement itself, does not propagate into the source SELECT — the same non-propagation rule that applies to any other setting.

select_sequential_consistency

Type: UInt64
Default: 0
Tier: Production
:::note This setting differ in behavior between SharedMergeTree and ReplicatedMergeTree, see SharedMergeTree consistency for more information about the behavior of select_sequential_consistency in SharedMergeTree. ::: Enables or disables sequential consistency for SELECT queries. Requires insert_quorum_parallel to be disabled (enabled by default). Possible values: - 0 — Disabled. - 1 — Enabled. Usage When sequential consistency is enabled, RawTree allows the client to execute the SELECT query only for those replicas that contain data from all previous INSERT queries executed with insert_quorum. If the client refers to a partial replica, RawTree will generate an exception. The SELECT query will not include data that has not yet been written to the quorum of replicas. When insert_quorum_parallel is enabled (the default), then select_sequential_consistency does not work. This is because parallel INSERT queries can be written to different sets of quorum replicas so there is no guarantee a single replica will have received all writes. See also: - insert_quorum - insert_quorum_timeout - insert_quorum_parallel

send_hints

Type: Bool
Default: 1
Tier: Production
Enables or disables sending of hints packets to the client. This can be disabled to reduce network traffic for clients that do not require hints. Possible values: - 0 — Disabled. - 1 — Enabled.

send_logs_level

Type: LogsLevel
Default: fatal
Tier: Production
Send server text logs with specified minimum level to client. Valid values: 'test', 'trace', 'debug', 'information', 'warning', 'error', 'fatal', 'none'

send_logs_source_regexp

Type: String
Default: ``
Tier: Production
Send server text logs with specified regexp to match log source name. Empty means all sources.

send_profile_events

Type: Bool
Default: 1
Tier: Production
Enables or disables sending of ProfileEvents packets to the client. This can be disabled to reduce network traffic for clients that do not require profile events. Possible values: - 0 — Disabled. - 1 — Enabled.

send_progress_in_http_headers

Type: Bool
Default: 0
Tier: Production
Enables or disables X-RawTree-Progress / X-ClickHouse-Progress HTTP response headers in rawtree-server responses. For more information, read the HTTP interface description. Possible values: - 0 — Disabled. - 1 — Enabled.

send_table_structure_on_insert_with_inline_data

Type: Bool
Default: 1
Tier: Production
If disabled and the INSERT query contains inline data, the server will not send the table structure and column defaults back to the client over the native protocol. Instead, the server will parse the inline data itself. This can improve performance for many small inserts over the native protocol.

send_timeout

Type: Seconds
Default: 300
Tier: Production
Timeout for sending data to the network, in seconds. If a client needs to send some data but is not able to send any bytes in this interval, the exception is thrown. If you set this setting on the client, the 'receive_timeout' for the socket will also be set on the corresponding connection end on the server.

serialize_query_plan

Type: Bool
Default: 0
Tier: Production
Serialize query plan for distributed processing

serialize_string_in_memory_with_zero_byte

Type: Bool
Default: 1
Tier: Production
Serialize String values during aggregation with zero byte at the end. Enable to keep compatibility when querying cluster of incompatible versions.

session_timezone

Type: Timezone
Default: ``
Tier: Beta
Sets the implicit time zone of the current session or query. The implicit time zone is the time zone applied to values of type DateTime/DateTime64 which have no explicitly specified time zone. The setting takes precedence over the globally configured (server-level) implicit time zone. A value of '' (empty string) means that the implicit time zone of the current session or query is equal to the server time zone. You can use functions timeZone() and serverTimeZone() to get the session time zone and server time zone. Possible values: - Any time zone name from system.time_zones, e.g. Europe/Berlin, UTC or Zulu Examples: sql SELECT timeZone(), serverTimeZone() FORMAT CSV "Europe/Berlin","Europe/Berlin" sql SELECT timeZone(), serverTimeZone() SETTINGS session_timezone = 'Asia/Novosibirsk' FORMAT CSV "Asia/Novosibirsk","Europe/Berlin" Assign session time zone 'America/Denver' to the inner DateTime without explicitly specified time zone: sql SELECT toDateTime64(toDateTime64('1999-12-12 23:23:23.123', 3), 3, 'Europe/Zurich') SETTINGS session_timezone = 'America/Denver' FORMAT TSV 1999-12-13 07:23:23.123 :::warning Not all functions that parse DateTime/DateTime64 respect session_timezone. This can lead to subtle errors. See the following example and explanation. ::: sql CREATE TABLE test_tz (`d` DateTime('UTC')) ENGINE = Memory AS SELECT toDateTime('2000-01-01 00:00:00', 'UTC'); SELECT *, timeZone() FROM test_tz WHERE d = toDateTime('2000-01-01 00:00:00') SETTINGS session_timezone = 'Asia/Novosibirsk' 0 rows in set. SELECT *, timeZone() FROM test_tz WHERE d = '2000-01-01 00:00:00' SETTINGS session_timezone = 'Asia/Novosibirsk' ┌───────────────────d─┬─timeZone()───────┐ │ 2000-01-01 00:00:00 │ Asia/Novosibirsk │ └─────────────────────┴──────────────────┘ This happens due to different parsing pipelines: - toDateTime() without explicitly given time zone used in the first SELECT query honors setting session_timezone and the global time zone. - In the second query, a DateTime is parsed from a String, and inherits the type and time zone of the existing columnd. Thus, setting session_timezone and the global time zone are not honored. See also - timezone

set_overflow_mode

Type: OverflowMode
Default: throw
Tier: Production
Sets what happens when the amount of data exceeds one of the limits. Possible values: - throw: throw an exception (default). - break: stop executing the query and return the partial result, as if the source data ran out.

shared_merge_tree_sequential_consistency_initial_parts_update_backoff_ms

Type: UInt64
Default: 50
Tier: Production
Initial backoff in milliseconds for parts update when using select_sequential_consistency with SharedMergeTree. Only available in ClickHouse Cloud.

shared_merge_tree_sequential_consistency_max_parts_update_backoff_ms

Type: UInt64
Default: 1000
Tier: Production
Max backoff in milliseconds for parts update when using select_sequential_consistency with SharedMergeTree. Only available in ClickHouse Cloud.

shared_merge_tree_sequential_consistency_parts_update_max_retries

Type: UInt64
Default: 10
Tier: Production
Max retries for parts update when using select_sequential_consistency with SharedMergeTree. Only available in ClickHouse Cloud.

shared_merge_tree_sync_parts_on_partition_operations

Type: Bool
Default: 1
Tier: Production
Automatically synchronize set of data parts after MOVE|REPLACE|ATTACH partition operations in SMT tables. Cloud only

short_circuit_function_evaluation

Type: ShortCircuitFunctionEvaluation
Default: enable
Tier: Production
Allows calculating the if, multiIf, and, and or functions according to a short scheme. This helps optimize the execution of complex expressions in these functions and prevent possible exceptions (such as division by zero when it is not expected). Possible values: - enable — Enables short-circuit function evaluation for functions that are suitable for it (can throw an exception or computationally heavy). - force_enable — Enables short-circuit function evaluation for all functions. - disable — Disables short-circuit function evaluation.

short_circuit_function_evaluation_for_nulls

Type: Bool
Default: 1
Tier: Production
Optimizes evaluation of functions that return NULL when any argument is NULL. When the percentage of NULL values in the function's arguments exceeds the short_circuit_function_evaluation_for_nulls_threshold, the system skips evaluating the function row-by-row. Instead, it immediately returns NULL for all rows, avoiding unnecessary computation.

short_circuit_function_evaluation_for_nulls_threshold

Type: Double
Default: 1
Tier: Production
Ratio threshold of NULL values to execute functions with Nullable arguments only on rows with non-NULL values in all arguments. Applies when setting short_circuit_function_evaluation_for_nulls is enabled. When the ratio of rows containing NULL values to the total number of rows exceeds this threshold, these rows containing NULL values will not be evaluated.

show_create_query_identifier_quoting_rule

Type: IdentifierQuotingRule
Default: when_necessary
Tier: Production
Set the quoting rule for identifiers in SHOW CREATE query

show_create_query_identifier_quoting_style

Type: IdentifierQuotingStyle
Default: Backticks
Tier: Production
Set the quoting style for identifiers in SHOW CREATE query

show_data_lake_catalogs_in_system_tables

Type: Bool
Default: 0
Tier: Production
Enables showing data lake catalogs in system tables.

show_processlist_include_internal

Type: Bool
Default: 1
Tier: Production
Show internal auxiliary processes in the SHOW PROCESSLIST query output. Internal processes include dictionary reloads, refreshable materialized view reloads, auxiliary SELECTs executed in SHOW ... queries, auxiliary CREATE DATABASE ... queries executed internally to accommodate broken tables and more.

show_remote_databases_in_system_tables

Type: Bool
Default: 1
Tier: Production
Enables showing MySQL and PostgreSQL databases in system tables.

show_table_uuid_in_table_create_query_if_not_nil

Type: Bool
Default: 0
Tier: Production
Sets the SHOW TABLE query display. Possible values: - 0 — The query will be displayed without table UUID. - 1 — The query will be displayed with table UUID.

shrink_over_allocated_columns_min_waste_bytes

Type: UInt64
Default: 16777216
Tier: Production
Minimum absolute amount of wasted (reserved but unused) memory in a column, in bytes, for it to be shrunk to fit on INSERT. See shrink_over_allocated_columns_min_waste_ratio. Prevents reallocating columns whose over-allocation is small, where the memory saving would not justify the cost.

shrink_over_allocated_columns_min_waste_ratio

Type: Float
Default: 1
Tier: Production
On INSERT, over-allocated columns (whose reserved memory exceeds the used memory, e.g. due to power-of-two growth of variable-length columns) are shrunk to fit before the expensive materialization and part-writing stages, to reduce peak memory usage. A column is shrunk only when allocatedBytes() > byteSize() * shrink_over_allocated_columns_min_waste_ratio and the absolute waste is at least shrink_over_allocated_columns_min_waste_bytes. Possible values: - Float greater than 1. - Value less than or equal to 1 disables the shrinking (the default 1.0 keeps it disabled).

single_join_prefer_left_table

Type: Bool
Default: 1
Tier: Production
For single JOIN in case of identifier ambiguity prefer left table

skip_download_if_exceeds_query_cache

Type: Bool
Default: 1
Tier: Production
Skip download from remote filesystem if exceeds query cache size

skip_redundant_aliases_in_udf

Type: Bool
Default: 0
Tier: Production
Redundant aliases are not used (substituted) in user-defined functions in order to simplify it's usage. Possible values: - 1 — The aliases are skipped (substituted) in UDFs. - 0 — The aliases are not skipped (substituted) in UDFs. Example The difference between enabled and disabled: Query: sql SET skip_redundant_aliases_in_udf = 0; CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2)); EXPLAIN SYNTAX SELECT test_03274(4 + 2); Result: text SELECT ((4 + 2) + 1 AS y, y + 2) Query: sql SET skip_redundant_aliases_in_udf = 1; CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2)); EXPLAIN SYNTAX SELECT test_03274(4 + 2); Result: text SELECT ((4 + 2) + 1, ((4 + 2) + 1) + 2)

skip_unavailable_shards

Type: Bool
Default: 0
Tier: Production
Enables or disables silently skipping of unavailable shards. The behavior of this setting is controlled by the skip_unavailable_shards_mode parameter. Possible values: - 1 — skipping enabled. If a shard is unavailable, RawTree returns a result based on partial data and does not report node availability issues. - 0 — skipping disabled. If a shard is unavailable, RawTree throws an exception.

skip_unavailable_shards_mode

Type: SkipUnavailableShardsMode
Default: unavailable_or_table_missing
Tier: Production
Controls which exceptions from a remote shard are silently ignored when skip_unavailable_shards is enabled. The setting has no effect when skip_unavailable_shards = 0. Possible values: - unavailable — Only connection-related errors are ignored. A shard is considered unavailable when ClickHouse cannot connect to any of its replicas, or when a replica's hostname cannot be resolved through DNS. - unavailable_or_table_missing — In addition to unavailable, errors caused by a missing table or database on the shard are ignored. This is useful while a table is being created or dropped across a cluster. This is the default and matches the historical behavior of skip_unavailable_shards, which also treated a shard whose table does not exist as unavailable. - unavailable_or_exception_before_processing — In addition to unavailable, any exception received from a shard before it returned any data block to the initiator is ignored. An exception that arrives after the shard already returned some data is always rethrown. Note that "before it returned any data" is checked at the initiator: a shard that performs a blocking computation (for example an aggregation, sort, or LIMIT BY) may process rows and fail before emitting any block, in which case its partial work is silently discarded and the query returns a result built from the remaining shards. This is therefore the most permissive mode and should be used with care.

sleep_after_receiving_query_ms

Type: Milliseconds
Default: 0
Tier: Production
Time to sleep after receiving query in TCPHandler

sleep_in_send_data_ms

Type: Milliseconds
Default: 0
Tier: Production
Time to sleep in sending data in TCPHandler

sleep_in_send_tables_status_ms

Type: Milliseconds
Default: 0
Tier: Production
Time to sleep in sending tables status response in TCPHandler

snappy_mode

Type: SnappyMode
Default: basic
Tier: Production
Controls the wire format used for snappy compression for generic file I/O paths such as file and url. HTTP Content-Encoding: snappy always uses the framing format and ignores this setting. Note that the raw snappy block format produced by a single snappy::Compress call (for example, the Prometheus remote protocol payloads handled by SnappyBasicReadBuffer) is a separate, protocol-specific wire format and is not controlled by this setting. Possible values: - basic — Hadoop snappy block format. Compatible with files read and written by Hadoop. Supports both reading and writing. - framed — Snappy framing format, the standard streaming format defined by Google. Supports both reading and writing.

sort

Type: String
Default: ``
Tier: Production
Adds a simple ORDER BY clause to the query as a wrapping subquery. Accepts a comma-separated list of identifiers or positional column references (positive integers) with an optional + (ASC) or - (DESC) prefix. Example: sort=a,-b orders by a ascending and b descending; sort=1,-2 orders by the first column ascending and the second descending. Cannot be combined with order. This is a query-construction setting applied by the engine on the parsed query (wrapping it as a derived table), so it composes with the existing query and works on every protocol: it can be supplied via the HTTP URL parameter, an in-query SETTINGS clause, or a user profile. It shapes result-producing SELECT / UNION queries. For a write query (INSERT … SELECT, CREATE … AS SELECT) it takes effect only when the source SELECT carries it in its own SETTINGS clause; a value inherited from a profile or session, or set on the INSERT / CREATE statement itself, does not propagate into the source SELECT — the same non-propagation rule that applies to any other setting.

sort_overflow_mode

Type: OverflowMode
Default: throw
Tier: Production
Sets what happens if the number of rows received before sorting exceeds one of the limits. Possible values: - throw: throw an exception. - break: stop executing the query and return the partial result.

split_intersecting_parts_ranges_into_layers_final

Type: Bool
Default: 1
Tier: Production
Split intersecting parts ranges into layers during FINAL optimization

split_parts_ranges_into_intersecting_and_non_intersecting_final

Type: Bool
Default: 1
Tier: Production
Split parts ranges into intersecting and non intersecting during FINAL optimization

splitby_max_substrings_includes_remaining_string

Type: Bool
Default: 0
Tier: Production
Controls whether function splitBy*() with argument max_substrings > 0 will include the remaining string in the last element of the result array. Possible values: - 0 - The remaining string will not be included in the last element of the result array. - 1 - The remaining string will be included in the last element of the result array. This is the behavior of Spark's split() function and Python's 'string.split()' method.

statistics_max_set_size_for_exact_selectivity_estimation

Type: UInt64
Default: 10000
Tier: Production
The maximum size of the set in the right-hand side of the IN operator for which the selectivity estimator derives the exact ranges covered by the set. Deriving them costs a Field per element, a sort, and one statistics probe per element, which for a large set dominates query planning. Above this limit the estimator instead derives the selectivity from the size of the set and its bounding range, which is a single linear pass over the set without the sort or the per-element statistics probes. Zero means no limit.

stop_refreshable_materialized_views_on_startup

Type: Bool
Default: 0
Tier: Experimental
On server startup, prevent scheduling of refreshable materialized views, as if with SYSTEM STOP VIEWS. You can manually start them with SYSTEM START VIEWS or SYSTEM START VIEW <name> afterwards. Also applies to newly created views. Has no effect on non-refreshable materialized views.

storage_file_read_method

Type: LocalFSReadMethod
Default: pread
Tier: Production
Method of reading data from storage file, one of: read, pread, mmap. The mmap method does not apply to rawtree-server (it's intended for rawtree-local).

storage_system_stack_trace_pipe_read_timeout_ms

Type: Milliseconds
Default: 100
Tier: Production
Maximum time to read from a pipe for receiving information from the threads when querying the system.stack_trace table. This setting is used for testing purposes and not meant to be changed by users.

stream_flush_interval_ms

Type: Milliseconds
Default: 7500
Tier: Production
Works for tables with streaming in the case of a timeout, or when a thread generates max_insert_block_size rows. The default value is 7500. The smaller the value, the more often data is flushed into the table. Setting the value too low leads to poor performance.

stream_like_engine_allow_direct_select

Type: Bool
Default: 0
Tier: Production
Allow direct SELECT query for Kafka, RabbitMQ, FileLog, Redis Streams, S3Queue, AzureQueue and NATS engines. In case there are attached materialized views, SELECT query is not allowed even if this setting is enabled. If there are no attached materialized views, enabling this setting allows to read data. Be aware that usually the read data is removed from the queue. In order to avoid removing read data the related engine settings should be configured properly.

stream_like_engine_insert_queue

Type: String
Default: ``
Tier: Production
When stream-like engine reads from multiple queues, the user will need to select one queue to insert into when writing. Used by Redis Streams and NATS.

stream_poll_timeout_ms

Type: Milliseconds
Default: 500
Tier: Production
Timeout for polling data from/to streaming storages.

system_events_show_zero_values

Type: Bool
Default: 0
Tier: Production
Allows to select zero-valued events from system.events. Some monitoring systems require passing all the metrics values to them for each checkpoint, even if the metric value is zero. Possible values: - 0 — Disabled. - 1 — Enabled. Examples Query sql SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded'; Result text Ok. Query sql SET system_events_show_zero_values = 1; SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded'; Result text ┌─event────────────────────┬─value─┬─description───────────────────────────────────────────┐ │ QueryMemoryLimitExceeded │ 0 │ Number of times when memory limit exceeded for query. │ └──────────────────────────┴───────┴───────────────────────────────────────────────────────┘

system_metric_log_show_zero_values_in_histograms

Type: Bool
Default: 0
Tier: Production
Controls whether zero-valued histogram data is written to the histograms nested column of system.metric_log. By default, histograms whose total observation count is zero are skipped, and within each emitted histogram, bucket entries with no observations are also omitted from the histogram map. Enable this to write every histogram and every bucket regardless of count — useful for monitoring systems that require every metric to appear at every checkpoint. Possible values: - 0 — Disabled. Histograms with count = 0 are not emitted; emitted histograms include only buckets that received at least one observation. - 1 — Enabled. All histograms are written, and every bucket boundary appears in histogram.

table_engine_read_through_distributed_cache

Type: Bool
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. Allow reading from distributed cache via table engines / table functions (s3, azure, etc)

table_function_remote_max_addresses

Type: UInt64
Default: 1000
Tier: Production
Sets the maximum number of addresses generated from patterns for the remote function. Possible values: - Positive integer.

tcp_keep_alive_timeout

Type: Seconds
Default: 290
Tier: Production
The time in seconds the connection needs to remain idle before TCP starts sending keepalive probes

temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds

Type: UInt64
Default: 600000
Tier: Production
Wait time to lock cache for space reservation for temporary data in filesystem cache

temporary_files_buffer_size

Type: NonZeroUInt64
Default: 1048576
Tier: Production
Size of the buffer for temporary files writers. Larger buffer size means less system calls, but more memory consumption.

temporary_files_codec

Type: String
Default: LZ4
Tier: Production
Sets compression codec for temporary files used in sorting and joining operations on disk. Possible values: - LZ4 — LZ4 compression is applied. - NONE — No compression is applied.

text_index_density_threshold

Type: Float
Default: 0.2
Tier: Production
Posting list density threshold that selects the intersection algorithm in lazy posting list apply mode (text_index_posting_list_apply_mode = 'lazy'). Below the threshold: leapfrog intersection (favors sparse posting lists). At or above: brute-force bitmap intersection (favors dense posting lists).

text_index_hint_max_selectivity

Type: Float
Default: 0.2
Tier: Production
Maximal selectivity of the filter to use the hint built from the inverted text index.

text_index_lazy_intersection_density_threshold

Type: Float
Default: 0.2
Tier: Production
Posting list density threshold that selects the intersection algorithm in lazy posting list apply mode (text_index_posting_list_apply_mode = 'lazy'). Below the threshold: leapfrog intersection (favors sparse posting lists). At or above: brute-force bitmap intersection (favors dense posting lists).

text_index_like_max_postings_to_read

Type: UInt64
Default: 50
Tier: Production
Maximum number of large postings to read when text index LIKE evaluation by the dictionary scan is enabled. Requires use_text_index_like_evaluation_by_dictionary_scan to be enabled.

text_index_like_min_pattern_length

Type: UInt64
Default: 4
Tier: Production
Minimum length of the alphanumeric needle in a LIKE/ILIKE pattern, or of a startsWith/endsWith needle, required to use the text index LIKE evaluation by the dictionary scan. Patterns shorter than this threshold match too many dictionary tokens and are skipped to avoid expensive scans. Requires use_text_index_like_evaluation_by_dictionary_scan to be enabled.

text_index_posting_list_apply_mode

Type: TextIndexPostingListApplyMode
Default: lazy
Tier: Production
Controls how posting lists are applied during text index queries. 'materialize' eagerly decodes posting lists into Roaring Bitmaps. 'lazy' (default) uses cursor-based on-demand decoding (requires an index format with a serialized codec). 'lazy' is applied only where it is supported: queries with patterns (such as LIKE) and parts with an index written by an older version fall back to 'materialize'.

throw_if_no_data_to_insert

Type: Bool
Default: 1
Tier: Production
Allows or forbids empty INSERTs, enabled by default (throws an error on an empty insert). Only applies to INSERTs using rawtree-client or using the gRPC interface.

throw_on_error_from_cache_on_write_operations

Type: Bool
Default: 0
Tier: Production
Ignore error from cache when caching on write operations (INSERT, merges)

throw_on_hive_partitioning_resolution_failure

Type: Bool
Default: 1
Tier: Production
Throw an exception instead of logging a warning when Hive-style partitioning detection for an object storage table fails to list the storage. When disabled, the query runs without the Hive partition columns, which may change its result.

throw_on_max_partitions_per_insert_block

Type: Bool
Default: 1
Tier: Production
Allows you to control the behaviour when max_partitions_per_insert_block is reached. Possible values: - true - When an insert block reaches max_partitions_per_insert_block, an exception is raised. - false - Logs a warning when max_partitions_per_insert_block is reached. :::tip This can be useful if you're trying to understand the impact on users when changing max_partitions_per_insert_block. :::

throw_on_unsupported_query_inside_transaction

Type: Bool
Default: 1
Tier: Experimental
Throw exception if unsupported query is used inside transaction

time_series_prefer_recent_samples_table

Type: Bool
Default: 1
Tier: Experimental
Read from the recent samples table of a TimeSeries table instead of the main samples table when the whole requested time range fits in the TTL window of the recent samples table (see the recent_samples_ttl_seconds setting of the TimeSeries table engine).

timeout_before_checking_execution_speed

Type: Seconds
Default: 10
Tier: Production
Checks that execution speed is not too slow (no less than min_execution_speed), after the specified time in seconds has expired.

timeout_overflow_mode

Type: OverflowMode
Default: throw
Tier: Production
Sets what to do if the query is run longer than the max_execution_time or the estimated running time is longer than max_estimated_execution_time (the estimate is only checked with throw). Possible values: - throw: throw an exception (default). - break: stop executing the query and return the partial result, as if the source data ran out. Some operations cannot return a partial result safely, so instead of a smaller result they stop without producing one. A function computing a single value stops without producing that value; whether the stop also reaches the client as a TIMEOUT_EXCEEDED error, or only as a missing result, depends on where the query was interrupted. A Memory-table mutation left incomplete by the timeout keeps the table unchanged and reports TIMEOUT_EXCEEDED. An INSERT may report QUERY_WAS_CANCELLED. Some operations that wait for other replicas or for background work do not stop at max_execution_time at all: a quorum write keeps waiting until its quorum is satisfied, or reports UNKNOWN_STATUS_OF_INSERT if insert_quorum_timeout elapses first.

timeout_overflow_mode_leaf

Type: OverflowMode
Default: throw
Tier: Production
Sets what happens when the query in leaf node run longer than max_execution_time_leaf. Possible values: - throw: throw an exception (default). - break: stop executing the query and return the partial result, as if the source data ran out. Some operations cannot return a partial result safely, so instead of a smaller result they stop without producing one: a function computing a single value stops without producing that value. Whether such a stop also reaches the client as a TIMEOUT_EXCEEDED error, or only as a missing result, depends on where the query was interrupted.

totals_auto_threshold

Type: Float
Default: 0.5
Tier: Production
The threshold for totals_mode = 'auto'. See the section "WITH TOTALS modifier".

totals_mode

Type: TotalsMode
Default: after_having_exclusive
Tier: Production
How to calculate TOTALS when HAVING is present, as well as when max_rows_to_group_by and group_by_overflow_mode = 'any' are present. See the section "WITH TOTALS modifier".

trace_profile_events

Type: Bool
Default: 0
Tier: Production
Enables or disables collecting stacktraces on each update of profile events along with the name of profile event and the value of increment and sending them into trace_log. Possible values: - 1 — Tracing of profile events enabled. - 0 — Tracing of profile events disabled.

trace_profile_events_list

Type: String
Default: ``
Tier: Production
When the setting trace_profile_events is enabled, limit the traced events to the specified list of comma-separated names. If the trace_profile_events_list is an empty string (by default), trace all profile events. Example value: 'DiskS3ReadMicroseconds,DiskS3ReadRequestsCount,SelectQueryTimeMicroseconds,ReadBufferFromS3Bytes' Using this setting allows more precise collection of data for a large number of queries, because otherwise the vast amount of events can overflow the internal system log queue and some portion of them will be dropped.

transfer_overflow_mode

Type: OverflowMode
Default: throw
Tier: Production
Sets what happens when the amount of data exceeds one of the limits. Possible values: - throw: throw an exception (default). - break: stop executing the query and return the partial result, as if the source data ran out.

transform_null_in

Type: Bool
Default: 0
Tier: Production
Enables equality of NULL values for IN operator. By default, NULL values can't be compared because NULL means undefined value. Thus, comparison expr = NULL must always return false. With this setting NULL = NULL returns true for IN operator. Possible values: - 0 — Comparison of NULL values in IN operator returns false. - 1 — Comparison of NULL values in IN operator returns true. Example Consider the null_in table: text ┌──idx─┬─────i─┐ │ 1 │ 1 │ │ 2 │ NULL │ │ 3 │ 3 │ └──────┴───────┘ Query: sql SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 0; Result: text ┌──idx─┬────i─┐ │ 1 │ 1 │ └──────┴──────┘ Query: sql SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 1; Result: text ┌──idx─┬─────i─┐ │ 1 │ 1 │ │ 2 │ NULL │ └──────┴───────┘ See Also - NULL Processing in IN Operators

traverse_shadow_remote_data_paths

Type: Bool
Default: 0
Tier: Production
Traverse frozen data (shadow directory) in addition to actual table data when query system.remote_data_paths

type_json_allow_duplicated_key_with_literal_and_nested_object

Type: Bool
Default: 1
Tier: Production
When enabled, JSONs like {"a" : 42, "a" : {"b" : 42}} where some key is duplicated but one of them is a nested object are allowed to be parsed.

type_json_skip_duplicated_paths

Type: Bool
Default: 0
Tier: Production
When enabled, during parsing JSON object into JSON type duplicated paths will be ignored and only the first one will be inserted instead of an exception

type_json_skip_invalid_typed_paths

Type: Bool
Default: 0
Tier: Production
When enabled, fields with values that cannot be coerced to their declared type in JSON type columns with typed paths are skipped instead of throwing an error. Skipped fields are treated as missing and will use default/null values based on the typed path definition. This setting only applies to JSON type columns (e.g., JSON(a Int64, b String)) where specific paths have declared types. It does not apply to regular JSON input formats like JSONEachRow when inserting into regular typed columns. Possible values: + 0 — Disable (throw error on type mismatch). + 1 — Enable (skip field on type mismatch).

type_json_use_partial_match_to_skip_paths_by_regexp

Type: Bool
Default: 1
Tier: Production
When enabled, during parsing JSON object into JSON type regular expressions specified using SKIP REGEXP will require partial match to skip a path. When disabled, full match will be required.

union_default_mode

Type: SetOperationMode
Default: ``
Tier: Production
Sets a mode for combining SELECT query results. The setting is only used when shared with UNION without explicitly specifying the UNION ALL or UNION DISTINCT. Possible values: - 'DISTINCT' — RawTree outputs rows as a result of combining queries removing duplicate rows. - 'ALL' — RawTree outputs all rows as a result of combining queries including duplicate rows. - '' — RawTree generates an exception when used with UNION. See examples in UNION.

unique_key_max_encoded_size

Type: UInt64
Default: 256
Tier: Experimental
Maximum size (in bytes) of the order-preserving binary encoding of a single UNIQUE KEY row.

unique_key_probe_implementation

Type: UniqueKeyProbeImplementation
Default: auto
Tier: Experimental
Selects the UNIQUE KEY write-path probe implementation. Currently only a single-threaded baseline exists, so auto and simple both resolve to it. Reserved: this setting has no effect yet — the value is not read until the UNIQUE KEY INSERT write path that constructs the probe is wired up. Declared now so the lever ships with the implementation.

unknown_packet_in_send_data

Type: UInt64
Default: 0
Tier: Production
Send unknown packet instead of data Nth data packet

update_parallel_mode

Type: UpdateParallelMode
Default: auto
Tier: Production
Determines the behavior of concurrent update queries. Possible values: - sync - run sequentially all UPDATE queries. - auto - run sequentially only UPDATE queries with dependencies between columns updated in one query and columns used in expressions of another query. - async - do not synchronize update queries.

update_sequential_consistency

Type: Bool
Default: 1
Tier: Production
If true set of parts is updated to the latest version before execution of update.

url_base

Type: String
Default: ``
Tier: Production
The base URL used to resolve relative URLs in the url table function and the URL table engine. When set, relative URLs are resolved as follows: - Path-relative URL (e.g. data.csv): merged with the base URL path per RFC 3986. Everything after the last / in the base path is replaced by the relative URL, so a trailing slash matters: https://example.com/dir/ + data.csv = https://example.com/dir/data.csv, but https://example.com/dir + data.csv = https://example.com/data.csv. If the base has no path (e.g. https://example.com), a / is inserted: https://example.com/data.csv. Dot segments (./ and ../) in the relative URL are normalized: https://example.com/dir/ + ../a.csv = https://example.com/a.csv. - Host-relative URL (e.g. /test/data.csv): resolved against the base URL's scheme and host. - Scheme-relative URL (e.g. //other.com/test/data.csv): resolved using the base URL's scheme. - Query-only reference (e.g. ?x=1): appended to the base URL path (replacing any existing query/fragment). - Fragment-only reference (e.g. #frag): appended to the base URL, preserving any query string (replacing any existing fragment). - Empty reference: returns the base URL without fragment. - If the base URL is only a scheme (e.g. file://), a path-relative URL is appended to it directly: file:// + data.csv = file://data.csv, which for the file:// scheme means a path relative to the user_files directory (the current directory for rawtree-local). Dot segments are kept as-is in this case, so the target engine resolves them against its own base directory. For example, if url_base is https://example.com/def/, then: - data.csv resolves to https://example.com/def/data.csv - /test/data.csv resolves to https://example.com/test/data.csv - //other.com/test/data.csv resolves to https://other.com/test/data.csv When the relative URL comes from a named collection, resolving it counts as an override of the url key of the collection and requires the SHOW NAMED COLLECTIONS SECRETS privilege on that collection.

url_wildcard_max_directories_to_read

Type: UInt64
Default: 100000
Tier: Production
Maximum number of directories that can be traversed while expanding URL wildcards from index pages.

use_aggregation_memory_tracker

Type: Bool
Default: 0
Tier: Production
Measure the size of the aggregation state compared with group_by_two_level_threshold_bytes with the memory tracker dedicated to the aggregation. When disabled, the size is measured as the growth of the memory usage of the whole query since the aggregation was created, so an aggregation with a small state can be converted to two-level.

use_async_executor_for_materialized_views

Type: Bool
Default: 0
Tier: Production
Use async and potentially multithreaded execution of materialized view query, can speedup views processing during INSERT, but also consume more memory.

use_cache_for_count_from_files

Type: Bool
Default: 1
Tier: Production
Enables caching of rows number during count from files in table functions file/s3/url/hdfs/azureBlobStorage. Enabled by default.

use_client_time_zone

Type: Bool
Default: 0
Tier: Production
Use client timezone for interpreting DateTime string values, instead of adopting server timezone.

use_compact_format_in_distributed_parts_names

Type: Bool
Default: 1
Tier: Production
Uses compact format for storing blocks for background (distributed_foreground_insert) INSERT into tables with Distributed engine. Possible values: - 0 — Uses user[:password]@host:port#default_database directory format. - 1 — Uses [shard{shard_index}[_replica{replica_index}]] directory format. :::note - with use_compact_format_in_distributed_parts_names=0 changes from cluster definition will not be applied for background INSERT. - with use_compact_format_in_distributed_parts_names=1 changing the order of the nodes in the cluster definition, will change the shard_index/replica_index so be aware. :::

use_concurrency_control

Type: Bool
Default: 1
Tier: Production
Respect the server's concurrency control (see the concurrent_threads_soft_limit_num and concurrent_threads_soft_limit_ratio_to_cores global server settings). If disabled, it allows using a larger number of threads even if the server is overloaded (not recommended for normal usage, and needed mostly for tests).

use_constant_folding_in_index_analysis

Type: Bool
Default: 0
Tier: Production
Substitute partition-level constants into the filter predicate when analyzing per-part primary key and skip indexes. When the partition key appears in the filter together with primary-key or skip-index columns, this lets index analysis fold the partition value separately within each part. It is most useful for disjunctive filters whose branches target different partitions. For example, with PARTITION BY a and ORDER BY b: sql SELECT * FROM t WHERE (a = 1 AND b >= 1) OR (a = 2 AND b > 10) OR (a = 3 AND b > 10) For the part in partition a = 1 the condition folds to b >= 1, while for partitions a = 2 and a = 3 it folds to b > 10, so each part is analyzed with the predicate that actually applies to it. Possible values: - 0 — Disabled. - 1 — Enabled.

use_dynamic_aggregation_for_dynamic_columns

Type: Bool
Default: 1
Tier: Production
Enables or disables the type-scatter aggregation of GROUP BY with Dynamic keys: the rows are split by the types of their Dynamic keys and every type is aggregated with concrete keys. It is several times faster than the ordinary aggregation, which hashes serialized Dynamic values. The result is the same: two Dynamic values are the same key only if they have the same type and value, and all NULL values are one key.

use_dynamic_distinct_for_dynamic_columns

Type: Bool
Default: 1
Tier: Production
Enables or disables the type-scatter DISTINCT of Dynamic columns: the rows are split by the types of their Dynamic columns and every type is deduplicated with concrete keys. It is several times faster than the ordinary DISTINCT, which hashes serialized Dynamic values. The result is the same: two Dynamic values are distinct unless they have the same type and value, and all NULL values are one value.

use_hash_table_stats_for_join_reordering

Type: Bool
Default: 1
Tier: Production
Enable using collected hash table statistics for cardinality estimation during join reordering

use_hedged_requests

Type: Bool
Default: 1
Tier: Production
Enables hedged requests logic for remote queries. It allows to establish many connections with different replicas for query. New connection is enabled in case existent connection(s) with replica(s) were not established within hedged_connection_timeout or no data was received within receive_data_timeout. Query uses the first connection which send non empty progress packet (or data packet, if allow_changing_replica_until_first_data_packet); other connections are cancelled. Queries with max_parallel_replicas > 1 are supported. Enabled by default. Cloud default value: 0.

use_hive_partitioning

Type: Bool
Default: 1
Tier: Production
When enabled, RawTree will detect Hive-style partitioning in path (/name=value/) in file-like table engines File/S3/URL/HDFS/AzureBlobStorage and will allow to use partition columns as virtual columns in the query. These virtual columns will have the same names as in the partitioned path, but starting with _.

use_iceberg_metadata_files_cache

Type: Bool
Default: 1
Tier: Production
If turned on, iceberg table function and iceberg storage may utilize the iceberg metadata files cache. Possible values: - 0 - Disabled - 1 - Enabled

use_iceberg_partition_pruning

Type: Bool
Default: 1
Tier: Production
Use Iceberg partition pruning for Iceberg tables

use_index_for_in_with_subqueries

Type: Bool
Default: 1
Tier: Production
Try using an index if there is a subquery or a table expression on the right side of the IN operator.

use_index_for_in_with_subqueries_max_values

Type: UInt64
Default: 0
Tier: Production
The maximum size of the set in the right-hand side of the IN operator to use table index for filtering. It allows to avoid performance degradation and higher memory usage due to the preparation of additional data structures for large queries. Zero means no limit.

use_indexes_refiner_in_read_pools

Type: Bool
Default: 0
Tier: Production
Apply indexes evaluated at data-read time already inside MergeTree read pools: mark ranges fully filtered out by skip indexes (see use_skip_indexes_on_data_read) or by the projection index (see optimize_use_projection_filtering) are dropped before a read task is created for them, instead of being skipped granule by granule during reading. In the prefetched read pool the dropped ranges are never prefetched, but the task boundaries and the prefetch admission by filesystem_prefetch_max_memory_usage / filesystem_prefetches_limit are still decided before the filtering, so under highly selective filters the surviving tasks may be smaller than the intended task size and the admission may be conservative.

use_join_disjunctions_push_down

Type: Bool
Default: 1
Tier: Production
Enable pushing OR-connected parts of JOIN conditions down to the corresponding input sides ("partial pushdown"). This allows storage engines to filter earlier, which can reduce data read. The optimization is semantics-preserving and is applied only when each top-level OR branch contributes at least one deterministic predicate for the target side.

use_legacy_to_time

Type: Bool
Default: 0
Tier: Production
When enabled, the name toTime refers to the legacy toTime function, which converts a date with time to a certain fixed date, while preserving the time. Otherwise, the name refers to the new toTime function, which converts values of different types into the Time type. The legacy function is also unconditionally accessible as toTimeWithFixedDate, regardless of this setting. While this setting is enabled, use CAST(x AS Time) or x::Time to convert to the Time type.

use_lightweight_primary_key_index_analysis

Type: Bool
Default: 1
Tier: Production
Optimize primary key index analysis for MergeTree tables with long primary keys. When enabled, the run time of index analysis mainly depends on the complexity of the query's filter (the key columns it actually uses), not on the length of the primary key — so extending the sorting key has negligible extra overhead on index analysis for queries that filter on only a few of its columns. Possible values: - 0 — Disabled. All primary key columns are processed during index analysis. - 1 — Enabled.

use_page_cache_for_disks_without_file_cache

Type: Bool
Default: 0
Tier: Production
Use userspace page cache for remote disks that don't have filesystem cache enabled.

use_page_cache_for_local_disks

Type: Bool
Default: 0
Tier: Production
Use userspace page cache when reading from local disks. Used for testing, unlikely to improve performance in practice. Requires local_filesystem_read_method = 'pread' or 'read'. Doesn't disable the OS page cache; min_bytes_to_use_direct_io can be used for that. Only affects regular tables, not file() table function or File() table engine.

use_page_cache_for_object_storage

Type: Bool
Default: 0
Tier: Production
Use userspace page cache when reading from object storage table functions (s3, azure, hdfs) and table engines (S3, Azure, HDFS).

use_page_cache_with_distributed_cache

Type: Bool
Default: 0
Tier: Production
Use userspace page cache when distributed cache is used.

use_paimon_metadata_files_cache

Type: Bool
Default: 0
Tier: Production
If turned on, paimon table function and paimon storage may utilize the paimon metadata files cache. Paimon table functions evaluate this setting per query, while persistent Paimon table engines latch it at metadata initialization: to change the decision for an already-created table, it must be dropped and recreated. Possible values: - 0 - Disabled - 1 - Enabled

use_paimon_partition_pruning

Type: Bool
Default: 0
Tier: Experimental
Use Paimon partition pruning for Paimon table functions

use_parquet_metadata_cache

Type: Bool
Default: 1
Tier: Production
If turned on, parquet format may utilize the parquet metadata cache. Possible values: - 0 - Disabled - 1 - Enabled

use_partition_key

Type: Bool
Default: 1
Tier: Production
Use partition key to prune partitions during query execution for MergeTree tables. Possible values: - 0 — Disabled. - 1 — Enabled.

use_partition_minmax_for_primary_key_pruning

Type: Bool
Default: 1
Tier: Production
Use partition minmax index bounds to prune more granules during primary key analysis for MergeTree tables, when a primary key column is also an input column of the partition key. For example, in a MergeTree table with ORDER BY (id, event_time) and PARTITION BY toYYYYMM(event_time), ClickHouse will use the partition minmax index on event_time during primary key index analysis to make more informed granule-pruning decisions. Possible values: - 0 — Disabled. - 1 — Enabled.

use_partition_pruning

Type: Bool
Default: 1
Tier: Production
Use partition key to prune partitions during query execution for MergeTree tables. Possible values: - 0 — Disabled. - 1 — Enabled.

use_primary_key

Type: Bool
Default: 1
Tier: Production
Use the primary key to prune granules during query execution for MergeTree tables. Possible values: - 0 — Disabled. - 1 — Enabled.

use_query_cache

Type: Bool
Default: 0
Tier: Production
If turned on, SELECT queries may utilize the query cache. Parameters enable_reads_from_query_cache and enable_writes_to_query_cache control in more detail how the cache is used. Possible values: - 0 - Disabled - 1 - Enabled

use_query_condition_cache

Type: Bool
Default: 1
Tier: Production
Enable the query condition cache. The cache stores ranges of granules in data parts which do not satisfy the condition in the WHERE clause, and reuse this information as an ephemeral index for subsequent queries. Possible values: - 0 - Disabled - 1 - Enabled

use_query_condition_cache_for_top_k

Type: Bool
Default: 1
Tier: Production
Enable the query condition cache for queries that use the ORDER BY <column> LIMIT n (TopK) optimization (dynamic filtering or skip-index based). When disabled, such reads neither consult nor populate the cache. Such queries can drop granules during execution depending on the running threshold, so their cache entries are partitioned by the TopK plan parameters and by the set of parts read. This setting has no effect unless use_query_condition_cache is also enabled. Possible values: - 0 - Disabled - 1 - Enabled

use_reader_executor

Type: Bool
Default: 0
Tier: Experimental
Experimental. Route reads through the new pipeline ReaderExecutor instead of the legacy matryoshka of read buffers. Falls back to the legacy path for configurations the executor does not yet support.

use_roaring_bitmap_iceberg_positional_deletes

Type: Bool
Default: 0
Tier: Production
Use roaring bitmap for iceberg positional deletes.

use_runtime_projections

Type: Bool
Default: 1
Tier: Production
If turned on, GROUP BY queries over MergeTree tables may use runtime projections: the partial aggregation states of big parts are kept in memory and reused by later queries.

use_skip_indexes

Type: Bool
Default: 1
Tier: Production
Use data skipping indexes during query execution. Possible values: - 0 — Disabled. - 1 — Enabled.

use_skip_indexes_for_disjunctions

Type: Bool
Default: 1
Tier: Production
Evaluate WHERE filters with mixed AND and OR conditions using skip indexes. Example: WHERE A = 5 AND (B = 5 OR C = 5). If disabled, skip indexes are still used to evaluate WHERE conditions but they must only contain AND-ed clauses. Possible values: - 0 — Disabled. - 1 — Enabled.

use_skip_indexes_for_top_k

Type: Bool
Default: 1
Tier: Production
Enable using data skipping indexes for TopK filtering. When enabled, if a minmax skip index exists on the column in ORDER BY <column> LIMIT n query, optimizer will attempt to use the minmax index to skip granules that are not relevant for the final result . This can reduce query latency. Possible values: - 0 — Disabled. - 1 — Enabled.

use_skip_indexes_if_final

Type: Bool
Default: 1
Tier: Production
Controls whether skipping indexes are used when executing a query with the FINAL modifier. Skip indexes may exclude rows (granules) containing the latest data, which could lead to incorrect results from a query with the FINAL modifier. When this setting is enabled, skipping indexes are applied even with the FINAL modifier, potentially improving performance but with the risk of missing recent updates. This setting should be enabled in sync with the setting use_skip_indexes_if_final_exact_mode (default is enabled). Possible values: - 0 — Disabled. - 1 — Enabled.

use_skip_indexes_if_final_exact_mode

Type: Bool
Default: 1
Tier: Production
Controls whether granules returned by a skipping index are expanded in newer parts to return correct results when executing a query with the FINAL modifier. Using skip indexes may exclude rows (granules) containing the latest data which could lead to incorrect results. This setting can ensure that correct results are returned by scanning newer parts that have overlap with the ranges returned by the skip index. This setting should be disabled only if approximate results based on looking up the skip index are okay for an application. Possible values: - 0 — Disabled. - 1 — Enabled.

use_skip_indexes_on_data_read

Type: Bool
Default: 1
Tier: Production
Enable using data skipping indexes during data reading. When enabled, skip indexes are evaluated dynamically at the time each data granule is being read, rather than being analyzed in advance before query execution begins. This can reduce query startup latency. Possible values: - 0 — Disabled. - 1 — Enabled.

use_statistics

Type: Bool
Default: 1
Tier: Production
/// preferred over 'allow_statistics_optimize' because of consistency with 'use_primary_key' and 'use_skip_indexes' Allows using statistics to optimize queries

use_statistics_cache

Type: Bool
Default: 1
Tier: Production
Use statistics cache in a query to avoid the overhead of loading statistics of every parts

use_statistics_for_part_pruning

Type: Bool
Default: 1
Tier: Production
Use statistics to filter out parts during query execution. When enabled, pruning in SELECT queries will use column statistics (e.g. MinMax statistics) to eliminate parts that cannot contain matching data before reading any data. Possible values: - 0 — Disabled. - 1 — Enabled.

use_streaming_marks_compression

Type: Bool
Default: 0
Tier: Production
When loading marks for MergeTree parts, compress them into the in-memory representation one block at a time (streaming) instead of materializing the full plain marks array first. This significantly reduces peak memory usage during marks loading for compact parts with many substreams (e.g. tables with JSON columns and write_marks_for_substreams_in_compact_parts enabled).

use_strict_insert_block_limits

Type: Bool
Default: 0
Tier: Production
When enabled, strictly enforces both minimum and maximum insert block size limits. A block is emitted when: - Min thresholds (AND): Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached. - Max thresholds (OR): Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached. When disabled, a block is emitted when: - Min thresholds (OR): min_insert_block_size_rows OR min_insert_block_size_bytes is reached. Note: If max settings are smaller than min settings, the max limits take precedence and blocks will be emitted before min thresholds are reached. Note: This setting is automatically disabled for async inserts, because async inserts attach per-entry deduplication tokens that are incompatible with block splitting that is needed for enforcement of strict limits. Disabled by default.

use_structure_from_insertion_table_in_table_functions

Type: UInt64
Default: 2
Tier: Production
Use structure from insertion table instead of schema inference from data. Possible values: 0 - disabled, 1 - enabled, 2 - auto

use_text_index_header_cache

Type: Bool
Default: 1
Tier: Production
Whether to cache deserialized text index headers in memory. Using the text index header cache can significantly reduce latency and increase throughput when working with a large number of text index queries.

use_text_index_like_evaluation_by_dictionary_scan

Type: Bool
Default: 1
Tier: Production
Enable evaluation of LIKE/ILIKE queries by scanning the inverted text index dictionary. The accelerated patterns are %value%, value% and %value, as well as the startsWith and endsWith calls that optimize_rewrite_like_perfect_affix rewrites into value% and %value.

use_text_index_negative_tokens_cache

Type: Bool
Default: 1
Tier: Production
Whether to cache text index tokens that are absent from a data part. The negative tokens cache uses the text index tokens cache and avoids repeated dictionary lookups for absent tokens.

use_text_index_postings_cache

Type: Bool
Default: 0
Tier: Production
Whether to cache deserialized text index deserialized posting lists in memory. Using the text index postings cache can significantly reduce latency and increase throughput when working with a large number of text index queries.

use_text_index_tokens_cache

Type: Bool
Default: 1
Tier: Production
Whether to cache deserialized text index token infos in memory. Using the text index tokens cache can significantly reduce latency and increase throughput when working with a large number of text index queries.

use_top_k_dynamic_filtering

Type: Bool
Default: 1
Tier: Production
Enable dynamic filtering optimization when executing a ORDER BY <column> LIMIT n query. When enabled, the query executor will try to skip granules and rows that will not be part of the final top N rows in the resultset. This optimization is dynamic in nature and latency improvements depends on data distribution and presence of other predicates in the query. Possible values: - 0 — Disabled. - 1 — Enabled.

use_top_k_dynamic_filtering_for_variable_length_types

Type: Bool
Default: 0
Tier: Production
Allow use_top_k_dynamic_filtering to apply when the sort column has a variable-length data type (e.g. String, Array, Map, Tuple containing variable-length elements). For such types, the per-row threshold comparison performed by the dynamic filter can outweigh its savings when the column's lexicographic minimum dominates (e.g. mostly empty strings) and few granules can be skipped. In that case the dynamic filter degrades query latency rather than improving it. When this setting is 0, dynamic filtering is restricted to columns whose values have a fixed maximum size in memory (numbers, Date, DateTime, FixedString, Enum, Nullable of such types, Tuple of such types). When set to 1, dynamic filtering applies to variable-length types as well. Possible values: - 0 — Disabled. - 1 — Enabled.

use_uncompressed_cache

Type: Bool
Default: 0
Tier: Production
Whether to use a cache of uncompressed blocks. Accepts 0 or 1. By default, 0 (disabled). Using the uncompressed cache (only for tables in the MergeTree family) can significantly reduce latency and increase throughput when working with a large number of short queries. Enable this setting for users who send frequent short requests. Also pay attention to the uncompressed_cache_size configuration parameter (only set in the config file) – the size of uncompressed cache blocks. By default, it is 8 GiB. The uncompressed cache is filled in as needed and the least-used data is automatically deleted. For queries that read at least a somewhat large volume of data (one million rows or more), the uncompressed cache is disabled automatically to save space for truly small queries. This means that you can keep the 'use_uncompressed_cache' setting always set to 1.

use_variant_as_common_type

Type: Bool
Default: 1
Tier: Production
Allows to use Variant type as a result type for if/multiIf/array/map functions when there is no common type for argument types. Example: sql SET use_variant_as_common_type = 1; SELECT toTypeName(if(number % 2, number, range(number))) as variant_type FROM numbers(1); SELECT if(number % 2, number, range(number)) as variant FROM numbers(5); text ┌─variant_type───────────────────┐ │ Variant(Array(UInt64), UInt64) │ └────────────────────────────────┘ ┌─variant───┐ │ [] │ │ 1 │ │ [0,1] │ │ 3 │ │ [0,1,2,3] │ └───────────┘ sql SET use_variant_as_common_type = 1; SELECT toTypeName(multiIf((number % 4) = 0, 42, (number % 4) = 1, [1, 2, 3], (number % 4) = 2, 'Hello, World!', NULL)) AS variant_type FROM numbers(1); SELECT multiIf((number % 4) = 0, 42, (number % 4) = 1, [1, 2, 3], (number % 4) = 2, 'Hello, World!', NULL) AS variant FROM numbers(4); text ─variant_type─────────────────────────┐ │ Variant(Array(UInt8), String, UInt8) │ └──────────────────────────────────────┘ ┌─variant───────┐ │ 42 │ │ [1,2,3] │ │ Hello, World! │ │ ᴺᵁᴸᴸ │ └───────────────┘ sql SET use_variant_as_common_type = 1; SELECT toTypeName(array(range(number), number, 'str_' || toString(number))) as array_of_variants_type from numbers(1); SELECT array(range(number), number, 'str_' || toString(number)) as array_of_variants FROM numbers(3); text ┌─array_of_variants_type────────────────────────┐ │ Array(Variant(Array(UInt64), String, UInt64)) │ └───────────────────────────────────────────────┘ ┌─array_of_variants─┐ │ [[],0,'str_0'] │ │ [[0],1,'str_1'] │ │ [[0,1],2,'str_2'] │ └───────────────────┘ sql SET use_variant_as_common_type = 1; SELECT toTypeName(map('a', range(number), 'b', number, 'c', 'str_' || toString(number))) as map_of_variants_type from numbers(1); SELECT map('a', range(number), 'b', number, 'c', 'str_' || toString(number)) as map_of_variants FROM numbers(3); text ┌─map_of_variants_type────────────────────────────────┐ │ Map(String, Variant(Array(UInt64), String, UInt64)) │ └─────────────────────────────────────────────────────┘ ┌─map_of_variants───────────────┐ │ {'a':[],'b':0,'c':'str_0'} │ │ {'a':[0],'b':1,'c':'str_1'} │ │ {'a':[0,1],'b':2,'c':'str_2'} │ └───────────────────────────────┘

use_variant_default_implementation_for_comparisons

Type: Bool
Default: 1
Tier: Production
Enables or disables default implementation for Variant type in comparison functions.

use_with_fill_by_sorting_prefix

Type: Bool
Default: 1
Tier: Production
Columns preceding WITH FILL columns in ORDER BY clause form sorting prefix. Rows with different values in sorting prefix are filled independently

validate_enum_literals_in_operators

Type: Bool
Default: 0
Tier: Production
If enabled, validate enum literals in operators like IN, NOT IN, ==, != against the enum type and throw an exception if the literal is not a valid enum value.

validate_experimental_and_suspicious_types_inside_nested_types

Type: Bool
Default: 1
Tier: Production
Validate usage of experimental and suspicious types inside nested types like Array/Map/Tuple

validate_group_by_all_key_types

Type: Bool
Default: 1
Tier: Production
Controls whether the grouping keys that GROUP BY ALL expands the SELECT expressions into are checked against allow_suspicious_types_in_group_by. Disable it to restore the behavior of versions before 26.7, which accepted a Variant or Dynamic key written as GROUP BY ALL, for example a grouping key that is an untyped JSON subpath. Takes effect only when the analyzer is enabled (enable_analyzer = 1, the default); with the old analyzer such a key was rejected before 26.7 as well, so there is nothing to restore there. An explicit GROUP BY is unaffected and keeps rejecting such a key either way, so this is narrower than setting allow_suspicious_types_in_group_by, which also permits them in an explicit GROUP BY. Possible values: - 0 - The key types GROUP BY ALL expands into are not validated. - 1 - They are validated, as an explicit GROUP BY validates its own keys.

validate_mutation_query

Type: Bool
Default: 1
Tier: Production
Validate mutation queries before accepting them. Mutations are executed in the background, and running an invalid query will cause mutations to get stuck, requiring manual intervention. Only change this setting if you encounter a backward-incompatible bug.

validate_polygons

Type: Bool
Default: 1
Tier: Production
Enables or disables throwing an exception in the pointInPolygon function, if the polygon is self-intersecting or self-tangent. Possible values: - 0 — Throwing an exception is disabled. pointInPolygon accepts invalid polygons and returns possibly incorrect results for them. - 1 — Throwing an exception is enabled.

variant_throw_on_type_mismatch

Type: Bool
Default: 0
Tier: Production
When applying a function to a Variant column using the default implementation, controls what happens for rows whose actual type is incompatible with the function: - true — throw an exception. - false (default) — return NULL for those rows instead.

vector_search_filter_strategy

Type: VectorSearchFilterStrategy
Default: auto
Tier: Production
If a vector search query has a WHERE clause, this setting determines if it is evaluated first (pre-filtering) OR if the vector similarity index is checked first (post-filtering). Possible values: - 'auto' - Postfiltering (the exact semantics may change in future). - 'postfilter' - Use vector similarity index to identify the nearest neighbours, then apply other filters - 'prefilter' - Evaluate other filters first, then perform brute-force search to identify neighbours.

vector_search_index_fetch_multiplier

Type: Float
Default: 1
Tier: Production
Multiply the number of fetched nearest neighbors from the vector similarity index by this number. Only applied for post-filtering with other predicates or if setting 'vector_search_with_rescoring = 1'. Valid range: [1.0, 1000.0]. Values outside this range are rejected.

vector_search_postfilter_multiplier

Type: Float
Default: 1
Tier: Production
Multiply the number of fetched nearest neighbors from the vector similarity index by this number. Only applied for post-filtering with other predicates or if setting 'vector_search_with_rescoring = 1'. Valid range: [1.0, 1000.0]. Values outside this range are rejected.

vector_search_use_quantized_codes

Type: Bool
Default: 0
Tier: Production
Enables a two-stage approximate vector search without index (brute force scan) over a Quantized-compressed column. When enabled, ORDER BY L2Distance|cosineDistance(vec, reference) LIMIT k against a column encoded with a Quantized(...) codec will 1. scan and filter the quantized vectors (this step produces k * vector_search_index_fetch_multiplier results), and 2. rescore the found vectors against original, full-precision vectors.

vector_search_with_rescoring

Type: Bool
Default: 0
Tier: Production
If RawTree performs rescoring for queries that use the vector similarity index. Without rescoring, the vector similarity index returns the rows containing the best matches directly. With rescoring, the vector similarity index fetches candidate rows and ClickHouse computes the exact distance for these rows from the original full-precision vectors in the regular SQL pipeline. When possible, ClickHouse filters the scan to candidate rows before the final distance computation. Increase vector_search_index_fetch_multiplier if more candidate rows are needed for better recall, especially with additional filters or quantized vector indexes. Note: A query run without rescoring and with parallel replicas enabled may fall back to rescoring.

wait_changes_become_visible_after_commit_mode

Type: TransactionsWaitCSNMode
Default: wait_unknown
Tier: Experimental
Wait for committed changes to become actually visible in the latest snapshot

wait_for_async_insert

Type: Bool
Default: 1
Tier: Production
If true wait for processing of asynchronous insertion

wait_for_async_insert_timeout

Type: Seconds
Default: 120
Tier: Production
Timeout for waiting for processing asynchronous insertion

wait_for_part_commit_in_dependent_materialized_views

Type: Bool
Default: 0
Tier: Production
Controls whether each sink commits its just-written part before its own dependent materialized view cascade runs, so a cascade that reads back from the source via JOIN observes the part written by that sink. The guarantee is per sink instance — parts written by other sink threads of the same INSERT may not yet be visible. The setting does not provide cross-thread commit ordering. Has no effect on inserts into tables with no dependent materialized views.

wait_for_window_view_fire_signal_timeout

Type: Seconds
Default: 10
Tier: Experimental
Timeout for waiting for window view fire signal in event time processing

webassembly_udf_max_fuel

Type: UInt64
Default: 100000
Tier: Experimental
Fuel limit per WebAssembly UDF instance execution. Each WebAssembly instruction consumes some amount of fuel. The value is scaled by 1024 before being passed to the runtime, so webassembly_udf_max_fuel = 1 corresponds to approximately 1024 fuel units. Set to 0 for no finite limit. Applies only to functions whose per-function setting webassembly_udf_enable_fuel is true, which is the default.

webassembly_udf_max_input_block_size

Type: UInt64
Default: 0
Tier: Experimental
Maximum number of rows passed to a WebAssembly UDF in a single block. Set to 0 to process all rows at once.

webassembly_udf_max_instances

Type: UInt64
Default: 32
Tier: Experimental
Maximum number of WebAssembly UDF instances that can run in parallel per function.

webassembly_udf_max_memory

Type: UInt64
Default: 134217728
Tier: Experimental
Memory limit in bytes per WebAssembly UDF instance.

window_view_clean_interval

Type: Seconds
Default: 60
Tier: Experimental
The clean interval of window view in seconds to free outdated data.

window_view_heartbeat_interval

Type: Seconds
Default: 15
Tier: Experimental
The heartbeat interval in seconds to indicate watch query is alive.

workload

Type: String
Default: default
Tier: Production
Name of workload to be used to access resources

write_full_path_in_iceberg_metadata

Type: Bool
Default: 0
Tier: Experimental
Write full paths (including s3://) into iceberg metadata files.

write_through_distributed_cache_buffer_size

Type: UInt64
Default: 0
Tier: Production
Only has an effect in RawTree Cloud. Set buffer size for write-through distributed cache. If 0, will use buffer size which would have been used if there was not distributed cache.

zstd_window_log_max

Type: Int64
Default: 0
Tier: Production
Allows you to select the max window log of ZSTD (it will not be used for MergeTree family)