mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-12-01 12:01:58 +00:00

Vladimir Cherkasov fff2eff9a9

Merge branch 'master' into vdimir/followup-69411

2024-10-14 10:40:42 +02:00

301 KiB

Raw Blame History

sidebar_label	sidebar_position	slug	toc_max_heading_level
Core Settings	2	/en/operations/settings/settings	2

Core Settings

All below settings are also available in table system.settings.

add_http_cors_header

Type: Bool

Default value: 0

Write add http CORS header.

additional_result_filter

Type: String

Default value:

An additional filter expression to apply to the result of SELECT query. This setting is not applied to any subquery.

Example

INSERT INTO table_1 VALUES (1, 'a'), (2, 'bb'), (3, 'ccc'), (4, 'dddd');
SElECT * FROM table_1;

┌─x─┬─y────┐
│ 1 │ a    │
│ 2 │ bb   │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

SELECT *
FROM table_1
SETTINGS additional_result_filter = 'x != 2'

┌─x─┬─y────┐
│ 1 │ a    │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

additional_table_filters

Type: Map

Default value: {}

An additional filter expression that is applied after reading from the specified table.

Example

INSERT INTO table_1 VALUES (1, 'a'), (2, 'bb'), (3, 'ccc'), (4, 'dddd');
SELECT * FROM table_1;

┌─x─┬─y────┐
│ 1 │ a    │
│ 2 │ bb   │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

SELECT *
FROM table_1
SETTINGS additional_table_filters = {'table_1': 'x != 2'}

┌─x─┬─y────┐
│ 1 │ a    │
│ 3 │ ccc  │
│ 4 │ dddd │
└───┴──────┘

aggregate_functions_null_for_empty

Type: Bool

Default value: 0

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:

SELECT SUM(-1), MAX(0) FROM system.one WHERE 0;

With aggregate_functions_null_for_empty = 0 it would produce:

┌─SUM(-1)─┬─MAX(0)─┐
│       0 │      0 │
└─────────┴────────┘

With aggregate_functions_null_for_empty = 1 the result would be:

┌─SUMOrNull(-1)─┬─MAXOrNull(0)─┐
│          NULL │         NULL │
└───────────────┴──────────────┘

Allows creation of a deprecated LIVE VIEW.

Possible values:

0 — Working with live views is disabled.
1 — Working with live views is enabled.

Possible values:

0 — the TimeSeries table engine is disabled.
1 — the TimeSeries table engine is enabled.

Possible values:

1 — Introspection functions enabled.
0 — Introspection functions disabled.

See Also

Sampling Query Profiler
System table trace_log

allow_materialized_view_with_bad_select

Type: Bool

Default value: 1

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_named_collection_override_by_default

Type: Bool

Default value: 1

Allow named collections' fields override by default.

allow_non_metadata_alters

Type: Bool

Default value: 1

Allow to execute alters which affects not only tables metadata, but also data on disk

allow_nonconst_timezone_arguments

Type: Bool

Default value: 0

Allow non-const timezone arguments in certain time-related functions like toTimeZone(), fromUnixTimestamp*(), snowflakeToDateTime*()

allow_nondeterministic_mutations

Type: Bool

Default value: 0

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

<profiles>
    <default>
        <allow_nondeterministic_mutations>1</allow_nondeterministic_mutations>

        <!-- ... -->
    </default>

    <!-- ... -->

</profiles>

allow_nondeterministic_optimize_skip_unused_shards

Type: Bool

Default value: 0

Allow nondeterministic (like rand or dictGet, since later has some caveats with updates) functions in sharding key.

Possible values:

0 — Disallowed.
1 — Allowed.

allow_prefetched_read_pool_for_local_filesystem

Type: Bool

Default value: 0

Prefer prefetched threadpool if all parts are on local filesystem

allow_prefetched_read_pool_for_remote_filesystem

Type: Bool

Default value: 1

Prefer prefetched threadpool if all parts are on remote filesystem

allow_push_predicate_when_subquery_contains_with

Type: Bool

Default value: 1

Allows push predicate when subquery contains WITH clause

allow_settings_after_format_in_insert

Type: Bool

Default value: 0

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:

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:

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.

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 ClickHouse 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.

Possible values:

0 — disable verbosity.
1 — enable verbosity.

Example

CREATE TABLE test(a Int64, d Date, s String) ENGINE = MergeTree PARTITION BY toYYYYMM(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/clickhouse/shadow/8/ │ /var/lib/clickhouse/shadow/8/data/default/test/202101_7_7_0 │
│ FREEZE ALL   │ 202101       │ 202101_8_8_0 │ 8           │ /var/lib/clickhouse/shadow/8/ │ /var/lib/clickhouse/shadow/8/data/default/test/202101_8_8_0 │
└──────────────┴──────────────┴──────────────┴─────────────┴───────────────────────────────┴─────────────────────────────────────────────────────────────┘

alter_sync

Type: UInt64

Default value: 1

Allows to set up waiting for actions 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.

Cloud default value: 0.

:::note alter_sync is applicable to Replicated tables only, it does nothing to alters of not Replicated tables. :::

analyze_index_with_space_filling_curves

Type: Bool

Default value: 1

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_join_using_top_level_identifier

Type: Bool

Default value: 0

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).

any_join_distinct_right_table_keys

Type: Bool

Default value: 0

Enables legacy ClickHouse 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 ClickHouse 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 ClickHouse 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 value: 1

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 value: 0

If true, mutations (UPDATEs and DELETEs) which are not materialized in data part will be applied on SELECTs. Only available in ClickHouse Cloud.

asterisk_include_alias_columns

Type: Bool

Default value: 0

Include ALIAS columns for wildcard query (SELECT *).

Possible values:

0 - disabled
1 - enabled

asterisk_include_materialized_columns

Type: Bool

Default value: 0

Include MATERIALIZED columns for wildcard query (SELECT *).

Possible values:

0 - disabled
1 - enabled

Type: Bool

Default value: 1

Use multiple threads for azure multipart upload.

azure_create_new_file_on_insert

Type: Bool

Default value: 0

Enables or disables creating a new file on each insert in azure engine tables

azure_ignore_file_doesnt_exist

Type: Bool

Default value: 0

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_skip_empty_files

Type: Bool

Default value: 0

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 value: 0

The exact size of part to upload during multipart upload to Azure blob storage.

azure_throw_on_zero_files_match

Type: Bool

Default value: 0

Throw an error if matched zero files according to glob expansion rules.

Possible values:

1 — SELECT throws an exception.
0 — SELECT returns empty result.

Cloud default value: 1.

cast_ipv4_ipv6_default_on_conversion_error

Type: Bool

Default value: 0

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 value: 0

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:

SET cast_keep_nullable = 0;
SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x);

Result:

┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐
│ 0 │ Int32                                             │
└───┴───────────────────────────────────────────────────┘

The following query results in the Nullable modification on the destination data type:

SET cast_keep_nullable = 1;
SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x);

Result:

┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐
│ 0 │ Nullable(Int32)                                   │
└───┴───────────────────────────────────────────────────┘

See Also

CAST function

cast_string_to_dynamic_use_inference

Type: Bool

Default value: 0

Use types inference during String to Dynamic conversion

check_query_single_value_result

Type: Bool

Default value: 1

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.

Possible values:

0 — Aggregation is done without JIT compilation.
1 — Aggregation is done using JIT compilation.

See Also

min_count_to_compile_aggregate_expression

Possible values:

Positive integer.
0 — Infinite timeout.

connections_with_failover_max_tries

Type: UInt64

Default value: 3

The maximum number of connection attempts with each replica for the Distributed table engine.

convert_query_to_cnf

Type: Bool

Default value: 0

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):

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:

┌─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:

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:

┌─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

count_distinct_implementation

Type: String

Type: Bool

Default value: 0

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_atomic_wait_for_drop_and_detach_synchronously

Type: Bool

Default value: 0

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_replicated_initial_query_timeout_sec

Type: UInt64

Default value: 300

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.

decimal_check_overflow

Type: Bool

Default value: 1

Check overflow of decimal arithmetic/comparison operations

deduplicate_blocks_in_dependent_materialized_views

Type: Bool

Default value: 0

Enables or disables the deduplication check for materialized views that receive data from Replicated* tables.

Possible values:

  0 — Disabled.
  1 — Enabled.

Usage

By default, deduplication is not performed for materialized views but is done upstream, in the source table. If an INSERTed block is skipped due to deduplication in the source table, there will be no insertion into attached materialized views. This behaviour exists to enable the insertion of highly aggregated data into materialized views, for cases where inserted blocks are the same after materialized view aggregation but derived from different INSERTs into the source table. At the same time, this behaviour “breaks” INSERT idempotency. If an INSERT into the main table was successful and INSERT into a materialized view failed (e.g. because of communication failure with ClickHouse Keeper) a client will get an error and can retry the operation. However, the materialized view won’t receive the second insert because it will be discarded by deduplication in the main (source) table. The setting deduplicate_blocks_in_dependent_materialized_views allows for changing this behaviour. On retry, a materialized view will receive the repeat insert and will perform a deduplication check by itself, ignoring check result for the source table, and will insert rows lost because of the first failure.

default_materialized_view_sql_security

Type: SQLSecurityType

Default value: DEFINER

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 value: 1000000000

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 value: INVOKER

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 value: MergeTree

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:

SET default_table_engine = 'Log';

SELECT name, value, changed FROM system.settings WHERE name = 'default_table_engine';

Result:

┌─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:

CREATE TABLE my_table (
    x UInt32,
    y UInt32
);

SHOW CREATE TABLE my_table;

Result:

┌─statement────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.my_table
(
    `x` UInt32,
    `y` UInt32
)
ENGINE = Log
└──────────────────────────────────────────────────────────────────────────┘

default_temporary_table_engine

Type: DefaultTableEngine

Default value: Memory

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:

SET default_temporary_table_engine = 'Log';

CREATE TEMPORARY TABLE my_table (
    x UInt32,
    y UInt32
);

SHOW CREATE TEMPORARY TABLE my_table;

Result:

┌─statement────────────────────────────────────────────────────────────────┐
│ CREATE TEMPORARY TABLE default.my_table
(
    `x` UInt32,
    `y` UInt32
)
ENGINE = Log
└──────────────────────────────────────────────────────────────────────────┘

default_view_definer

Type: String

Type: Bool

Default value: 0

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 value: 30000

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 value: 100

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 value: 0

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.

Default value: 5

Compatibility version of distributed DDL (ON CLUSTER) queries

distributed_ddl_output_mode

Type: DistributedDDLOutputMode

Default value: throw

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.

distributed_ddl_task_timeout

Type: Int64

Default value: 180

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_foreground_insert

Type: Bool

Default value: 0

Enables or disables synchronous data insertion into a Distributed table.

By default, when inserting data into a Distributed table, the ClickHouse 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_group_by_no_merge

Type: UInt64

Default value: 0

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

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 │
└───────┘

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_insert_skip_read_only_replicas

Type: Bool

Default value: 0

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_product_mode

Type: DistributedProductMode

Default value: deny

Changes the behaviour of distributed subqueries.

ClickHouse 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 value: 1

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 value: 1000

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 value: 60

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 value: 0

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 value: 0

Merge parts only in one partition in select final

empty_result_for_aggregation_by_constant_keys_on_empty_set

Type: Bool

Default value: 1

Return empty result when aggregating by constant keys on empty set.

empty_result_for_aggregation_by_empty_set

Type: Bool

Default value: 0

Return empty result when aggregating without keys on empty set.

enable_blob_storage_log

Type: Bool

Default value: 1

Write information about blob storage operations to system.blob_storage_log table

enable_deflate_qpl_codec

Type: Bool

Default value: 0

If turned on, the DEFLATE_QPL codec may be used to compress columns.

Possible values:

0 - Disabled
1 - Enabled

enable_early_constant_folding

Type: Bool

Default value: 1

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 value: 0

Enables or disables returning results of type:

Date32 with extended range (compared to type Date) for functions toStartOfYear, toStartOfISOYear, toStartOfQuarter, toStartOfMonth, toLastDayOfMonth, toStartOfWeek, toLastDayOfWeek and toMonday.
DateTime64 with extended range (compared to type DateTime) for functions toStartOfDay, toStartOfHour, toStartOfMinute, toStartOfFiveMinutes, toStartOfTenMinutes, toStartOfFifteenMinutes and timeSlot.

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.

For more information, read the HTTP interface description.

Possible values:

0 — Disabled.
1 — Enabled.

Predicate pushdown may significantly reduce network traffic for distributed queries.

Possible values:

0 — Disabled.
1 — Enabled.

Usage

Consider the following queries:

SELECT count() FROM test_table WHERE date = '2018-10-10'
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 ClickHouse 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 value: 1

Allow push predicate to final subquery.

enable_order_by_all

Type: Bool

Default value: 1

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_parsing_to_custom_serialization

Type: Bool

Default value: 1

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 value: 1

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:

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:

┌─one─┬─two─┬─three─┐
│  30 │  10 │   20  │
│  20 │  20 │   10  │
│  10 │  20 │   30  │
└─────┴─────┴───────┘

enable_reads_from_query_cache

Type: Bool

Default value: 1

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

Possible values:

0 - Disabled
1 - Enabled

enable_url_encoding

Type: Bool

Default value: 1

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

Enabled by default.

enable_vertical_final

Type: Bool

Default value: 1

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 value: 1

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

Possible values:

0 - Disabled
1 - Enabled

enable_zstd_qat_codec

Type: Bool

Default value: 0

If turned on, the ZSTD_QAT codec may be used to compress columns.

Possible values:

0 - Disabled
1 - Enabled

engine_file_allow_create_multiple_files

Type: Bool

Default value: 0

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 value: 0

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 value: 0

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 value: 0

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 value: 0

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.

except_default_mode

Type: Bool

Default value: 1

Forces a query to an out-of-date replica if updated data is not available. See Replication.

Type: Bool

Default value: 0

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:

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 │
└─────┴────────┘

flatten_nested

Type: Bool

Default value: 1

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:

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:

┌─statement───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_nest
(
    `n.a` Array(UInt32),
    `n.b` Array(UInt32)
)
ENGINE = MergeTree
ORDER BY tuple()
SETTINGS index_granularity = 8192 │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Query:

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:

┌─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 value: 0

Force the use of optimization when it is applicable, but heuristics decided not to use it

force_aggregation_in_order

Type: Bool

Default value: 0

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_data_skipping_indices

Type: String

Default value:

Disables query execution if passed data skipping indices wasn't used.

Consider the following example:

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_grouping_standard_compatibility

Type: Bool

Default value: 1

Make GROUPING function to return 1 when argument is not used as an aggregation key

force_index_by_date

Type: Bool

Default value: 0

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, ClickHouse 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 value: 0

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 value:

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 value: 0

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. ClickHouse 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 value: 0

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 value: 0

function_implementation

Type: String

Default value:

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 value: 0

Control whether allow to return complex type (such as: struct, array, map) for json_value function.

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 value: 0

Control whether allow to return NULL when value is not exist for JSON_VALUE function.

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 value: 1

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 value: 500000000

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

Possible values:

0 — The default value for the aggregation key type is used to produce missing values.
1 — ClickHouse 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

handshake_timeout_ms

Type: Milliseconds

Default value: 10000

Timeout in milliseconds for receiving Hello packet from replicas during handshake.

hdfs_create_new_file_on_insert

Type: Bool

Default value: 0

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 value: 0

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 value: 0

The actual number of replications can be specified when the hdfs file is created.

hdfs_skip_empty_files

Type: Bool

Default value: 0

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 value: 0

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 value: 0

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 value: 50

Connection timeout for establishing connection with replica for Hedged requests

hsts_max_age

Type: UInt64

Default value: 0

Expired time for HSTS. 0 means disable HSTS.

http_connection_timeout

Type: Seconds

Default value: 1

HTTP connection timeout (in seconds).

Possible values:

Any positive integer.
0 - Disabled (infinite timeout).

http_max_uri_size

Type: UInt64

Default value: 1048576

Sets the maximum URI length of an HTTP request.

Possible values:

Positive integer.

http_native_compression_disable_checksumming_on_decompress

Type: Bool

Default value: 0

Enables or disables checksum verification when decompressing the HTTP POST data from the client. Used only for ClickHouse 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 value: 30

HTTP receive timeout (in seconds).

Possible values:

Any positive integer.
0 - Disabled (infinite timeout).

http_response_buffer_size

Type: UInt64

Default value: 0

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_retry_initial_backoff_ms

Type: UInt64

Default value: 100

Min milliseconds for backoff, when retrying read via http

http_retry_max_backoff_ms

Type: UInt64

Default value: 10000

Max milliseconds for backoff, when retrying read via http

http_send_timeout

Type: Seconds

Default value: 30

HTTP send timeout (in seconds).

Possible values:

Any positive integer.
0 - Disabled (infinite timeout).

:::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 value: 1

Skip URLs for globs with HTTP_NOT_FOUND error

http_wait_end_of_query

Type: Bool

Default value: 0

Enable HTTP response buffering on the server-side.

http_write_exception_in_output_format

Type: Bool

Default value: 1

Write exception in output format to produce valid output. Works with JSON and XML formats.

http_zlib_compression_level

Type: Int64

Default value: 3

Sets the level of data compression in the response to an HTTP request if enable_http_compression = 1.

Possible values: Numbers from 1 to 9.

iceberg_engine_ignore_schema_evolution

Type: Bool

Default value: 0

Allow to ignore schema evolution in Iceberg table engine and read all data using schema specified by the user on table creation or latest schema parsed from metadata on table creation.

:::note Enabling this setting can lead to incorrect result as in case of evolved schema all data files will be read using the same schema. :::

idle_connection_timeout

Type: UInt64

Default value: 3600

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 value: 0

Only available in ClickHouse 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 value:

Ignores the skipping indexes specified if used by the query.

Consider the following example:

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:

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:

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

If enabled and not already inside a transaction, wraps the query inside a full transaction (begin + commit or rollback)

input_format_parallel_parsing

Type: Bool

Default value: 1

Enables or disables order-preserving parallel parsing of data formats. Supported only for TSV, TSKV, CSV and JSONEachRow formats.

Possible values:

1 — Enabled.
0 — Disabled.

insert_allow_materialized_columns

Type: Bool

Default value: 0

If setting is enabled, Allow materialized columns in INSERT.

insert_deduplicate

Type: Bool

Default value: 1

Enables or disables block deduplication of INSERT (for Replicated* tables).

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 value:

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 works on a partition level (the same as insert_deduplication checksum). Multiple partitions can have the same insert_deduplication_token. :::

Example:

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_keeper_fault_injection_probability

Type: Float

Default value: 0

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 value: 0

0 - random seed, otherwise the setting value

insert_keeper_max_retries

Type: UInt64

Default value: 20

The setting sets the maximum number of retries for ClickHouse 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

Cloud default value: 20.

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 value: 100

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 value: 10000

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 value: 1

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 value: 0

:::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 ClickHouse 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 ClickHouse 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.

ClickHouse 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 value: 1

:::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 value: 600000

Write to a quorum timeout in milliseconds. If the timeout has passed and no write has taken place yet, ClickHouse 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 value: 0

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:

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:

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:

┌─number─┐
│      0 │
│      0 │
│      1 │
│      1 │
│      2 │
│      2 │
│      3 │
│      3 │
│      4 │
│      4 │
└────────┘

interactive_delay

Type: UInt64

Default value: 100000

The interval in microseconds for checking whether request execution has been canceled and sending the progress.

intersect_default_mode

Type: SetOperationMode

Default value: ALL

Set default mode in INTERSECT query. Possible values: empty string, 'ALL', 'DISTINCT'. If empty, query without mode will throw exception.

join_algorithm

Type: JoinAlgorithm

Default value: default

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.

Possible values:

default

This is the equivalent of hash or direct, if possible (same as direct,hash)

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.

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 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, ClickHouse sorts the data and dumps it to the disk. The partial_merge algorithm in ClickHouse differs slightly from the classic realization. First, ClickHouse 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

This algorithm can be applied when the storage for the right table supports key-value requests.

The direct algorithm performs a lookup in the right table using rows from the left table as keys. It's supported only by special storage such as Dictionary or EmbeddedRocksDB and only the LEFT and INNER JOINs.

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 joined tables before joining.

prefer_partial_merge

ClickHouse always tries to use partial_merge join if possible, otherwise, it uses hash. Deprecated, same as partial_merge,hash.

join_any_take_last_row

Type: Bool

Default value: 0

Changes the behaviour of join operations with ANY strictness.

:::note This setting applies only for JOIN operations with Join engine tables. :::

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_default_strictness

Type: JoinStrictness

Default value: ALL

Sets default strictness for JOIN clauses.

Possible values:

ALL — If the right table has several matching rows, ClickHouse 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, ClickHouse throws an exception.

join_on_disk_max_files_to_merge

Type: UInt64

Default value: 64

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 value: 5

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 value: throw

What to do when the limit is exceeded.

join_to_sort_maximum_table_rows

Type: UInt64

Default value: 10000

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 value: 40

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 value: 0

Sets the type of JOIN behaviour. When merging tables, empty cells may appear. ClickHouse 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_subquery_requires_alias

Type: Bool

Default value: 1

Force joined subqueries and table functions to have aliases for correct name qualification.

kafka_disable_num_consumers_limit

Type: Bool

Default value: 0

Disable limit on kafka_num_consumers that depends on the number of available CPU cores.

kafka_max_wait_ms

Type: Milliseconds

Default value: 5000

The wait time in milliseconds for reading messages from Kafka before retry.

Possible values:

Positive integer.
0 — Infinite timeout.

See also:

Apache Kafka

Possible values:

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).

See Also

limit

Type: UInt64

Default value: 0

Sets the maximum number of rows to get from the query result. It adjusts the value set by the LIMIT clause, so that the limit, specified in the query, cannot exceed the limit, set by this setting.

Possible values:

0 — The number of rows is not limited.
Positive integer.

live_view_heartbeat_interval

Type: Seconds

Default value: 15

The heartbeat interval in seconds to indicate live query is alive.

load_balancing

Type: LoadBalancing

Default value: random

Specifies the algorithm of replicas selection that is used for distributed query processing.

ClickHouse supports the following algorithms of choosing replicas:

Random (by default)
Nearest hostname
Hostname levenshtein distance
In order
First or random
Round robin

See also:

distributed_replica_max_ignored_errors

Random (by Default)

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

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

load_balancing = hostname_levenshtein_distance

Just like nearest_hostname, but it compares hostname in a levenshtein distance manner. For example:

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

In Order

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

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

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 value: 0

Which replica to preferably send a query when FIRST_OR_RANDOM load balancing strategy is used.

load_marks_asynchronously

Type: Bool

Default value: 0

Load MergeTree marks asynchronously

local_filesystem_read_method

Type: String

Default value: pread_threadpool

Method of reading data from local filesystem, one of: read, pread, mmap, io_uring, pread_threadpool. 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.

local_filesystem_read_prefetch

Type: Bool

Default value: 0

Should use prefetching when reading data from local filesystem.

lock_acquire_timeout

Type: Seconds

Default value: 120

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 ClickHouse 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 value:

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 clickhouse-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:

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:

┌─type────────┬─query─────┐
│ QueryStart  │ SELECT 1; │
│ QueryFinish │ SELECT 1; │
└─────────────┴───────────┘

log_formatted_queries

Type: Bool

Default value: 0

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 value: 1

Write time that processor spent during execution/waiting for data to system.processors_profile_log table.

See also:

log_profile_events

Type: Bool

Default value: 1

Log query performance statistics into the query_log, query_thread_log and query_views_log.

log_queries

Type: Bool

Default value: 1

Setting up query logging.

Queries sent to ClickHouse with this setup are logged according to the rules in the query_log server configuration parameter.

Example:

log_queries=1

log_queries_cut_to_length

Type: UInt64

Default value: 100000

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 value: 0

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 value: QUERY_START

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:

log_queries_min_type='EXCEPTION_WHILE_PROCESSING'

log_queries_probability

Type: Float

Default value: 1

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 value: 1

Log query settings into the query_log.

log_query_threads

Type: Bool

Default value: 0

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 ClickHouse with this setup are logged according to the rules in the query_thread_log server configuration parameter.

Possible values:

0 — Disabled.
1 — Enabled.

Example

log_query_threads=1

log_query_views

Type: Bool

Default value: 1

Setting up query views logging.

When a query run by ClickHouse with this setting enabled has associated views (materialized or live views), they are logged in the query_views_log server configuration parameter.

Example:

log_query_views=1

low_cardinality_allow_in_native_format

Type: Bool

Default value: 1

Allows or restricts using the LowCardinality data type with the Native format.

If usage of LowCardinality is restricted, ClickHouse 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 value: 8192

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 ClickHouse writes in an ordinary method.

Possible values:

Any positive integer.

low_cardinality_use_single_dictionary_for_part

Type: Bool

Default value: 0

Turns on or turns off using of single dictionary for the data part.

By default, the ClickHouse 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.

max_block_size

Type: UInt64

Default value: 65409

Type: UInt64

Default value: 1048576

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 ClickHouse. :::

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 value: 0

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

<max_concurrent_queries_for_all_users>99</max_concurrent_queries_for_all_users>

See Also

max_concurrent_queries

max_concurrent_queries_for_user

Type: UInt64

Default value: 0

The maximum number of simultaneously processed queries per user.

Possible values:

Positive integer.
0 — No limit.

Example

<max_concurrent_queries_for_user>5</max_concurrent_queries_for_user>

max_distributed_connections

Type: UInt64

Default value: 1024

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 value: 5

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.

Possible values:

Positive integer.
0 or 1 — Disabled. SELECT queries are executed in a single thread.

max_http_get_redirects

Type: UInt64

Default value: 0

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.

max_hyperscan_regexp_length

Type: UInt64

Default value: 0

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:

SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 3;

Result:

┌─multiMatchAny('abcd', ['ab', 'bcd', 'c', 'd'])─┐
│                                              1 │
└────────────────────────────────────────────────┘

Query:

SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 2;

Result:

Exception: Regexp length too large.

See Also

max_hyperscan_regexp_total_length

max_hyperscan_regexp_total_length

Type: UInt64

Default value: 0

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:

SELECT multiMatchAny('abcd', ['a','b','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5;

Result:

┌─multiMatchAny('abcd', ['a', 'b', 'c', 'd'])─┐
│                                           1 │
└─────────────────────────────────────────────┘

Query:

SELECT multiMatchAny('abcd', ['ab','bc','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5;

Result:

Exception: Total regexp lengths too large.

See Also

max_hyperscan_regexp_length

max_insert_block_size

Type: UInt64

Default value: 1048449

The size of blocks (in a count of rows) to form for insertion into a table. This setting only applies in cases when the server forms the blocks. For example, for an INSERT via the HTTP interface, the server parses the data format and forms blocks of the specified size. But when using clickhouse-client, the client parses the data itself, and the ‘max_insert_block_size’ setting on the server does not affect the size of the inserted blocks. The setting also does not have a purpose when using INSERT SELECT, since data is inserted using the same blocks that are formed after SELECT.

The default is slightly more than max_block_size. The reason for this is that certain table engines (*MergeTree) form a data part on the disk for each inserted block, which is a fairly large entity. Similarly, *MergeTree tables sort data during insertion, and a large enough block size allow sorting more data in RAM.

max_insert_delayed_streams_for_parallel_write

Type: UInt64

Default value: 0

The maximum number of streams (columns) to delay final part flush. Default - auto (1000 in case of underlying storage supports parallel write, for example S3 and disabled otherwise)

max_insert_threads

Type: UInt64

Default value: 0

The maximum number of threads to execute the INSERT SELECT query.

Possible values:

0 (or 1) — INSERT SELECT no parallel execution.
Positive integer. Bigger than 1.

Default value: 0

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 value: 0

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 value: 0

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 value: 0

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 value: 128

Maximal number of partitions in table to apply optimization

max_parallel_replicas

Type: NonZeroUInt64

Default value: 1

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.

:::note This setting will produce incorrect results when joins or subqueries are involved, and all tables don't meet certain requirements. See Distributed Subqueries and max_parallel_replicas for more details. :::

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

Limit the number of parts that can be moved in one query. Zero means unlimited.

Default value: 1000.

max_query_size

Type: UInt64

Possible values:

Positive integer.
0 — Replica lags are not checked.

Default value: 0

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_table_size_to_drop

Type: UInt64

Default value: 50000000000

Default value: 4194304

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 value: 0

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 value: 5000000

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_tree_coarse_index_granularity

Type: UInt64

Default value: 8

When searching for data, ClickHouse checks the data marks in the index file. If ClickHouse 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 value: 16

Only available in ClickHouse 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.

merge_tree_determine_task_size_by_prewhere_columns

Type: Bool

Default value: 1

Whether to use only prewhere columns size to determine reading task size.

merge_tree_max_bytes_to_use_cache

Type: UInt64

Default value: 2013265920

If ClickHouse 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. ClickHouse 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 value: 1048576

If ClickHouse should read more than merge_tree_max_rows_to_use_cache rows in one query, it does not use the cache of uncompressed blocks.

Possible values:

Any positive integer.

merge_tree_min_bytes_for_concurrent_read

Type: UInt64

Default value: 251658240

If the number of bytes to read from one file of a MergeTree-engine table exceeds merge_tree_min_bytes_for_concurrent_read, then ClickHouse 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 value: 251658240

The minimum number of bytes to read from one file before MergeTree engine can parallelize reading, when reading from remote filesystem.

Possible values:

Positive integer.

merge_tree_min_bytes_for_seek

Type: UInt64

Default value: 0

If the distance between two data blocks to be read in one file is less than merge_tree_min_bytes_for_seek bytes, then ClickHouse sequentially reads a range of file that contains both blocks, thus avoiding extra seek.

Possible values:

Any positive integer.

merge_tree_min_bytes_per_task_for_remote_reading

Type: UInt64

Default value: 2097152

Min bytes to read per task.

merge_tree_min_rows_for_concurrent_read

Type: UInt64

Default value: 163840

If the number of rows to be read from a file of a MergeTree table exceeds merge_tree_min_rows_for_concurrent_read then ClickHouse 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 value: 163840

The minimum number of lines to read from one file before the MergeTree engine can parallelize reading, when reading from remote filesystem.

Possible values:

Positive integer.

merge_tree_min_rows_for_seek

Type: UInt64

Default value: 0

If the distance between two data blocks to be read in one file is less than merge_tree_min_rows_for_seek rows, then ClickHouse does not seek through the file but reads the data sequentially.

Possible values:

Any positive integer.

merge_tree_read_split_ranges_into_intersecting_and_non_intersecting_injection_probability

Type: Float

Default value: 0

For testing of PartsSplitter - split read ranges into intersecting and non intersecting every time you read from MergeTree with the specified probability.

merge_tree_use_const_size_tasks_for_remote_reading

Type: Bool

Default value: 1

Whether to use constant size tasks for reading from a remote table.

metrics_perf_events_enabled

Type: Bool

Default value: 0

If enabled, some of the perf events will be measured throughout queries' execution.

metrics_perf_events_list

Type: String

Default value:

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 value: 0

The minimum data volume required for using direct I/O access to the storage disk.

ClickHouse 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 ClickHouse 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 value: 0

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: UInt64

Default value: 10485760

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 value: 65536

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 ClickHouse. :::

min_count_to_compile_aggregate_expression

Type: UInt64

Default value: 3

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_insert_block_size_bytes

Type: UInt64

Default value: 268402944

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.

Possible values:

Positive integer.
0 — Squashing disabled.

min_insert_block_size_bytes_for_materialized_views

Type: UInt64

Default value: 0

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 value: 1048449

Sets the minimum number of rows in the block that can be inserted into a table by an INSERT query. Smaller-sized blocks are squashed into bigger ones.

Possible values:

Positive integer.
0 — Squashing disabled.

min_insert_block_size_rows_for_materialized_views

Type: UInt64

Default value: 0

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

Possible values:

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).

mysql_datatypes_support_level

Type: MySQLDataTypesSupport

Default value:

Defines how MySQL types are converted to corresponding ClickHouse types. A comma separated list in any combination of decimal, datetime64, date2Date32 or date2String.

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.

mysql_map_fixed_string_to_text_in_show_columns

Type: Bool

Default value: 1

When enabled, FixedString ClickHouse 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 value: 1

When enabled, String ClickHouse 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 value: 65536

The maximum number of rows in MySQL batch insertion of the MySQL storage engine

network_compression_method

Type: String

Default value: LZ4

Sets the method of data compression that is used for communication between servers and between server and clickhouse-client.

Possible values:

LZ4 — sets LZ4 compression method.
ZSTD — sets ZSTD compression method.

See Also

network_zstd_compression_level

network_zstd_compression_level

Type: Int64

Default value: 1

Adjusts the level of ZSTD compression. Used only when network_compression_method is set to ZSTD.

Possible values:

Positive integer from 1 to 15.

Possible values:

0 — No rows are skipped .
Positive integer.

Example

Input table:

CREATE TABLE test (i UInt64) ENGINE = MergeTree() ORDER BY i;
INSERT INTO test SELECT number FROM numbers(500);

Query:

SET limit = 5;
SET offset = 7;
SELECT * FROM test LIMIT 10 OFFSET 100;

Result:

┌───i─┐
│ 107 │
│ 108 │
│ 109 │
└─────┘

opentelemetry_start_trace_probability

Type: Float

Default value: 0

Sets the probability that the ClickHouse 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, ClickHouse can start a trace on average for half of the queries.
1 — The trace for all executed queries is enabled.

opentelemetry_trace_processors

Type: Bool

Default value: 0

Collect OpenTelemetry spans for processors.

optimize_aggregation_in_order

Type: Bool

Default value: 0

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_aggregators_of_group_by_keys

Type: Bool

Default value: 1

Eliminates min/max/any/anyLast aggregators of GROUP BY keys in SELECT section

optimize_append_index

Type: Bool

Default value: 0

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 value: 1

Move arithmetic operations out of aggregation functions

optimize_count_from_files

Type: Bool

Default value: 1

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_distinct_in_order

Type: Bool

Default value: 1

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 value: 1

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_functions_to_subcolumns

Type: Bool

Default value: 1

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_move_to_prewhere

Type: Bool

Default value: 1

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 value: 0

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 value: 1

Replace 'multiIf' with only one condition to 'if'.

optimize_normalize_count_variants

Type: Bool

Default value: 1

Rewrite aggregate functions that semantically equals to count() as count().

optimize_on_insert

Type: Bool

Default value: 1

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:

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:

┌─FirstTable─┐
│          0 │
│          1 │
└────────────┘

┌─SecondTable─┐
│           0 │
│           0 │
│           0 │
│           1 │
│           1 │
└─────────────┘

Note that this setting influences Materialized view and MaterializedMySQL behaviour.

optimize_or_like_chain

Type: Bool

Default value: 0

Optimize multiple OR LIKE into multiMatchAny. This optimization should not be enabled by default, because it defies index analysis in some cases.

optimize_read_in_order

Type: Bool

Default value: 1

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 value: 1

Enable ORDER BY optimization in window clause for reading data in corresponding order in MergeTree tables.

optimize_redundant_functions_in_order_by

Type: Bool

Default value: 1

Remove functions from ORDER BY if its argument is also in ORDER BY

optimize_respect_aliases

Type: Bool

Default value: 1

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 value: 1

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 experimental analyzer (enable_analyzer = 1). :::

optimize_rewrite_array_exists_to_has

Type: Bool

Default value: 0

Rewrite arrayExists() functions to has() when logically equivalent. For example, arrayExists(x -> x = 1, arr) can be rewritten to has(arr, 1)

optimize_rewrite_sum_if_to_count_if

Type: Bool

Default value: 1

Rewrite sumIf() and sum(if()) function countIf() function when logically equivalent

optimize_skip_merged_partitions

Type: Bool

Default value: 0

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 value: 0

Enables or disables skipping of unused shards for SELECT queries that have sharding key condition in WHERE/PREWHERE (assuming 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 value: 1000

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 value: 0

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 value: 1

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 value: 1

Optimize sorting by sorting properties of input stream

optimize_substitute_columns

Type: Bool

Default value: 0

Use constraints for column substitution. The default is false.

Possible values:

true, false

optimize_syntax_fuse_functions

Type: Bool

Default value: 0

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:

CREATE TABLE fuse_tbl(a Int8, b Int8) Engine = Log;
SET optimize_syntax_fuse_functions = 1;
EXPLAIN SYNTAX SELECT sum(a), sum(b), count(b), avg(b) from fuse_tbl FORMAT TSV;

Result:

SELECT
    sum(a),
    sumCount(b).1,
    sumCount(b).2,
    (sumCount(b).1) / (sumCount(b).2)
FROM fuse_tbl

optimize_throw_if_noop

Type: Bool

Default value: 0

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 value: 1

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 value: 0

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 value: 1

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_insert_select

Type: Bool

Default value: 0

Optimize trivial 'INSERT INTO table SELECT ... FROM TABLES' query

optimize_uniq_to_count

Type: Bool

Default value: 1

Rewrite uniq and its variants(except uniqUpTo) to count if subquery has distinct or group by clause.

optimize_use_implicit_projections

Type: Bool

Default value: 1

Automatically choose implicit projections to perform SELECT query

optimize_use_projections

Type: Bool

Default value: 1

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 value: 0

Use constraints for query optimization. The default is false.

Possible values:

true, false

os_thread_priority

Type: Int64

Default value: 0

Sets the priority (nice) for threads that execute queries. The OS scheduler considers this priority when choosing the next thread to run on each available CPU core.

:::note To use this setting, you need to set the CAP_SYS_NICE capability. The clickhouse-server package sets it up during installation. Some virtual environments do not allow you to set the CAP_SYS_NICE capability. In this case, clickhouse-server shows a message about it at the start. :::

Possible values:

You can set values in the range [-20, 19].

Lower values mean higher priority. Threads with low nice priority values are executed more frequently than threads with high values. High values are preferable for long-running non-interactive queries because it allows them to quickly give up resources in favour of short interactive queries when they arrive.

output_format_compression_level

Type: UInt64

Default value: 3

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.

Possible values: from 1 to 22

output_format_compression_zstd_window_log

Type: UInt64

Default value: 0

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_parallel_formatting

Type: Bool

Default value: 1

Enables or disables parallel formatting of data formats. Supported only for TSV, TSKV, CSV and JSONEachRow formats.

Possible values:

1 — Enabled.
0 — Disabled.

page_cache_inject_eviction

Type: Bool

Default value: 0

Userspace page cache will sometimes invalidate some pages at random. Intended for testing.

parallel_distributed_insert_select

Type: UInt64

Default value: 0

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.

parallel_replica_offset

Type: UInt64

Default value: 0

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 value: 1

If true, subquery for IN will be executed on every follower replica.

parallel_replicas_count

Type: UInt64

Default value: 0

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 value:

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.

parallel_replicas_custom_key_range_lower

Type: UInt64

Default value: 0

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

Type: UInt64

Default value: 65536

Limits sizes of right-hand join data blocks in partial merge join algorithm for JOIN queries.

ClickHouse server:

Splits right-hand join data into blocks with up to the specified number of rows.
Indexes each block with its minimum and maximum values.
Unloads prepared blocks to disk if it is possible.

Possible values:

Any positive integer. Recommended range of values: [1000, 100000].

prefer_column_name_to_alias

Type: Bool

Default value: 0

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 ClickHouse 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:

SET prefer_column_name_to_alias = 0;
SELECT avg(number) AS number, max(number) FROM numbers(10);

Result:

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:

SET prefer_column_name_to_alias = 1;
SELECT avg(number) AS number, max(number) FROM numbers(10);

Result:

┌─number─┬─max(number)─┐
│    4.5 │           9 │
└────────┴─────────────┘

prefer_external_sort_block_bytes

Type: UInt64

Default value: 16744704

Prefer maximum block bytes for external sort, reduce the memory usage during merging.

prefer_global_in_and_join

Type: Bool

Default value: 0

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 value: 1

Enables/disables preferable using the localhost replica when processing distributed queries.

Possible values:

1 — ClickHouse always sends a query to the localhost replica if it exists.
0 — ClickHouse 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 value: 0

Only available in ClickHouse 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 ReplicatedMergeTree. 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 value: 1000000

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 value: 0

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 value:

If it is set to a non-empty string, ClickHouse will try to apply specified projection in query.

Possible values:

string: name of preferred projection

prefetch_buffer_size

Type: UInt64

Default value: 1048576

The maximum size of the prefetch buffer to read from the filesystem.

print_pretty_type_names

Type: Bool

Default value: 1

Allows to print deep-nested type names in a pretty way with indents in DESCRIBE query and in toTypeName() function.

Example:

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 value: 0

Priority of the query. 1 - the highest, higher value - lower priority; 0 - do not use priorities.

query_cache_compress_entries

Type: Bool

Default value: 1

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_max_entries

Type: UInt64

Default value: 0

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 value: 0

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 value: 0

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 value: 0

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: QueryCacheNondeterministicFunctionHandling

Default value: throw

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 value: 0

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 value: 1

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: QueryCacheSystemTableHandling

Default value: throw

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 value:

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 value: 60

After this time in seconds entries in the query cache become stale.

Possible values:

Positive integer >= 0.

query_plan_aggregation_in_order

Type: Bool

Default value: 1

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_outer_join_to_inner_join

Type: Bool

Default value: 1

Allow to convert OUTER JOIN to INNER JOIN if filter after JOIN always filters default values

query_plan_enable_multithreading_after_window_functions

Type: Bool

Default value: 1

Enable multithreading after evaluating window functions to allow parallel stream processing

query_plan_enable_optimizations

Type: Bool

Default value: 1

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 value: 1

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 value: 1

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_lift_up_array_join

Type: Bool

Default value: 1

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 value: 1

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_optimizations_to_apply

Type: UInt64

Default value: 10000

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. 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_merge_expressions

Type: Bool

Default value: 1

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_filters

Type: Bool

Default value: 0

Allow to merge filters in the query plan

query_plan_optimize_prewhere

Type: Bool

Default value: 1

Allow to push down filter to PREWHERE expression for supported storages

query_plan_push_down_limit

Type: Bool

Default value: 1

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_read_in_order

Type: Bool

Default value: 1

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_remove_redundant_distinct

Type: Bool

Default value: 1

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 value: 1

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_reuse_storage_ordering_for_window_functions

Type: Bool

Default value: 1

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_split_filter

Type: Bool

Default value: 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. :::

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_profiler_cpu_time_period_ns

Type: UInt64

Default value: 1000000000

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.

Temporarily disabled in ClickHouse Cloud.

See also:

System table trace_log

query_profiler_real_time_period_ns

Type: UInt64

Default value: 1000000000

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.

Temporarily disabled in ClickHouse Cloud.

See also:

System table trace_log

regexp_max_matches_per_row

Type: UInt64

Default value: 1000

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 value: 1

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 value: 2

If memory usage after remerge does not reduced by this ratio, remerge will be disabled.

remote_filesystem_read_method

Type: String

Default value: threadpool

Method of reading data from remote filesystem, one of: read, threadpool.

remote_filesystem_read_prefetch

Type: Bool

Default value: 1

Should use prefetching when reading data from remote filesystem.

remote_fs_read_backoff_max_tries

Type: UInt64

Default value: 5

Max attempts to read with backoff

remote_fs_read_max_backoff_ms

Type: UInt64

Default value: 10000

Max wait time when trying to read data for remote disk

remote_read_min_bytes_for_seek

Type: UInt64

Default value: 4194304

Min bytes required for remote read (url, s3) to do seek, instead of read with ignore.

rename_files_after_processing

Type: String

Default value:

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.

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 value: 0

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 value: 5000

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_wait_for_inactive_replica_timeout

Type: Int64

Default value: 120

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.

restore_replace_external_dictionary_source_to_null

Type: Bool

Default value: 0

Replace external dictionary sources to Null on restore. Useful for testing purposes

restore_replace_external_engines_to_null

Type: Bool

Default value: 0

For testing purposes. Replaces all external engines to Null to not initiate external connections.

restore_replace_external_table_functions_to_null

Type: Bool

Default value: 0

For testing purposes. Replaces all external table functions to Null to not initiate external connections.

result_overflow_mode

Type: OverflowMode

Default value: throw

What to do when the limit is exceeded.

rewrite_count_distinct_if_with_count_distinct_implementation

Type: Bool

Default value: 0

Allows you to rewrite countDistcintIf with count_distinct_implementation setting.

Possible values:

true — Allow.
false — Disallow.

s3_allow_parallel_part_upload

Type: Bool

Default value: 1

Use multiple threads for s3 multipart upload. It may lead to slightly higher memory usage

s3_check_objects_after_upload

Type: Bool

Default value: 0

Check each uploaded object to s3 with head request to be sure that upload was successful

s3_connect_timeout_ms

Type: UInt64

Default value: 1000

Connection timeout for host from s3 disks.

s3_create_new_file_on_insert

Type: Bool

Default value: 0

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 appends new data to the end of the file.
1 — INSERT query creates a new file.

s3_disable_checksum

Type: Bool

Default value: 0

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 ClickHouse 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 value: 0

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.

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_strict_upload_part_size

Type: UInt64

Default value: 0

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 value: 0

Throw an error, when ListObjects request cannot match any files

s3_truncate_on_insert

Type: Bool

Default value: 0

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 appends new data to the end of the file.
1 — INSERT query replaces existing content of the file with the new data.

s3_upload_part_size_multiply_factor

Type: UInt64

Default value: 2

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 value: 500

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_use_adaptive_timeouts

Type: Bool

Default value: 1

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_request_settings

Type: Bool

Default value: 1

Enables s3 request settings validation.

Possible values:

1 — validate settings.
0 — do not validate settings.

select_sequential_consistency

Type: UInt64

Default value: 0

:::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, ClickHouse 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, ClickHouse 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_logs_level

Type: LogsLevel

Default value: fatal

Send server text logs with specified minimum level to client. Valid values: 'trace', 'debug', 'information', 'warning', 'error', 'fatal', 'none'

send_logs_source_regexp

Type: String

Default value:

Send server text logs with specified regexp to match log source name. Empty means all sources.

send_progress_in_http_headers

Type: Bool

Default value: 0

Enables or disables X-ClickHouse-Progress HTTP response headers in clickhouse-server responses.

For more information, read the HTTP interface description.

Possible values:

0 — Disabled.
1 — Enabled.

send_timeout

Type: Seconds

Default value: 300

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.

session_timezone

Type: Timezone

Default value:

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:

SELECT timeZone(), serverTimeZone() FORMAT TSV

Europe/Berlin	Europe/Berlin

SELECT timeZone(), serverTimeZone() SETTINGS session_timezone = 'Asia/Novosibirsk' FORMAT TSV

Asia/Novosibirsk	Europe/Berlin

Assign session time zone 'America/Denver' to the inner DateTime without explicitly specified time zone:

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. :::

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 value: throw

What to do when the limit is exceeded.

short_circuit_function_evaluation

Type: ShortCircuitFunctionEvaluation

Default value: enable

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.

show_table_uuid_in_table_create_query_if_not_nil

Type: Bool

Default value: 0

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.

single_join_prefer_left_table

Type: Bool

Default value: 1

For single JOIN in case of identifier ambiguity prefer left table

skip_download_if_exceeds_query_cache

Type: Bool

Default value: 1

Skip download from remote filesystem if exceeds query cache size

skip_unavailable_shards

Type: Bool

Default value: 0

Enables or disables silently skipping of unavailable shards.

Shard is considered unavailable if all its replicas are unavailable. A replica is unavailable in the following cases:

ClickHouse can’t connect to replica for any reason.

When connecting to a replica, ClickHouse performs several attempts. If all these attempts fail, the replica is considered unavailable.
Replica can’t be resolved through DNS.

If replica’s hostname can’t be resolved through DNS, it can indicate the following situations:
- Replica’s host has no DNS record. It can occur in systems with dynamic DNS, for example, Kubernetes, where nodes can be unresolvable during downtime, and this is not an error.
- Configuration error. ClickHouse configuration file contains a wrong hostname.

Possible values:

1 — skipping enabled.

If a shard is unavailable, ClickHouse returns a result based on partial data and does not report node availability issues.
0 — skipping disabled.

If a shard is unavailable, ClickHouse throws an exception.

splitby_max_substrings_includes_remaining_string

Type: Bool

Default value: 0

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.

stop_refreshable_materialized_views_on_startup

Type: Bool

Default value: 0

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 value: pread

Method of reading data from storage file, one of: read, pread, mmap. The mmap method does not apply to clickhouse-server (it's intended for clickhouse-local).

storage_system_stack_trace_pipe_read_timeout_ms

Type: Milliseconds

Default value: 100

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 value: 7500

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 value: 0

Allow direct SELECT query for Kafka, RabbitMQ, FileLog, Redis Streams, and NATS engines. In case there are attached materialized views, SELECT query is not allowed even if this setting is enabled.

stream_like_engine_insert_queue

Type: String

Default value:

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 value: 500

Timeout for polling data from/to streaming storages.

system_events_show_zero_values

Type: Bool

Default value: 0

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

SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded';

Result

Ok.

Query

SET system_events_show_zero_values = 1;
SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded';

Result

┌─event────────────────────┬─value─┬─description───────────────────────────────────────────┐
│ QueryMemoryLimitExceeded │     0 │ Number of times when memory limit exceeded for query. │
└──────────────────────────┴───────┴───────────────────────────────────────────────────────┘

table_function_remote_max_addresses

Type: UInt64

Default value: 1000

Sets the maximum number of addresses generated from patterns for the remote function.

Possible values:

Positive integer.

tcp_keep_alive_timeout

Type: Seconds

Default value: 290

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 value: 600000

Wait time to lock cache for space reservation for temporary data in filesystem cache

temporary_files_codec

Type: String

Default value: LZ4

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.

trace_profile_events

Type: Bool

Default value: 0

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.

transfer_overflow_mode

Type: OverflowMode

Default value: throw

What to do when the limit is exceeded.

transform_null_in

Type: Bool

Default value: 0

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:

┌──idx─┬─────i─┐
│    1 │     1 │
│    2 │  NULL │
│    3 │     3 │
└──────┴───────┘

Query:

SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 0;

Result:

┌──idx─┬────i─┐
│    1 │    1 │
└──────┴──────┘

Query:

SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 1;

Result:

┌──idx─┬─────i─┐
│    1 │     1 │
│    2 │  NULL │
└──────┴───────┘

See Also

NULL Processing in IN Operators

traverse_shadow_remote_data_paths

Type: Bool

Default value: 0

Traverse shadow directory when query system.remote_data_paths

union_default_mode

Type: SetOperationMode

Default value:

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' — ClickHouse outputs rows as a result of combining queries removing duplicate rows.
'ALL' — ClickHouse outputs all rows as a result of combining queries including duplicate rows.
'' — ClickHouse generates an exception when used with UNION.

See examples in UNION.

unknown_packet_in_send_data

Type: UInt64

Default value: 0

Send unknown packet instead of data Nth data packet

use_cache_for_count_from_files

Type: Bool

Default value: 1

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 value: 0

Use client timezone for interpreting DateTime string values, instead of adopting server timezone.

use_compact_format_in_distributed_parts_names

Type: Bool

Default value: 1

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 value: 1

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_hedged_requests

Type: Bool

Default value: 1

0 - Disabled
1 - Enabled

use_skip_indexes

Type: Bool

Default value: 1

Use data skipping indexes during query execution.

Possible values:

0 — Disabled.
1 — Enabled.

use_skip_indexes_if_final

Type: Bool

Default value: 0

Controls whether skipping indexes are used when executing a query with the FINAL modifier.

By default, this setting is disabled because skip indexes may exclude rows (granules) containing the latest data, which could lead to incorrect results. When enabled, skipping indexes are applied even with the FINAL modifier, potentially improving performance but with the risk of missing recent updates.

Possible values:

0 — Disabled.
1 — Enabled.

use_structure_from_insertion_table_in_table_functions

Type: UInt64

Default value: 2

Use structure from insertion table instead of schema inference from data. Possible values: 0 - disabled, 1 - enabled, 2 - auto

use_uncompressed_cache

Type: Bool

Default value: 0

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 value: 0

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:

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);

┌─variant_type───────────────────┐
│ Variant(Array(UInt64), UInt64) │
└────────────────────────────────┘
┌─variant───┐
│ []        │
│ 1         │
│ [0,1]     │
│ 3         │
│ [0,1,2,3] │
└───────────┘

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);

─variant_type─────────────────────────┐
│ Variant(Array(UInt8), String, UInt8) │
└──────────────────────────────────────┘

┌─variant───────┐
│ 42            │
│ [1,2,3]       │
│ Hello, World! │
│ ᴺᵁᴸᴸ          │
└───────────────┘

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);

┌─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'] │
└───────────────────┘

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);

┌─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_with_fill_by_sorting_prefix

Type: Bool

Default value: 1

Columns preceding WITH FILL columns in ORDER BY clause form sorting prefix. Rows with different values in sorting prefix are filled independently

validate_polygons

Type: Bool

Default value: 1

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.

enforce_strict_identifier_format

If enabled, only allow identifiers containing alphanumeric characters and underscores.

workload

Type: String

Default value: default

Name of workload to be used to access resources

write_through_distributed_cache

Type: Bool

Default value: 0

Only in ClickHouse Cloud. Allow writing to distributed cache (writing to s3 will also be done by distributed cache)

zstd_window_log_max

Type: Int64

Default value: 0

Allows you to select the max window log of ZSTD (it will not be used for MergeTree family)

Default value: true.

301 KiB Raw Blame History Unescape Escape

Core Settings

add_http_cors_header

additional_result_filter

additional_table_filters

aggregate_functions_null_for_empty

aggregation_in_order_max_block_bytes

aggregation_memory_efficient_merge_threads

allow_aggregate_partitions_independently

allow_archive_path_syntax

allow_asynchronous_read_from_io_pool_for_merge_tree

allow_changing_replica_until_first_data_packet

allow_create_index_without_type

allow_custom_error_code_in_throwif

allow_ddl

allow_deprecated_database_ordinary

allow_deprecated_error_prone_window_functions

allow_deprecated_snowflake_conversion_functions

allow_deprecated_syntax_for_merge_tree

allow_distributed_ddl

allow_drop_detached

allow_execute_multiif_columnar

allow_experimental_analyzer

allow_experimental_codecs

allow_experimental_database_materialized_mysql

allow_experimental_database_materialized_postgresql

allow_experimental_dynamic_type

allow_experimental_full_text_index

allow_experimental_funnel_functions

allow_experimental_hash_functions

allow_experimental_inverted_index

allow_experimental_join_condition

allow_experimental_join_right_table_sorting

allow_experimental_json_type

allow_experimental_kafka_offsets_storage_in_keeper

allow_experimental_live_view

allow_experimental_materialized_postgresql_table

allow_experimental_nlp_functions

allow_experimental_object_type

allow_experimental_parallel_reading_from_replicas

allow_experimental_query_deduplication

allow_experimental_shared_set_join

allow_experimental_statistics

allow_experimental_time_series_table

allow_experimental_variant_type

allow_experimental_vector_similarity_index

allow_experimental_window_view

allow_get_client_http_header

allow_hyperscan

allow_introspection_functions

allow_materialized_view_with_bad_select

allow_named_collection_override_by_default

allow_non_metadata_alters

allow_nonconst_timezone_arguments

allow_nondeterministic_mutations

allow_nondeterministic_optimize_skip_unused_shards

allow_prefetched_read_pool_for_local_filesystem

allow_prefetched_read_pool_for_remote_filesystem

allow_push_predicate_when_subquery_contains_with

allow_settings_after_format_in_insert

allow_simdjson

allow_statistics_optimize

allow_suspicious_codecs

allow_suspicious_fixed_string_types

allow_suspicious_indices

allow_suspicious_low_cardinality_types

allow_suspicious_primary_key

allow_suspicious_ttl_expressions

allow_suspicious_variant_types

allow_unrestricted_reads_from_keeper

alter_move_to_space_execute_async

alter_partition_verbose_result

alter_sync

analyze_index_with_space_filling_curves

analyzer_compatibility_join_using_top_level_identifier

any_join_distinct_right_table_keys

apply_deleted_mask

apply_mutations_on_fly

asterisk_include_alias_columns

asterisk_include_materialized_columns

301 KiB

Raw Blame History