enable_* session settings

ClickHouse session settings in the enable_* generated group.

These settings are available in system.settings and are autogenerated from source.

enable_adaptive_aggregator

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

Trigger processor to spill data into external storage adpatively. grace join is supported at present.

enable_add_distinct_to_in_subqueries

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

Allows using the experimental ALP compression codec.

enable_automatic_decision_for_merging_across_partitions_for_final

If set, ClickHouse 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_cascades_optimizer

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

Enable query optimization where we analyze function and subqueries results and rewrite query if there are constants there

enable_extended_results_for_datetime_functions

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_full_text_index

Aliases: allow_experimental_full_text_index

If set to true, allow using the text index.

enable_function_early_short_circuit

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

Propagate WITH statements to UNION queries and all subqueries

enable_group_by_top_k_optimization

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

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

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

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

Output stack trace of a job creator when job results in exception. Disabled by default to avoid performance overhead.

enable_json_ast_dialect

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:

SET enable_json_ast_dialect = 1;
SET dialect = 'clickhouse_json';

-- Subsequent queries are parsed as JSON ASTs:
{"type":"SelectWithUnionQuery", ...}

enable_lazy_columns_replication

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_materialized_cte

Enable materialized common table expressions, it will be preferred over enable_global_with_statement

enable_memory_bound_merging_of_aggregation_results

Enable memory bound merging strategy for aggregation.

enable_multiple_prewhere_read_steps

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

Generate named tuples in function tuple() when all names are unique and can be treated as unquoted identifiers.

enable_order_by_all

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:

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:

┌─C1─┬─C2─┬─ALL─┐
│ 20 │ 20 │  10 │
│ 30 │ 10 │  20 │
│ 10 │ 20 │  30 │
└────┴────┴─────┘

enable_packed_string_keys_in_aggregation

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_parsing_to_custom_serialization

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_producing_buckets_out_of_order_in_aggregation

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

Allows using the experimental Quantized compression codec.

enable_reads_from_query_cache

If turned on, results of SELECT queries are retrieved from the query cache.

Possible values:

• 0 - Disabled
• 1 - Enabled

enable_s3_requests_logging

Enable very explicit logging of S3 requests. Makes sense for debug only.

enable_scalar_subquery_optimization

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

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

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

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:

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

Allow sharing set objects build for IN subqueries between different tasks of the same mutation. This reduces memory usage and CPU consumptio

enable_streaming_queries

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

Allows using the experimental SZ3 compression codec.

enable_time_time64_type

Aliases: allow_experimental_time_time64_type

Allows creation of Time and Time64 data types.

enable_unaligned_array_join

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

Allows to enable/disable decoding/encoding path in uri in URL engine tables.

Disabled by default.

enable_vertical_final

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

If turned on, results of SELECT queries are stored in the query cache.

Possible values:

• 0 - Disabled
• 1 - Enabled

enable_zxc_codec

Allows using the experimental ZXC compression codec.