Branch data Line data Source code
1 : : #include <Columns/ColumnArray.h>
2 : : #include <Columns/ColumnLowCardinality.h>
3 : : #include <Columns/ColumnMap.h>
4 : : #include <Columns/ColumnTuple.h>
5 : : #include <Core/BaseSettings.h>
6 : : #include <Core/BaseSettingsFwdMacrosImpl.h>
7 : : #include <Core/BaseSettingsProgramOptions.h>
8 : : #include <Core/DistributedCacheDefines.h>
9 : : #include <Core/FormatFactorySettings.h>
10 : : #include <Core/Settings.h>
11 : : #include <Core/SettingsChangesHistory.h>
12 : : #include <Core/SettingsEnums.h>
13 : : #include <Core/SettingsFields.h>
14 : : #include <Core/SettingsObsoleteMacros.h>
15 : : #include <Core/SettingsTierType.h>
16 : : #include <IO/ReadBufferFromString.h>
17 : : #include <IO/S3Defines.h>
18 : : #include <Storages/System/MutableColumnsAndConstraints.h>
19 : : #include <base/types.h>
20 : : #include <Common/NamePrompter.h>
21 : : #include <Common/typeid_cast.h>
22 : :
23 : : #include <boost/program_options.hpp>
24 : : #include <Poco/Util/AbstractConfiguration.h>
25 : : #include <Poco/Util/Application.h>
26 : :
27 : : #include <cstring>
28 : :
29 : : namespace
30 : : {
31 : : #if !CLICKHOUSE_CLOUD
32 : : constexpr UInt64 default_max_size_to_drop = 50000000000lu;
33 : : constexpr UInt64 default_distributed_cache_connect_max_tries = 5lu;
34 : : constexpr UInt64 default_distributed_cache_read_request_max_tries = 10lu;
35 : : constexpr UInt64 default_distributed_cache_write_request_max_tries = 10lu;
36 : : constexpr UInt64 default_distributed_cache_credentials_refresh_period_seconds = 5;
37 : : constexpr UInt64 default_distributed_cache_connect_backoff_min_ms = 0;
38 : : constexpr UInt64 default_distributed_cache_connect_backoff_max_ms = 50;
39 : : constexpr UInt64 default_distributed_cache_connect_timeout_ms = 50;
40 : : constexpr UInt64 default_distributed_cache_send_timeout_ms = 3000;
41 : : constexpr UInt64 default_distributed_cache_receive_timeout_ms = 3000;
42 : : constexpr UInt64 default_distributed_cache_tcp_keep_alive_timeout_ms = 2900;
43 : : constexpr UInt64 default_distributed_cache_use_clients_cache_for_read = true;
44 : : constexpr UInt64 default_distributed_cache_use_clients_cache_for_write = false;
45 : : #else
46 : : constexpr UInt64 default_max_size_to_drop = 0lu;
47 : : constexpr UInt64 default_distributed_cache_connect_max_tries = DistributedCache::DEFAULT_CONNECT_MAX_TRIES;
48 : : constexpr UInt64 default_distributed_cache_read_request_max_tries = DistributedCache::DEFAULT_READ_REQUEST_MAX_TRIES;
49 : : constexpr UInt64 default_distributed_cache_write_request_max_tries = DistributedCache::DEFAULT_WRITE_REQUEST_MAX_TRIES;
50 : : constexpr UInt64 default_distributed_cache_credentials_refresh_period_seconds = DistributedCache::DEFAULT_CREDENTIALS_REFRESH_PERIOD_SECONDS;
51 : : constexpr UInt64 default_distributed_cache_connect_backoff_min_ms = DistributedCache::DEFAULT_CONNECT_BACKOFF_MIN_MS;
52 : : constexpr UInt64 default_distributed_cache_connect_backoff_max_ms = DistributedCache::DEFAULT_CONNECT_BACKOFF_MAX_MS;
53 : : constexpr UInt64 default_distributed_cache_connect_timeout_ms = DistributedCache::DEFAULT_CONNECT_TIMEOUTS_MS;
54 : : constexpr UInt64 default_distributed_cache_send_timeout_ms = DistributedCache::DEFAULT_SEND_TIMEOUT_MS;
55 : : constexpr UInt64 default_distributed_cache_receive_timeout_ms = DistributedCache::DEFAULT_RECEIVE_TIMEOUT_MS;
56 : : constexpr UInt64 default_distributed_cache_tcp_keep_alive_timeout_ms = DistributedCache::DEFAULT_TCP_KEEP_ALIVE_TIMEOUT_MS;
57 : : constexpr UInt64 default_distributed_cache_use_clients_cache_for_read = DistributedCache::DEFAULT_USE_CLIENTS_CACHE_FOR_READ;
58 : : constexpr UInt64 default_distributed_cache_use_clients_cache_for_write = DistributedCache::DEFAULT_USE_CLIENTS_CACHE_FOR_WRITE;
59 : : #endif
60 : : }
61 : :
62 : : namespace DB
63 : : {
64 : :
65 : : namespace ErrorCodes
66 : : {
67 : : extern const int THERE_IS_NO_PROFILE;
68 : : extern const int NO_ELEMENTS_IN_CONFIG;
69 : : extern const int UNKNOWN_ELEMENT_IN_CONFIG;
70 : : extern const int BAD_ARGUMENTS;
71 : : }
72 : :
73 : : /** List of settings: type, name, default value, description, flags
74 : : *
75 : : * This looks rather inconvenient. It is done that way to avoid repeating settings in different places.
76 : : * Note: as an alternative, we could implement settings to be completely dynamic in the form of the map: String -> Field,
77 : : * but we are not going to do it, because settings are used everywhere as static struct fields.
78 : : *
79 : : * `flags` can include a Tier (BETA | EXPERIMENTAL) and an optional bitwise AND with IMPORTANT.
80 : : * The default (0) means a PRODUCTION ready setting
81 : : *
82 : : * A setting is "IMPORTANT" if it affects the results of queries and can't be ignored by older versions.
83 : : * Tiers:
84 : : * EXPERIMENTAL: The feature is in active development stage. Mostly for developers or for ClickHouse enthusiasts.
85 : : * BETA: There are no known bugs problems in the functionality, but the outcome of using it together with other
86 : : * features/components is unknown and correctness is not guaranteed.
87 : : * PRODUCTION (Default): The feature is safe to use along with other features from the PRODUCTION tier.
88 : : *
89 : : * When adding new or changing existing settings add them to the settings changes history in SettingsChangesHistory.cpp
90 : : * for tracking settings changes in different versions and for special `compatibility` settings to work correctly.
91 : : *
92 : : * The settings in this list are used to autogenerate the markdown documentation. You can find the script which
93 : : * generates the markdown from source here: https://github.com/ClickHouse/clickhouse-docs/blob/main/scripts/settings/autogenerate-settings.sh
94 : : *
95 : : * If a setting has an effect only in ClickHouse Cloud, then please include in the description: "Only has an effect in ClickHouse Cloud."
96 : : */
97 : :
98 : : // clang-format off
99 : : #if defined(__CLION_IDE__)
100 : : /// CLion freezes for a minute every time it processes this
101 : : #define COMMON_SETTINGS(DECLARE, DECLARE_WITH_ALIAS)
102 : : #define OBSOLETE_SETTINGS(DECLARE, DECLARE_WITH_ALIAS)
103 : : #else
104 : : #define COMMON_SETTINGS(DECLARE, DECLARE_WITH_ALIAS) \
105 : 113429 : DECLARE(Dialect, dialect, Dialect::clickhouse, R"(
106 : 113429 : Which dialect will be used to parse query
107 : 113429 : )", 0)\
108 : 113429 : DECLARE(UInt64, min_compress_block_size, 65536, R"(
109 : 113429 : For [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md) 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.
110 : 113429 :
111 : 113429 : 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.
112 : 113429 :
113 : 113429 : Let's look at an example. Assume that `index_granularity` was set to 8192 during table creation.
114 : 113429 :
115 : 113429 : 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.
116 : 113429 :
117 : 113429 : 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.
118 : 113429 :
119 : 113429 : :::note
120 : 113429 : This is an expert-level setting, and you shouldn't change it if you're just getting started with ClickHouse.
121 : 113429 : :::
122 : 113429 : )", 0) \
123 : 113429 : DECLARE(UInt64, max_compress_block_size, 1048576, R"(
124 : 113429 : 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.
125 : 113429 :
126 : 113429 : :::note
127 : 113429 : This is an expert-level setting, and you shouldn't change it if you're just getting started with ClickHouse.
128 : 113429 : :::
129 : 113429 :
130 : 113429 : 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).
131 : 113429 : )", 0) \
132 : 113429 : DECLARE(NonZeroUInt64, max_block_size, DEFAULT_BLOCK_SIZE, R"(
133 : 113429 : In ClickHouse, data is processed by blocks, which are sets of column parts. The internal processing cycles for a single block are efficient but there are noticeable costs when processing each block.
134 : 113429 :
135 : 113429 : The `max_block_size` setting indicates the recommended maximum number of rows to include in a single block when loading data from tables. Blocks the size of `max_block_size` are not always loaded from the table: if ClickHouse determines that less data needs to be retrieved, a smaller block is processed.
136 : 113429 :
137 : 113429 : The block size should not be too small to avoid noticeable costs when processing each block. It should also not be too large to ensure that queries with a LIMIT clause execute quickly after processing the first block. When setting `max_block_size`, the goal should be to avoid consuming too much memory when extracting a large number of columns in multiple threads and to preserve at least some cache locality.
138 : 113429 : )", 0) \
139 : 113429 : DECLARE(Bool, use_strict_insert_block_limits, false, R"(
140 : 113429 : When enabled, strictly enforces both minimum and maximum insert block size limits.
141 : 113429 :
142 : 113429 : A block is emitted when:
143 : 113429 : - Min thresholds (AND): Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached.
144 : 113429 : - Max thresholds (OR): Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached.
145 : 113429 :
146 : 113429 : When disabled, a block is emitted when:
147 : 113429 : - Min thresholds (OR): min_insert_block_size_rows OR min_insert_block_size_bytes is reached.
148 : 113429 :
149 : 113429 : **Note**: If max settings are smaller than min settings, the max limits take precedence and blocks will be emitted before min thresholds are reached.
150 : 113429 :
151 : 113429 : **Note**: This setting is automatically disabled for async inserts, because async inserts attach per-entry deduplication tokens that are incompatible with block splitting that is needed for enforcement of strict limits.
152 : 113429 :
153 : 113429 : Disabled by default.
154 : 113429 : )", 0) \
155 : 113429 : DECLARE_WITH_ALIAS(NonZeroUInt64, max_insert_block_size, DEFAULT_INSERT_BLOCK_SIZE, R"(
156 : 113429 : The maximum size of blocks (in a count of rows) to form for insertion into a table.
157 : 113429 :
158 : 113429 : This setting controls block formation in two contexts:
159 : 113429 :
160 : 113429 : 1. Format parsing: When the server parses row-based input formats (CSV, TSV, JSONEachRow, etc.) from any interface (HTTP, clickhouse-client with inline data, gRPC, PostgreSQL wire protocol), blocks are emitted when:
161 : 113429 : - Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached, OR
162 : 113429 : - Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached
163 : 113429 :
164 : 113429 : Note: When using clickhouse-client or clickhouse-local to read from a file, the client itself parses the data and this setting applies on the client side.
165 : 113429 :
166 : 113429 : 2. INSERT operations: During INSERT queries and when data flows through materialized views, this setting's behavior depends on `use_strict_insert_block_limits`:
167 : 113429 :
168 : 113429 : - When enabled: Blocks are emitted when:
169 : 113429 : - Min thresholds (AND): Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached
170 : 113429 : - Max thresholds (OR): Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached
171 : 113429 :
172 : 113429 : - When disabled: Blocks are emitted when min_insert_block_size_rows OR min_insert_block_size_bytes is reached. The max_insert_block_size settings are not enforced.
173 : 113429 :
174 : 113429 : Possible values:
175 : 113429 : - Positive integer.
176 : 113429 : )", 0, max_insert_block_size_rows) \
177 : 113429 : DECLARE(UInt64, max_insert_block_size_bytes, 0, R"(
178 : 113429 : The maximum size of blocks (in bytes) to form for insertion into a table.
179 : 113429 :
180 : 113429 : This setting works together with max_insert_block_size_rows and controls block formation in the same context. See max_insert_block_size_rows for detailed information about when and how these settings are applied.
181 : 113429 :
182 : 113429 : Possible values:
183 : 113429 : - Positive integer.
184 : 113429 : - 0 — setting does not participate in block formation.
185 : 113429 : )", 0) \
186 : 113429 : DECLARE(UInt64, min_insert_block_size_rows, DEFAULT_INSERT_BLOCK_SIZE, R"(
187 : 113429 : The minimum size of blocks (in rows) to form for insertion into a table.
188 : 113429 :
189 : 113429 : This setting controls block formation in two contexts:
190 : 113429 :
191 : 113429 : 1. Format parsing: When the server parses row-based input formats (CSV, TSV, JSONEachRow, etc.) from any interface (HTTP, clickhouse-client with inline data, gRPC, PostgreSQL wire protocol), blocks are emitted when:
192 : 113429 : - Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached, OR
193 : 113429 : - Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached
194 : 113429 :
195 : 113429 : Note: When using clickhouse-client or clickhouse-local to read from a file, the client itself parses the data and this setting applies on the client side.
196 : 113429 :
197 : 113429 : 2. INSERT operations: During INSERT queries and when data flows through materialized views, this setting's behavior depends on `use_strict_insert_block_limits`:
198 : 113429 :
199 : 113429 : - When enabled: Blocks are emitted when:
200 : 113429 : - Min thresholds (AND): Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached
201 : 113429 : - Max thresholds (OR): Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached
202 : 113429 :
203 : 113429 : - When disabled (default): Blocks are emitted when min_insert_block_size_rows OR min_insert_block_size_bytes is reached. The max_insert_block_size settings are not enforced.
204 : 113429 :
205 : 113429 : Possible values:
206 : 113429 : - Positive integer.
207 : 113429 : - 0 — setting does not participate in block formation.
208 : 113429 : )", 0) \
209 : 113429 : DECLARE(UInt64, min_insert_block_size_bytes, (DEFAULT_INSERT_BLOCK_SIZE * 256), R"(
210 : 113429 : The minimum size of blocks (in bytes) to form for insertion into a table.
211 : 113429 :
212 : 113429 : This setting works together with min_insert_block_size_rows and controls block formation in the same contexts (format parsing and INSERT operations). See min_insert_block_size_rows for detailed information about when and how these settings are applied.
213 : 113429 :
214 : 113429 : Possible values:
215 : 113429 :
216 : 113429 : - Positive integer.
217 : 113429 : - 0 — setting does not participate in block formation.
218 : 113429 : )", 0) \
219 : 113429 : DECLARE(UInt64, min_insert_block_size_rows_for_materialized_views, 0, R"(
220 : 113429 : 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](../../sql-reference/statements/create/view.md). By adjusting this setting, you control blocks squashing while pushing to materialized view and avoid excessive memory usage.
221 : 113429 :
222 : 113429 : Possible values:
223 : 113429 :
224 : 113429 : - Any positive integer.
225 : 113429 : - 0 — Squashing disabled.
226 : 113429 :
227 : 113429 : **See Also**
228 : 113429 :
229 : 113429 : - [min_insert_block_size_rows](#min_insert_block_size_rows)
230 : 113429 : )", 0) \
231 : 113429 : DECLARE(UInt64, min_insert_block_size_bytes_for_materialized_views, 0, R"(
232 : 113429 : 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](../../sql-reference/statements/create/view.md). By adjusting this setting, you control blocks squashing while pushing to materialized view and avoid excessive memory usage.
233 : 113429 :
234 : 113429 : Possible values:
235 : 113429 :
236 : 113429 : - Any positive integer.
237 : 113429 : - 0 — Squashing disabled.
238 : 113429 :
239 : 113429 : **See also**
240 : 113429 :
241 : 113429 : - [min_insert_block_size_bytes](#min_insert_block_size_bytes)
242 : 113429 : )", 0) \
243 : 113429 : DECLARE(UInt64, min_external_table_block_size_rows, DEFAULT_INSERT_BLOCK_SIZE, R"(
244 : 113429 : Squash blocks passed to external table to specified size in rows, if blocks are not big enough.
245 : 113429 : )", 0) \
246 : 113429 : DECLARE(UInt64, min_external_table_block_size_bytes, (DEFAULT_INSERT_BLOCK_SIZE * 256), R"(
247 : 113429 : Squash blocks passed to the external table to a specified size in bytes, if blocks are not big enough.
248 : 113429 : )", 0) \
249 : 113429 : DECLARE(UInt64, max_joined_block_size_rows, DEFAULT_BLOCK_SIZE, R"(
250 : 113429 : Maximum block size for JOIN result (if join algorithm supports it). 0 means unlimited.
251 : 113429 : )", 0) \
252 : 113429 : DECLARE(UInt64, max_joined_block_size_bytes, 4_MiB, R"(
253 : 113429 : Maximum block size in bytes for JOIN result (if join algorithm supports it). 0 means unlimited.
254 : 113429 : )", 0) \
255 : 113429 : DECLARE(UInt64, min_joined_block_size_rows, DEFAULT_BLOCK_SIZE, R"(
256 : 113429 : Minimum block size in rows for JOIN input and output blocks (if join algorithm supports it). Small blocks will be squashed. 0 means unlimited.
257 : 113429 : )", 0) \
258 : 113429 : DECLARE(UInt64, min_joined_block_size_bytes, 512 * 1024, R"(
259 : 113429 : Minimum block size in bytes for JOIN input and output blocks (if join algorithm supports it). Small blocks will be squashed. 0 means unlimited.
260 : 113429 : )", 0) \
261 : 113429 : DECLARE(Bool, joined_block_split_single_row, false, R"(
262 : 113429 : Allow to chunk hash join result by rows corresponding to single row from left table.
263 : 113429 : This may reduce memory usage in case of row with many matches in right table, but may increase CPU usage.
264 : 113429 : Note that `max_joined_block_size_rows != 0` is mandatory for this setting to have effect.
265 : 113429 : The `max_joined_block_size_bytes` combined with this setting is helpful to avoid excessive memory usage in case of skewed data with some large rows having many matches in right table.
266 : 113429 : )", 0) \
267 : 113429 : DECLARE(Bool, parallel_non_joined_rows_processing, true, R"(
268 : 113429 : Allow multiple threads to process non-joined rows from the right table in parallel during RIGHT and FULL JOINs.
269 : 113429 : This can speed up the non-joined phase when using the `parallel_hash` join algorithm with large tables.
270 : 113429 : When disabled, non-joined rows are processed by a single thread.
271 : 113429 : )", 0) \
272 : 113429 : DECLARE(UInt64, max_insert_threads, 0, R"(
273 : 113429 : The maximum number of threads to execute the `INSERT SELECT` query.
274 : 113429 :
275 : 113429 : Possible values:
276 : 113429 :
277 : 113429 : - 0 (or 1) — `INSERT SELECT` no parallel execution.
278 : 113429 : - Positive integer. Bigger than 1.
279 : 113429 :
280 : 113429 : Cloud default value:
281 : 113429 : - `1` for nodes with 8 GiB memory
282 : 113429 : - `2` for nodes with 16 GiB memory
283 : 113429 : - `4` for larger nodes
284 : 113429 :
285 : 113429 : Parallel `INSERT SELECT` has effect only if the `SELECT` part is executed in parallel, see [`max_threads`](#max_threads) setting.
286 : 113429 : Higher values will lead to higher memory usage.
287 : 113429 : )", 0) \
288 : 113429 : DECLARE(UInt64, max_insert_delayed_streams_for_parallel_write, 0, R"(
289 : 113429 : The maximum number of streams (columns) to delay final part flush. Default - auto (100 in case of underlying storage supports parallel write, for example S3 and disabled otherwise)
290 : 113429 :
291 : 113429 : Cloud default value: `50`.
292 : 113429 : )", 0) \
293 : 113429 : DECLARE(Bool, finalize_projection_parts_synchronously, false, R"(
294 : 113429 : When enabled, projection parts are finalized synchronously during INSERT, reducing peak memory usage at the cost of reduced S3 upload parallelism. By default, each projection's output stream is kept alive until the entire part (including all projections) is finalized, which allows overlapping S3 uploads but increases peak memory proportional to the number of projections. This setting only affects the INSERT path; merge and mutation already finalize projections synchronously.
295 : 113429 : )", 0) \
296 : 113429 : DECLARE(MaxThreads, max_final_threads, 0, R"(
297 : 113429 : Sets the maximum number of parallel threads for the `SELECT` query data read phase with the [FINAL](/sql-reference/statements/select/from#final-modifier) modifier.
298 : 113429 :
299 : 113429 : Possible values:
300 : 113429 :
301 : 113429 : - Positive integer.
302 : 113429 : - 0 or 1 — Disabled. `SELECT` queries are executed in a single thread.
303 : 113429 : )", 0) \
304 : 113429 : DECLARE(UInt64, max_threads_for_indexes, 0, R"(
305 : 113429 : The maximum number of threads process indices.
306 : 113429 : )", 0) \
307 : 113429 : DECLARE(MaxThreads, max_threads, 0, R"(
308 : 113429 : The maximum number of query processing threads, excluding threads for retrieving data from remote servers (see the ['max_distributed_connections'](/operations/settings/settings#max_distributed_connections) parameter).
309 : 113429 :
310 : 113429 : This parameter applies to threads that perform the same stages of the query processing pipeline in parallel.
311 : 113429 : For example, when reading from a table, if it is possible to evaluate expressions with functions, filter with `WHERE` and pre-aggregate for `GROUP BY` in parallel using at least 'max_threads' number of threads, then 'max_threads' are used.
312 : 113429 :
313 : 113429 : For queries that are completed quickly because of a LIMIT, you can set a lower 'max_threads'.
314 : 113429 : For example, if the necessary number of entries are located in every block and max_threads = 8, then 8 blocks are retrieved, although it would have been enough to read just one.
315 : 113429 : The smaller the `max_threads` value, the less memory is consumed.
316 : 113429 :
317 : 113429 : The `max_threads` setting by default matches the number of hardware threads (number of CPU cores) available to ClickHouse.
318 : 113429 : As a special case, for x86 processors with less than 32 CPU cores and SMT (e.g. Intel HyperThreading), ClickHouse uses the number of logical cores (= 2 x physical core count) by default.
319 : 113429 :
320 : 113429 : Without SMT (e.g. Intel HyperThreading), this corresponds to the number of CPU cores.
321 : 113429 :
322 : 113429 : For ClickHouse Cloud users, the default value will display as `auto(N)` where N matches the vCPU size of your service e.g. 2vCPU/8GiB, 4vCPU/16GiB etc.
323 : 113429 : See the settings tab in the Cloud console for a list of all service sizes.
324 : 113429 : )", 0) \
325 : 113429 : DECLARE(Bool, use_concurrency_control, true, R"(
326 : 113429 : 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).
327 : 113429 :
328 : 113429 : Cloud default value: `0`.
329 : 113429 : )", 0) \
330 : 113429 : DECLARE(MaxThreads, max_download_threads, 4, R"(
331 : 113429 : The maximum number of threads to download data (e.g. for URL engine).
332 : 113429 : )", 0) \
333 : 113429 : DECLARE(MaxThreads, max_parsing_threads, 0, R"(
334 : 113429 : The maximum number of threads to parse data in input formats that support parallel parsing. By default, it is determined automatically.
335 : 113429 : )", 0) \
336 : 113429 : DECLARE(UInt64, max_download_buffer_size, 10*1024*1024, R"(
337 : 113429 : The maximal size of buffer for parallel downloading (e.g. for URL engine) per each thread.
338 : 113429 : )", 0) \
339 : 113429 : DECLARE(NonZeroUInt64, max_read_buffer_size, DBMS_DEFAULT_BUFFER_SIZE, R"(
340 : 113429 : The maximum size of the buffer to read from the filesystem.
341 : 113429 : )", 0) \
342 : 113429 : DECLARE(UInt64, max_read_buffer_size_local_fs, 128*1024, R"(
343 : 113429 : The maximum size of the buffer to read from local filesystem. If set to 0 then max_read_buffer_size will be used.
344 : 113429 : )", 0) \
345 : 113429 : DECLARE(UInt64, max_read_buffer_size_remote_fs, 0, R"(
346 : 113429 : The maximum size of the buffer to read from remote filesystem. If set to 0 then max_read_buffer_size will be used.
347 : 113429 : )", 0) \
348 : 113429 : DECLARE(UInt64, max_distributed_connections, 1024, R"(
349 : 113429 : 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.
350 : 113429 :
351 : 113429 : 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.
352 : 113429 : )", 0) \
353 : 113429 : DECLARE(UInt64, max_query_size, DBMS_DEFAULT_MAX_QUERY_SIZE, R"(
354 : 113429 : The maximum number of bytes of a query string parsed by the SQL parser.
355 : 113429 : Data in the VALUES clause of INSERT queries is processed by a separate stream parser (that consumes O(1) RAM) and not affected by this restriction.
356 : 113429 :
357 : 113429 : :::note
358 : 113429 : `max_query_size` cannot be set within an SQL query (e.g., `SELECT now() SETTINGS max_query_size=10000`) because ClickHouse needs to allocate a buffer to parse the query, and this buffer size is determined by the `max_query_size` setting, which must be configured before the query is executed.
359 : 113429 : :::
360 : 113429 : )", 0) \
361 : 113429 : DECLARE(UInt64, interactive_delay, 100000, R"(
362 : 113429 : The interval in microseconds for checking whether request execution has been canceled and sending the progress.
363 : 113429 : )", 0) \
364 : 113429 : DECLARE(Seconds, connect_timeout, DBMS_DEFAULT_CONNECT_TIMEOUT_SEC, R"(
365 : 113429 : Connection timeout if there are no replicas.
366 : 113429 : )", 0) \
367 : 113429 : DECLARE(Milliseconds, handshake_timeout_ms, 10000, R"(
368 : 113429 : Timeout in milliseconds for receiving Hello packet from replicas during handshake.
369 : 113429 : )", 0) \
370 : 113429 : DECLARE(Milliseconds, connect_timeout_with_failover_ms, 1000, R"(
371 : 113429 : The timeout in milliseconds for connecting to a remote server for a Distributed table engine, if the 'shard' and 'replica' sections are used in the cluster definition.
372 : 113429 : If unsuccessful, several attempts are made to connect to various replicas.
373 : 113429 : )", 0) \
374 : 113429 : DECLARE(Milliseconds, connect_timeout_with_failover_secure_ms, 1000, R"(
375 : 113429 : Connection timeout for selecting first healthy replica (for secure connections).
376 : 113429 : )", 0) \
377 : 113429 : DECLARE(Seconds, receive_timeout, DBMS_DEFAULT_RECEIVE_TIMEOUT_SEC, R"(
378 : 113429 : Timeout for receiving data from the network, in seconds. If no bytes were received in this interval, the exception is thrown. If you set this setting on the client, the 'send_timeout' for the socket will also be set on the corresponding connection end on the server.
379 : 113429 : )", 0) \
380 : 113429 : DECLARE(Seconds, send_timeout, DBMS_DEFAULT_SEND_TIMEOUT_SEC, R"(
381 : 113429 : 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.
382 : 113429 : )", 0) \
383 : 113429 : DECLARE(Seconds, tcp_keep_alive_timeout, DEFAULT_TCP_KEEP_ALIVE_TIMEOUT /* less than DBMS_DEFAULT_RECEIVE_TIMEOUT_SEC */, R"(
384 : 113429 : The time in seconds the connection needs to remain idle before TCP starts sending keepalive probes
385 : 113429 : )", 0) \
386 : 113429 : DECLARE(Milliseconds, hedged_connection_timeout_ms, 50, R"(
387 : 113429 : Connection timeout for establishing connection with replica for Hedged requests
388 : 113429 : )", 0) \
389 : 113429 : DECLARE(Milliseconds, receive_data_timeout_ms, 2000, R"(
390 : 113429 : Connection timeout for receiving first packet of data or packet with positive progress from replica
391 : 113429 : )", 0) \
392 : 113429 : DECLARE(Bool, use_hedged_requests, true, R"(
393 : 113429 : Enables hedged requests logic for remote queries. It allows to establish many connections with different replicas for query.
394 : 113429 : New connection is enabled in case existent connection(s) with replica(s) were not established within `hedged_connection_timeout`
395 : 113429 : or no data was received within `receive_data_timeout`. Query uses the first connection which send non empty progress packet (or data packet, if `allow_changing_replica_until_first_data_packet`);
396 : 113429 : other connections are cancelled. Queries with `max_parallel_replicas > 1` are supported.
397 : 113429 :
398 : 113429 : Enabled by default.
399 : 113429 :
400 : 113429 : Cloud default value: `0`.
401 : 113429 : )", 0) \
402 : 113429 : DECLARE(Bool, allow_changing_replica_until_first_data_packet, false, R"(
403 : 113429 : If it's enabled, in hedged requests we can start new connection until receiving first data packet even if we have already made some progress
404 : 113429 : (but progress haven't updated for `receive_data_timeout` timeout), otherwise we disable changing replica after the first time we made progress.
405 : 113429 : )", 0) \
406 : 113429 : DECLARE(Milliseconds, queue_max_wait_ms, 0, R"(
407 : 113429 : The wait time in the request queue, if the number of concurrent requests exceeds the maximum.
408 : 113429 : )", 0) \
409 : 113429 : DECLARE(Milliseconds, connection_pool_max_wait_ms, 0, R"(
410 : 113429 : The wait time in milliseconds for a connection when the connection pool is full.
411 : 113429 :
412 : 113429 : Possible values:
413 : 113429 :
414 : 113429 : - Positive integer.
415 : 113429 : - 0 — Infinite timeout.
416 : 113429 : )", 0) \
417 : 113429 : DECLARE(Milliseconds, replace_running_query_max_wait_ms, 5000, R"(
418 : 113429 : The wait time for running the query with the same `query_id` to finish, when the [replace_running_query](#replace_running_query) setting is active.
419 : 113429 :
420 : 113429 : Possible values:
421 : 113429 :
422 : 113429 : - Positive integer.
423 : 113429 : - 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`.
424 : 113429 : )", 0) \
425 : 113429 : DECLARE(Milliseconds, kafka_max_wait_ms, 5000, R"(
426 : 113429 : The wait time in milliseconds for reading messages from [Kafka](/engines/table-engines/integrations/kafka) before retry.
427 : 113429 :
428 : 113429 : Possible values:
429 : 113429 :
430 : 113429 : - Positive integer.
431 : 113429 : - 0 — Infinite timeout.
432 : 113429 :
433 : 113429 : See also:
434 : 113429 :
435 : 113429 : - [Apache Kafka](https://kafka.apache.org/)
436 : 113429 : )", 0) \
437 : 113429 : DECLARE(Milliseconds, rabbitmq_max_wait_ms, 5000, R"(
438 : 113429 : The wait time for reading from RabbitMQ before retry.
439 : 113429 : )", 0) \
440 : 113429 : DECLARE(UInt64, poll_interval, DBMS_DEFAULT_POLL_INTERVAL, R"(
441 : 113429 : Block at the query wait loop on the server for the specified number of seconds.
442 : 113429 : )", 0) \
443 : 113429 : DECLARE(UInt64, idle_connection_timeout, 3600, R"(
444 : 113429 : Timeout to close idle TCP connections after specified number of seconds.
445 : 113429 :
446 : 113429 : Possible values:
447 : 113429 :
448 : 113429 : - Positive integer (0 - close immediately, after 0 seconds).
449 : 113429 : )", 0) \
450 : 113429 : DECLARE(UInt64, distributed_connections_pool_size, 1024, R"(
451 : 113429 : The maximum number of simultaneous connections with remote servers for distributed processing of all queries to a single Distributed table. We recommend setting a value no less than the number of servers in the cluster.
452 : 113429 : )", 0) \
453 : 113429 : DECLARE(UInt64, connections_with_failover_max_tries, 3, R"(
454 : 113429 : The maximum number of connection attempts with each replica for the Distributed table engine.
455 : 113429 : )", 0) \
456 : 113429 : DECLARE(UInt64, s3_strict_upload_part_size, S3::DEFAULT_STRICT_UPLOAD_PART_SIZE, R"(
457 : 113429 : The exact size of part to upload during multipart upload to S3 (some implementations does not supports variable size parts).
458 : 113429 : )", 0) \
459 : 113429 : DECLARE(UInt64, azure_strict_upload_part_size, 0, R"(
460 : 113429 : The exact size of part to upload during multipart upload to Azure blob storage.
461 : 113429 : )", 0) \
462 : 113429 : DECLARE(UInt64, azure_max_blocks_in_multipart_upload, 50000, R"(
463 : 113429 : Maximum number of blocks in multipart upload for Azure.
464 : 113429 : )", 0) \
465 : 113429 : DECLARE(UInt64, s3_min_upload_part_size, S3::DEFAULT_MIN_UPLOAD_PART_SIZE, R"(
466 : 113429 : The minimum size of part to upload during multipart upload to S3.
467 : 113429 : )", 0) \
468 : 113429 : DECLARE(UInt64, s3_max_upload_part_size, S3::DEFAULT_MAX_UPLOAD_PART_SIZE, R"(
469 : 113429 : The maximum size of part to upload during multipart upload to S3.
470 : 113429 : )", 0) \
471 : 113429 : DECLARE(UInt64, azure_min_upload_part_size, 16*1024*1024, R"(
472 : 113429 : The minimum size of part to upload during multipart upload to Azure blob storage.
473 : 113429 : )", 0) \
474 : 113429 : DECLARE(UInt64, azure_max_upload_part_size, 5ull*1024*1024*1024, R"(
475 : 113429 : The maximum size of part to upload during multipart upload to Azure blob storage.
476 : 113429 : )", 0) \
477 : 113429 : DECLARE(UInt64, s3_upload_part_size_multiply_factor, S3::DEFAULT_UPLOAD_PART_SIZE_MULTIPLY_FACTOR, R"(
478 : 113429 : 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.
479 : 113429 : )", 0) \
480 : 113429 : DECLARE(UInt64, s3_upload_part_size_multiply_parts_count_threshold, S3::DEFAULT_UPLOAD_PART_SIZE_MULTIPLY_PARTS_COUNT_THRESHOLD, R"(
481 : 113429 : Each time this number of parts was uploaded to S3, s3_min_upload_part_size is multiplied by s3_upload_part_size_multiply_factor.
482 : 113429 : )", 0) \
483 : 113429 : DECLARE(UInt64, s3_max_part_number, S3::DEFAULT_MAX_PART_NUMBER, R"(
484 : 113429 : Maximum part number number for s3 upload part.
485 : 113429 : )", 0) \
486 : 113429 : DECLARE(Bool, s3_allow_multipart_copy, true, R"(
487 : 113429 : Allow multipart copy in S3.
488 : 113429 : )", 0) \
489 : 113429 : DECLARE(UInt64, s3_max_single_operation_copy_size, S3::DEFAULT_MAX_SINGLE_OPERATION_COPY_SIZE, R"(
490 : 113429 : Maximum size for single-operation copy in s3. This setting is used only if s3_allow_multipart_copy is true.
491 : 113429 : )", 0) \
492 : 113429 : DECLARE(UInt64, azure_upload_part_size_multiply_factor, 2, R"(
493 : 113429 : Multiply azure_min_upload_part_size by this factor each time azure_multiply_parts_count_threshold parts were uploaded from a single write to Azure blob storage.
494 : 113429 : )", 0) \
495 : 113429 : DECLARE(UInt64, azure_upload_part_size_multiply_parts_count_threshold, 500, R"(
496 : 113429 : Each time this number of parts was uploaded to Azure blob storage, azure_min_upload_part_size is multiplied by azure_upload_part_size_multiply_factor.
497 : 113429 : )", 0) \
498 : 113429 : DECLARE(UInt64, s3_max_inflight_parts_for_one_file, S3::DEFAULT_MAX_INFLIGHT_PARTS_FOR_ONE_FILE, R"(
499 : 113429 : The maximum number of a concurrent loaded parts in multipart upload request. 0 means unlimited.
500 : 113429 : )", 0) \
501 : 113429 : DECLARE(UInt64, azure_max_inflight_parts_for_one_file, 20, R"(
502 : 113429 : The maximum number of a concurrent loaded parts in multipart upload request. 0 means unlimited.
503 : 113429 : )", 0) \
504 : 113429 : DECLARE(UInt64, s3_max_single_part_upload_size, S3::DEFAULT_MAX_SINGLE_PART_UPLOAD_SIZE, R"(
505 : 113429 : The maximum size of object to upload using singlepart upload to S3.
506 : 113429 : )", 0) \
507 : 113429 : DECLARE(UInt64, azure_max_single_part_upload_size, S3::DEFAULT_MAX_SINGLE_PART_UPLOAD_SIZE, R"(
508 : 113429 : The maximum size of object to upload using singlepart upload to Azure blob storage.
509 : 113429 : )", 0) \
510 : 113429 : DECLARE(UInt64, azure_max_single_part_copy_size, 256*1024*1024, R"(
511 : 113429 : The maximum size of object to copy using single part copy to Azure blob storage.
512 : 113429 : )", 0) \
513 : 113429 : DECLARE(UInt64, s3_max_single_read_retries, S3::DEFAULT_MAX_SINGLE_READ_TRIES, R"(
514 : 113429 : The maximum number of retries during single S3 read.
515 : 113429 : )", 0) \
516 : 113429 : DECLARE(UInt64, azure_max_single_read_retries, 4, R"(
517 : 113429 : The maximum number of retries during single Azure blob storage read.
518 : 113429 : )", 0) \
519 : 113429 : DECLARE(UInt64, azure_max_unexpected_write_error_retries, 4, R"(
520 : 113429 : The maximum number of retries in case of unexpected errors during Azure blob storage write
521 : 113429 : )", 0) \
522 : 113429 : DECLARE(UInt64, s3_max_unexpected_write_error_retries, S3::DEFAULT_MAX_UNEXPECTED_WRITE_ERROR_RETRIES, R"(
523 : 113429 : The maximum number of retries in case of unexpected errors during S3 write.
524 : 113429 : )", 0) \
525 : 113429 : DECLARE(UInt64, azure_max_redirects, S3::DEFAULT_MAX_REDIRECTS, R"(
526 : 113429 : Max number of azure redirects hops allowed.
527 : 113429 : )", 0) \
528 : 113429 : DECLARE(UInt64, azure_max_get_rps, 0, R"(
529 : 113429 : Limit on Azure GET request per second rate before throttling. Zero means unlimited.
530 : 113429 : )", 0) \
531 : 113429 : DECLARE(UInt64, azure_max_get_burst, 0, R"(
532 : 113429 : Max number of requests that can be issued simultaneously before hitting request per second limit. By default (0) equals to `azure_max_get_rps`
533 : 113429 : )", 0) \
534 : 113429 : DECLARE(UInt64, azure_max_put_rps, 0, R"(
535 : 113429 : Limit on Azure PUT request per second rate before throttling. Zero means unlimited.
536 : 113429 : )", 0) \
537 : 113429 : DECLARE(UInt64, azure_max_put_burst, 0, R"(
538 : 113429 : Max number of requests that can be issued simultaneously before hitting request per second limit. By default (0) equals to `azure_max_put_rps`
539 : 113429 : )", 0) \
540 : 113429 : DECLARE(UInt64, s3_max_connections, S3::DEFAULT_MAX_CONNECTIONS, R"(
541 : 113429 : The maximum number of connections per server.
542 : 113429 : )", 0) \
543 : 113429 : DECLARE(UInt64, s3_max_get_rps, 0, R"(
544 : 113429 : Limit on S3 GET request per second rate before throttling. Zero means unlimited.
545 : 113429 : )", 0) \
546 : 113429 : DECLARE(UInt64, s3_max_get_burst, 0, R"(
547 : 113429 : Max number of requests that can be issued simultaneously before hitting request per second limit. By default (0) equals to `s3_max_get_rps`
548 : 113429 : )", 0) \
549 : 113429 : DECLARE(UInt64, s3_max_put_rps, 0, R"(
550 : 113429 : Limit on S3 PUT request per second rate before throttling. Zero means unlimited.
551 : 113429 : )", 0) \
552 : 113429 : DECLARE(UInt64, s3_max_put_burst, 0, R"(
553 : 113429 : Max number of requests that can be issued simultaneously before hitting request per second limit. By default (0) equals to `s3_max_put_rps`
554 : 113429 : )", 0) \
555 : 113429 : DECLARE(UInt64, s3_list_object_keys_size, S3::DEFAULT_LIST_OBJECT_KEYS_SIZE, R"(
556 : 113429 : Maximum number of files that could be returned in batch by ListObject request
557 : 113429 : )", 0) \
558 : 113429 : DECLARE(Bool, s3_use_adaptive_timeouts, S3::DEFAULT_USE_ADAPTIVE_TIMEOUTS, R"(
559 : 113429 : When set to `true` than for all s3 requests first two attempts are made with low send and receive timeouts.
560 : 113429 : When set to `false` than all attempts are made with identical timeouts.
561 : 113429 : )", 0) \
562 : 113429 : DECLARE(Bool, azure_use_adaptive_timeouts, S3::DEFAULT_USE_ADAPTIVE_TIMEOUTS, R"(
563 : 113429 : When set to `true` than for all azure requests first two attempts are made with low send and receive timeouts.
564 : 113429 : When set to `false` than all attempts are made with identical timeouts.
565 : 113429 : )", 0) \
566 : 113429 : DECLARE(Bool, s3_slow_all_threads_after_network_error, true, R"(
567 : 113429 : When set to `true`, all threads executing S3 requests to the same backup endpoint are slowed down
568 : 113429 : after any single s3 request encounters a retryable network error, such as socket timeout.
569 : 113429 : When set to `false`, each thread handles S3 request backoff independently of the others.
570 : 113429 : )", 0) \
571 : 113429 : DECLARE(Bool, backup_slow_all_threads_after_retryable_s3_error, false, R"(
572 : 113429 : When set to `true`, all threads executing S3 requests to the same backup endpoint are slowed down
573 : 113429 : after any single S3 request encounters a retryable S3 error, such as 'Slow Down'.
574 : 113429 : When set to `false`, each thread handles s3 request backoff independently of the others.
575 : 113429 : )", 0) \
576 : 113429 : DECLARE(UInt64, azure_list_object_keys_size, 1000, R"(
577 : 113429 : Maximum number of files that could be returned in batch by ListObject request
578 : 113429 : )", 0) \
579 : 113429 : DECLARE(Bool, s3_truncate_on_insert, false, R"(
580 : 113429 : 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.
581 : 113429 :
582 : 113429 : Possible values:
583 : 113429 : - 0 — `INSERT` query creates a new file or fail if file exists and s3_create_new_file_on_insert is not set.
584 : 113429 : - 1 — `INSERT` query replaces existing content of the file with the new data.
585 : 113429 :
586 : 113429 : See more details [here](/integrations/s3#inserting-data).
587 : 113429 : )", 0) \
588 : 113429 : DECLARE(Bool, azure_truncate_on_insert, false, R"(
589 : 113429 : Enables or disables truncate before insert in azure engine tables.
590 : 113429 : )", 0) \
591 : 113429 : DECLARE(Bool, s3_create_new_file_on_insert, false, R"(
592 : 113429 : 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:
593 : 113429 :
594 : 113429 : initial: `data.Parquet.gz` -> `data.1.Parquet.gz` -> `data.2.Parquet.gz`, etc.
595 : 113429 :
596 : 113429 : Possible values:
597 : 113429 : - 0 — `INSERT` query creates a new file or fail if file exists and s3_truncate_on_insert is not set.
598 : 113429 : - 1 — `INSERT` query creates a new file on each insert using suffix (from the second one) if s3_truncate_on_insert is not set.
599 : 113429 :
600 : 113429 : See more details [here](/integrations/s3#inserting-data).
601 : 113429 : )", 0) \
602 : 113429 : DECLARE(Bool, s3_skip_empty_files, true, R"(
603 : 113429 : Enables or disables skipping empty files in [S3](../../engines/table-engines/integrations/s3.md) engine tables.
604 : 113429 :
605 : 113429 : Possible values:
606 : 113429 : - 0 — `SELECT` throws an exception if empty file is not compatible with requested format.
607 : 113429 : - 1 — `SELECT` returns empty result for empty file.
608 : 113429 : )", 0) \
609 : 113429 : DECLARE(Bool, azure_create_new_file_on_insert, false, R"(
610 : 113429 : Enables or disables creating a new file on each insert in azure engine tables
611 : 113429 : )", 0) \
612 : 113429 : DECLARE(Bool, s3_check_objects_after_upload, false, R"(
613 : 113429 : Check each uploaded object to s3 with head request to be sure that upload was successful
614 : 113429 : )", 0) \
615 : 113429 : DECLARE(Bool, azure_check_objects_after_upload, false, R"(
616 : 113429 : Check each uploaded object in azure blob storage to be sure that upload was successful
617 : 113429 : )", 0) \
618 : 113429 : DECLARE(Bool, s3_allow_parallel_part_upload, true, R"(
619 : 113429 : Use multiple threads for s3 multipart upload. It may lead to slightly higher memory usage
620 : 113429 : )", 0) \
621 : 113429 : DECLARE(Bool, azure_allow_parallel_part_upload, true, R"(
622 : 113429 : Use multiple threads for azure multipart upload.
623 : 113429 : )", 0) \
624 : 113429 : DECLARE(Bool, s3_throw_on_zero_files_match, false, R"(
625 : 113429 : Throw an error, when ListObjects request cannot match any files
626 : 113429 : )", 0) \
627 : 113429 : DECLARE(Bool, hdfs_throw_on_zero_files_match, false, R"(
628 : 113429 : Throw an error if matched zero files according to glob expansion rules.
629 : 113429 :
630 : 113429 : Possible values:
631 : 113429 : - 1 — `SELECT` throws an exception.
632 : 113429 : - 0 — `SELECT` returns empty result.
633 : 113429 : )", 0) \
634 : 113429 : DECLARE(Bool, azure_throw_on_zero_files_match, false, R"(
635 : 113429 : Throw an error if matched zero files according to glob expansion rules.
636 : 113429 :
637 : 113429 : Possible values:
638 : 113429 : - 1 — `SELECT` throws an exception.
639 : 113429 : - 0 — `SELECT` returns empty result.
640 : 113429 : )", 0) \
641 : 113429 : DECLARE(Bool, s3_ignore_file_doesnt_exist, false, R"(
642 : 113429 : Ignore absence of file if it does not exist when reading certain keys.
643 : 113429 :
644 : 113429 : Possible values:
645 : 113429 : - 1 — `SELECT` returns empty result.
646 : 113429 : - 0 — `SELECT` throws an exception.
647 : 113429 : )", 0) \
648 : 113429 : DECLARE(Bool, hdfs_ignore_file_doesnt_exist, false, R"(
649 : 113429 : Ignore absence of file if it does not exist when reading certain keys.
650 : 113429 :
651 : 113429 : Possible values:
652 : 113429 : - 1 — `SELECT` returns empty result.
653 : 113429 : - 0 — `SELECT` throws an exception.
654 : 113429 : )", 0) \
655 : 113429 : DECLARE(Bool, azure_ignore_file_doesnt_exist, false, R"(
656 : 113429 : Ignore absence of file if it does not exist when reading certain keys.
657 : 113429 :
658 : 113429 : Possible values:
659 : 113429 : - 1 — `SELECT` returns empty result.
660 : 113429 : - 0 — `SELECT` throws an exception.
661 : 113429 : )", 0) \
662 : 113429 : DECLARE(UInt64, azure_sdk_max_retries, 10, R"(
663 : 113429 : Maximum number of retries in azure sdk
664 : 113429 : )", 0) \
665 : 113429 : DECLARE(UInt64, azure_sdk_retry_initial_backoff_ms, 10, R"(
666 : 113429 : Minimal backoff between retries in azure sdk
667 : 113429 : )", 0) \
668 : 113429 : DECLARE(UInt64, azure_sdk_retry_max_backoff_ms, 1000, R"(
669 : 113429 : Maximal backoff between retries in azure sdk
670 : 113429 : )", 0) \
671 : 113429 : DECLARE(UInt64, azure_request_timeout_ms, S3::DEFAULT_REQUEST_TIMEOUT_MS, R"(
672 : 113429 : Idleness timeout for sending and receiving data to/from azure. Fail if a single TCP read or write call blocks for this long.
673 : 113429 : )", 0) \
674 : 113429 : DECLARE(UInt64, azure_connect_timeout_ms, S3::DEFAULT_CONNECT_TIMEOUT_MS, R"(
675 : 113429 : Connection timeout for host from azure disks.
676 : 113429 : )", 0) \
677 : 113429 : DECLARE(Bool, s3_validate_request_settings, true, R"(
678 : 113429 : Enables s3 request settings validation.
679 : 113429 : Possible values:
680 : 113429 : - 1 — validate settings.
681 : 113429 : - 0 — do not validate settings.
682 : 113429 : )", 0) \
683 : 113429 : DECLARE(Bool, compatibility_s3_presigned_url_query_in_path, false, R"(
684 : 113429 : Compatibility: when enabled, folds pre-signed URL query parameters (e.g. X-Amz-*) into the S3 key (legacy behavior),
685 : 113429 : so '?' acts as a wildcard in the path. When disabled (default), pre-signed URL query parameters are kept in the URL query
686 : 113429 : to avoid interpreting '?' as a wildcard.
687 : 113429 : )", 0) \
688 : 113429 : DECLARE(Bool, s3_disable_checksum, S3::DEFAULT_DISABLE_CHECKSUM, R"(
689 : 113429 : 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.
690 : 113429 : )", 0) \
691 : 113429 : DECLARE(UInt64, s3_request_timeout_ms, S3::DEFAULT_REQUEST_TIMEOUT_MS, R"(
692 : 113429 : Idleness timeout for sending and receiving data to/from S3. Fail if a single TCP read or write call blocks for this long.
693 : 113429 : )", 0) \
694 : 113429 : DECLARE(UInt64, s3_connect_timeout_ms, S3::DEFAULT_CONNECT_TIMEOUT_MS, R"(
695 : 113429 : Connection timeout for host from s3 disks.
696 : 113429 : )", 0) \
697 : 113429 : DECLARE(Bool, enable_s3_requests_logging, false, R"(
698 : 113429 : Enable very explicit logging of S3 requests. Makes sense for debug only.
699 : 113429 : )", 0) \
700 : 113429 : DECLARE(String, s3queue_default_zookeeper_path, "/clickhouse/s3queue/", R"(
701 : 113429 : Default zookeeper path prefix for S3Queue engine
702 : 113429 : )", 0) \
703 : 113429 : DECLARE(Bool, s3queue_migrate_old_metadata_to_buckets, false, R"(
704 : 113429 : Migrate old metadata structure of S3Queue table to a new one
705 : 113429 : )", 0) \
706 : 113429 : DECLARE(Bool, s3queue_enable_logging_to_s3queue_log, false, R"(
707 : 113429 : Enable writing to system.s3queue_log. The value can be overwritten per table with table settings
708 : 113429 : )", 0) \
709 : 113429 : DECLARE(Float, s3queue_keeper_fault_injection_probability, 0.0, R"(
710 : 113429 : Keeper fault injection probability for S3Queue.
711 : 113429 : )", 0) \
712 : 113429 : DECLARE(UInt64, hdfs_replication, 0, R"(
713 : 113429 : The actual number of replications can be specified when the hdfs file is created.
714 : 113429 : )", 0) \
715 : 113429 : DECLARE(Bool, hdfs_truncate_on_insert, false, R"(
716 : 113429 : 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.
717 : 113429 :
718 : 113429 : Possible values:
719 : 113429 : - 0 — `INSERT` query appends new data to the end of the file.
720 : 113429 : - 1 — `INSERT` query replaces existing content of the file with the new data.
721 : 113429 : )", 0) \
722 : 113429 : DECLARE(Bool, hdfs_create_new_file_on_insert, false, R"(
723 : 113429 : 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:
724 : 113429 :
725 : 113429 : initial: `data.Parquet.gz` -> `data.1.Parquet.gz` -> `data.2.Parquet.gz`, etc.
726 : 113429 :
727 : 113429 : Possible values:
728 : 113429 : - 0 — `INSERT` query appends new data to the end of the file.
729 : 113429 : - 1 — `INSERT` query creates a new file.
730 : 113429 : )", 0) \
731 : 113429 : DECLARE(Bool, hdfs_skip_empty_files, false, R"(
732 : 113429 : Enables or disables skipping empty files in [HDFS](../../engines/table-engines/integrations/hdfs.md) engine tables.
733 : 113429 :
734 : 113429 : Possible values:
735 : 113429 : - 0 — `SELECT` throws an exception if empty file is not compatible with requested format.
736 : 113429 : - 1 — `SELECT` returns empty result for empty file.
737 : 113429 : )", 0) \
738 : 113429 : DECLARE(Bool, enable_hdfs_pread, true, R"(
739 : 113429 : Enable or disables pread for HDFS files. By default, `hdfsPread` is used. If disabled, `hdfsRead` and `hdfsSeek` will be used to read hdfs files.)", 0) \
740 : 113429 : DECLARE(Bool, azure_skip_empty_files, false, R"(
741 : 113429 : Enables or disables skipping empty files in S3 engine.
742 : 113429 :
743 : 113429 : Possible values:
744 : 113429 : - 0 — `SELECT` throws an exception if empty file is not compatible with requested format.
745 : 113429 : - 1 — `SELECT` returns empty result for empty file.
746 : 113429 : )", 0) \
747 : 113429 : DECLARE(ArrowFlightDescriptorType, arrow_flight_request_descriptor_type, ArrowFlightDescriptorType::Path, R"(
748 : 113429 : Type of descriptor to use for Arrow Flight requests. 'path' sends the dataset name as a path descriptor. 'command' sends a SQL query as a command descriptor (required for Dremio).
749 : 113429 :
750 : 113429 : Possible values:
751 : 113429 : - 'path' — Use FlightDescriptor::Path (default, works with most Arrow Flight servers)
752 : 113429 : - 'command' — Use FlightDescriptor::Command with a SELECT query (required for Dremio)
753 : 113429 : )", 0) \
754 : 113429 : DECLARE(UInt64, hsts_max_age, 0, R"(
755 : 113429 : Expired time for HSTS. 0 means disable HSTS.
756 : 113429 : )", 0) \
757 : 113429 : DECLARE(Bool, extremes, false, R"(
758 : 113429 : Whether to count extreme values (the minimums and maximums in columns of a query result). Accepts 0 or 1. By default, 0 (disabled).
759 : 113429 : For more information, see the section "Extreme values".
760 : 113429 : )", IMPORTANT) \
761 : 113429 : DECLARE(Bool, use_uncompressed_cache, false, R"(
762 : 113429 : Whether to use a cache of uncompressed blocks. Accepts 0 or 1. By default, 0 (disabled).
763 : 113429 : 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](/operations/server-configuration-parameters/settings#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.
764 : 113429 :
765 : 113429 : 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.
766 : 113429 : )", 0) \
767 : 113429 : DECLARE(Bool, replace_running_query, false, R"(
768 : 113429 : When using the HTTP interface, the 'query_id' parameter can be passed. This is any string that serves as the query identifier.
769 : 113429 : 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.
770 : 113429 :
771 : 113429 : `0` (default) – Throw an exception (do not allow the query to run if a query with the same 'query_id' is already running).
772 : 113429 :
773 : 113429 : `1` – Cancel the old query and start running the new one.
774 : 113429 :
775 : 113429 : 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.
776 : 113429 : )", 0) \
777 : 113429 : DECLARE(UInt64, max_remote_read_network_bandwidth, 0, R"(
778 : 113429 : The maximum speed of data exchange over the network in bytes per second for read.
779 : 113429 : )", 0) \
780 : 113429 : DECLARE(UInt64, max_remote_write_network_bandwidth, 0, R"(
781 : 113429 : The maximum speed of data exchange over the network in bytes per second for write.
782 : 113429 : )", 0) \
783 : 113429 : DECLARE(UInt64, max_local_read_bandwidth, 0, R"(
784 : 113429 : The maximum speed of local reads in bytes per second.
785 : 113429 : )", 0) \
786 : 113429 : DECLARE(UInt64, max_local_write_bandwidth, 0, R"(
787 : 113429 : The maximum speed of local writes in bytes per second.
788 : 113429 : )", 0) \
789 : 113429 : DECLARE(Bool, stream_like_engine_allow_direct_select, false, R"(
790 : 113429 : Allow direct SELECT query for Kafka, RabbitMQ, FileLog, Redis Streams, S3Queue, AzureQueue and NATS engines. In case there are attached materialized views, SELECT query is not allowed even if this setting is enabled.
791 : 113429 : If there are no attached materialized views, enabling this setting allows to read data. Be aware that usually the read data is removed from the queue. In order to avoid removing read data the related engine settings should be configured properly.
792 : 113429 : )", 0) \
793 : 113429 : DECLARE(String, stream_like_engine_insert_queue, "", R"(
794 : 113429 : 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.
795 : 113429 : )", 0) \
796 : 113429 : DECLARE(Bool, dictionary_validate_primary_key_type, false, R"(
797 : 113429 : Validate primary key type for dictionaries. By default id type for simple layouts will be implicitly converted to UInt64.
798 : 113429 : )", 0) \
799 : 113429 : DECLARE(Bool, distributed_insert_skip_read_only_replicas, false, R"(
800 : 113429 : Enables skipping read-only replicas for INSERT queries into Distributed.
801 : 113429 :
802 : 113429 : Possible values:
803 : 113429 :
804 : 113429 : - 0 — INSERT was as usual, if it will go to read-only replica it will fail
805 : 113429 : - 1 — Initiator will skip read-only replicas before sending data to shards.
806 : 113429 : )", 0) \
807 : 113429 : DECLARE_WITH_ALIAS(Bool, distributed_foreground_insert, false, R"(
808 : 113429 : Enables or disables synchronous data insertion into a [Distributed](/engines/table-engines/special/distributed) table.
809 : 113429 :
810 : 113429 : 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).
811 : 113429 :
812 : 113429 : Possible values:
813 : 113429 :
814 : 113429 : - `0` — Data is inserted in background mode.
815 : 113429 : - `1` — Data is inserted in synchronous mode.
816 : 113429 :
817 : 113429 : Cloud default value: `1`.
818 : 113429 :
819 : 113429 : **See Also**
820 : 113429 :
821 : 113429 : - [Distributed Table Engine](/engines/table-engines/special/distributed)
822 : 113429 : - [Managing Distributed Tables](/sql-reference/statements/system#managing-distributed-tables)
823 : 113429 : )", 0, insert_distributed_sync) \
824 : 113429 : DECLARE_WITH_ALIAS(UInt64, distributed_background_insert_timeout, 0, R"(
825 : 113429 : Timeout for insert query into distributed. Setting is used only with insert_distributed_sync enabled. Zero value means no timeout.
826 : 113429 : )", 0, insert_distributed_timeout) \
827 : 113429 : DECLARE_WITH_ALIAS(Milliseconds, distributed_background_insert_sleep_time_ms, 100, R"(
828 : 113429 : Base interval for the [Distributed](../../engines/table-engines/special/distributed.md) table engine to send data. The actual interval grows exponentially in the event of errors.
829 : 113429 :
830 : 113429 : Possible values:
831 : 113429 :
832 : 113429 : - A positive integer number of milliseconds.
833 : 113429 : )", 0, distributed_directory_monitor_sleep_time_ms) \
834 : 113429 : DECLARE_WITH_ALIAS(Milliseconds, distributed_background_insert_max_sleep_time_ms, 30000, R"(
835 : 113429 : Maximum interval for the [Distributed](../../engines/table-engines/special/distributed.md) table engine to send data. Limits exponential growth of the interval set in the [distributed_background_insert_sleep_time_ms](#distributed_background_insert_sleep_time_ms) setting.
836 : 113429 :
837 : 113429 : Possible values:
838 : 113429 :
839 : 113429 : - A positive integer number of milliseconds.
840 : 113429 : )", 0, distributed_directory_monitor_max_sleep_time_ms) \
841 : 113429 : DECLARE_WITH_ALIAS(Bool, distributed_background_insert_batch, false, R"(
842 : 113429 : Enables/disables inserted data sending in batches.
843 : 113429 :
844 : 113429 : When batch sending is enabled, the [Distributed](../../engines/table-engines/special/distributed.md) 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.
845 : 113429 :
846 : 113429 : Possible values:
847 : 113429 :
848 : 113429 : - 1 — Enabled.
849 : 113429 : - 0 — Disabled.
850 : 113429 : )", 0, distributed_directory_monitor_batch_inserts) \
851 : 113429 : DECLARE_WITH_ALIAS(Bool, distributed_background_insert_split_batch_on_failure, false, R"(
852 : 113429 : Enables/disables splitting batches on failures.
853 : 113429 :
854 : 113429 : 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.
855 : 113429 :
856 : 113429 : So installing this setting to `1` will disable batching for such batches (i.e. temporary disables `distributed_background_insert_batch` for failed batches).
857 : 113429 :
858 : 113429 : Possible values:
859 : 113429 :
860 : 113429 : - 1 — Enabled.
861 : 113429 : - 0 — Disabled.
862 : 113429 :
863 : 113429 : :::note
864 : 113429 : This setting also affects broken batches (that may appears because of abnormal server (machine) termination and no `fsync_after_insert`/`fsync_directories` for [Distributed](../../engines/table-engines/special/distributed.md) table engine).
865 : 113429 : :::
866 : 113429 :
867 : 113429 : :::note
868 : 113429 : You should not rely on automatic batch splitting, since this may hurt performance.
869 : 113429 : :::
870 : 113429 : )", 0, distributed_directory_monitor_split_batch_on_failure) \
871 : 113429 : \
872 : 113429 : DECLARE(Bool, optimize_move_to_prewhere, true, R"(
873 : 113429 : Enables or disables automatic [PREWHERE](../../sql-reference/statements/select/prewhere.md) optimization in [SELECT](../../sql-reference/statements/select/index.md) queries.
874 : 113429 :
875 : 113429 : Works only for [*MergeTree](../../engines/table-engines/mergetree-family/index.md) tables.
876 : 113429 :
877 : 113429 : Possible values:
878 : 113429 :
879 : 113429 : - 0 — Automatic `PREWHERE` optimization is disabled.
880 : 113429 : - 1 — Automatic `PREWHERE` optimization is enabled.
881 : 113429 : )", 0) \
882 : 113429 : DECLARE(Bool, optimize_move_to_prewhere_if_final, false, R"(
883 : 113429 : Enables or disables automatic [PREWHERE](../../sql-reference/statements/select/prewhere.md) optimization in [SELECT](../../sql-reference/statements/select/index.md) queries with [FINAL](/sql-reference/statements/select/from#final-modifier) modifier.
884 : 113429 :
885 : 113429 : Works only for [*MergeTree](../../engines/table-engines/mergetree-family/index.md) tables.
886 : 113429 :
887 : 113429 : Possible values:
888 : 113429 :
889 : 113429 : - 0 — Automatic `PREWHERE` optimization in `SELECT` queries with `FINAL` modifier is disabled.
890 : 113429 : - 1 — Automatic `PREWHERE` optimization in `SELECT` queries with `FINAL` modifier is enabled.
891 : 113429 :
892 : 113429 : **See Also**
893 : 113429 :
894 : 113429 : - [optimize_move_to_prewhere](#optimize_move_to_prewhere) setting
895 : 113429 : )", 0) \
896 : 113429 : DECLARE(Bool, move_all_conditions_to_prewhere, true, R"(
897 : 113429 : Move all viable conditions from WHERE to PREWHERE
898 : 113429 : )", 0) \
899 : 113429 : DECLARE(Bool, enable_multiple_prewhere_read_steps, true, R"(
900 : 113429 : Move more conditions from WHERE to PREWHERE and do reads from disk and filtering in multiple steps if there are multiple conditions combined with AND
901 : 113429 : )", 0) \
902 : 113429 : DECLARE(Bool, move_primary_key_columns_to_end_of_prewhere, true, R"(
903 : 113429 : Move PREWHERE conditions containing primary key columns to the end of AND chain. It is likely that these conditions are taken into account during primary key analysis and thus will not contribute a lot to PREWHERE filtering.
904 : 113429 : )", 0) \
905 : 113429 : DECLARE(Bool, allow_reorder_prewhere_conditions, true, R"(
906 : 113429 : When moving conditions from WHERE to PREWHERE, allow reordering them to optimize filtering
907 : 113429 : )", 0) \
908 : 113429 : \
909 : 113429 : DECLARE_WITH_ALIAS(UInt64, alter_sync, 1, R"(
910 : 113429 : Allows you to specify the wait behavior for actions that are to be executed on replicas by [`ALTER`](../../sql-reference/statements/alter/index.md), [`OPTIMIZE`](../../sql-reference/statements/optimize.md) or [`TRUNCATE`](../../sql-reference/statements/truncate.md) queries.
911 : 113429 :
912 : 113429 : Possible values:
913 : 113429 :
914 : 113429 : - `0` — Do not wait.
915 : 113429 : - `1` — Wait for own execution.
916 : 113429 : - `2` — Wait for everyone.
917 : 113429 : - `3` - Only wait for active replicas.
918 : 113429 :
919 : 113429 : Cloud default value: `0`.
920 : 113429 :
921 : 113429 : :::note
922 : 113429 : `alter_sync` is applicable to `Replicated` and `SharedMergeTree` tables only, it does nothing to alter non `Replicated` or `Shared` tables.
923 : 113429 : :::
924 : 113429 : )", 0, replication_alter_partitions_sync) \
925 : 113429 : DECLARE(Int64, replication_wait_for_inactive_replica_timeout, 120, R"(
926 : 113429 : Specifies how long (in seconds) to wait for inactive replicas to execute [`ALTER`](../../sql-reference/statements/alter/index.md), [`OPTIMIZE`](../../sql-reference/statements/optimize.md) or [`TRUNCATE`](../../sql-reference/statements/truncate.md) queries.
927 : 113429 :
928 : 113429 : Possible values:
929 : 113429 :
930 : 113429 : - `0` — Do not wait.
931 : 113429 : - Negative integer — Wait for unlimited time.
932 : 113429 : - Positive integer — The number of seconds to wait.
933 : 113429 : )", 0) \
934 : 113429 : DECLARE(Bool, alter_move_to_space_execute_async, false, R"(
935 : 113429 : Execute ALTER TABLE MOVE ... TO [DISK|VOLUME] asynchronously
936 : 113429 : )", 0) \
937 : 113429 : \
938 : 113429 : DECLARE(LoadBalancing, load_balancing, LoadBalancing::RANDOM, R"(
939 : 113429 : Specifies the algorithm of replicas selection that is used for distributed query processing.
940 : 113429 :
941 : 113429 : ClickHouse supports the following algorithms of choosing replicas:
942 : 113429 :
943 : 113429 : - [Random](#load_balancing-random) (by default)
944 : 113429 : - [Nearest hostname](#load_balancing-nearest_hostname)
945 : 113429 : - [Hostname levenshtein distance](#load_balancing-hostname_levenshtein_distance)
946 : 113429 : - [In order](#load_balancing-in_order)
947 : 113429 : - [First or random](#load_balancing-first_or_random)
948 : 113429 : - [Round robin](#load_balancing-round_robin)
949 : 113429 :
950 : 113429 : See also:
951 : 113429 :
952 : 113429 : - [distributed_replica_max_ignored_errors](#distributed_replica_max_ignored_errors)
953 : 113429 :
954 : 113429 : ### Random (by Default) {#load_balancing-random}
955 : 113429 :
956 : 113429 : ```sql
957 : 113429 : load_balancing = random
958 : 113429 : ```
959 : 113429 :
960 : 113429 : 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.
961 : 113429 : Disadvantages: Server proximity is not accounted for; if the replicas have different data, you will also get different data.
962 : 113429 :
963 : 113429 : ### Nearest Hostname {#load_balancing-nearest_hostname}
964 : 113429 :
965 : 113429 : ```sql
966 : 113429 : load_balancing = nearest_hostname
967 : 113429 : ```
968 : 113429 :
969 : 113429 : 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).
970 : 113429 :
971 : 113429 : 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.
972 : 113429 : 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.
973 : 113429 :
974 : 113429 : Thus, if there are equivalent replicas, the closest one by name is preferred.
975 : 113429 : 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.
976 : 113429 :
977 : 113429 : ### Hostname levenshtein distance {#load_balancing-hostname_levenshtein_distance}
978 : 113429 :
979 : 113429 : ```sql
980 : 113429 : load_balancing = hostname_levenshtein_distance
981 : 113429 : ```
982 : 113429 :
983 : 113429 : Just like `nearest_hostname`, but it compares hostname in a [levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) manner. For example:
984 : 113429 :
985 : 113429 : ```text
986 : 113429 : example-clickhouse-0-0 ample-clickhouse-0-0
987 : 113429 : 1
988 : 113429 :
989 : 113429 : example-clickhouse-0-0 example-clickhouse-1-10
990 : 113429 : 2
991 : 113429 :
992 : 113429 : example-clickhouse-0-0 example-clickhouse-12-0
993 : 113429 : 3
994 : 113429 : ```
995 : 113429 :
996 : 113429 : ### In Order {#load_balancing-in_order}
997 : 113429 :
998 : 113429 : ```sql
999 : 113429 : load_balancing = in_order
1000 : 113429 : ```
1001 : 113429 :
1002 : 113429 : Replicas with the same number of errors are accessed in the same order as they are specified in the configuration.
1003 : 113429 : This method is appropriate when you know exactly which replica is preferable.
1004 : 113429 :
1005 : 113429 : ### First or Random {#load_balancing-first_or_random}
1006 : 113429 :
1007 : 113429 : ```sql
1008 : 113429 : load_balancing = first_or_random
1009 : 113429 : ```
1010 : 113429 :
1011 : 113429 : 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.
1012 : 113429 :
1013 : 113429 : 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.
1014 : 113429 :
1015 : 113429 : 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.
1016 : 113429 :
1017 : 113429 : ### Round Robin {#load_balancing-round_robin}
1018 : 113429 :
1019 : 113429 : ```sql
1020 : 113429 : load_balancing = round_robin
1021 : 113429 : ```
1022 : 113429 :
1023 : 113429 : This algorithm uses a round-robin policy across replicas with the same number of errors (only the queries with `round_robin` policy is accounted).
1024 : 113429 : )", 0) \
1025 : 113429 : DECLARE(UInt64, load_balancing_first_offset, 0, R"(
1026 : 113429 : Which replica to preferably send a query when FIRST_OR_RANDOM load balancing strategy is used.
1027 : 113429 : )", 0) \
1028 : 113429 : \
1029 : 113429 : DECLARE(TotalsMode, totals_mode, TotalsMode::AFTER_HAVING_EXCLUSIVE, R"(
1030 : 113429 : How to calculate TOTALS when HAVING is present, as well as when max_rows_to_group_by and group_by_overflow_mode = 'any' are present.
1031 : 113429 : See the section "WITH TOTALS modifier".
1032 : 113429 : )", IMPORTANT) \
1033 : 113429 : DECLARE(Float, totals_auto_threshold, 0.5, R"(
1034 : 113429 : The threshold for `totals_mode = 'auto'`.
1035 : 113429 : See the section "WITH TOTALS modifier".
1036 : 113429 : )", 0) \
1037 : 113429 : \
1038 : 113429 : DECLARE(Bool, allow_suspicious_low_cardinality_types, false, R"(
1039 : 113429 : Allows or restricts using [LowCardinality](../../sql-reference/data-types/lowcardinality.md) with data types with fixed size of 8 bytes or less: numeric data types and `FixedString(8_bytes_or_less)`.
1040 : 113429 :
1041 : 113429 : For small fixed values using of `LowCardinality` is usually inefficient, because ClickHouse stores a numeric index for each row. As a result:
1042 : 113429 :
1043 : 113429 : - Disk space usage can rise.
1044 : 113429 : - RAM consumption can be higher, depending on a dictionary size.
1045 : 113429 : - Some functions can work slower due to extra coding/encoding operations.
1046 : 113429 :
1047 : 113429 : Merge times in [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md)-engine tables can grow due to all the reasons described above.
1048 : 113429 :
1049 : 113429 : Possible values:
1050 : 113429 :
1051 : 113429 : - 1 — Usage of `LowCardinality` is not restricted.
1052 : 113429 : - 0 — Usage of `LowCardinality` is restricted.
1053 : 113429 : )", 0) \
1054 : 113429 : DECLARE(Bool, allow_suspicious_fixed_string_types, false, R"(
1055 : 113429 : In CREATE TABLE statement allows creating columns of type FixedString(n) with n > 256. FixedString with length >= 256 is suspicious and most likely indicates a misuse
1056 : 113429 : )", 0) \
1057 : 113429 : DECLARE(Bool, allow_suspicious_indices, false, R"(
1058 : 113429 : Reject primary/secondary indexes and sorting keys with identical expressions
1059 : 113429 : )", 0) \
1060 : 113429 : DECLARE(Bool, allow_suspicious_ttl_expressions, false, R"(
1061 : 113429 : Reject TTL expressions that don't depend on any of table's columns. It indicates a user error most of the time.
1062 : 113429 : )", 0) \
1063 : 113429 : DECLARE(Bool, allow_suspicious_variant_types, false, R"(
1064 : 113429 : In CREATE TABLE statement allows specifying Variant type with similar variant types (for example, with different numeric or date types). Enabling this setting may introduce some ambiguity when working with values with similar types.
1065 : 113429 : )", 0) \
1066 : 113429 : DECLARE(Bool, allow_suspicious_primary_key, false, R"(
1067 : 113429 : Allow suspicious `PRIMARY KEY`/`ORDER BY` for MergeTree (i.e. SimpleAggregateFunction).
1068 : 113429 : )", 0) \
1069 : 113429 : DECLARE(Bool, allow_suspicious_types_in_group_by, false, R"(
1070 : 113429 : Allows or restricts using [Variant](../../sql-reference/data-types/variant.md) and [Dynamic](../../sql-reference/data-types/dynamic.md) types in GROUP BY keys.
1071 : 113429 : )", 0) \
1072 : 113429 : DECLARE(Bool, allow_suspicious_types_in_order_by, false, R"(
1073 : 113429 : Allows or restricts using [Variant](../../sql-reference/data-types/variant.md) and [Dynamic](../../sql-reference/data-types/dynamic.md) types in ORDER BY keys.
1074 : 113429 : )", 0) \
1075 : 113429 : DECLARE(Bool, use_variant_default_implementation_for_comparisons, true, R"(
1076 : 113429 : Enables or disables default implementation for Variant type in comparison functions.
1077 : 113429 : )", 0) \
1078 : 113429 : DECLARE(Bool, variant_throw_on_type_mismatch, true, R"(
1079 : 113429 : When applying a function to a [Variant](../../sql-reference/data-types/variant.md) column using the default implementation,
1080 : 113429 : controls what happens for rows whose actual type is incompatible with the function:
1081 : 113429 : - `true` (default) — throw an exception.
1082 : 113429 : - `false` — return `NULL` for those rows instead.
1083 : 113429 : )", 0) \
1084 : 113429 : DECLARE(Bool, dynamic_throw_on_type_mismatch, true, R"(
1085 : 113429 : When applying a function to a [Dynamic](../../sql-reference/data-types/dynamic.md) column using the default implementation,
1086 : 113429 : controls what happens for rows whose actual type is incompatible with the function:
1087 : 113429 : - `true` (default) — throw an exception.
1088 : 113429 : - `false` — return `NULL` for those rows instead.
1089 : 113429 : )", 0) \
1090 : 113429 : DECLARE(Bool, compile_expressions, true, R"(
1091 : 113429 : Compile some scalar functions and operators to native code.
1092 : 113429 : )", 0) \
1093 : 113429 : DECLARE(UInt64, min_count_to_compile_expression, 3, R"(
1094 : 113429 : Minimum count of executing same expression before it is get compiled.
1095 : 113429 : )", 0) \
1096 : 113429 : DECLARE(Bool, compile_aggregate_expressions, true, R"(
1097 : 113429 : Enables or disables JIT-compilation of aggregate functions to native code. Enabling this setting can improve the performance.
1098 : 113429 :
1099 : 113429 : Possible values:
1100 : 113429 :
1101 : 113429 : - 0 — Aggregation is done without JIT compilation.
1102 : 113429 : - 1 — Aggregation is done using JIT compilation.
1103 : 113429 :
1104 : 113429 : **See Also**
1105 : 113429 :
1106 : 113429 : - [min_count_to_compile_aggregate_expression](#min_count_to_compile_aggregate_expression)
1107 : 113429 : )", 0) \
1108 : 113429 : DECLARE(UInt64, min_count_to_compile_aggregate_expression, 3, R"(
1109 : 113429 : The minimum number of identical aggregate expressions to start JIT-compilation. Works only if the [compile_aggregate_expressions](#compile_aggregate_expressions) setting is enabled.
1110 : 113429 :
1111 : 113429 : Possible values:
1112 : 113429 :
1113 : 113429 : - Positive integer.
1114 : 113429 : - 0 — Identical aggregate expressions are always JIT-compiled.
1115 : 113429 : )", 0) \
1116 : 113429 : DECLARE(Bool, compile_sort_description, true, R"(
1117 : 113429 : Compile sort description to native code.
1118 : 113429 : )", 0) \
1119 : 113429 : DECLARE(UInt64, min_count_to_compile_sort_description, 3, R"(
1120 : 113429 : The number of identical sort descriptions before they are JIT-compiled
1121 : 113429 : )", 0) \
1122 : 113429 : DECLARE(UInt64, group_by_two_level_threshold, 100000, R"(
1123 : 113429 : From what number of keys, a two-level aggregation starts. 0 - the threshold is not set.
1124 : 113429 : )", 0) \
1125 : 113429 : DECLARE(UInt64, group_by_two_level_threshold_bytes, 50000000, R"(
1126 : 113429 : From what size of the aggregation state in bytes, a two-level aggregation begins to be used. 0 - the threshold is not set. Two-level aggregation is used when at least one of the thresholds is triggered.
1127 : 113429 : )", 0) \
1128 : 113429 : DECLARE(Bool, distributed_aggregation_memory_efficient, true, R"(
1129 : 113429 : Is the memory-saving mode of distributed aggregation enabled.
1130 : 113429 : )", 0) \
1131 : 113429 : DECLARE(UInt64, aggregation_memory_efficient_merge_threads, 0, R"(
1132 : 113429 : Number of threads to use for merge intermediate aggregation results in memory efficient mode. When bigger, then more memory is consumed. 0 means - same as 'max_threads'.
1133 : 113429 : )", 0) \
1134 : 113429 : DECLARE(Bool, enable_memory_bound_merging_of_aggregation_results, true, R"(
1135 : 113429 : Enable memory bound merging strategy for aggregation.
1136 : 113429 : )", 0) \
1137 : 113429 : DECLARE(Bool, enable_positional_arguments, true, R"(
1138 : 113429 : Enables or disables supporting positional arguments for [GROUP BY](/sql-reference/statements/select/group-by), [LIMIT BY](../../sql-reference/statements/select/limit-by.md), [ORDER BY](../../sql-reference/statements/select/order-by.md) statements.
1139 : 113429 :
1140 : 113429 : Possible values:
1141 : 113429 :
1142 : 113429 : - 0 — Positional arguments aren't supported.
1143 : 113429 : - 1 — Positional arguments are supported: column numbers can use instead of column names.
1144 : 113429 :
1145 : 113429 : **Example**
1146 : 113429 :
1147 : 113429 : Query:
1148 : 113429 :
1149 : 113429 : ```sql
1150 : 113429 : CREATE TABLE positional_arguments(one Int, two Int, three Int) ENGINE=Memory();
1151 : 113429 :
1152 : 113429 : INSERT INTO positional_arguments VALUES (10, 20, 30), (20, 20, 10), (30, 10, 20);
1153 : 113429 :
1154 : 113429 : SELECT * FROM positional_arguments ORDER BY 2,3;
1155 : 113429 : ```
1156 : 113429 :
1157 : 113429 : Result:
1158 : 113429 :
1159 : 113429 : ```text
1160 : 113429 : ┌─one─┬─two─┬─three─┐
1161 : 113429 : │ 30 │ 10 │ 20 │
1162 : 113429 : │ 20 │ 20 │ 10 │
1163 : 113429 : │ 10 │ 20 │ 30 │
1164 : 113429 : └─────┴─────┴───────┘
1165 : 113429 : ```
1166 : 113429 : )", 0) \
1167 : 113429 : DECLARE(Bool, enable_positional_arguments_for_projections, false, R"(
1168 : 113429 : Enables or disables supporting positional arguments in PROJECTION definitions. See also [enable_positional_arguments](#enable_positional_arguments) setting.
1169 : 113429 :
1170 : 113429 : :::note
1171 : 113429 : This is an expert-level setting, and you shouldn't change it if you're just getting started with ClickHouse.
1172 : 113429 : :::
1173 : 113429 :
1174 : 113429 : Possible values:
1175 : 113429 :
1176 : 113429 : - 0 — Positional arguments aren't supported.
1177 : 113429 : - 1 — Positional arguments are supported: column numbers can use instead of column names.
1178 : 113429 : )", 0) \
1179 : 113429 : DECLARE(Bool, enable_extended_results_for_datetime_functions, false, R"(
1180 : 113429 : Enables or disables returning results of type `Date32` with extended range (compared to type `Date`)
1181 : 113429 : or `DateTime64` with extended range (compared to type `DateTime`).
1182 : 113429 :
1183 : 113429 : Possible values:
1184 : 113429 :
1185 : 113429 : - `0` — Functions return `Date` or `DateTime` for all types of arguments.
1186 : 113429 : - `1` — Functions return `Date32` or `DateTime64` for `Date32` or `DateTime64` arguments and `Date` or `DateTime` otherwise.
1187 : 113429 :
1188 : 113429 : The table below shows the behavior of this setting for various date-time functions.
1189 : 113429 :
1190 : 113429 : | Function | `enable_extended_results_for_datetime_functions = 0` | `enable_extended_results_for_datetime_functions = 1` |
1191 : 113429 : |----------|---------------------------------------------------|---------------------------------------------------|
1192 : 113429 : | `toStartOfYear` | Returns `Date` or `DateTime` | Returns `Date`/`DateTime` for `Date`/`DateTime` input<br/>Returns `Date32`/`DateTime64` for `Date32`/`DateTime64` input |
1193 : 113429 : | `toStartOfISOYear` | Returns `Date` or `DateTime` | Returns `Date`/`DateTime` for `Date`/`DateTime` input<br/>Returns `Date32`/`DateTime64` for `Date32`/`DateTime64` input |
1194 : 113429 : | `toStartOfQuarter` | Returns `Date` or `DateTime` | Returns `Date`/`DateTime` for `Date`/`DateTime` input<br/>Returns `Date32`/`DateTime64` for `Date32`/`DateTime64` input |
1195 : 113429 : | `toStartOfMonth` | Returns `Date` or `DateTime` | Returns `Date`/`DateTime` for `Date`/`DateTime` input<br/>Returns `Date32`/`DateTime64` for `Date32`/`DateTime64` input |
1196 : 113429 : | `toStartOfWeek` | Returns `Date` or `DateTime` | Returns `Date`/`DateTime` for `Date`/`DateTime` input<br/>Returns `Date32`/`DateTime64` for `Date32`/`DateTime64` input |
1197 : 113429 : | `toLastDayOfWeek` | Returns `Date` or `DateTime` | Returns `Date`/`DateTime` for `Date`/`DateTime` input<br/>Returns `Date32`/`DateTime64` for `Date32`/`DateTime64` input |
1198 : 113429 : | `toLastDayOfMonth` | Returns `Date` or `DateTime` | Returns `Date`/`DateTime` for `Date`/`DateTime` input<br/>Returns `Date32`/`DateTime64` for `Date32`/`DateTime64` input |
1199 : 113429 : | `toMonday` | Returns `Date` or `DateTime` | Returns `Date`/`DateTime` for `Date`/`DateTime` input<br/>Returns `Date32`/`DateTime64` for `Date32`/`DateTime64` input |
1200 : 113429 : | `toStartOfDay` | Returns `DateTime`<br/>*Note: Wrong results for values outside 1970-2149 range* | Returns `DateTime` for `Date`/`DateTime` input<br/>Returns `DateTime64` for `Date32`/`DateTime64` input |
1201 : 113429 : | `toStartOfHour` | Returns `DateTime`<br/>*Note: Wrong results for values outside 1970-2149 range* | Returns `DateTime` for `Date`/`DateTime` input<br/>Returns `DateTime64` for `Date32`/`DateTime64` input |
1202 : 113429 : | `toStartOfFifteenMinutes` | Returns `DateTime`<br/>*Note: Wrong results for values outside 1970-2149 range* | Returns `DateTime` for `Date`/`DateTime` input<br/>Returns `DateTime64` for `Date32`/`DateTime64` input |
1203 : 113429 : | `toStartOfTenMinutes` | Returns `DateTime`<br/>*Note: Wrong results for values outside 1970-2149 range* | Returns `DateTime` for `Date`/`DateTime` input<br/>Returns `DateTime64` for `Date32`/`DateTime64` input |
1204 : 113429 : | `toStartOfFiveMinutes` | Returns `DateTime`<br/>*Note: Wrong results for values outside 1970-2149 range* | Returns `DateTime` for `Date`/`DateTime` input<br/>Returns `DateTime64` for `Date32`/`DateTime64` input |
1205 : 113429 : | `toStartOfMinute` | Returns `DateTime`<br/>*Note: Wrong results for values outside 1970-2149 range* | Returns `DateTime` for `Date`/`DateTime` input<br/>Returns `DateTime64` for `Date32`/`DateTime64` input |
1206 : 113429 : | `timeSlot` | Returns `DateTime`<br/>*Note: Wrong results for values outside 1970-2149 range* | Returns `DateTime` for `Date`/`DateTime` input<br/>Returns `DateTime64` for `Date32`/`DateTime64` input |
1207 : 113429 : )", 0) \
1208 : 113429 : DECLARE(Bool, allow_nonconst_timezone_arguments, false, R"(
1209 : 113429 : Allow non-const timezone arguments in certain time-related functions like toTimeZone(), fromUnixTimestamp*(), snowflakeToDateTime*().
1210 : 113429 : This setting exists only for compatibility reasons. In ClickHouse, the time zone is a property of the data type, respectively of the column.
1211 : 113429 : Enabling this setting gives the wrong impression that different values within a column can have different timezones.
1212 : 113429 : Therefore, please do not enable this setting.
1213 : 113429 : )", 0) \
1214 : 113429 : DECLARE(Bool, use_legacy_to_time, true, R"(
1215 : 113429 : When enabled, allows to use legacy toTime function, which converts a date with time to a certain fixed date, while preserving the time.
1216 : 113429 : Otherwise, uses a new toTime function, that converts different type of data into the Time type.
1217 : 113429 : The old legacy function is also unconditionally accessible as toTimeWithFixedDate.
1218 : 113429 : )", 0) \
1219 : 113429 : DECLARE_WITH_ALIAS(Bool, enable_time_time64_type, true, R"(
1220 : 113429 : Allows creation of [Time](../../sql-reference/data-types/time.md) and [Time64](../../sql-reference/data-types/time64.md) data types.
1221 : 113429 : )", 0, allow_experimental_time_time64_type) \
1222 : 113429 : DECLARE(Bool, function_locate_has_mysql_compatible_argument_order, true, R"(
1223 : 113429 : Controls the order of arguments in function [locate](../../sql-reference/functions/string-search-functions.md/#locate).
1224 : 113429 :
1225 : 113429 : Possible values:
1226 : 113429 :
1227 : 113429 : - 0 — Function `locate` accepts arguments `(haystack, needle[, start_pos])`.
1228 : 113429 : - 1 — Function `locate` accepts arguments `(needle, haystack, [, start_pos])` (MySQL-compatible behavior)
1229 : 113429 : )", 0) \
1230 : 113429 : \
1231 : 113429 : DECLARE(Bool, group_by_use_nulls, false, R"(
1232 : 113429 : Changes the way the [GROUP BY clause](/sql-reference/statements/select/group-by) treats the types of aggregation keys.
1233 : 113429 : When the `ROLLUP`, `CUBE`, or `GROUPING SETS` specifiers are used, some aggregation keys may not be used to produce some result rows.
1234 : 113429 : Columns for these keys are filled with either default value or `NULL` in corresponding rows depending on this setting.
1235 : 113429 :
1236 : 113429 : Possible values:
1237 : 113429 :
1238 : 113429 : - 0 — The default value for the aggregation key type is used to produce missing values.
1239 : 113429 : - 1 — ClickHouse executes `GROUP BY` the same way as the SQL standard says. The types of aggregation keys are converted to [Nullable](/sql-reference/data-types/nullable). Columns for corresponding aggregation keys are filled with [NULL](/sql-reference/syntax#null) for rows that didn't use it.
1240 : 113429 :
1241 : 113429 : See also:
1242 : 113429 :
1243 : 113429 : - [GROUP BY clause](/sql-reference/statements/select/group-by)
1244 : 113429 : )", 0) \
1245 : 113429 : \
1246 : 113429 : DECLARE(Bool, skip_unavailable_shards, false, R"(
1247 : 113429 : Enables or disables silently skipping of unavailable shards.
1248 : 113429 :
1249 : 113429 : Shard is considered unavailable if all its replicas are unavailable. A replica is unavailable in the following cases:
1250 : 113429 :
1251 : 113429 : - ClickHouse can't connect to replica for any reason.
1252 : 113429 :
1253 : 113429 : When connecting to a replica, ClickHouse performs several attempts. If all these attempts fail, the replica is considered unavailable.
1254 : 113429 :
1255 : 113429 : - Replica can't be resolved through DNS.
1256 : 113429 :
1257 : 113429 : If replica's hostname can't be resolved through DNS, it can indicate the following situations:
1258 : 113429 :
1259 : 113429 : - Replica's host has no DNS record. It can occur in systems with dynamic DNS, for example, [Kubernetes](https://kubernetes.io), where nodes can be unresolvable during downtime, and this is not an error.
1260 : 113429 :
1261 : 113429 : - Configuration error. ClickHouse configuration file contains a wrong hostname.
1262 : 113429 :
1263 : 113429 : Possible values:
1264 : 113429 :
1265 : 113429 : - 1 — skipping enabled.
1266 : 113429 :
1267 : 113429 : If a shard is unavailable, ClickHouse returns a result based on partial data and does not report node availability issues.
1268 : 113429 :
1269 : 113429 : - 0 — skipping disabled.
1270 : 113429 :
1271 : 113429 : If a shard is unavailable, ClickHouse throws an exception.
1272 : 113429 : )", 0) \
1273 : 113429 : \
1274 : 113429 : DECLARE(UInt64, max_skip_unavailable_shards_num, 0, R"(
1275 : 113429 : When `skip_unavailable_shards` is enabled, limits the maximum number of shards that can be silently skipped.
1276 : 113429 : If the number of unavailable shards exceeds this value, an exception is thrown instead of silently skipping.
1277 : 113429 :
1278 : 113429 : A value of 0 means no limit (default behavior — all unavailable shards can be skipped).
1279 : 113429 : )", 0) \
1280 : 113429 : \
1281 : 113429 : DECLARE(Float, max_skip_unavailable_shards_ratio, 0, R"(
1282 : 113429 : When `skip_unavailable_shards` is enabled, limits the maximum ratio (0 to 1) of shards that can be silently skipped.
1283 : 113429 : If the ratio of unavailable shards to total shards exceeds this value, an exception is thrown instead of silently skipping.
1284 : 113429 :
1285 : 113429 : A value of 0 means no limit (default behavior — all unavailable shards can be skipped).
1286 : 113429 : )", 0) \
1287 : 113429 : \
1288 : 113429 : DECLARE(UInt64, parallel_distributed_insert_select, 2, R"(
1289 : 113429 : Enables parallel distributed `INSERT ... SELECT` query.
1290 : 113429 :
1291 : 113429 : 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](../../engines/table-engines/mergetree-family/replication.md) or non-replicated, then this query is processed locally on every shard.
1292 : 113429 :
1293 : 113429 : Possible values:
1294 : 113429 :
1295 : 113429 : - `0` — Disabled.
1296 : 113429 : - `1` — `SELECT` will be executed on each shard from the underlying table of the distributed engine.
1297 : 113429 : - `2` — `SELECT` and `INSERT` will be executed on each shard from/to the underlying table of the distributed engine.
1298 : 113429 :
1299 : 113429 : Setting `enable_parallel_replicas = 1` is needed when using this setting.
1300 : 113429 : )", 0) \
1301 : 113429 : DECLARE(UInt64, distributed_group_by_no_merge, 0, R"(
1302 : 113429 : 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
1303 : 113429 :
1304 : 113429 : Possible values:
1305 : 113429 :
1306 : 113429 : - `0` — Disabled (final query processing is done on the initiator node).
1307 : 113429 : - `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.
1308 : 113429 : - `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`).
1309 : 113429 :
1310 : 113429 : **Example**
1311 : 113429 :
1312 : 113429 : ```sql
1313 : 113429 : SELECT *
1314 : 113429 : FROM remote('127.0.0.{2,3}', system.one)
1315 : 113429 : GROUP BY dummy
1316 : 113429 : LIMIT 1
1317 : 113429 : SETTINGS distributed_group_by_no_merge = 1
1318 : 113429 : FORMAT PrettyCompactMonoBlock
1319 : 113429 :
1320 : 113429 : ┌─dummy─┐
1321 : 113429 : │ 0 │
1322 : 113429 : │ 0 │
1323 : 113429 : └───────┘
1324 : 113429 : ```
1325 : 113429 :
1326 : 113429 : ```sql
1327 : 113429 : SELECT *
1328 : 113429 : FROM remote('127.0.0.{2,3}', system.one)
1329 : 113429 : GROUP BY dummy
1330 : 113429 : LIMIT 1
1331 : 113429 : SETTINGS distributed_group_by_no_merge = 2
1332 : 113429 : FORMAT PrettyCompactMonoBlock
1333 : 113429 :
1334 : 113429 : ┌─dummy─┐
1335 : 113429 : │ 0 │
1336 : 113429 : └───────┘
1337 : 113429 : ```
1338 : 113429 : )", 0) \
1339 : 113429 : DECLARE(UInt64, distributed_push_down_limit, 1, R"(
1340 : 113429 : Enables or disables [LIMIT](#limit) applying on each shard separately.
1341 : 113429 :
1342 : 113429 : This will allow to avoid:
1343 : 113429 : - Sending extra rows over network;
1344 : 113429 : - Processing rows behind the limit on the initiator.
1345 : 113429 :
1346 : 113429 : 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:
1347 : 113429 : - [distributed_group_by_no_merge](#distributed_group_by_no_merge) > 0.
1348 : 113429 : - Query **does not have** `GROUP BY`/`DISTINCT`/`LIMIT BY`, but it has `ORDER BY`/`LIMIT`.
1349 : 113429 : - Query **has** `GROUP BY`/`DISTINCT`/`LIMIT BY` with `ORDER BY`/`LIMIT` and:
1350 : 113429 : - [optimize_skip_unused_shards](#optimize_skip_unused_shards) is enabled.
1351 : 113429 : - [optimize_distributed_group_by_sharding_key](#optimize_distributed_group_by_sharding_key) is enabled.
1352 : 113429 :
1353 : 113429 : Possible values:
1354 : 113429 :
1355 : 113429 : - 0 — Disabled.
1356 : 113429 : - 1 — Enabled.
1357 : 113429 :
1358 : 113429 : See also:
1359 : 113429 :
1360 : 113429 : - [distributed_group_by_no_merge](#distributed_group_by_no_merge)
1361 : 113429 : - [optimize_skip_unused_shards](#optimize_skip_unused_shards)
1362 : 113429 : - [optimize_distributed_group_by_sharding_key](#optimize_distributed_group_by_sharding_key)
1363 : 113429 : )", 0) \
1364 : 113429 : DECLARE(Bool, optimize_distributed_group_by_sharding_key, true, R"(
1365 : 113429 : 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).
1366 : 113429 :
1367 : 113429 : The following types of queries are supported (and all combinations of them):
1368 : 113429 :
1369 : 113429 : - `SELECT DISTINCT [..., ]sharding_key[, ...] FROM dist`
1370 : 113429 : - `SELECT ... FROM dist GROUP BY sharding_key[, ...]`
1371 : 113429 : - `SELECT ... FROM dist GROUP BY sharding_key[, ...] ORDER BY x`
1372 : 113429 : - `SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1`
1373 : 113429 : - `SELECT ... FROM dist GROUP BY sharding_key[, ...] LIMIT 1 BY x`
1374 : 113429 :
1375 : 113429 : The following types of queries are not supported (support for some of them may be added later):
1376 : 113429 :
1377 : 113429 : - `SELECT ... GROUP BY sharding_key[, ...] WITH TOTALS`
1378 : 113429 : - `SELECT ... GROUP BY sharding_key[, ...] WITH ROLLUP`
1379 : 113429 : - `SELECT ... GROUP BY sharding_key[, ...] WITH CUBE`
1380 : 113429 : - `SELECT ... GROUP BY sharding_key[, ...] SETTINGS extremes=1`
1381 : 113429 :
1382 : 113429 : Possible values:
1383 : 113429 :
1384 : 113429 : - 0 — Disabled.
1385 : 113429 : - 1 — Enabled.
1386 : 113429 :
1387 : 113429 : See also:
1388 : 113429 :
1389 : 113429 : - [distributed_group_by_no_merge](#distributed_group_by_no_merge)
1390 : 113429 : - [distributed_push_down_limit](#distributed_push_down_limit)
1391 : 113429 : - [optimize_skip_unused_shards](#optimize_skip_unused_shards)
1392 : 113429 :
1393 : 113429 : :::note
1394 : 113429 : 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).
1395 : 113429 : :::
1396 : 113429 : )", 0) \
1397 : 113429 : DECLARE(UInt64, optimize_skip_unused_shards_limit, 1000, R"(
1398 : 113429 : Limit for number of sharding key values, turns off `optimize_skip_unused_shards` if the limit is reached.
1399 : 113429 :
1400 : 113429 : 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.
1401 : 113429 : )", 0) \
1402 : 113429 : DECLARE(Bool, optimize_skip_unused_shards, false, R"(
1403 : 113429 : Enables or disables skipping of unused shards for [SELECT](../../sql-reference/statements/select/index.md) queries that have sharding key condition in `WHERE/PREWHERE`, and activates related optimizations for distributed queries (e.g. aggregation by sharding key).
1404 : 113429 :
1405 : 113429 : :::note
1406 : 113429 : Assumes that the data is distributed by sharding key, otherwise a query yields incorrect result.
1407 : 113429 : :::
1408 : 113429 :
1409 : 113429 : Possible values:
1410 : 113429 :
1411 : 113429 : - 0 — Disabled.
1412 : 113429 : - 1 — Enabled.
1413 : 113429 : )", 0) \
1414 : 113429 : DECLARE(Bool, optimize_skip_unused_shards_rewrite_in, true, R"(
1415 : 113429 : Rewrite IN in query for remote shards to exclude values that does not belong to the shard (requires optimize_skip_unused_shards).
1416 : 113429 :
1417 : 113429 : Possible values:
1418 : 113429 :
1419 : 113429 : - 0 — Disabled.
1420 : 113429 : - 1 — Enabled.
1421 : 113429 : )", 0) \
1422 : 113429 : DECLARE(Bool, allow_nondeterministic_optimize_skip_unused_shards, false, R"(
1423 : 113429 : Allow nondeterministic (like `rand` or `dictGet`, since later has some caveats with updates) functions in sharding key.
1424 : 113429 :
1425 : 113429 : Possible values:
1426 : 113429 :
1427 : 113429 : - 0 — Disallowed.
1428 : 113429 : - 1 — Allowed.
1429 : 113429 : )", 0) \
1430 : 113429 : DECLARE(UInt64, force_optimize_skip_unused_shards, 0, R"(
1431 : 113429 : Enables or disables query execution if [optimize_skip_unused_shards](#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.
1432 : 113429 :
1433 : 113429 : Possible values:
1434 : 113429 :
1435 : 113429 : - 0 — Disabled. ClickHouse does not throw an exception.
1436 : 113429 : - 1 — Enabled. Query execution is disabled only if the table has a sharding key.
1437 : 113429 : - 2 — Enabled. Query execution is disabled regardless of whether a sharding key is defined for the table.
1438 : 113429 : )", 0) \
1439 : 113429 : DECLARE(UInt64, optimize_skip_unused_shards_nesting, 0, R"(
1440 : 113429 : Controls [`optimize_skip_unused_shards`](#optimize_skip_unused_shards) (hence still requires [`optimize_skip_unused_shards`](#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).
1441 : 113429 :
1442 : 113429 : Possible values:
1443 : 113429 :
1444 : 113429 : - 0 — Disabled, `optimize_skip_unused_shards` works always.
1445 : 113429 : - 1 — Enables `optimize_skip_unused_shards` only for the first level.
1446 : 113429 : - 2 — Enables `optimize_skip_unused_shards` up to the second level.
1447 : 113429 : )", 0) \
1448 : 113429 : DECLARE(UInt64, force_optimize_skip_unused_shards_nesting, 0, R"(
1449 : 113429 : Controls [`force_optimize_skip_unused_shards`](#force_optimize_skip_unused_shards) (hence still requires [`force_optimize_skip_unused_shards`](#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).
1450 : 113429 :
1451 : 113429 : Possible values:
1452 : 113429 :
1453 : 113429 : - 0 - Disabled, `force_optimize_skip_unused_shards` works always.
1454 : 113429 : - 1 — Enables `force_optimize_skip_unused_shards` only for the first level.
1455 : 113429 : - 2 — Enables `force_optimize_skip_unused_shards` up to the second level.
1456 : 113429 : )", 0) \
1457 : 113429 : \
1458 : 113429 : DECLARE(NonZeroUInt64, min_chunk_bytes_for_parallel_parsing, (10 * 1024 * 1024), R"(
1459 : 113429 : - Type: unsigned int
1460 : 113429 : - Default value: 1 MiB
1461 : 113429 :
1462 : 113429 : The minimum chunk size in bytes, which each thread will parse in parallel.
1463 : 113429 : )", 0) \
1464 : 113429 : DECLARE(Bool, allow_special_serialization_kinds_in_output_formats, true, R"(
1465 : 113429 : Allows to output columns with special serialization kinds like Sparse and Replicated without converting them to full column representation.
1466 : 113429 : It helps to avoid unnecessary data copy during formatting.
1467 : 113429 : )", 0) \
1468 : 113429 : DECLARE(Bool, enable_parsing_to_custom_serialization, true, R"(
1469 : 113429 : 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.
1470 : 113429 : )", 0) \
1471 : 113429 : DECLARE(Bool, ignore_format_null_for_explain, true, R"(
1472 : 113429 : If enabled, `FORMAT Null` will be ignored for `EXPLAIN` queries and default output format will be used instead.
1473 : 113429 : When disabled, `EXPLAIN` queries with `FORMAT Null` will produce no output (backward compatible behavior).
1474 : 113429 : )", 0) \
1475 : 113429 : \
1476 : 113429 : DECLARE(Bool, merge_tree_use_v1_object_and_dynamic_serialization, false, R"(
1477 : 113429 : When enabled, V1 serialization version of JSON and Dynamic types will be used in MergeTree instead of V2. Changing this setting takes affect only after server restart.
1478 : 113429 : )", 0) \
1479 : 113429 : DECLARE(UInt64, merge_tree_min_rows_for_concurrent_read, (20 * 8192), R"(
1480 : 113429 : If the number of rows to be read from a file of a [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md) table exceeds `merge_tree_min_rows_for_concurrent_read` then ClickHouse tries to perform a concurrent reading from this file on several threads.
1481 : 113429 :
1482 : 113429 : Possible values:
1483 : 113429 :
1484 : 113429 : - Positive integer.
1485 : 113429 : )", 0) \
1486 : 113429 : DECLARE(UInt64, merge_tree_min_bytes_for_concurrent_read, (24 * 10 * 1024 * 1024), R"(
1487 : 113429 : If the number of bytes to read from one file of a [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md)-engine table exceeds `merge_tree_min_bytes_for_concurrent_read`, then ClickHouse tries to concurrently read from this file in several threads.
1488 : 113429 :
1489 : 113429 : Possible value:
1490 : 113429 :
1491 : 113429 : - Positive integer.
1492 : 113429 : )", 0) \
1493 : 113429 : DECLARE(UInt64, merge_tree_min_rows_for_seek, 0, R"(
1494 : 113429 : 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.
1495 : 113429 :
1496 : 113429 : Possible values:
1497 : 113429 :
1498 : 113429 : - Any positive integer.
1499 : 113429 : )", 0) \
1500 : 113429 : DECLARE(UInt64, merge_tree_min_bytes_for_seek, 0, R"(
1501 : 113429 : 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.
1502 : 113429 :
1503 : 113429 : Possible values:
1504 : 113429 :
1505 : 113429 : - Any positive integer.
1506 : 113429 : )", 0) \
1507 : 113429 : DECLARE(UInt64, merge_tree_coarse_index_granularity, 8, R"(
1508 : 113429 : 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.
1509 : 113429 :
1510 : 113429 : Possible values:
1511 : 113429 :
1512 : 113429 : - Any positive even integer.
1513 : 113429 : )", 0) \
1514 : 113429 : DECLARE(UInt64, merge_tree_max_rows_to_use_cache, (128 * 8192), R"(
1515 : 113429 : 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.
1516 : 113429 :
1517 : 113429 : 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](/operations/server-configuration-parameters/settings#uncompressed_cache_size) server setting defines the size of the cache of uncompressed blocks.
1518 : 113429 :
1519 : 113429 : Possible values:
1520 : 113429 :
1521 : 113429 : - Any positive integer.
1522 : 113429 : )", 0) \
1523 : 113429 : DECLARE(UInt64, merge_tree_max_bytes_to_use_cache, (192 * 10 * 1024 * 1024), R"(
1524 : 113429 : 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.
1525 : 113429 :
1526 : 113429 : 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](/operations/server-configuration-parameters/settings#uncompressed_cache_size) server setting defines the size of the cache of uncompressed blocks.
1527 : 113429 :
1528 : 113429 : Possible values:
1529 : 113429 :
1530 : 113429 : - Any positive integer.
1531 : 113429 : )", 0) \
1532 : 113429 : DECLARE(Bool, merge_tree_use_deserialization_prefixes_cache, true, R"(
1533 : 113429 : Enables caching of columns metadata from the file prefixes during reading from remote disks in MergeTree.
1534 : 113429 : )", 0) \
1535 : 113429 : DECLARE(Bool, merge_tree_use_prefixes_deserialization_thread_pool, true, R"(
1536 : 113429 : Enables usage of the thread pool for parallel prefixes reading in Wide parts in MergeTree. Size of that thread pool is controlled by server setting `max_prefixes_deserialization_thread_pool_size`.
1537 : 113429 : )", 0) \
1538 : 113429 : DECLARE(Bool, do_not_merge_across_partitions_select_final, false, R"(
1539 : 113429 : Improve FINAL queries by avoiding merges across different partitions.
1540 : 113429 :
1541 : 113429 : When enabled, during SELECT FINAL queries, parts from different partitions will not be merged together. Instead, merging will only occur within each partition separately. This can significantly improve query performance when working with partitioned tables.
1542 : 113429 : )", 0) \
1543 : 113429 : DECLARE(Bool, enable_automatic_decision_for_merging_across_partitions_for_final, true, R"(
1544 : 113429 : If set, ClickHouse will automatically enable this optimization when the partition key expression is deterministic and all columns used in the partition key expression are included in the primary key.
1545 : 113429 : This automatic derivation ensures that rows with the same primary key values will always belong to the same partition, making it safe to avoid cross-partition merges.
1546 : 113429 : )", 0) \
1547 : 113429 : DECLARE(Bool, split_parts_ranges_into_intersecting_and_non_intersecting_final, true, R"(
1548 : 113429 : Split parts ranges into intersecting and non intersecting during FINAL optimization
1549 : 113429 : )", 0) \
1550 : 113429 : DECLARE(Bool, split_intersecting_parts_ranges_into_layers_final, true, R"(
1551 : 113429 : Split intersecting parts ranges into layers during FINAL optimization
1552 : 113429 : )", 0) \
1553 : 113429 : DECLARE(Bool, apply_row_policy_after_final, true, R"(
1554 : 113429 : When enabled, row policies and PREWHERE are applied after FINAL processing for *MergeTree tables. (Especially for ReplacingMergeTree)
1555 : 113429 : When disabled, row policies are applied before FINAL, which can cause different results when the policy
1556 : 113429 : filters out rows that should be used for deduplication in ReplacingMergeTree or similar engines.
1557 : 113429 :
1558 : 113429 : If the row policy expression depends only on columns in ORDER BY, it will still be applied before FINAL as an optimization,
1559 : 113429 : since such filtering cannot affect the deduplication result.
1560 : 113429 :
1561 : 113429 : Possible values:
1562 : 113429 :
1563 : 113429 : - 0 — Row policy and PREWHERE are applied before FINAL (default).
1564 : 113429 : - 1 — Row policy and PREWHERE are applied after FINAL.
1565 : 113429 : )", 0) \
1566 : 113429 : DECLARE(Bool, apply_prewhere_after_final, false, R"(
1567 : 113429 : When enabled, PREWHERE conditions are applied after FINAL processing for ReplacingMergeTree and similar engines.
1568 : 113429 : This can be useful when PREWHERE references columns that may have different values across duplicate rows,
1569 : 113429 : and you want FINAL to select the winning row before filtering. When disabled, PREWHERE is applied during reading.
1570 : 113429 : Note: If apply_row_level_security_after_final is enabled and row policy uses non-sorting-key columns, PREWHERE will also
1571 : 113429 : be deferred to maintain correct execution order (row policy must be applied before PREWHERE).
1572 : 113429 : )", 0) \
1573 : 113429 : \
1574 : 113429 : DECLARE(UInt64, mysql_max_rows_to_insert, 65536, R"(
1575 : 113429 : The maximum number of rows in MySQL batch insertion of the MySQL storage engine
1576 : 113429 : )", 0) \
1577 : 113429 : DECLARE(Bool, mysql_map_string_to_text_in_show_columns, true, R"(
1578 : 113429 : When enabled, [String](../../sql-reference/data-types/string.md) ClickHouse data type will be displayed as `TEXT` in [SHOW COLUMNS](../../sql-reference/statements/show.md/#show_columns).
1579 : 113429 :
1580 : 113429 : Has an effect only when the connection is made through the MySQL wire protocol.
1581 : 113429 :
1582 : 113429 : - 0 - Use `BLOB`.
1583 : 113429 : - 1 - Use `TEXT`.
1584 : 113429 : )", 0) \
1585 : 113429 : DECLARE(Bool, mysql_map_fixed_string_to_text_in_show_columns, true, R"(
1586 : 113429 : When enabled, [FixedString](../../sql-reference/data-types/fixedstring.md) ClickHouse data type will be displayed as `TEXT` in [SHOW COLUMNS](../../sql-reference/statements/show.md/#show_columns).
1587 : 113429 :
1588 : 113429 : Has an effect only when the connection is made through the MySQL wire protocol.
1589 : 113429 :
1590 : 113429 : - 0 - Use `BLOB`.
1591 : 113429 : - 1 - Use `TEXT`.
1592 : 113429 : )", 0) \
1593 : 113429 : \
1594 : 113429 : DECLARE(UInt64, optimize_min_equality_disjunction_chain_length, 3, R"(
1595 : 113429 : The minimum length of the expression `expr = x1 OR ... expr = xN` for optimization
1596 : 113429 : )", 0) \
1597 : 113429 : DECLARE(UInt64, optimize_min_inequality_conjunction_chain_length, 3, R"(
1598 : 113429 : The minimum length of the expression `expr <> x1 AND ... expr <> xN` for optimization
1599 : 113429 : )", 0) \
1600 : 113429 : \
1601 : 113429 : DECLARE(UInt64, min_bytes_to_use_direct_io, 0, R"(
1602 : 113429 : The minimum data volume required for using direct I/O access to the storage disk.
1603 : 113429 :
1604 : 113429 : 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.
1605 : 113429 :
1606 : 113429 : Possible values:
1607 : 113429 :
1608 : 113429 : - 0 — Direct I/O is disabled.
1609 : 113429 : - Positive integer.
1610 : 113429 : )", 0) \
1611 : 113429 : DECLARE(UInt64, min_bytes_to_use_mmap_io, 0, R"(
1612 : 113429 : 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](https://en.wikipedia.org/wiki/Mmap) is slow. It makes sense only for large files and helps only if data reside in the page cache.
1613 : 113429 :
1614 : 113429 : Possible values:
1615 : 113429 :
1616 : 113429 : - Positive integer.
1617 : 113429 : - 0 — Big files read with only copying data from kernel to userspace.
1618 : 113429 : )", 0) \
1619 : 113429 : DECLARE(Bool, checksum_on_read, true, R"(
1620 : 113429 : Validate checksums on reading. It is enabled by default and should be always enabled in production. Please do not expect any benefits in disabling this setting. It may only be used for experiments and benchmarks. The setting is only applicable for tables of MergeTree family. Checksums are always validated for other table engines and when receiving data over the network.
1621 : 113429 : )", 0) \
1622 : 113429 : \
1623 : 113429 : DECLARE(Bool, force_index_by_date, false, R"(
1624 : 113429 : Disables query execution if the index can't be used by date.
1625 : 113429 :
1626 : 113429 : Works with tables in the MergeTree family.
1627 : 113429 :
1628 : 113429 : 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](../../engines/table-engines/mergetree-family/mergetree.md).
1629 : 113429 : )", 0) \
1630 : 113429 : DECLARE(Bool, use_primary_key, true, R"(
1631 : 113429 : Use the primary key to prune granules during query execution for MergeTree tables.
1632 : 113429 :
1633 : 113429 : Possible values:
1634 : 113429 :
1635 : 113429 : - 0 — Disabled.
1636 : 113429 : - 1 — Enabled.
1637 : 113429 : )", 0) \
1638 : 113429 : DECLARE_WITH_ALIAS(Bool, use_partition_pruning, true, R"(
1639 : 113429 : Use partition key to prune partitions during query execution for MergeTree tables.
1640 : 113429 :
1641 : 113429 : Possible values:
1642 : 113429 :
1643 : 113429 : - 0 — Disabled.
1644 : 113429 : - 1 — Enabled.
1645 : 113429 : )", 0, use_partition_key) \
1646 : 113429 : DECLARE(Bool, force_primary_key, false, R"(
1647 : 113429 : Disables query execution if indexing by the primary key is not possible.
1648 : 113429 :
1649 : 113429 : Works with tables in the MergeTree family.
1650 : 113429 :
1651 : 113429 : If `force_primary_key=1`, ClickHouse checks to see if the query has a primary key condition that can be used for restricting data ranges. If there is no suitable condition, it throws an exception. However, it does not check whether the condition reduces the amount of data to read. For more information about data ranges in MergeTree tables, see [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md).
1652 : 113429 : )", 0) \
1653 : 113429 : DECLARE(Bool, use_skip_indexes, true, R"(
1654 : 113429 : Use data skipping indexes during query execution.
1655 : 113429 :
1656 : 113429 : Possible values:
1657 : 113429 :
1658 : 113429 : - 0 — Disabled.
1659 : 113429 : - 1 — Enabled.
1660 : 113429 : )", 0) \
1661 : 113429 : DECLARE(Bool, use_skip_indexes_if_final, true, R"(
1662 : 113429 : Controls whether skipping indexes are used when executing a query with the FINAL modifier.
1663 : 113429 :
1664 : 113429 : Skip indexes may exclude rows (granules) containing the latest data, which could lead to incorrect results from a query with the FINAL modifier. When this setting is enabled, skipping indexes are applied even with the FINAL modifier, potentially improving performance but with the risk of missing recent updates. This setting should be enabled in sync with the setting use_skip_indexes_if_final_exact_mode (default is enabled).
1665 : 113429 :
1666 : 113429 : Possible values:
1667 : 113429 :
1668 : 113429 : - 0 — Disabled.
1669 : 113429 : - 1 — Enabled.
1670 : 113429 : )", 0) \
1671 : 113429 : DECLARE(Bool, use_skip_indexes_if_final_exact_mode, true, R"(
1672 : 113429 : Controls whether granules returned by a skipping index are expanded in newer parts to return correct results when executing a query with the FINAL modifier.
1673 : 113429 :
1674 : 113429 : Using skip indexes may exclude rows (granules) containing the latest data which could lead to incorrect results. This setting can ensure that correct results are returned by scanning newer parts that have overlap with the ranges returned by the skip index. This setting should be disabled only if approximate results based on looking up the skip index are okay for an application.
1675 : 113429 :
1676 : 113429 : Possible values:
1677 : 113429 :
1678 : 113429 : - 0 — Disabled.
1679 : 113429 : - 1 — Enabled.
1680 : 113429 : )", 0) \
1681 : 113429 : DECLARE(Bool, use_skip_indexes_on_data_read, true, R"(
1682 : 113429 : Enable using data skipping indexes during data reading.
1683 : 113429 :
1684 : 113429 : When enabled, skip indexes are evaluated dynamically at the time each data granule is being read, rather than being analyzed in advance before query execution begins. This can reduce query startup latency.
1685 : 113429 :
1686 : 113429 : Possible values:
1687 : 113429 :
1688 : 113429 : - 0 — Disabled.
1689 : 113429 : - 1 — Enabled.
1690 : 113429 : )", 0) \
1691 : 113429 : DECLARE(Bool, use_skip_indexes_for_disjunctions, true, R"(
1692 : 113429 : Evaluate WHERE filters with mixed AND and OR conditions using skip indexes. Example: WHERE A = 5 AND (B = 5 OR C = 5).
1693 : 113429 : If disabled, skip indexes are still used to evaluate WHERE conditions but they must only contain AND-ed clauses.
1694 : 113429 :
1695 : 113429 : Possible values:
1696 : 113429 :
1697 : 113429 : - 0 — Disabled.
1698 : 113429 : - 1 — Enabled.
1699 : 113429 : )", 0) \
1700 : 113429 : DECLARE(Bool, use_skip_indexes_for_top_k, false, R"(
1701 : 113429 : Enable using data skipping indexes for TopK filtering.
1702 : 113429 :
1703 : 113429 : When enabled, if a minmax skip index exists on the column in `ORDER BY <column> LIMIT n` query, optimizer will attempt to use the minmax index to skip granules that are not relevant for the final result . This can reduce query latency.
1704 : 113429 :
1705 : 113429 : Possible values:
1706 : 113429 :
1707 : 113429 : - 0 — Disabled.
1708 : 113429 : - 1 — Enabled.
1709 : 113429 : )", 0) \
1710 : 113429 : DECLARE(Bool, use_statistics_for_part_pruning, true, R"(
1711 : 113429 : Use statistics to filter out parts during query execution.
1712 : 113429 :
1713 : 113429 : When enabled, pruning in SELECT queries will use column statistics (e.g. MinMax statistics) to eliminate parts that cannot contain matching data before reading any data.
1714 : 113429 :
1715 : 113429 : Possible values:
1716 : 113429 :
1717 : 113429 : - 0 — Disabled.
1718 : 113429 : - 1 — Enabled.
1719 : 113429 : )", 0) \
1720 : 113429 : DECLARE(Bool, use_top_k_dynamic_filtering, false, R"(
1721 : 113429 : Enable dynamic filtering optimization when executing a `ORDER BY <column> LIMIT n` query.
1722 : 113429 :
1723 : 113429 : When enabled, the query executor will try to skip granules and rows that will not be part of the final `top N` rows in the resultset. This optimization is dynamic in nature and latency improvements depends on data distribution and presence of other predicates in the query.
1724 : 113429 :
1725 : 113429 : Possible values:
1726 : 113429 :
1727 : 113429 : - 0 — Disabled.
1728 : 113429 : - 1 — Enabled.
1729 : 113429 : )", 0) \
1730 : 113429 : DECLARE(UInt64, query_plan_max_limit_for_top_k_optimization, 1000, R"(Control maximum limit value that allows to evaluate query plan for TopK optimization by using minmax skip index and dynamic threshold filtering. If zero, there is no limit.
1731 : 113429 : )", 0) \
1732 : 113429 : DECLARE(Bool, materialize_skip_indexes_on_insert, true, R"(
1733 : 113429 : If INSERTs build and store skip indexes. If disabled, skip indexes will only be built and stored [during merges](merge-tree-settings.md/#materialize_skip_indexes_on_merge) or by explicit [MATERIALIZE INDEX](/sql-reference/statements/alter/skipping-index.md/#materialize-index).
1734 : 113429 :
1735 : 113429 : See also [exclude_materialize_skip_indexes_on_insert](#exclude_materialize_skip_indexes_on_insert).
1736 : 113429 : )", 0) \
1737 : 113429 : DECLARE(String, exclude_materialize_skip_indexes_on_insert, "", R"(
1738 : 113429 : Excludes specified skip indexes from being built and stored during INSERTs. The excluded skip indexes will still be built and stored [during merges](merge-tree-settings.md/#materialize_skip_indexes_on_merge) or by an explicit
1739 : 113429 : [MATERIALIZE INDEX](/sql-reference/statements/alter/skipping-index.md/#materialize-index) query.
1740 : 113429 :
1741 : 113429 : Has no effect if [materialize_skip_indexes_on_insert](#materialize_skip_indexes_on_insert) is false.
1742 : 113429 :
1743 : 113429 : Example:
1744 : 113429 :
1745 : 113429 : ```sql
1746 : 113429 : CREATE TABLE tab
1747 : 113429 : (
1748 : 113429 : a UInt64,
1749 : 113429 : b UInt64,
1750 : 113429 : INDEX idx_a a TYPE minmax,
1751 : 113429 : INDEX idx_b b TYPE set(3)
1752 : 113429 : )
1753 : 113429 : ENGINE = MergeTree ORDER BY tuple();
1754 : 113429 :
1755 : 113429 : SET exclude_materialize_skip_indexes_on_insert='idx_a'; -- idx_a will be not be updated upon insert
1756 : 113429 : --SET exclude_materialize_skip_indexes_on_insert='idx_a, idx_b'; -- neither index would be updated on insert
1757 : 113429 :
1758 : 113429 : INSERT INTO tab SELECT number, number / 50 FROM numbers(100); -- only idx_b is updated
1759 : 113429 :
1760 : 113429 : -- since it is a session setting it can be set on a per-query level
1761 : 113429 : INSERT INTO tab SELECT number, number / 50 FROM numbers(100, 100) SETTINGS exclude_materialize_skip_indexes_on_insert='idx_b';
1762 : 113429 :
1763 : 113429 : ALTER TABLE tab MATERIALIZE INDEX idx_a; -- this query can be used to explicitly materialize the index
1764 : 113429 :
1765 : 113429 : SET exclude_materialize_skip_indexes_on_insert = DEFAULT; -- reset setting to default
1766 : 113429 : ```
1767 : 113429 : )", 0) \
1768 : 113429 : DECLARE(Bool, per_part_index_stats, false, R"(
1769 : 113429 : Logs index statistics per part
1770 : 113429 : )", 0) \
1771 : 113429 : DECLARE(Bool, materialize_statistics_on_insert, false, R"(
1772 : 113429 : If INSERTs build and insert statistics. If disabled, statistics will be build and stored during merges or by explicit MATERIALIZE STATISTICS
1773 : 113429 : )", 0) \
1774 : 113429 : DECLARE(String, ignore_data_skipping_indices, "", R"(
1775 : 113429 : Ignores the skipping indexes specified if used by the query.
1776 : 113429 :
1777 : 113429 : Consider the following example:
1778 : 113429 :
1779 : 113429 : ```sql
1780 : 113429 : CREATE TABLE data
1781 : 113429 : (
1782 : 113429 : key Int,
1783 : 113429 : x Int,
1784 : 113429 : y Int,
1785 : 113429 : INDEX x_idx x TYPE minmax GRANULARITY 1,
1786 : 113429 : INDEX y_idx y TYPE minmax GRANULARITY 1,
1787 : 113429 : INDEX xy_idx (x,y) TYPE minmax GRANULARITY 1
1788 : 113429 : )
1789 : 113429 : Engine=MergeTree()
1790 : 113429 : ORDER BY key;
1791 : 113429 :
1792 : 113429 : INSERT INTO data VALUES (1, 2, 3);
1793 : 113429 :
1794 : 113429 : SELECT * FROM data;
1795 : 113429 : SELECT * FROM data SETTINGS ignore_data_skipping_indices=''; -- query will produce CANNOT_PARSE_TEXT error.
1796 : 113429 : SELECT * FROM data SETTINGS ignore_data_skipping_indices='x_idx'; -- Ok.
1797 : 113429 : SELECT * FROM data SETTINGS ignore_data_skipping_indices='na_idx'; -- Ok.
1798 : 113429 :
1799 : 113429 : 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.
1800 : 113429 : SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx';
1801 : 113429 : ```
1802 : 113429 :
1803 : 113429 : The query without ignoring any indexes:
1804 : 113429 : ```sql
1805 : 113429 : EXPLAIN indexes = 1 SELECT * FROM data WHERE x = 1 AND y = 2;
1806 : 113429 :
1807 : 113429 : Expression ((Projection + Before ORDER BY))
1808 : 113429 : Filter (WHERE)
1809 : 113429 : ReadFromMergeTree (default.data)
1810 : 113429 : Indexes:
1811 : 113429 : PrimaryKey
1812 : 113429 : Condition: true
1813 : 113429 : Parts: 1/1
1814 : 113429 : Granules: 1/1
1815 : 113429 : Skip
1816 : 113429 : Name: x_idx
1817 : 113429 : Description: minmax GRANULARITY 1
1818 : 113429 : Parts: 0/1
1819 : 113429 : Granules: 0/1
1820 : 113429 : Skip
1821 : 113429 : Name: y_idx
1822 : 113429 : Description: minmax GRANULARITY 1
1823 : 113429 : Parts: 0/0
1824 : 113429 : Granules: 0/0
1825 : 113429 : Skip
1826 : 113429 : Name: xy_idx
1827 : 113429 : Description: minmax GRANULARITY 1
1828 : 113429 : Parts: 0/0
1829 : 113429 : Granules: 0/0
1830 : 113429 : ```
1831 : 113429 :
1832 : 113429 : Ignoring the `xy_idx` index:
1833 : 113429 : ```sql
1834 : 113429 : EXPLAIN indexes = 1 SELECT * FROM data WHERE x = 1 AND y = 2 SETTINGS ignore_data_skipping_indices='xy_idx';
1835 : 113429 :
1836 : 113429 : Expression ((Projection + Before ORDER BY))
1837 : 113429 : Filter (WHERE)
1838 : 113429 : ReadFromMergeTree (default.data)
1839 : 113429 : Indexes:
1840 : 113429 : PrimaryKey
1841 : 113429 : Condition: true
1842 : 113429 : Parts: 1/1
1843 : 113429 : Granules: 1/1
1844 : 113429 : Skip
1845 : 113429 : Name: x_idx
1846 : 113429 : Description: minmax GRANULARITY 1
1847 : 113429 : Parts: 0/1
1848 : 113429 : Granules: 0/1
1849 : 113429 : Skip
1850 : 113429 : Name: y_idx
1851 : 113429 : Description: minmax GRANULARITY 1
1852 : 113429 : Parts: 0/0
1853 : 113429 : Granules: 0/0
1854 : 113429 : ```
1855 : 113429 :
1856 : 113429 : Works with tables in the MergeTree family.
1857 : 113429 : )", 0) \
1858 : 113429 : \
1859 : 113429 : DECLARE(String, force_data_skipping_indices, "", R"(
1860 : 113429 : Disables query execution if passed data skipping indices wasn't used.
1861 : 113429 :
1862 : 113429 : Consider the following example:
1863 : 113429 :
1864 : 113429 : ```sql
1865 : 113429 : CREATE TABLE data
1866 : 113429 : (
1867 : 113429 : key Int,
1868 : 113429 : d1 Int,
1869 : 113429 : d1_null Nullable(Int),
1870 : 113429 : INDEX d1_idx d1 TYPE minmax GRANULARITY 1,
1871 : 113429 : INDEX d1_null_idx assumeNotNull(d1_null) TYPE minmax GRANULARITY 1
1872 : 113429 : )
1873 : 113429 : Engine=MergeTree()
1874 : 113429 : ORDER BY key;
1875 : 113429 :
1876 : 113429 : SELECT * FROM data_01515;
1877 : 113429 : SELECT * FROM data_01515 SETTINGS force_data_skipping_indices=''; -- query will produce CANNOT_PARSE_TEXT error.
1878 : 113429 : SELECT * FROM data_01515 SETTINGS force_data_skipping_indices='d1_idx'; -- query will produce INDEX_NOT_USED error.
1879 : 113429 : SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='d1_idx'; -- Ok.
1880 : 113429 : SELECT * FROM data_01515 WHERE d1 = 0 SETTINGS force_data_skipping_indices='`d1_idx`'; -- Ok (example of full featured parser).
1881 : 113429 : 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.
1882 : 113429 : SELECT * FROM data_01515 WHERE d1 = 0 AND assumeNotNull(d1_null) = 0 SETTINGS force_data_skipping_indices='`d1_idx`, d1_null_idx'; -- Ok.
1883 : 113429 : ```
1884 : 113429 : )", 0) \
1885 : 113429 : DECLARE(Bool, secondary_indices_enable_bulk_filtering, true, R"(
1886 : 113429 : Enable the bulk filtering algorithm for indices. It is expected to be always better, but we have this setting for compatibility and control.
1887 : 113429 : )", 0) \
1888 : 113429 : DECLARE(Float, max_streams_to_max_threads_ratio, 1, R"(
1889 : 113429 : Allows you to use more sources than the number of threads - to more evenly distribute work across threads. It is assumed that this is a temporary solution since it will be possible in the future to make the number of sources equal to the number of threads, but for each source to dynamically select available work for itself.
1890 : 113429 : )", 0) \
1891 : 113429 : DECLARE(Float, max_streams_multiplier_for_merge_tables, 5, R"(
1892 : 113429 : Ask more streams when reading from Merge table. Streams will be spread across tables that Merge table will use. This allows more even distribution of work across threads and is especially helpful when merged tables differ in size.
1893 : 113429 : )", 0) \
1894 : 113429 : \
1895 : 113429 : DECLARE(String, network_compression_method, "LZ4", R"(
1896 : 113429 : The codec for compressing the client/server and server/server communication.
1897 : 113429 :
1898 : 113429 : Possible values:
1899 : 113429 :
1900 : 113429 : - `NONE` — no compression.
1901 : 113429 : - `LZ4` — use the LZ4 codec.
1902 : 113429 : - `LZ4HC` — use the LZ4HC codec.
1903 : 113429 : - `ZSTD` — use the ZSTD codec.
1904 : 113429 :
1905 : 113429 : **See Also**
1906 : 113429 :
1907 : 113429 : - [network_zstd_compression_level](#network_zstd_compression_level)
1908 : 113429 : )", 0) \
1909 : 113429 : \
1910 : 113429 : DECLARE(Int64, network_zstd_compression_level, 1, R"(
1911 : 113429 : Adjusts the level of ZSTD compression. Used only when [network_compression_method](#network_compression_method) is set to `ZSTD`.
1912 : 113429 :
1913 : 113429 : Possible values:
1914 : 113429 :
1915 : 113429 : - Positive integer from 1 to 15.
1916 : 113429 : )", 0) \
1917 : 113429 : \
1918 : 113429 : DECLARE(Int64, zstd_window_log_max, 0, R"(
1919 : 113429 : Allows you to select the max window log of ZSTD (it will not be used for MergeTree family)
1920 : 113429 : )", 0) \
1921 : 113429 : \
1922 : 113429 : DECLARE(UInt64, priority, 0, R"(
1923 : 113429 : Priority of the query. 1 - the highest, higher value - lower priority; 0 - do not use priorities.
1924 : 113429 : )", 0) \
1925 : 113429 : DECLARE(Bool, log_queries, true, R"(
1926 : 113429 : Setting up query logging.
1927 : 113429 :
1928 : 113429 : Queries sent to ClickHouse with this setup are logged according to the rules in the [query_log](../../operations/server-configuration-parameters/settings.md/#query_log) server configuration parameter.
1929 : 113429 :
1930 : 113429 : Example:
1931 : 113429 :
1932 : 113429 : ```text
1933 : 113429 : log_queries=1
1934 : 113429 : ```
1935 : 113429 : )", 0) \
1936 : 113429 : DECLARE(Bool, log_formatted_queries, false, R"(
1937 : 113429 : Allows to log formatted queries to the [system.query_log](../../operations/system-tables/query_log.md) system table (populates `formatted_query` column in the [system.query_log](../../operations/system-tables/query_log.md)).
1938 : 113429 :
1939 : 113429 : Possible values:
1940 : 113429 :
1941 : 113429 : - 0 — Formatted queries are not logged in the system table.
1942 : 113429 : - 1 — Formatted queries are logged in the system table.
1943 : 113429 : )", 0) \
1944 : 113429 : DECLARE(LogQueriesType, log_queries_min_type, QueryLogElementType::QUERY_START, R"(
1945 : 113429 : `query_log` minimal type to log.
1946 : 113429 :
1947 : 113429 : Possible values:
1948 : 113429 : - `QUERY_START` (`=1`)
1949 : 113429 : - `QUERY_FINISH` (`=2`)
1950 : 113429 : - `EXCEPTION_BEFORE_START` (`=3`)
1951 : 113429 : - `EXCEPTION_WHILE_PROCESSING` (`=4`)
1952 : 113429 :
1953 : 113429 : 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`:
1954 : 113429 :
1955 : 113429 : ```text
1956 : 113429 : log_queries_min_type='EXCEPTION_WHILE_PROCESSING'
1957 : 113429 : ```
1958 : 113429 : )", 0) \
1959 : 113429 : DECLARE(Milliseconds, log_queries_min_query_duration_ms, 0, R"(
1960 : 113429 : 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](https://dev.mysql.com/doc/refman/5.7/slow-query-log.html)), and this basically means that you will not find them in the following tables:
1961 : 113429 :
1962 : 113429 : - `system.query_log`
1963 : 113429 : - `system.query_thread_log`
1964 : 113429 :
1965 : 113429 : Only the queries with the following type will get to the log:
1966 : 113429 :
1967 : 113429 : - `QUERY_FINISH`
1968 : 113429 : - `EXCEPTION_WHILE_PROCESSING`
1969 : 113429 :
1970 : 113429 : - Type: milliseconds
1971 : 113429 : - Default value: 0 (any query)
1972 : 113429 : )", 0) \
1973 : 113429 : DECLARE(UInt64, log_queries_cut_to_length, 100000, R"(
1974 : 113429 : 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.
1975 : 113429 : )", 0) \
1976 : 113429 : DECLARE(Float, log_queries_probability, 1., R"(
1977 : 113429 : Allows a user to write to [query_log](../../operations/system-tables/query_log.md), [query_thread_log](../../operations/system-tables/query_thread_log.md), and [query_views_log](../../operations/system-tables/query_views_log.md) 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.
1978 : 113429 :
1979 : 113429 : Possible values:
1980 : 113429 :
1981 : 113429 : - 0 — Queries are not logged in the system tables.
1982 : 113429 : - 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.
1983 : 113429 : - 1 — All queries are logged in the system tables.
1984 : 113429 : )", 0) \
1985 : 113429 : \
1986 : 113429 : DECLARE(Bool, log_processors_profiles, true, R"(
1987 : 113429 : Write time that processor spent during execution/waiting for data to `system.processors_profile_log` table.
1988 : 113429 :
1989 : 113429 : See also:
1990 : 113429 :
1991 : 113429 : - [`system.processors_profile_log`](../../operations/system-tables/processors_profile_log.md)
1992 : 113429 : - [`EXPLAIN PIPELINE`](../../sql-reference/statements/explain.md/#explain-pipeline)
1993 : 113429 : )", 0) \
1994 : 113429 : DECLARE(DistributedProductMode, distributed_product_mode, DistributedProductMode::DENY, R"(
1995 : 113429 : Changes the behaviour of [distributed subqueries](../../sql-reference/operators/in.md).
1996 : 113429 :
1997 : 113429 : 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.
1998 : 113429 :
1999 : 113429 : Restrictions:
2000 : 113429 :
2001 : 113429 : - Only applied for IN and JOIN subqueries.
2002 : 113429 : - Only if the FROM section uses a distributed table containing more than one shard.
2003 : 113429 : - If the subquery concerns a distributed table containing more than one shard.
2004 : 113429 : - Not used for a table-valued [remote](../../sql-reference/table-functions/remote.md) function.
2005 : 113429 :
2006 : 113429 : Possible values:
2007 : 113429 :
2008 : 113429 : - `deny` — Default value. Prohibits using these types of subqueries (returns the "Double-distributed in/JOIN subqueries is denied" exception).
2009 : 113429 : - `local` — Replaces the database and table in the subquery with local ones for the destination server (shard), leaving the normal `IN`/`JOIN.`
2010 : 113429 : - `global` — Replaces the `IN`/`JOIN` query with `GLOBAL IN`/`GLOBAL JOIN.`
2011 : 113429 : - `allow` — Allows the use of these types of subqueries.
2012 : 113429 : )", IMPORTANT) \
2013 : 113429 : \
2014 : 113429 : DECLARE(UInt64, max_concurrent_queries_for_all_users, 0, R"(
2015 : 113429 : Throw exception if the value of this setting is less or equal than the current number of simultaneously processed queries.
2016 : 113429 :
2017 : 113429 : 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.
2018 : 113429 :
2019 : 113429 : Modifying the setting for one query or user does not affect other queries.
2020 : 113429 :
2021 : 113429 : Possible values:
2022 : 113429 :
2023 : 113429 : - Positive integer.
2024 : 113429 : - 0 — No limit.
2025 : 113429 :
2026 : 113429 : **Example**
2027 : 113429 :
2028 : 113429 : ```xml
2029 : 113429 : <max_concurrent_queries_for_all_users>99</max_concurrent_queries_for_all_users>
2030 : 113429 : ```
2031 : 113429 :
2032 : 113429 : **See Also**
2033 : 113429 :
2034 : 113429 : - [max_concurrent_queries](/operations/server-configuration-parameters/settings#max_concurrent_queries)
2035 : 113429 :
2036 : 113429 : Cloud default value: `1000`.
2037 : 113429 : )", 0) \
2038 : 113429 : DECLARE(UInt64, max_concurrent_queries_for_user, 0, R"(
2039 : 113429 : The maximum number of simultaneously processed queries per user.
2040 : 113429 :
2041 : 113429 : Possible values:
2042 : 113429 :
2043 : 113429 : - Positive integer.
2044 : 113429 : - 0 — No limit.
2045 : 113429 :
2046 : 113429 : **Example**
2047 : 113429 :
2048 : 113429 : ```xml
2049 : 113429 : <max_concurrent_queries_for_user>5</max_concurrent_queries_for_user>
2050 : 113429 : ```
2051 : 113429 : )", 0) \
2052 : 113429 : \
2053 : 113429 : DECLARE(DeduplicateInsertMode, deduplicate_insert, DeduplicateInsertMode::ENABLE, R"(
2054 : 113429 : Enables or disables block deduplication of `INSERT INTO` (for Replicated\* tables).
2055 : 113429 : The setting overrides `insert_deduplicate` and `async_insert_deduplicate` settings.
2056 : 113429 : That setting has three possible values:
2057 : 113429 : - disable — Deduplication is disabled for `INSERT INTO` query.
2058 : 113429 : - enable — Deduplication is enabled for `INSERT INTO` query.
2059 : 113429 : - backward_compatible_choice — Deduplication is enabled if `insert_deduplicate` or `async_insert_deduplicate` are enabled for specific insert type.
2060 : 113429 : )", 0) \
2061 : 113429 : \
2062 : 113429 : DECLARE(DeduplicateInsertSelectMode, deduplicate_insert_select, DeduplicateInsertSelectMode::ENABLE_WHEN_POSSIBLE, R"(
2063 : 113429 : Enables or disables block deduplication of `INSERT SELECT` (for Replicated\* tables).
2064 : 113429 : The setting overrids `insert_deduplicate` and `deduplicate_insert` for `INSERT SELECT` queries.
2065 : 113429 : That setting has four possible values:
2066 : 113429 : - disable — Deduplication is disabled for `INSERT SELECT` query.
2067 : 113429 : - force_enable — Deduplication is enabled for `INSERT SELECT` query. If select result is not stable, exception is thrown.
2068 : 113429 : - enable_when_possible — Deduplication is enabled if `insert_deduplicate` is enable and select result is stable, otherwise disabled.
2069 : 113429 : - enable_even_for_bad_queries - Deduplication is enabled if `insert_deduplicate` is enable. If select result is not stable, warning is logged, but query is executed with deduplication. This option is for backward compatibility. Consider to use other options instead as it may lead to unexpected results.
2070 : 113429 : )", 0) \
2071 : 113429 : \
2072 : 113429 : DECLARE(Bool, insert_deduplicate, true, R"(
2073 : 113429 : Enables or disables block deduplication of `INSERT` (for Replicated\* tables).
2074 : 113429 :
2075 : 113429 : Possible values:
2076 : 113429 :
2077 : 113429 : - 0 — Disabled.
2078 : 113429 : - 1 — Enabled.
2079 : 113429 :
2080 : 113429 : By default, blocks inserted into replicated tables by the `INSERT` statement are deduplicated (see [Data Replication](../../engines/table-engines/mergetree-family/replication.md)).
2081 : 113429 : For the replicated tables by default the only 100 of the most recent blocks for each partition are deduplicated (see [replicated_deduplication_window](merge-tree-settings.md/#replicated_deduplication_window), [replicated_deduplication_window_seconds](merge-tree-settings.md/#replicated_deduplication_window_seconds)).
2082 : 113429 : For not replicated tables see [non_replicated_deduplication_window](merge-tree-settings.md/#non_replicated_deduplication_window).
2083 : 113429 : )", 0) \
2084 : 113429 : DECLARE(Bool, async_insert_deduplicate, false, R"(
2085 : 113429 : For async INSERT queries in the replicated table, specifies that deduplication of inserting blocks should be performed
2086 : 113429 : )", 0) \
2087 : 113429 : \
2088 : 113429 : DECLARE(UInt64Auto, insert_quorum, 0, R"(
2089 : 113429 : :::note
2090 : 113429 : This setting is not applicable to SharedMergeTree, see [SharedMergeTree consistency](/cloud/reference/shared-merge-tree#consistency) for more information.
2091 : 113429 : :::
2092 : 113429 :
2093 : 113429 : Enables the quorum writes.
2094 : 113429 :
2095 : 113429 : - If `insert_quorum < 2`, the quorum writes are disabled.
2096 : 113429 : - If `insert_quorum >= 2`, the quorum writes are enabled.
2097 : 113429 : - If `insert_quorum = 'auto'`, use majority number (`number_of_replicas / 2 + 1`) as quorum number.
2098 : 113429 :
2099 : 113429 : Quorum writes
2100 : 113429 :
2101 : 113429 : `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.
2102 : 113429 :
2103 : 113429 : 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](#select_sequential_consistency).
2104 : 113429 :
2105 : 113429 : ClickHouse generates an exception:
2106 : 113429 :
2107 : 113429 : - If the number of available replicas at the time of the query is less than the `insert_quorum`.
2108 : 113429 : - 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.
2109 : 113429 :
2110 : 113429 : See also:
2111 : 113429 :
2112 : 113429 : - [insert_quorum_timeout](#insert_quorum_timeout)
2113 : 113429 : - [insert_quorum_parallel](#insert_quorum_parallel)
2114 : 113429 : - [select_sequential_consistency](#select_sequential_consistency)
2115 : 113429 : )", 0) \
2116 : 113429 : DECLARE(Milliseconds, insert_quorum_timeout, 600000, R"(
2117 : 113429 : 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.
2118 : 113429 :
2119 : 113429 : See also:
2120 : 113429 :
2121 : 113429 : - [insert_quorum](#insert_quorum)
2122 : 113429 : - [insert_quorum_parallel](#insert_quorum_parallel)
2123 : 113429 : - [select_sequential_consistency](#select_sequential_consistency)
2124 : 113429 : )", 0) \
2125 : 113429 : DECLARE(Bool, insert_quorum_parallel, true, R"(
2126 : 113429 : :::note
2127 : 113429 : This setting is not applicable to SharedMergeTree, see [SharedMergeTree consistency](/cloud/reference/shared-merge-tree#consistency) for more information.
2128 : 113429 : :::
2129 : 113429 :
2130 : 113429 : 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.
2131 : 113429 :
2132 : 113429 : Possible values:
2133 : 113429 :
2134 : 113429 : - 0 — Disabled.
2135 : 113429 : - 1 — Enabled.
2136 : 113429 :
2137 : 113429 : See also:
2138 : 113429 :
2139 : 113429 : - [insert_quorum](#insert_quorum)
2140 : 113429 : - [insert_quorum_timeout](#insert_quorum_timeout)
2141 : 113429 : - [select_sequential_consistency](#select_sequential_consistency)
2142 : 113429 : )", 0) \
2143 : 113429 : DECLARE(UInt64, select_sequential_consistency, 0, R"(
2144 : 113429 : :::note
2145 : 113429 : This setting differ in behavior between SharedMergeTree and ReplicatedMergeTree, see [SharedMergeTree consistency](/cloud/reference/shared-merge-tree#consistency) for more information about the behavior of `select_sequential_consistency` in SharedMergeTree.
2146 : 113429 : :::
2147 : 113429 :
2148 : 113429 : Enables or disables sequential consistency for `SELECT` queries. Requires `insert_quorum_parallel` to be disabled (enabled by default).
2149 : 113429 :
2150 : 113429 : Possible values:
2151 : 113429 :
2152 : 113429 : - 0 — Disabled.
2153 : 113429 : - 1 — Enabled.
2154 : 113429 :
2155 : 113429 : Usage
2156 : 113429 :
2157 : 113429 : 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.
2158 : 113429 :
2159 : 113429 : 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.
2160 : 113429 :
2161 : 113429 : See also:
2162 : 113429 :
2163 : 113429 : - [insert_quorum](#insert_quorum)
2164 : 113429 : - [insert_quorum_timeout](#insert_quorum_timeout)
2165 : 113429 : - [insert_quorum_parallel](#insert_quorum_parallel)
2166 : 113429 : )", 0) \
2167 : 113429 : DECLARE(Bool, update_sequential_consistency, true, R"(
2168 : 113429 : If true set of parts is updated to the latest version before execution of update.
2169 : 113429 : )", 0) \
2170 : 113429 : DECLARE(UpdateParallelMode, update_parallel_mode, UpdateParallelMode::AUTO, R"(
2171 : 113429 : Determines the behavior of concurrent update queries.
2172 : 113429 :
2173 : 113429 : Possible values:
2174 : 113429 : - `sync` - run sequentially all `UPDATE` queries.
2175 : 113429 : - `auto` - run sequentially only `UPDATE` queries with dependencies between columns updated in one query and columns used in expressions of another query.
2176 : 113429 : - `async` - do not synchronize update queries.
2177 : 113429 : )", 0) \
2178 : 113429 : DECLARE(UInt64, table_function_remote_max_addresses, 1000, R"(
2179 : 113429 : Sets the maximum number of addresses generated from patterns for the [remote](../../sql-reference/table-functions/remote.md) function.
2180 : 113429 :
2181 : 113429 : Possible values:
2182 : 113429 :
2183 : 113429 : - Positive integer.
2184 : 113429 : )", 0) \
2185 : 113429 : DECLARE(Milliseconds, read_backoff_min_latency_ms, 1000, R"(
2186 : 113429 : Setting to reduce the number of threads in case of slow reads. Pay attention only to reads that took at least that much time.
2187 : 113429 : )", 0) \
2188 : 113429 : DECLARE(UInt64, read_backoff_max_throughput, 1048576, R"(
2189 : 113429 : Settings to reduce the number of threads in case of slow reads. Count events when the read bandwidth is less than that many bytes per second.
2190 : 113429 : )", 0) \
2191 : 113429 : DECLARE(Milliseconds, read_backoff_min_interval_between_events_ms, 1000, R"(
2192 : 113429 : Settings to reduce the number of threads in case of slow reads. Do not pay attention to the event, if the previous one has passed less than a certain amount of time.
2193 : 113429 : )", 0) \
2194 : 113429 : DECLARE(UInt64, read_backoff_min_events, 2, R"(
2195 : 113429 : Settings to reduce the number of threads in case of slow reads. The number of events after which the number of threads will be reduced.
2196 : 113429 : )", 0) \
2197 : 113429 : \
2198 : 113429 : DECLARE(UInt64, read_backoff_min_concurrency, 1, R"(
2199 : 113429 : Settings to try keeping the minimal number of threads in case of slow reads.
2200 : 113429 : )", 0) \
2201 : 113429 : \
2202 : 113429 : DECLARE(Float, memory_tracker_fault_probability, 0., R"(
2203 : 113429 : For testing of `exception safety` - throw an exception every time you allocate memory with the specified probability.
2204 : 113429 : )", 0) \
2205 : 113429 : DECLARE(Float, merge_tree_read_split_ranges_into_intersecting_and_non_intersecting_injection_probability, 0.0, R"(
2206 : 113429 : For testing of `PartsSplitter` - split read ranges into intersecting and non intersecting every time you read from MergeTree with the specified probability.
2207 : 113429 : )", 0) \
2208 : 113429 : \
2209 : 113429 : DECLARE(Bool, enable_http_compression, true, R"(
2210 : 113429 : Enables or disables data compression in the response to an HTTP request.
2211 : 113429 :
2212 : 113429 : For more information, read the [HTTP interface description](/interfaces/http).
2213 : 113429 :
2214 : 113429 : Possible values:
2215 : 113429 :
2216 : 113429 : - 0 — Disabled.
2217 : 113429 : - 1 — Enabled.
2218 : 113429 : )", 0) \
2219 : 113429 : DECLARE(Int64, http_zlib_compression_level, 3, R"(
2220 : 113429 : Sets the level of data compression in the response to an HTTP request if [enable_http_compression = 1](#enable_http_compression).
2221 : 113429 :
2222 : 113429 : Possible values: Numbers from 1 to 9.
2223 : 113429 : )", 0) \
2224 : 113429 : \
2225 : 113429 : DECLARE(Bool, http_native_compression_disable_checksumming_on_decompress, false, R"(
2226 : 113429 : 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`).
2227 : 113429 :
2228 : 113429 : For more information, read the [HTTP interface description](/interfaces/http).
2229 : 113429 :
2230 : 113429 : Possible values:
2231 : 113429 :
2232 : 113429 : - 0 — Disabled.
2233 : 113429 : - 1 — Enabled.
2234 : 113429 : )", 0) \
2235 : 113429 : DECLARE(Map, http_response_headers, "", R"(
2236 : 113429 : Allows to add or override HTTP headers which the server will return in the response with a successful query result.
2237 : 113429 : This only affects the HTTP interface.
2238 : 113429 :
2239 : 113429 : If the header is already set by default, the provided value will override it.
2240 : 113429 : If the header was not set by default, it will be added to the list of headers.
2241 : 113429 : Headers that are set by the server by default and not overridden by this setting, will remain.
2242 : 113429 :
2243 : 113429 : The setting allows you to set a header to a constant value. Currently there is no way to set a header to a dynamically calculated value.
2244 : 113429 :
2245 : 113429 : Neither names or values can contain ASCII control characters.
2246 : 113429 :
2247 : 113429 : If you implement a UI application which allows users to modify settings but at the same time makes decisions based on the returned headers, it is recommended to restrict this setting to readonly.
2248 : 113429 :
2249 : 113429 : Example: `SET http_response_headers = '{"Content-Type": "image/png"}'`
2250 : 113429 : )", 0) \
2251 : 113429 : \
2252 : 113429 : DECLARE(String, count_distinct_implementation, "uniqExact", R"(
2253 : 113429 : Specifies which of the `uniq*` functions should be used to perform the [COUNT(DISTINCT ...)](/sql-reference/aggregate-functions/reference/count) construction.
2254 : 113429 :
2255 : 113429 : Possible values:
2256 : 113429 :
2257 : 113429 : - [uniq](/sql-reference/aggregate-functions/reference/uniq)
2258 : 113429 : - [uniqCombined](/sql-reference/aggregate-functions/reference/uniqcombined)
2259 : 113429 : - [uniqCombined64](/sql-reference/aggregate-functions/reference/uniqcombined64)
2260 : 113429 : - [uniqHLL12](/sql-reference/aggregate-functions/reference/uniqhll12)
2261 : 113429 : - [uniqExact](/sql-reference/aggregate-functions/reference/uniqexact)
2262 : 113429 : )", 0) \
2263 : 113429 : \
2264 : 113429 : DECLARE(Bool, add_http_cors_header, false, R"(
2265 : 113429 : Write add http CORS header.
2266 : 113429 : )", 0) \
2267 : 113429 : \
2268 : 113429 : DECLARE(UInt64, max_http_get_redirects, 0, R"(
2269 : 113429 : 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.
2270 : 113429 :
2271 : 113429 : Cloud default value: `10`.
2272 : 113429 : )", 0) \
2273 : 113429 : \
2274 : 113429 : DECLARE(Bool, use_client_time_zone, false, R"(
2275 : 113429 : Use client timezone for interpreting DateTime string values, instead of adopting server timezone.
2276 : 113429 : )", 0) \
2277 : 113429 : \
2278 : 113429 : DECLARE(Bool, send_profile_events, true, R"(
2279 : 113429 : Enables or disables sending of [ProfileEvents](/native-protocol/server.md#profile-events) packets to the client.
2280 : 113429 :
2281 : 113429 : This can be disabled to reduce network traffic for clients that do not require profile events.
2282 : 113429 :
2283 : 113429 : Possible values:
2284 : 113429 :
2285 : 113429 : - 0 — Disabled.
2286 : 113429 : - 1 — Enabled.
2287 : 113429 : )", 0) \
2288 : 113429 : \
2289 : 113429 : DECLARE(Bool, send_progress_in_http_headers, false, R"(
2290 : 113429 : Enables or disables `X-ClickHouse-Progress` HTTP response headers in `clickhouse-server` responses.
2291 : 113429 :
2292 : 113429 : For more information, read the [HTTP interface description](/interfaces/http).
2293 : 113429 :
2294 : 113429 : Possible values:
2295 : 113429 :
2296 : 113429 : - 0 — Disabled.
2297 : 113429 : - 1 — Enabled.
2298 : 113429 : )", 0) \
2299 : 113429 : \
2300 : 113429 : DECLARE(UInt64, http_headers_progress_interval_ms, 100, R"(
2301 : 113429 : Do not send HTTP headers X-ClickHouse-Progress more frequently than at each specified interval.
2302 : 113429 : )", 0) \
2303 : 113429 : DECLARE(Bool, http_wait_end_of_query, false, R"(
2304 : 113429 : Enable HTTP response buffering on the server-side.
2305 : 113429 : )", 0) \
2306 : 113429 : DECLARE(Bool, http_write_exception_in_output_format, false, R"(
2307 : 113429 : Write exception in output format to produce valid output. Works with JSON and XML formats.
2308 : 113429 : )", 0) \
2309 : 113429 : DECLARE(UInt64, http_response_buffer_size, 0, R"(
2310 : 113429 : 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).
2311 : 113429 : )", 0) \
2312 : 113429 : \
2313 : 113429 : DECLARE(Bool, fsync_metadata, true, R"(
2314 : 113429 : Enables or disables [fsync](http://pubs.opengroup.org/onlinepubs/9699919799/functions/fsync.html) when writing `.sql` files. Enabled by default.
2315 : 113429 :
2316 : 113429 : It makes sense to disable it if the server has millions of tiny tables that are constantly being created and destroyed.
2317 : 113429 : )", 0) \
2318 : 113429 : \
2319 : 113429 : DECLARE(Bool, join_use_nulls, false, R"(
2320 : 113429 : Sets the type of [JOIN](../../sql-reference/statements/select/join.md) behaviour. When merging tables, empty cells may appear. ClickHouse fills them differently based on this setting.
2321 : 113429 :
2322 : 113429 : Possible values:
2323 : 113429 :
2324 : 113429 : - 0 — The empty cells are filled with the default value of the corresponding field type.
2325 : 113429 : - 1 — `JOIN` behaves the same way as in standard SQL. The type of the corresponding field is converted to [Nullable](/sql-reference/data-types/nullable), and empty cells are filled with [NULL](/sql-reference/syntax).
2326 : 113429 : )", IMPORTANT) \
2327 : 113429 : \
2328 : 113429 : DECLARE(UInt64, join_output_by_rowlist_perkey_rows_threshold, 5, R"(
2329 : 113429 : The lower limit of per-key average rows in the right table to determine whether to output by row list in hash join.
2330 : 113429 : )", 0) \
2331 : 113429 : DECLARE(JoinStrictness, join_default_strictness, JoinStrictness::All, R"(
2332 : 113429 : Sets default strictness for [JOIN clauses](/sql-reference/statements/select/join).
2333 : 113429 :
2334 : 113429 : Possible values:
2335 : 113429 :
2336 : 113429 : - `ALL` — If the right table has several matching rows, ClickHouse creates a [Cartesian product](https://en.wikipedia.org/wiki/Cartesian_product) from matching rows. This is the normal `JOIN` behaviour from standard SQL.
2337 : 113429 : - `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.
2338 : 113429 : - `ASOF` — For joining sequences with an uncertain match.
2339 : 113429 : - `Empty string` — If `ALL` or `ANY` is not specified in the query, ClickHouse throws an exception.
2340 : 113429 : )", 0) \
2341 : 113429 : DECLARE(Bool, any_join_distinct_right_table_keys, false, R"(
2342 : 113429 : Enables legacy ClickHouse server behaviour in `ANY INNER|LEFT JOIN` operations.
2343 : 113429 :
2344 : 113429 : :::note
2345 : 113429 : Use this setting only for backward compatibility if your use cases depend on legacy `JOIN` behaviour.
2346 : 113429 : :::
2347 : 113429 :
2348 : 113429 : When the legacy behaviour is enabled:
2349 : 113429 :
2350 : 113429 : - 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.
2351 : 113429 : - Results of `ANY INNER JOIN` operations contain all rows from the left table like the `SEMI LEFT JOIN` operations do.
2352 : 113429 :
2353 : 113429 : When the legacy behaviour is disabled:
2354 : 113429 :
2355 : 113429 : - 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.
2356 : 113429 : - Results of `ANY INNER JOIN` operations contain one row per key from both the left and right tables.
2357 : 113429 :
2358 : 113429 : Possible values:
2359 : 113429 :
2360 : 113429 : - 0 — Legacy behaviour is disabled.
2361 : 113429 : - 1 — Legacy behaviour is enabled.
2362 : 113429 :
2363 : 113429 : See also:
2364 : 113429 :
2365 : 113429 : - [JOIN strictness](/sql-reference/statements/select/join#settings)
2366 : 113429 : )", IMPORTANT) \
2367 : 113429 : DECLARE(Bool, single_join_prefer_left_table, true, R"(
2368 : 113429 : For single JOIN in case of identifier ambiguity prefer left table
2369 : 113429 : )", IMPORTANT) \
2370 : 113429 : \
2371 : 113429 : DECLARE(BoolAuto, query_plan_join_swap_table, Field("auto"), R"(
2372 : 113429 : Determine which side of the join should be the build table (also called inner, the one inserted into the hash table for a hash join) in the query plan. This setting is supported only for `ALL` join strictness with the `JOIN ON` clause. Possible values are:
2373 : 113429 : - 'auto': Let the planner decide which table to use as the build table.
2374 : 113429 : - 'false': Never swap tables (the right table is the build table).
2375 : 113429 : - 'true': Always swap tables (the left table is the build table).
2376 : 113429 : )", 0) \
2377 : 113429 : DECLARE(UInt64, query_plan_optimize_join_order_limit, 10, R"(
2378 : 113429 : Optimize the order of joins within the same subquery. Currently only supported for very limited cases.
2379 : 113429 : Value is the maximum number of tables to optimize.
2380 : 113429 : )", 0) \
2381 : 113429 : DECLARE(UInt64, query_plan_optimize_join_order_randomize, 0, R"(
2382 : 113429 : When non-zero, the join order optimizer uses randomly generated cardinalities and NDVs instead of real statistics.
2383 : 113429 : When set to 1, a random seed is generated, when set to a value > 1, that value is used as the seed directly.
2384 : 113429 : This is intended for testing to find errors caused by different join orderings.
2385 : 113429 : )", EXPERIMENTAL) \
2386 : 113429 : \
2387 : 113429 : DECLARE(Bool, enable_join_transitive_predicates, false, R"(
2388 : 113429 : Infer transitive equi-join predicates from existing join conditions.
2389 : 113429 : For example, given `A.x = B.x` and `B.x = C.x`, a synthetic `A.x = C.x` predicate
2390 : 113429 : is added so the join order optimizer can consider direct (A JOIN C) plans.
2391 : 113429 : )", EXPERIMENTAL) \
2392 : 113429 : \
2393 : 113429 : DECLARE(Bool, query_plan_join_shard_by_pk_ranges, false, R"(
2394 : 113429 : Apply sharding for JOIN if join keys contain a prefix of PRIMARY KEY for both tables. Supported for hash, parallel_hash and full_sorting_merge algorithms. Usually does not speed up queries but may lower memory consumption.
2395 : 113429 : )", 0) \
2396 : 113429 : \
2397 : 113429 : DECLARE(Bool, query_plan_display_internal_aliases, false, R"(
2398 : 113429 : Show internal aliases (such as __table1) in EXPLAIN PLAN instead of those specified in the original query.
2399 : 113429 : )", 0) \
2400 : 113429 : \
2401 : 113429 : DECLARE(UInt64, query_plan_max_step_description_length, 500, R"(
2402 : 113429 : Maximum length of step description in EXPLAIN PLAN.
2403 : 113429 : )", 0) \
2404 : 113429 : \
2405 : 113429 : DECLARE(UInt64, preferred_block_size_bytes, 1000000, R"(
2406 : 113429 : 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.
2407 : 113429 : )", 0) \
2408 : 113429 : \
2409 : 113429 : DECLARE(UInt64, max_replica_delay_for_distributed_queries, 300, R"(
2410 : 113429 : Disables lagging replicas for distributed queries. See [Replication](../../engines/table-engines/mergetree-family/replication.md).
2411 : 113429 :
2412 : 113429 : Sets the time in seconds. If a replica's lag is greater than or equal to the set value, this replica is not used.
2413 : 113429 :
2414 : 113429 : Possible values:
2415 : 113429 :
2416 : 113429 : - Positive integer.
2417 : 113429 : - 0 — Replica lags are not checked.
2418 : 113429 :
2419 : 113429 : To prevent the use of any replica with a non-zero lag, set this parameter to 1.
2420 : 113429 :
2421 : 113429 : Used when performing `SELECT` from a distributed table that points to replicated tables.
2422 : 113429 : )", 0) \
2423 : 113429 : DECLARE(Bool, fallback_to_stale_replicas_for_distributed_queries, true, R"(
2424 : 113429 : Forces a query to an out-of-date replica if updated data is not available. See [Replication](../../engines/table-engines/mergetree-family/replication.md).
2425 : 113429 :
2426 : 113429 : ClickHouse selects the most relevant from the outdated replicas of the table.
2427 : 113429 :
2428 : 113429 : Used when performing `SELECT` from a distributed table that points to replicated tables.
2429 : 113429 :
2430 : 113429 : By default, 1 (enabled).
2431 : 113429 : )", 0) \
2432 : 113429 : DECLARE(UInt64, preferred_max_column_in_block_size_bytes, 0, R"(
2433 : 113429 : Limit on max column size in block while reading. Helps to decrease cache misses count. Should be close to L2 cache size.
2434 : 113429 : )", 0) \
2435 : 113429 : \
2436 : 113429 : DECLARE(UInt64, parts_to_delay_insert, 0, R"(
2437 : 113429 : If the destination table contains at least that many active parts in a single partition, artificially slow down insert into table.
2438 : 113429 : )", 0) \
2439 : 113429 : DECLARE(UInt64, parts_to_throw_insert, 0, R"(
2440 : 113429 : If more than this number active parts in a single partition of the destination table, throw 'Too many parts ...' exception.
2441 : 113429 : )", 0) \
2442 : 113429 : DECLARE(UInt64, number_of_mutations_to_delay, 0, R"(
2443 : 113429 : If the mutated table contains at least that many unfinished mutations, artificially slow down mutations of table. 0 - disabled
2444 : 113429 : )", 0) \
2445 : 113429 : DECLARE(UInt64, number_of_mutations_to_throw, 0, R"(
2446 : 113429 : If the mutated table contains at least that many unfinished mutations, throw 'Too many mutations ...' exception. 0 - disabled
2447 : 113429 : )", 0) \
2448 : 113429 : DECLARE(Int64, distributed_ddl_task_timeout, 180, R"(
2449 : 113429 : 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.
2450 : 113429 :
2451 : 113429 : Possible values:
2452 : 113429 :
2453 : 113429 : - Positive integer.
2454 : 113429 : - 0 — Async mode.
2455 : 113429 : - Negative integer — infinite timeout.
2456 : 113429 : )", 0) \
2457 : 113429 : DECLARE(Milliseconds, stream_flush_interval_ms, 7500, R"(
2458 : 113429 : Works for tables with streaming in the case of a timeout, or when a thread generates [max_insert_block_size](#max_insert_block_size) rows.
2459 : 113429 :
2460 : 113429 : The default value is 7500.
2461 : 113429 :
2462 : 113429 : The smaller the value, the more often data is flushed into the table. Setting the value too low leads to poor performance.
2463 : 113429 : )", 0) \
2464 : 113429 : DECLARE(Milliseconds, stream_poll_timeout_ms, 500, R"(
2465 : 113429 : Timeout for polling data from/to streaming storages.
2466 : 113429 : )", 0) \
2467 : 113429 : DECLARE(UInt64, min_free_disk_bytes_to_perform_insert, 0, R"(
2468 : 113429 : Minimum free disk space bytes to perform an insert.
2469 : 113429 : )", 0) \
2470 : 113429 : DECLARE(Float, min_free_disk_ratio_to_perform_insert, 0.0, R"(
2471 : 113429 : Minimum free disk space ratio to perform an insert.
2472 : 113429 : )", 0) \
2473 : 113429 : \
2474 : 113429 : DECLARE(Bool, final, false, R"(
2475 : 113429 : Automatically applies [FINAL](../../sql-reference/statements/select/from.md/#final-modifier) modifier to all tables in a query, to tables where [FINAL](../../sql-reference/statements/select/from.md/#final-modifier) is applicable, including joined tables and tables in sub-queries, and
2476 : 113429 : distributed tables.
2477 : 113429 :
2478 : 113429 : Possible values:
2479 : 113429 :
2480 : 113429 : - 0 - disabled
2481 : 113429 : - 1 - enabled
2482 : 113429 :
2483 : 113429 : Example:
2484 : 113429 :
2485 : 113429 : ```sql
2486 : 113429 : CREATE TABLE test
2487 : 113429 : (
2488 : 113429 : key Int64,
2489 : 113429 : some String
2490 : 113429 : )
2491 : 113429 : ENGINE = ReplacingMergeTree
2492 : 113429 : ORDER BY key;
2493 : 113429 :
2494 : 113429 : INSERT INTO test FORMAT Values (1, 'first');
2495 : 113429 : INSERT INTO test FORMAT Values (1, 'second');
2496 : 113429 :
2497 : 113429 : SELECT * FROM test;
2498 : 113429 : ┌─key─┬─some───┐
2499 : 113429 : │ 1 │ second │
2500 : 113429 : └─────┴────────┘
2501 : 113429 : ┌─key─┬─some──┐
2502 : 113429 : │ 1 │ first │
2503 : 113429 : └─────┴───────┘
2504 : 113429 :
2505 : 113429 : SELECT * FROM test SETTINGS final = 1;
2506 : 113429 : ┌─key─┬─some───┐
2507 : 113429 : │ 1 │ second │
2508 : 113429 : └─────┴────────┘
2509 : 113429 :
2510 : 113429 : SET final = 1;
2511 : 113429 : SELECT * FROM test;
2512 : 113429 : ┌─key─┬─some───┐
2513 : 113429 : │ 1 │ second │
2514 : 113429 : └─────┴────────┘
2515 : 113429 : ```
2516 : 113429 : )", 0) \
2517 : 113429 : \
2518 : 113429 : DECLARE(Bool, partial_result_on_first_cancel, false, R"(
2519 : 113429 : Allows query to return a partial result after cancel.
2520 : 113429 : )", 0) \
2521 : 113429 : \
2522 : 113429 : DECLARE(Bool, ignore_on_cluster_for_replicated_udf_queries, false, R"(
2523 : 113429 : Ignore ON CLUSTER clause for replicated UDF management queries.
2524 : 113429 : )", 0) \
2525 : 113429 : DECLARE(Bool, ignore_on_cluster_for_replicated_access_entities_queries, false, R"(
2526 : 113429 : Ignore ON CLUSTER clause for replicated access entities management queries.
2527 : 113429 : )", 0) \
2528 : 113429 : DECLARE(Bool, ignore_on_cluster_for_replicated_named_collections_queries, false, R"(
2529 : 113429 : Ignore ON CLUSTER clause for replicated named collections management queries.
2530 : 113429 : )", 0) \
2531 : 113429 : /** Settings for testing hedged requests */ \
2532 : 113429 : DECLARE(Milliseconds, sleep_in_send_tables_status_ms, 0, R"(
2533 : 113429 : Time to sleep in sending tables status response in TCPHandler
2534 : 113429 : )", 0) \
2535 : 113429 : DECLARE(Milliseconds, sleep_in_send_data_ms, 0, R"(
2536 : 113429 : Time to sleep in sending data in TCPHandler
2537 : 113429 : )", 0) \
2538 : 113429 : DECLARE(Milliseconds, sleep_after_receiving_query_ms, 0, R"(
2539 : 113429 : Time to sleep after receiving query in TCPHandler
2540 : 113429 : )", 0) \
2541 : 113429 : DECLARE(UInt64, unknown_packet_in_send_data, 0, R"(
2542 : 113429 : Send unknown packet instead of data Nth data packet
2543 : 113429 : )", 0) \
2544 : 113429 : \
2545 : 113429 : DECLARE(Bool, insert_allow_materialized_columns, false, R"(
2546 : 113429 : If setting is enabled, Allow materialized columns in INSERT.
2547 : 113429 : )", 0) \
2548 : 113429 : DECLARE(Seconds, http_connection_timeout, DEFAULT_HTTP_READ_BUFFER_CONNECTION_TIMEOUT, R"(
2549 : 113429 : HTTP connection timeout (in seconds).
2550 : 113429 :
2551 : 113429 : Possible values:
2552 : 113429 :
2553 : 113429 : - Any positive integer.
2554 : 113429 : - 0 - Disabled (infinite timeout).
2555 : 113429 : )", 0) \
2556 : 113429 : DECLARE(Seconds, http_send_timeout, DEFAULT_HTTP_READ_BUFFER_TIMEOUT, R"(
2557 : 113429 : HTTP send timeout (in seconds).
2558 : 113429 :
2559 : 113429 : Possible values:
2560 : 113429 :
2561 : 113429 : - Any positive integer.
2562 : 113429 : - 0 - Disabled (infinite timeout).
2563 : 113429 :
2564 : 113429 : :::note
2565 : 113429 : It's applicable only to the default profile. A server reboot is required for the changes to take effect.
2566 : 113429 : :::
2567 : 113429 : )", 0) \
2568 : 113429 : DECLARE(Seconds, http_receive_timeout, DEFAULT_HTTP_READ_BUFFER_TIMEOUT, R"(
2569 : 113429 : HTTP receive timeout (in seconds).
2570 : 113429 :
2571 : 113429 : Possible values:
2572 : 113429 :
2573 : 113429 : - Any positive integer.
2574 : 113429 : - 0 - Disabled (infinite timeout).
2575 : 113429 : )", 0) \
2576 : 113429 : DECLARE(UInt64, http_max_uri_size, 1048576, R"(
2577 : 113429 : Sets the maximum URI length of an HTTP request.
2578 : 113429 :
2579 : 113429 : Possible values:
2580 : 113429 :
2581 : 113429 : - Positive integer.
2582 : 113429 : )", 0) \
2583 : 113429 : DECLARE(UInt64, http_max_fields, 1000, R"(
2584 : 113429 : Maximum number of fields in HTTP header
2585 : 113429 : )", 0) \
2586 : 113429 : DECLARE(UInt64, http_max_field_name_size, 4 * 1024, R"(
2587 : 113429 : Maximum length of field name in HTTP header
2588 : 113429 : )", 0) \
2589 : 113429 : DECLARE(UInt64, http_max_field_value_size, 128 * 1024, R"(
2590 : 113429 : Maximum length of field value in HTTP header
2591 : 113429 : )", 0) \
2592 : 113429 : DECLARE(UInt64, http_max_request_header_size, 10 * 1024 * 1024, R"(
2593 : 113429 : Maximum total size of all HTTP request headers (names and values combined) in bytes.
2594 : 113429 : )", 0) \
2595 : 113429 : DECLARE(Seconds, http_headers_read_timeout, 30, R"(
2596 : 113429 : Maximum time in seconds to read all HTTP request headers. This is a total deadline for the entire header parsing phase, not a per-read timeout. Protects against slowloris-style attacks where a client trickles header data slowly to hold connections open.
2597 : 113429 : )", 0) \
2598 : 113429 : DECLARE(Bool, http_skip_not_found_url_for_globs, true, R"(
2599 : 113429 : Skip URLs for globs with HTTP_NOT_FOUND error
2600 : 113429 : )", 0) \
2601 : 113429 : DECLARE(Bool, http_make_head_request, true, R"(
2602 : 113429 : The `http_make_head_request` setting allows the execution of a `HEAD` request while reading data from HTTP to retrieve information about the file to be read, such as its size. Since it's enabled by default, it may be desirable to disable this setting in cases where the server does not support `HEAD` requests.
2603 : 113429 : )", 0) \
2604 : 113429 : DECLARE(Bool, optimize_throw_if_noop, false, R"(
2605 : 113429 : Enables or disables throwing an exception if an [OPTIMIZE](../../sql-reference/statements/optimize.md) query didn't perform a merge.
2606 : 113429 :
2607 : 113429 : 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.
2608 : 113429 :
2609 : 113429 : Possible values:
2610 : 113429 :
2611 : 113429 : - 1 — Throwing an exception is enabled.
2612 : 113429 : - 0 — Throwing an exception is disabled.
2613 : 113429 : )", 0) \
2614 : 113429 : DECLARE(Bool, optimize_dry_run_check_part, true, R"(
2615 : 113429 : When enabled, `OPTIMIZE ... DRY RUN` validates the resulting merged part using `checkDataPart`. If the check fails, an exception is thrown.
2616 : 113429 : )", 0) \
2617 : 113429 : DECLARE(Bool, use_index_for_in_with_subqueries, true, R"(
2618 : 113429 : Try using an index if there is a subquery or a table expression on the right side of the IN operator.
2619 : 113429 : )", 0) \
2620 : 113429 : DECLARE(UInt64, use_index_for_in_with_subqueries_max_values, 0, R"(
2621 : 113429 : The maximum size of the set in the right-hand side of the IN operator to use table index for filtering. It allows to avoid performance degradation and higher memory usage due to the preparation of additional data structures for large queries. Zero means no limit.
2622 : 113429 : )", 0) \
2623 : 113429 : DECLARE(Bool, analyze_index_with_space_filling_curves, true, R"(
2624 : 113429 : 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.
2625 : 113429 : )", 0) \
2626 : 113429 : DECLARE(Bool, allow_key_condition_coalesce_rewrite, true, R"(
2627 : 113429 : Rewrite predicates of the form `coalesce(a_1, ..., a_N) <op> const` (and equivalently `ifNull`, or with the constant on the left) into the disjunction `(a_1 <op> const) OR (a_1 IS NULL AND a_2 <op> const) OR ... OR (a_1 IS NULL AND ... AND a_{N-1} IS NULL AND a_N <op> const)` before index analysis, so per-column primary key and skip indexes on each `a_i` can be used. Partial-constant forms such as `coalesce(a, 42, b)` and `coalesce(a, b, 42)` are handled: the argument list is normalized like `coalesce` itself (`NULL` literals dropped, arguments after the first non-`Nullable` one dropped), and a trailing non-`NULL` constant, if any, is emitted as the final branch. The rewrite is strictly additive for index pruning; runtime filtering still uses the original predicate.
2628 : 113429 : )", 0) \
2629 : 113429 : DECLARE(Bool, joined_subquery_requires_alias, true, R"(
2630 : 113429 : Force joined subqueries and table functions to have aliases for correct name qualification.
2631 : 113429 : )", 0) \
2632 : 113429 : DECLARE(Bool, empty_result_for_aggregation_by_empty_set, false, R"(
2633 : 113429 : Return empty result when aggregating without keys on empty set.
2634 : 113429 : )", 0) \
2635 : 113429 : DECLARE(Bool, empty_result_for_aggregation_by_constant_keys_on_empty_set, true, R"(
2636 : 113429 : Return empty result when aggregating by constant keys on empty set.
2637 : 113429 : )", 0) \
2638 : 113429 : DECLARE(Bool, allow_distributed_ddl, true, R"(
2639 : 113429 : If it is set to true, then a user is allowed to executed distributed DDL queries.
2640 : 113429 : )", 0) \
2641 : 113429 : DECLARE(Bool, allow_suspicious_codecs, false, R"(
2642 : 113429 : If it is set to true, allow to specify meaningless compression codecs.
2643 : 113429 : )", 0) \
2644 : 113429 : DECLARE(UInt64, query_profiler_real_time_period_ns, QUERY_PROFILER_DEFAULT_SAMPLE_RATE_NS, R"(
2645 : 113429 : Sets the period for a real clock timer of the [query profiler](../../operations/optimizing-performance/sampling-query-profiler.md). Real clock timer counts wall-clock time.
2646 : 113429 :
2647 : 113429 : Possible values:
2648 : 113429 :
2649 : 113429 : - Positive integer number, in nanoseconds.
2650 : 113429 :
2651 : 113429 : Recommended values:
2652 : 113429 :
2653 : 113429 : - 10000000 (100 times a second) nanoseconds and less for single queries.
2654 : 113429 : - 1000000000 (once a second) for cluster-wide profiling.
2655 : 113429 :
2656 : 113429 : - 0 for turning off the timer.
2657 : 113429 :
2658 : 113429 : See also:
2659 : 113429 :
2660 : 113429 : - System table [trace_log](/operations/system-tables/trace_log)
2661 : 113429 :
2662 : 113429 : Cloud default value: `3000000000`.
2663 : 113429 : )", 0) \
2664 : 113429 : DECLARE(UInt64, query_profiler_cpu_time_period_ns, QUERY_PROFILER_DEFAULT_SAMPLE_RATE_NS, R"(
2665 : 113429 : Sets the period for a CPU clock timer of the [query profiler](../../operations/optimizing-performance/sampling-query-profiler.md). This timer counts only CPU time.
2666 : 113429 :
2667 : 113429 : Possible values:
2668 : 113429 :
2669 : 113429 : - A positive integer number of nanoseconds.
2670 : 113429 :
2671 : 113429 : Recommended values:
2672 : 113429 :
2673 : 113429 : - 10000000 (100 times a second) nanoseconds and more for single queries.
2674 : 113429 : - 1000000000 (once a second) for cluster-wide profiling.
2675 : 113429 :
2676 : 113429 : - 0 for turning off the timer.
2677 : 113429 :
2678 : 113429 : See also:
2679 : 113429 :
2680 : 113429 : - System table [trace_log](/operations/system-tables/trace_log)
2681 : 113429 : )", 0) \
2682 : 113429 : DECLARE(Bool, metrics_perf_events_enabled, false, R"(
2683 : 113429 : If enabled, some of the perf events will be measured throughout queries' execution.
2684 : 113429 : )", 0) \
2685 : 113429 : DECLARE(String, metrics_perf_events_list, "", R"(
2686 : 113429 : 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.
2687 : 113429 : )", 0) \
2688 : 113429 : DECLARE(Float, opentelemetry_start_trace_probability, 0., R"(
2689 : 113429 : Sets the probability that the ClickHouse can start a trace for executed queries (if no parent [trace context](https://www.w3.org/TR/trace-context/) is supplied).
2690 : 113429 :
2691 : 113429 : Possible values:
2692 : 113429 :
2693 : 113429 : - 0 — The trace for all executed queries is disabled (if no parent trace context is supplied).
2694 : 113429 : - 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.
2695 : 113429 : - 1 — The trace for all executed queries is enabled.
2696 : 113429 : )", 0) \
2697 : 113429 : DECLARE(FloatAuto, opentelemetry_start_keeper_trace_probability, Field("auto"), R"(
2698 : 113429 : Probability to start a trace for ZooKeeper request - whether there is a parent trace or not.
2699 : 113429 :
2700 : 113429 : Possible values:
2701 : 113429 : - 'auto' - Equals the opentelemetry_start_trace_probability setting
2702 : 113429 : - 0 — Tracing is disabled
2703 : 113429 : - 0 to 1 — Probability (e.g., 1.0 = always enable)
2704 : 113429 :
2705 : 113429 : )", 0) \
2706 : 113429 : DECLARE(Bool, opentelemetry_trace_processors, false, R"(
2707 : 113429 : Collect OpenTelemetry spans for processors.
2708 : 113429 : )", 0) \
2709 : 113429 : DECLARE(Bool, opentelemetry_trace_cpu_scheduling, false, R"(
2710 : 113429 : Collect OpenTelemetry spans for workload preemptive CPU scheduling.
2711 : 113429 : )", 0) \
2712 : 113429 : DECLARE(Bool, prefer_column_name_to_alias, false, R"(
2713 : 113429 : 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](/sql-reference/syntax#notes-on-usage). Enable this setting to make aliases syntax rules in ClickHouse more compatible with most other database engines.
2714 : 113429 :
2715 : 113429 : Possible values:
2716 : 113429 :
2717 : 113429 : - 0 — The column name is substituted with the alias.
2718 : 113429 : - 1 — The column name is not substituted with the alias.
2719 : 113429 :
2720 : 113429 : **Example**
2721 : 113429 :
2722 : 113429 : The difference between enabled and disabled:
2723 : 113429 :
2724 : 113429 : Query:
2725 : 113429 :
2726 : 113429 : ```sql
2727 : 113429 : SET prefer_column_name_to_alias = 0;
2728 : 113429 : SELECT avg(number) AS number, max(number) FROM numbers(10);
2729 : 113429 : ```
2730 : 113429 :
2731 : 113429 : Result:
2732 : 113429 :
2733 : 113429 : ```text
2734 : 113429 : Received exception from server (version 21.5.1):
2735 : 113429 : 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.
2736 : 113429 : ```
2737 : 113429 :
2738 : 113429 : Query:
2739 : 113429 :
2740 : 113429 : ```sql
2741 : 113429 : SET prefer_column_name_to_alias = 1;
2742 : 113429 : SELECT avg(number) AS number, max(number) FROM numbers(10);
2743 : 113429 : ```
2744 : 113429 :
2745 : 113429 : Result:
2746 : 113429 :
2747 : 113429 : ```text
2748 : 113429 : ┌─number─┬─max(number)─┐
2749 : 113429 : │ 4.5 │ 9 │
2750 : 113429 : └────────┴─────────────┘
2751 : 113429 : ```
2752 : 113429 : )", 0) \
2753 : 113429 : \
2754 : 113429 : DECLARE(Bool, skip_redundant_aliases_in_udf, false, R"(
2755 : 113429 : Redundant aliases are not used (substituted) in user-defined functions in order to simplify it's usage.
2756 : 113429 :
2757 : 113429 : Possible values:
2758 : 113429 :
2759 : 113429 : - 1 — The aliases are skipped (substituted) in UDFs.
2760 : 113429 : - 0 — The aliases are not skipped (substituted) in UDFs.
2761 : 113429 :
2762 : 113429 : **Example**
2763 : 113429 :
2764 : 113429 : The difference between enabled and disabled:
2765 : 113429 :
2766 : 113429 : Query:
2767 : 113429 :
2768 : 113429 : ```sql
2769 : 113429 : SET skip_redundant_aliases_in_udf = 0;
2770 : 113429 : CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2));
2771 : 113429 :
2772 : 113429 : EXPLAIN SYNTAX SELECT test_03274(4 + 2);
2773 : 113429 : ```
2774 : 113429 :
2775 : 113429 : Result:
2776 : 113429 :
2777 : 113429 : ```text
2778 : 113429 : SELECT ((4 + 2) + 1 AS y, y + 2)
2779 : 113429 : ```
2780 : 113429 :
2781 : 113429 : Query:
2782 : 113429 :
2783 : 113429 : ```sql
2784 : 113429 : SET skip_redundant_aliases_in_udf = 1;
2785 : 113429 : CREATE FUNCTION IF NOT EXISTS test_03274 AS ( x ) -> ((x + 1 as y, y + 2));
2786 : 113429 :
2787 : 113429 : EXPLAIN SYNTAX SELECT test_03274(4 + 2);
2788 : 113429 : ```
2789 : 113429 :
2790 : 113429 : Result:
2791 : 113429 :
2792 : 113429 : ```text
2793 : 113429 : SELECT ((4 + 2) + 1, ((4 + 2) + 1) + 2)
2794 : 113429 : ```
2795 : 113429 : )", 0) \
2796 : 113429 : DECLARE(Bool, prefer_global_in_and_join, false, R"(
2797 : 113429 : Enables the replacement of `IN`/`JOIN` operators with `GLOBAL IN`/`GLOBAL JOIN`.
2798 : 113429 :
2799 : 113429 : Possible values:
2800 : 113429 :
2801 : 113429 : - 0 — Disabled. `IN`/`JOIN` operators are not replaced with `GLOBAL IN`/`GLOBAL JOIN`.
2802 : 113429 : - 1 — Enabled. `IN`/`JOIN` operators are replaced with `GLOBAL IN`/`GLOBAL JOIN`.
2803 : 113429 :
2804 : 113429 : **Usage**
2805 : 113429 :
2806 : 113429 : 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.
2807 : 113429 :
2808 : 113429 : 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`.
2809 : 113429 :
2810 : 113429 : 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.
2811 : 113429 :
2812 : 113429 : **See also:**
2813 : 113429 :
2814 : 113429 : - [Distributed subqueries](/sql-reference/operators/in#distributed-subqueries) for more information on how to use `GLOBAL IN`/`GLOBAL JOIN`
2815 : 113429 : )", 0) \
2816 : 113429 : DECLARE(Bool, enable_vertical_final, true, R"(
2817 : 113429 : If enable, remove duplicated rows during FINAL by marking rows as deleted and filtering them later instead of merging rows
2818 : 113429 : )", 0) \
2819 : 113429 : \
2820 : 113429 : \
2821 : 113429 : /** Limits during query execution are part of the settings. \
2822 : 113429 : * Used to provide a more safe execution of queries from the user interface. \
2823 : 113429 : * Basically, limits are checked for each block (not every row). That is, the limits can be slightly violated. \
2824 : 113429 : * Almost all limits apply only to SELECTs. \
2825 : 113429 : * Almost all limits apply to each stream individually. \
2826 : 113429 : */ \
2827 : 113429 : \
2828 : 113429 : DECLARE(UInt64, max_rows_to_read, 0, R"(
2829 : 113429 : The maximum number of rows that can be read from a table when running a query.
2830 : 113429 : The restriction is checked for each processed chunk of data, applied only to the
2831 : 113429 : deepest table expression and when reading from a remote server, checked only on
2832 : 113429 : the remote server.
2833 : 113429 : )", 0) \
2834 : 113429 : DECLARE(UInt64, max_bytes_to_read, 0, R"(
2835 : 113429 : The maximum number of bytes (of uncompressed data) that can be read from a table when running a query.
2836 : 113429 : The restriction is checked for each processed chunk of data, applied only to the
2837 : 113429 : deepest table expression and when reading from a remote server, checked only on
2838 : 113429 : the remote server.
2839 : 113429 : )", 0) \
2840 : 113429 : DECLARE(OverflowMode, read_overflow_mode, OverflowMode::THROW, R"(
2841 : 113429 : What to do when the limit is exceeded.
2842 : 113429 : )", 0) \
2843 : 113429 : \
2844 : 113429 : DECLARE(UInt64, max_rows_to_read_leaf, 0, R"(
2845 : 113429 : The maximum number of rows that can be read from a local table on a leaf node when
2846 : 113429 : running a distributed query. While distributed queries can issue multiple sub-queries
2847 : 113429 : to each shard (leaf) - this limit will be checked only on the read stage on the
2848 : 113429 : leaf nodes and ignored on the merging of results stage on the root node.
2849 : 113429 :
2850 : 113429 : For example, a cluster consists of 2 shards and each shard contains a table with
2851 : 113429 : 100 rows. The distributed query which is supposed to read all the data from both
2852 : 113429 : tables with setting `max_rows_to_read=150` will fail, as in total there will be
2853 : 113429 : 200 rows. A query with `max_rows_to_read_leaf=150` will succeed, since leaf nodes
2854 : 113429 : will read at max 100 rows.
2855 : 113429 :
2856 : 113429 : The restriction is checked for each processed chunk of data.
2857 : 113429 :
2858 : 113429 : :::note
2859 : 113429 : This setting is unstable with `prefer_localhost_replica=1`.
2860 : 113429 : :::
2861 : 113429 : )", 0) \
2862 : 113429 : DECLARE(UInt64, max_bytes_to_read_leaf, 0, R"(
2863 : 113429 : The maximum number of bytes (of uncompressed data) that can be read from a local
2864 : 113429 : table on a leaf node when running a distributed query. While distributed queries
2865 : 113429 : can issue a multiple sub-queries to each shard (leaf) - this limit will
2866 : 113429 : be checked only on the read stage on the leaf nodes and will be ignored on the
2867 : 113429 : merging of results stage on the root node.
2868 : 113429 :
2869 : 113429 : For example, a cluster consists of 2 shards and each shard contains a table with
2870 : 113429 : 100 bytes of data. A distributed query which is supposed to read all the data
2871 : 113429 : from both tables with setting `max_bytes_to_read=150` will fail as in total it
2872 : 113429 : will be 200 bytes. A query with `max_bytes_to_read_leaf=150` will succeed since
2873 : 113429 : leaf nodes will read 100 bytes at max.
2874 : 113429 :
2875 : 113429 : The restriction is checked for each processed chunk of data.
2876 : 113429 :
2877 : 113429 : :::note
2878 : 113429 : This setting is unstable with `prefer_localhost_replica=1`.
2879 : 113429 : :::
2880 : 113429 : )", 0) \
2881 : 113429 : DECLARE(OverflowMode, read_overflow_mode_leaf, OverflowMode::THROW, R"(
2882 : 113429 : Sets what happens when the volume of data read exceeds one of the leaf limits.
2883 : 113429 :
2884 : 113429 : Possible options:
2885 : 113429 : - `throw`: throw an exception (default).
2886 : 113429 : - `break`: stop executing the query and return the partial result.
2887 : 113429 : )", 0) \
2888 : 113429 : \
2889 : 113429 : DECLARE(UInt64, max_rows_to_group_by, 0, R"(
2890 : 113429 : The maximum number of unique keys received from aggregation. This setting lets
2891 : 113429 : you limit memory consumption when aggregating.
2892 : 113429 :
2893 : 113429 : If aggregation during GROUP BY is generating more than the specified number of
2894 : 113429 : rows (unique GROUP BY keys), the behavior will be determined by the
2895 : 113429 : 'group_by_overflow_mode' which by default is `throw`, but can be also switched
2896 : 113429 : to an approximate GROUP BY mode.
2897 : 113429 : )", 0) \
2898 : 113429 : DECLARE(OverflowModeGroupBy, group_by_overflow_mode, OverflowMode::THROW, R"(
2899 : 113429 : Sets what happens when the number of unique keys for aggregation exceeds the limit:
2900 : 113429 : - `throw`: throw an exception
2901 : 113429 : - `break`: stop executing the query and return the partial result
2902 : 113429 : - `any`: continue aggregation for the keys that got into the set, but do not add new keys to the set.
2903 : 113429 :
2904 : 113429 : Using the 'any' value lets you run an approximation of GROUP BY. The quality of
2905 : 113429 : this approximation depends on the statistical nature of the data.
2906 : 113429 : )", 0) \
2907 : 113429 : DECLARE(UInt64, max_bytes_before_external_group_by, 0, R"(
2908 : 113429 : Cloud default value: half the memory amount per replica.
2909 : 113429 :
2910 : 113429 : Enables or disables execution of `GROUP BY` clauses in external memory.
2911 : 113429 : (See [GROUP BY in external memory](/sql-reference/statements/select/group-by#group-by-in-external-memory))
2912 : 113429 :
2913 : 113429 : Possible values:
2914 : 113429 :
2915 : 113429 : - Maximum volume of RAM (in bytes) that can be used by the single [GROUP BY](/sql-reference/statements/select/group-by) operation.
2916 : 113429 : - `0` — `GROUP BY` in external memory disabled.
2917 : 113429 :
2918 : 113429 : :::note
2919 : 113429 : If memory usage during GROUP BY operations is exceeding this threshold in bytes,
2920 : 113429 : activate the 'external aggregation' mode (spill data to disk).
2921 : 113429 :
2922 : 113429 : The recommended value is half of the available system memory.
2923 : 113429 : :::
2924 : 113429 : )", 0) \
2925 : 113429 : DECLARE(Double, max_bytes_ratio_before_external_group_by, 0.5, R"(
2926 : 113429 : The ratio of available memory that is allowed for `GROUP BY`. Once reached,
2927 : 113429 : external memory is used for aggregation.
2928 : 113429 :
2929 : 113429 : For example, if set to `0.6`, `GROUP BY` will allow using 60% of the available memory
2930 : 113429 : (to server/user/merges) at the beginning of the execution, after that, it will
2931 : 113429 : start using external aggregation.
2932 : 113429 : )", 0) \
2933 : 113429 : \
2934 : 113429 : DECLARE(UInt64, max_rows_to_sort, 0, R"(
2935 : 113429 : The maximum number of rows before sorting. This allows you to limit memory consumption when sorting.
2936 : 113429 : If more than the specified amount of records have to be processed for the ORDER BY operation,
2937 : 113429 : the behavior will be determined by the `sort_overflow_mode` which by default is set to `throw`.
2938 : 113429 : )", 0) \
2939 : 113429 : DECLARE(UInt64, max_bytes_to_sort, 0, R"(
2940 : 113429 : The maximum number of bytes before sorting. If more than the specified amount of
2941 : 113429 : uncompressed bytes have to be processed for ORDER BY operation, the behavior will
2942 : 113429 : be determined by the `sort_overflow_mode` which by default is set to `throw`.
2943 : 113429 : )", 0) \
2944 : 113429 : DECLARE(OverflowMode, sort_overflow_mode, OverflowMode::THROW, R"(
2945 : 113429 : Sets what happens if the number of rows received before sorting exceeds one of the limits.
2946 : 113429 :
2947 : 113429 : Possible values:
2948 : 113429 : - `throw`: throw an exception.
2949 : 113429 : - `break`: stop executing the query and return the partial result.
2950 : 113429 : )", 0) \
2951 : 113429 : DECLARE(UInt64, prefer_external_sort_block_bytes, DEFAULT_BLOCK_SIZE * 256, R"(
2952 : 113429 : Prefer maximum block bytes for external sort, reduce the memory usage during merging.
2953 : 113429 : )", 0) \
2954 : 113429 : DECLARE(UInt64, max_bytes_before_external_sort, 0, R"(
2955 : 113429 : Cloud default value: half the memory amount per replica.
2956 : 113429 :
2957 : 113429 : Enables or disables execution of `ORDER BY` clauses in external memory. See [ORDER BY Implementation Details](../../sql-reference/statements/select/order-by.md#implementation-details)
2958 : 113429 : If memory usage during ORDER BY operation exceeds this threshold in bytes, the 'external sorting' mode (spill data to disk) is activated.
2959 : 113429 :
2960 : 113429 : Possible values:
2961 : 113429 :
2962 : 113429 : - Maximum volume of RAM (in bytes) that can be used by the single [ORDER BY](../../sql-reference/statements/select/order-by.md) operation.
2963 : 113429 : The recommended value is half of available system memory
2964 : 113429 : - `0` — `ORDER BY` in external memory disabled.
2965 : 113429 : )", 0) \
2966 : 113429 : DECLARE(Double, max_bytes_ratio_before_external_sort, 0.5, R"(
2967 : 113429 : The ratio of available memory that is allowed for `ORDER BY`. Once reached, external sort is used.
2968 : 113429 :
2969 : 113429 : For example, if set to `0.6`, `ORDER BY` will allow using `60%` of available memory (to server/user/merges) at the beginning of the execution, after that, it will start using external sort.
2970 : 113429 :
2971 : 113429 : Note, that `max_bytes_before_external_sort` is still respected, spilling to disk will be done only if the sorting block is bigger then `max_bytes_before_external_sort`.
2972 : 113429 : )", 0) \
2973 : 113429 : DECLARE(UInt64, max_bytes_before_remerge_sort, 1000000000, R"(
2974 : 113429 : In case of ORDER BY with LIMIT, when memory usage is higher than specified threshold, perform additional steps of merging blocks before final merge to keep just top LIMIT rows.
2975 : 113429 : )", 0) \
2976 : 113429 : DECLARE(Float, remerge_sort_lowered_memory_bytes_ratio, 2., R"(
2977 : 113429 : If memory usage after remerge does not reduced by this ratio, remerge will be disabled.
2978 : 113429 : )", 0) \
2979 : 113429 : \
2980 : 113429 : DECLARE(UInt64, max_result_rows, 0, R"(
2981 : 113429 : Cloud default value: `0`.
2982 : 113429 :
2983 : 113429 : Limits the number of rows in the result. Also checked for subqueries, and on remote servers when running parts of a distributed query.
2984 : 113429 : No limit is applied when the value is `0`.
2985 : 113429 :
2986 : 113429 : The query will stop after processing a block of data if the threshold is met, but
2987 : 113429 : it will not cut the last block of the result, therefore the result size can be
2988 : 113429 : larger than the threshold.
2989 : 113429 : )", 0) \
2990 : 113429 : DECLARE(UInt64, max_result_bytes, 0, R"(
2991 : 113429 : Limits the result size in bytes (uncompressed). The query will stop after processing a block of data if the threshold is met,
2992 : 113429 : but it will not cut the last block of the result, therefore the result size can be larger than the threshold.
2993 : 113429 :
2994 : 113429 : **Caveats**
2995 : 113429 :
2996 : 113429 : The result size in memory is taken into account for this threshold.
2997 : 113429 : Even if the result size is small, it can reference larger data structures in memory,
2998 : 113429 : representing dictionaries of LowCardinality columns, and Arenas of AggregateFunction columns,
2999 : 113429 : so the threshold can be exceeded despite the small result size.
3000 : 113429 :
3001 : 113429 : :::warning
3002 : 113429 : The setting is fairly low level and should be used with caution
3003 : 113429 : :::
3004 : 113429 : )", 0) \
3005 : 113429 : DECLARE(OverflowMode, result_overflow_mode, OverflowMode::THROW, R"(
3006 : 113429 : Cloud default value: `throw`
3007 : 113429 :
3008 : 113429 : Sets what to do if the volume of the result exceeds one of the limits.
3009 : 113429 :
3010 : 113429 : Possible values:
3011 : 113429 : - `throw`: throw an exception (default).
3012 : 113429 : - `break`: stop executing the query and return the partial result, as if the
3013 : 113429 : source data ran out.
3014 : 113429 :
3015 : 113429 : Using 'break' is similar to using LIMIT. `Break` interrupts execution only at the
3016 : 113429 : block level. This means that amount of returned rows is greater than
3017 : 113429 : [`max_result_rows`](/operations/settings/settings#max_result_rows), multiple of [`max_block_size`](/operations/settings/settings#max_block_size)
3018 : 113429 : and depends on [`max_threads`](/operations/settings/settings#max_threads).
3019 : 113429 :
3020 : 113429 : **Example**
3021 : 113429 :
3022 : 113429 : ```sql title="Query"
3023 : 113429 : SET max_threads = 3, max_block_size = 3333;
3024 : 113429 : SET max_result_rows = 3334, result_overflow_mode = 'break';
3025 : 113429 :
3026 : 113429 : SELECT *
3027 : 113429 : FROM numbers_mt(100000)
3028 : 113429 : FORMAT Null;
3029 : 113429 : ```
3030 : 113429 :
3031 : 113429 : ```text title="Result"
3032 : 113429 : 6666 rows in set. ...
3033 : 113429 : ```
3034 : 113429 : )", 0) \
3035 : 113429 : \
3036 : 113429 : /* TODO: Check also when merging and finalizing aggregate functions. */ \
3037 : 113429 : DECLARE(Seconds, max_execution_time, 0, R"(
3038 : 113429 : The maximum query execution time in seconds.
3039 : 113429 :
3040 : 113429 : The `max_execution_time` parameter can be a bit tricky to understand.
3041 : 113429 : It operates based on interpolation relative to the current query execution speed
3042 : 113429 : (this behaviour is controlled by [`timeout_before_checking_execution_speed`](/operations/settings/settings#timeout_before_checking_execution_speed)).
3043 : 113429 :
3044 : 113429 : ClickHouse will interrupt a query if the projected execution time exceeds the
3045 : 113429 : specified `max_execution_time`. By default, the `timeout_before_checking_execution_speed`
3046 : 113429 : is set to 10 seconds. This means that after 10 seconds of query execution, ClickHouse
3047 : 113429 : will begin estimating the total execution time. If, for example, `max_execution_time`
3048 : 113429 : is set to 3600 seconds (1 hour), ClickHouse will terminate the query if the estimated
3049 : 113429 : time exceeds this 3600-second limit. If you set `timeout_before_checking_execution_speed`
3050 : 113429 : to 0, ClickHouse will use the clock time as the basis for `max_execution_time`.
3051 : 113429 :
3052 : 113429 : If query runtime exceeds the specified number of seconds, the behavior will be
3053 : 113429 : determined by the 'timeout_overflow_mode', which by default is set to `throw`.
3054 : 113429 :
3055 : 113429 : :::note
3056 : 113429 : The timeout is checked and the query can stop only in designated places during data processing.
3057 : 113429 : It currently cannot stop during merging of aggregation states or during query analysis,
3058 : 113429 : and the actual run time will be higher than the value of this setting.
3059 : 113429 : :::
3060 : 113429 : )", 0) \
3061 : 113429 : DECLARE(OverflowMode, timeout_overflow_mode, OverflowMode::THROW, R"(
3062 : 113429 : Sets what to do if the query is run longer than the `max_execution_time` or the
3063 : 113429 : estimated running time is longer than `max_estimated_execution_time`.
3064 : 113429 :
3065 : 113429 : Possible values:
3066 : 113429 : - `throw`: throw an exception (default).
3067 : 113429 : - `break`: stop executing the query and return the partial result, as if the
3068 : 113429 : source data ran out.
3069 : 113429 : )", 0) \
3070 : 113429 : DECLARE(Seconds, max_execution_time_leaf, 0, R"(
3071 : 113429 : Similar semantically to [`max_execution_time`](#max_execution_time) but only
3072 : 113429 : applied on leaf nodes for distributed or remote queries.
3073 : 113429 :
3074 : 113429 : For example, if we want to limit the execution time on a leaf node to `10s` but
3075 : 113429 : have no limit on the initial node, instead of having `max_execution_time` in the
3076 : 113429 : nested subquery settings:
3077 : 113429 :
3078 : 113429 : ```sql
3079 : 113429 : SELECT count()
3080 : 113429 : FROM cluster(cluster, view(SELECT * FROM t SETTINGS max_execution_time = 10));
3081 : 113429 : ```
3082 : 113429 :
3083 : 113429 : We can use `max_execution_time_leaf` as the query settings:
3084 : 113429 :
3085 : 113429 : ```sql
3086 : 113429 : SELECT count()
3087 : 113429 : FROM cluster(cluster, view(SELECT * FROM t)) SETTINGS max_execution_time_leaf = 10;
3088 : 113429 : ```
3089 : 113429 : )", 0) \
3090 : 113429 : DECLARE(OverflowMode, timeout_overflow_mode_leaf, OverflowMode::THROW, R"(
3091 : 113429 : Sets what happens when the query in leaf node run longer than `max_execution_time_leaf`.
3092 : 113429 :
3093 : 113429 : Possible values:
3094 : 113429 : - `throw`: throw an exception (default).
3095 : 113429 : - `break`: stop executing the query and return the partial result, as if the
3096 : 113429 : source data ran out.
3097 : 113429 : )", 0) \
3098 : 113429 : \
3099 : 113429 : DECLARE(UInt64, min_execution_speed, 0, R"(
3100 : 113429 : Minimal execution speed in rows per second. Checked on every data block when
3101 : 113429 : [`timeout_before_checking_execution_speed`](/operations/settings/settings#timeout_before_checking_execution_speed)
3102 : 113429 : expires. If the execution speed is lower, an exception is thrown.
3103 : 113429 : )", 0) \
3104 : 113429 : DECLARE(UInt64, max_execution_speed, 0, R"(
3105 : 113429 : The maximum number of execution rows per second. Checked on every data block when
3106 : 113429 : [`timeout_before_checking_execution_speed`](/operations/settings/settings#timeout_before_checking_execution_speed)
3107 : 113429 : expires. If the execution speed is high, the execution speed will be reduced.
3108 : 113429 : )", 0) \
3109 : 113429 : DECLARE(UInt64, min_execution_speed_bytes, 0, R"(
3110 : 113429 : The minimum number of execution bytes per second. Checked on every data block when
3111 : 113429 : [`timeout_before_checking_execution_speed`](/operations/settings/settings#timeout_before_checking_execution_speed)
3112 : 113429 : expires. If the execution speed is lower, an exception is thrown.
3113 : 113429 : )", 0) \
3114 : 113429 : DECLARE(UInt64, max_execution_speed_bytes, 0, R"(
3115 : 113429 : The maximum number of execution bytes per second. Checked on every data block when
3116 : 113429 : [`timeout_before_checking_execution_speed`](/operations/settings/settings#timeout_before_checking_execution_speed)
3117 : 113429 : expires. If the execution speed is high, the execution speed will be reduced.
3118 : 113429 : )", 0) \
3119 : 113429 : DECLARE(Seconds, timeout_before_checking_execution_speed, 10, R"(
3120 : 113429 : Checks that execution speed is not too slow (no less than `min_execution_speed`),
3121 : 113429 : after the specified time in seconds has expired.
3122 : 113429 : )", 0) \
3123 : 113429 : DECLARE(Seconds, max_estimated_execution_time, 0, R"(
3124 : 113429 : Maximum query estimate execution time in seconds. Checked on every data block
3125 : 113429 : when [`timeout_before_checking_execution_speed`](/operations/settings/settings#timeout_before_checking_execution_speed)
3126 : 113429 : expires.
3127 : 113429 : )", 0) \
3128 : 113429 : \
3129 : 113429 : DECLARE(UInt64, max_columns_to_read, 0, R"(
3130 : 113429 : The maximum number of columns that can be read from a table in a single query.
3131 : 113429 : If a query requires reading more than the specified number of columns, an exception
3132 : 113429 : is thrown.
3133 : 113429 :
3134 : 113429 : :::tip
3135 : 113429 : This setting is useful for preventing overly complex queries.
3136 : 113429 : :::
3137 : 113429 :
3138 : 113429 : `0` value means unlimited.
3139 : 113429 : )", 0) \
3140 : 113429 : DECLARE(UInt64, max_temporary_columns, 0, R"(
3141 : 113429 : The maximum number of temporary columns that must be kept in RAM simultaneously
3142 : 113429 : when running a query, including constant columns. If a query generates more than
3143 : 113429 : the specified number of temporary columns in memory as a result of intermediate
3144 : 113429 : calculation, then an exception is thrown.
3145 : 113429 :
3146 : 113429 : :::tip
3147 : 113429 : This setting is useful for preventing overly complex queries.
3148 : 113429 : :::
3149 : 113429 :
3150 : 113429 : `0` value means unlimited.
3151 : 113429 : )", 0) \
3152 : 113429 : DECLARE(UInt64, max_temporary_non_const_columns, 0, R"(
3153 : 113429 : Like `max_temporary_columns`, the maximum number of temporary columns that must
3154 : 113429 : be kept in RAM simultaneously when running a query, but without counting constant
3155 : 113429 : columns.
3156 : 113429 :
3157 : 113429 : :::note
3158 : 113429 : Constant columns are formed fairly often when running a query, but they require
3159 : 113429 : approximately zero computing resources.
3160 : 113429 : :::
3161 : 113429 : )", 0) \
3162 : 113429 : \
3163 : 113429 : DECLARE(UInt64, max_sessions_for_user, 0, R"(
3164 : 113429 : Maximum number of simultaneous sessions per authenticated user to the ClickHouse server.
3165 : 113429 :
3166 : 113429 : Example:
3167 : 113429 :
3168 : 113429 : ```xml
3169 : 113429 : <profiles>
3170 : 113429 : <single_session_profile>
3171 : 113429 : <max_sessions_for_user>1</max_sessions_for_user>
3172 : 113429 : </single_session_profile>
3173 : 113429 : <two_sessions_profile>
3174 : 113429 : <max_sessions_for_user>2</max_sessions_for_user>
3175 : 113429 : </two_sessions_profile>
3176 : 113429 : <unlimited_sessions_profile>
3177 : 113429 : <max_sessions_for_user>0</max_sessions_for_user>
3178 : 113429 : </unlimited_sessions_profile>
3179 : 113429 : </profiles>
3180 : 113429 : <users>
3181 : 113429 : <!-- User Alice can connect to a ClickHouse server no more than once at a time. -->
3182 : 113429 : <Alice>
3183 : 113429 : <profile>single_session_user</profile>
3184 : 113429 : </Alice>
3185 : 113429 : <!-- User Bob can use 2 simultaneous sessions. -->
3186 : 113429 : <Bob>
3187 : 113429 : <profile>two_sessions_profile</profile>
3188 : 113429 : </Bob>
3189 : 113429 : <!-- User Charles can use arbitrarily many of simultaneous sessions. -->
3190 : 113429 : <Charles>
3191 : 113429 : <profile>unlimited_sessions_profile</profile>
3192 : 113429 : </Charles>
3193 : 113429 : </users>
3194 : 113429 : ```
3195 : 113429 :
3196 : 113429 : Possible values:
3197 : 113429 : - Positive integer
3198 : 113429 : - `0` - infinite count of simultaneous sessions (default)
3199 : 113429 : )", 0) \
3200 : 113429 : \
3201 : 113429 : DECLARE(UInt64, max_subquery_depth, 100, R"(
3202 : 113429 : If a query has more than the specified number of nested subqueries, throws an
3203 : 113429 : exception.
3204 : 113429 :
3205 : 113429 : :::tip
3206 : 113429 : This allows you to have a sanity check to protect against the users of your
3207 : 113429 : cluster from writing overly complex queries.
3208 : 113429 : :::
3209 : 113429 : )", 0) \
3210 : 113429 : DECLARE(UInt64, max_analyze_depth, 5000, R"(
3211 : 113429 : Maximum number of analyses performed by interpreter.
3212 : 113429 : )", 0) \
3213 : 113429 : DECLARE(UInt64, max_ast_depth, 1000, R"(
3214 : 113429 : The maximum nesting depth of a query syntactic tree. If exceeded, an exception is thrown.
3215 : 113429 :
3216 : 113429 : :::note
3217 : 113429 : At this time, it isn't checked during parsing, but only after parsing the query.
3218 : 113429 : This means that a syntactic tree that is too deep can be created during parsing,
3219 : 113429 : but the query will fail.
3220 : 113429 : :::
3221 : 113429 : )", 0) \
3222 : 113429 : DECLARE(UInt64, max_ast_elements, 50000, R"(
3223 : 113429 : The maximum number of elements in a query syntactic tree. If exceeded, an exception is thrown.
3224 : 113429 :
3225 : 113429 : :::note
3226 : 113429 : At this time, it isn't checked during parsing, but only after parsing the query.
3227 : 113429 : This means that a syntactic tree that is too deep can be created during parsing,
3228 : 113429 : but the query will fail.
3229 : 113429 : :::
3230 : 113429 : )", 0) \
3231 : 113429 : DECLARE(UInt64, max_expanded_ast_elements, 500000, R"(
3232 : 113429 : Maximum size of query syntax tree in number of nodes after expansion of aliases and the asterisk.
3233 : 113429 : )", 0) \
3234 : 113429 : \
3235 : 113429 : DECLARE(Float, ast_fuzzer_runs, 0, R"(
3236 : 113429 : Enables the server-side AST fuzzer that runs randomized queries after each normal query, discarding their results.
3237 : 113429 : - 0: disabled (default).
3238 : 113429 : - A value between 0 and 1 (exclusive): probability of running a single fuzzed query.
3239 : 113429 : - A value >= 1: the number of fuzzed queries to run per normal query.
3240 : 113429 :
3241 : 113429 : The fuzzer accumulates AST fragments from all queries across all sessions, producing increasingly interesting mutations over time. Fuzzed queries that fail are silently discarded; results are never returned to the client.
3242 : 113429 : )", EXPERIMENTAL) \
3243 : 113429 : DECLARE(Bool, ast_fuzzer_any_query, false, R"(
3244 : 113429 : When false (default), the server-side AST fuzzer (controlled by `ast_fuzzer_runs`) only fuzzes read-only queries (SELECT, EXPLAIN, SHOW, DESCRIBE, EXISTS). When true, all query types including DDL and INSERT are fuzzed.
3245 : 113429 : )", EXPERIMENTAL) \
3246 : 113429 : DECLARE(Bool, allow_fuzz_query_functions, false, R"(
3247 : 113429 : Enables the `fuzzQuery` function that applies random AST mutations to a query string.
3248 : 113429 : )", EXPERIMENTAL) \
3249 : 113429 : \
3250 : 113429 : DECLARE(UInt64, readonly, 0, R"(
3251 : 113429 : 0 - no read-only restrictions. 1 - only read requests, as well as changing explicitly allowed settings. 2 - only read requests, as well as changing settings, except for the 'readonly' setting.
3252 : 113429 : )", 0) \
3253 : 113429 : \
3254 : 113429 : DECLARE(UInt64, max_rows_in_set, 0, R"(
3255 : 113429 : The maximum number of rows for a data set in the IN clause created from a subquery.
3256 : 113429 : )", 0) \
3257 : 113429 : DECLARE(UInt64, max_bytes_in_set, 0, R"(
3258 : 113429 : The maximum number of bytes (of uncompressed data) used by a set in the IN clause
3259 : 113429 : created from a subquery.
3260 : 113429 : )", 0) \
3261 : 113429 : DECLARE(OverflowMode, set_overflow_mode, OverflowMode::THROW, R"(
3262 : 113429 : Sets what happens when the amount of data exceeds one of the limits.
3263 : 113429 :
3264 : 113429 : Possible values:
3265 : 113429 : - `throw`: throw an exception (default).
3266 : 113429 : - `break`: stop executing the query and return the partial result, as if the
3267 : 113429 : source data ran out.
3268 : 113429 : )", 0) \
3269 : 113429 : \
3270 : 113429 : DECLARE(Bool, exact_rows_before_limit, false, R"(
3271 : 113429 : When enabled, ClickHouse will provide exact value for rows_before_limit_at_least statistic, but with the cost that the data before limit will have to be read completely
3272 : 113429 : )", 0) \
3273 : 113429 : DECLARE(Bool, rows_before_aggregation, false, R"(
3274 : 113429 : When enabled, ClickHouse will provide exact value for rows_before_aggregation statistic, represents the number of rows read before aggregation
3275 : 113429 : )", 0) \
3276 : 113429 : DECLARE(UInt64, max_rows_in_join, 0, R"(
3277 : 113429 : Limits the number of rows in the hash table that is used when joining tables.
3278 : 113429 :
3279 : 113429 : This settings applies to [SELECT ... JOIN](/sql-reference/statements/select/join)
3280 : 113429 : operations and the [Join](/engines/table-engines/special/join) table engine.
3281 : 113429 :
3282 : 113429 : If a query contains multiple joins, ClickHouse checks this setting for every intermediate result.
3283 : 113429 :
3284 : 113429 : ClickHouse can proceed with different actions when the limit is reached. Use the
3285 : 113429 : [`join_overflow_mode`](/operations/settings/settings#join_overflow_mode) setting to choose the action.
3286 : 113429 :
3287 : 113429 : Possible values:
3288 : 113429 :
3289 : 113429 : - Positive integer.
3290 : 113429 : - `0` — Unlimited number of rows.
3291 : 113429 : )", 0) \
3292 : 113429 : DECLARE(UInt64, max_bytes_in_join, 0, R"(
3293 : 113429 : The maximum size in number of bytes of the hash table used when joining tables.
3294 : 113429 :
3295 : 113429 : This setting applies to [SELECT ... JOIN](/sql-reference/statements/select/join)
3296 : 113429 : operations and the [Join table engine](/engines/table-engines/special/join).
3297 : 113429 :
3298 : 113429 : If the query contains joins, ClickHouse checks this setting for every intermediate result.
3299 : 113429 :
3300 : 113429 : ClickHouse can proceed with different actions when the limit is reached. Use
3301 : 113429 : the [join_overflow_mode](/operations/settings/settings#join_overflow_mode) settings to choose the action.
3302 : 113429 :
3303 : 113429 : Possible values:
3304 : 113429 :
3305 : 113429 : - Positive integer.
3306 : 113429 : - 0 — Memory control is disabled.
3307 : 113429 : )", 0) \
3308 : 113429 : DECLARE(OverflowMode, join_overflow_mode, OverflowMode::THROW, R"(
3309 : 113429 : Defines what action ClickHouse performs when any of the following join limits is reached:
3310 : 113429 :
3311 : 113429 : - [max_bytes_in_join](/operations/settings/settings#max_bytes_in_join)
3312 : 113429 : - [max_rows_in_join](/operations/settings/settings#max_rows_in_join)
3313 : 113429 :
3314 : 113429 : Possible values:
3315 : 113429 :
3316 : 113429 : - `THROW` — ClickHouse throws an exception and breaks operation.
3317 : 113429 : - `BREAK` — ClickHouse breaks operation and does not throw an exception.
3318 : 113429 :
3319 : 113429 : Default value: `THROW`.
3320 : 113429 :
3321 : 113429 : **See Also**
3322 : 113429 :
3323 : 113429 : - [JOIN clause](/sql-reference/statements/select/join)
3324 : 113429 : - [Join table engine](/engines/table-engines/special/join)
3325 : 113429 : )", 0) \
3326 : 113429 : DECLARE(Bool, join_any_take_last_row, false, R"(
3327 : 113429 : Changes the behaviour of join operations with `ANY` strictness.
3328 : 113429 :
3329 : 113429 : :::note
3330 : 113429 : This setting applies only for `JOIN` operations with [Join](../../engines/table-engines/special/join.md) engine tables.
3331 : 113429 : :::
3332 : 113429 :
3333 : 113429 : Possible values:
3334 : 113429 :
3335 : 113429 : - 0 — If the right table has more than one matching row, only the first one found is joined.
3336 : 113429 : - 1 — If the right table has more than one matching row, only the last one found is joined.
3337 : 113429 :
3338 : 113429 : See also:
3339 : 113429 :
3340 : 113429 : - [JOIN clause](/sql-reference/statements/select/join)
3341 : 113429 : - [Join table engine](../../engines/table-engines/special/join.md)
3342 : 113429 : - [join_default_strictness](#join_default_strictness)
3343 : 113429 : )", IMPORTANT) \
3344 : 113429 : DECLARE(JoinAlgorithm, join_algorithm, "direct,parallel_hash,hash", R"(
3345 : 113429 : Specifies which [JOIN](../../sql-reference/statements/select/join.md) algorithm is used.
3346 : 113429 :
3347 : 113429 : Several algorithms can be specified, and an available one would be chosen for a particular query based on kind/strictness and table engine.
3348 : 113429 :
3349 : 113429 : Possible values:
3350 : 113429 :
3351 : 113429 : - grace_hash
3352 : 113429 :
3353 : 113429 : [Grace hash join](https://en.wikipedia.org/wiki/Hash_join#Grace_hash_join) is used. Grace hash provides an algorithm option that provides performant complex joins while limiting memory use.
3354 : 113429 :
3355 : 113429 : 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`](/operations/settings/settings#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.
3356 : 113429 :
3357 : 113429 : Supports `INNER/LEFT/RIGHT/FULL ALL/ANY JOIN`.
3358 : 113429 :
3359 : 113429 : - hash
3360 : 113429 :
3361 : 113429 : [Hash join algorithm](https://en.wikipedia.org/wiki/Hash_join) 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.
3362 : 113429 :
3363 : 113429 : When using the `hash` algorithm, the right part of `JOIN` is uploaded into RAM.
3364 : 113429 :
3365 : 113429 : - parallel_hash
3366 : 113429 :
3367 : 113429 : A variation of `hash` join that splits the data into buckets and builds several hashtables instead of one concurrently to speed up this process.
3368 : 113429 :
3369 : 113429 : When using the `parallel_hash` algorithm, the right part of `JOIN` is uploaded into RAM.
3370 : 113429 :
3371 : 113429 : - partial_merge
3372 : 113429 :
3373 : 113429 : A variation of the [sort-merge algorithm](https://en.wikipedia.org/wiki/Sort-merge_join), where only the right table is fully sorted.
3374 : 113429 :
3375 : 113429 : The `RIGHT JOIN` and `FULL JOIN` are supported only with `ALL` strictness (`SEMI`, `ANTI`, `ANY`, and `ASOF` are not supported).
3376 : 113429 :
3377 : 113429 : 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.
3378 : 113429 :
3379 : 113429 : - direct
3380 : 113429 :
3381 : 113429 : The `direct` (also known as nested loop) algorithm performs a lookup in the right table using rows from the left table as keys.
3382 : 113429 : It's supported by special storages such as [Dictionary](/engines/table-engines/special/dictionary), [EmbeddedRocksDB](../../engines/table-engines/integrations/embedded-rocksdb.md), and [MergeTree](/engines/table-engines/mergetree-family/mergetree) tables.
3383 : 113429 :
3384 : 113429 : For MergeTree tables, the algorithm pushes join key filters directly to the storage layer. This can be more efficient when the key can use the table's primary key index for lookups, otherwise it performs full scans of the right table for each left table block.
3385 : 113429 :
3386 : 113429 : Supports `INNER` and `LEFT` joins and only single-column equality join keys without other conditions.
3387 : 113429 :
3388 : 113429 : - auto
3389 : 113429 :
3390 : 113429 : 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.
3391 : 113429 :
3392 : 113429 : - full_sorting_merge
3393 : 113429 :
3394 : 113429 : [Sort-merge algorithm](https://en.wikipedia.org/wiki/Sort-merge_join) with full sorting of joined tables before joining.
3395 : 113429 :
3396 : 113429 : - prefer_partial_merge
3397 : 113429 :
3398 : 113429 : ClickHouse always tries to use `partial_merge` join if possible, otherwise, it uses `hash`. *Deprecated*, same as `partial_merge,hash`.
3399 : 113429 :
3400 : 113429 : - default (deprecated)
3401 : 113429 :
3402 : 113429 : Legacy value, please don't use anymore.
3403 : 113429 : Same as `direct,hash`, i.e. try to use direct join and hash join (in this order).
3404 : 113429 :
3405 : 113429 : )", 0) \
3406 : 113429 : DECLARE(UInt64, cross_to_inner_join_rewrite, 1, R"(
3407 : 113429 : Use inner join instead of comma/cross join if there are joining expressions in the WHERE section. Values: 0 - no rewrite, 1 - apply if possible for comma/cross, 2 - force rewrite all comma joins, cross - if possible
3408 : 113429 : )", 0) \
3409 : 113429 : DECLARE(UInt64, cross_join_min_rows_to_compress, 10000000, R"(
3410 : 113429 : Minimal count of rows to compress block in CROSS JOIN. Zero value means - disable this threshold. This block is compressed when any of the two thresholds (by rows or by bytes) are reached.
3411 : 113429 : )", 0) \
3412 : 113429 : DECLARE(UInt64, cross_join_min_bytes_to_compress, 1_GiB, R"(
3413 : 113429 : Minimal size of block to compress in CROSS JOIN. Zero value means - disable this threshold. This block is compressed when any of the two thresholds (by rows or by bytes) are reached.
3414 : 113429 : )", 0) \
3415 : 113429 : DECLARE(UInt64, default_max_bytes_in_join, 1000000000, R"(
3416 : 113429 : Maximum size of right-side table if limit is required but `max_bytes_in_join` is not set.
3417 : 113429 : )", 0) \
3418 : 113429 : DECLARE(UInt64, partial_merge_join_left_table_buffer_bytes, 0, R"(
3419 : 113429 : If not 0 group left table blocks in bigger ones for left-side table in partial merge join. It uses up to 2x of specified memory per joining thread.
3420 : 113429 : )", 0) \
3421 : 113429 : DECLARE(UInt64, partial_merge_join_rows_in_right_blocks, 65536, R"(
3422 : 113429 : Limits sizes of right-hand join data blocks in partial merge join algorithm for [JOIN](../../sql-reference/statements/select/join.md) queries.
3423 : 113429 :
3424 : 113429 : ClickHouse server:
3425 : 113429 :
3426 : 113429 : 1. Splits right-hand join data into blocks with up to the specified number of rows.
3427 : 113429 : 2. Indexes each block with its minimum and maximum values.
3428 : 113429 : 3. Unloads prepared blocks to disk if it is possible.
3429 : 113429 :
3430 : 113429 : Possible values:
3431 : 113429 :
3432 : 113429 : - Any positive integer. Recommended range of values: \[1000, 100000\].
3433 : 113429 : )", 0) \
3434 : 113429 : DECLARE(UInt64, join_on_disk_max_files_to_merge, 64, R"(
3435 : 113429 : Limits the number of files allowed for parallel sorting in MergeJoin operations when they are executed on disk.
3436 : 113429 :
3437 : 113429 : The bigger the value of the setting, the more RAM is used and the less disk I/O is needed.
3438 : 113429 :
3439 : 113429 : Possible values:
3440 : 113429 :
3441 : 113429 : - Any positive integer, starting from 2.
3442 : 113429 : )", 0) \
3443 : 113429 : DECLARE(UInt64, max_rows_in_set_to_optimize_join, 0, R"(
3444 : 113429 : Maximal size of the set to filter joined tables by each other's row sets before joining.
3445 : 113429 :
3446 : 113429 : Possible values:
3447 : 113429 :
3448 : 113429 : - 0 — Disable.
3449 : 113429 : - Any positive integer.
3450 : 113429 : )", 0) \
3451 : 113429 : \
3452 : 113429 : DECLARE(Bool, compatibility_ignore_collation_in_create_table, true, R"(
3453 : 113429 : Compatibility ignore collation in create table
3454 : 113429 : )", 0) \
3455 : 113429 : \
3456 : 113429 : DECLARE(String, temporary_files_codec, "LZ4", R"(
3457 : 113429 : Sets compression codec for temporary files used in sorting and joining operations on disk.
3458 : 113429 :
3459 : 113429 : Possible values:
3460 : 113429 :
3461 : 113429 : - LZ4 — [LZ4](https://en.wikipedia.org/wiki/LZ4_(compression_algorithm)) compression is applied.
3462 : 113429 : - NONE — No compression is applied.
3463 : 113429 : )", 0) \
3464 : 113429 : \
3465 : 113429 : DECLARE(NonZeroUInt64, temporary_files_buffer_size, DBMS_DEFAULT_BUFFER_SIZE, "Size of the buffer for temporary files writers. Larger buffer size means less system calls, but more memory consumption.", 0) \
3466 : 113429 : DECLARE(UInt64, max_rows_to_transfer, 0, R"(
3467 : 113429 : Maximum size (in rows) that can be passed to a remote server or saved in a
3468 : 113429 : temporary table when the GLOBAL IN/JOIN section is executed.
3469 : 113429 : )", 0) \
3470 : 113429 : DECLARE(UInt64, max_bytes_to_transfer, 0, R"(
3471 : 113429 : The maximum number of bytes (uncompressed data) that can be passed to a remote
3472 : 113429 : server or saved in a temporary table when the GLOBAL IN/JOIN section is executed.
3473 : 113429 : )", 0) \
3474 : 113429 : DECLARE(OverflowMode, transfer_overflow_mode, OverflowMode::THROW, R"(
3475 : 113429 : Sets what happens when the amount of data exceeds one of the limits.
3476 : 113429 :
3477 : 113429 : Possible values:
3478 : 113429 : - `throw`: throw an exception (default).
3479 : 113429 : - `break`: stop executing the query and return the partial result, as if the
3480 : 113429 : source data ran out.
3481 : 113429 : )", 0) \
3482 : 113429 : \
3483 : 113429 : DECLARE(UInt64, max_rows_in_distinct, 0, R"(
3484 : 113429 : The maximum number of different rows when using DISTINCT.
3485 : 113429 : )", 0) \
3486 : 113429 : DECLARE(UInt64, max_bytes_in_distinct, 0, R"(
3487 : 113429 : The maximum number of bytes of the state (in uncompressed bytes) in memory, which
3488 : 113429 : is used by a hash table when using DISTINCT.
3489 : 113429 : )", 0) \
3490 : 113429 : DECLARE(OverflowMode, distinct_overflow_mode, OverflowMode::THROW, R"(
3491 : 113429 : Sets what happens when the amount of data exceeds one of the limits.
3492 : 113429 :
3493 : 113429 : Possible values:
3494 : 113429 : - `throw`: throw an exception (default).
3495 : 113429 : - `break`: stop executing the query and return the partial result, as if the
3496 : 113429 : source data ran out.
3497 : 113429 : )", 0) \
3498 : 113429 : \
3499 : 113429 : DECLARE(UInt64, max_memory_usage, 0, R"(
3500 : 113429 : Cloud default value: depends on the amount of RAM on the replica.
3501 : 113429 :
3502 : 113429 : The maximum amount of RAM to use for running a query on a single server.
3503 : 113429 : A value of `0` means unlimited.
3504 : 113429 :
3505 : 113429 : This setting does not consider the volume of available memory or the total volume
3506 : 113429 : of memory on the machine. The restriction applies to a single query within a
3507 : 113429 : single server.
3508 : 113429 :
3509 : 113429 : You can use `SHOW PROCESSLIST` to see the current memory consumption for each query.
3510 : 113429 : Peak memory consumption is tracked for each query and written to the log.
3511 : 113429 :
3512 : 113429 : Memory usage is not fully tracked for states of the following aggregate functions
3513 : 113429 : from `String` and `Array` arguments:
3514 : 113429 : - `min`
3515 : 113429 : - `max`
3516 : 113429 : - `any`
3517 : 113429 : - `anyLast`
3518 : 113429 : - `argMin`
3519 : 113429 : - `argMax`
3520 : 113429 :
3521 : 113429 : Memory consumption is also restricted by the parameters [`max_memory_usage_for_user`](/operations/settings/settings#max_memory_usage_for_user)
3522 : 113429 : and [`max_server_memory_usage`](/operations/server-configuration-parameters/settings#max_server_memory_usage).
3523 : 113429 : )", 0) \
3524 : 113429 : DECLARE(UInt64, memory_overcommit_ratio_denominator, 1_GiB, R"(
3525 : 113429 : It represents the soft memory limit when the hard limit is reached on the global level.
3526 : 113429 : This value is used to compute the overcommit ratio for the query.
3527 : 113429 : Zero means skip the query.
3528 : 113429 : Read more about [memory overcommit](memory-overcommit.md).
3529 : 113429 : )", 0) \
3530 : 113429 : DECLARE(UInt64, max_memory_usage_for_user, 0, R"(
3531 : 113429 : The maximum amount of RAM to use for running a user's queries on a single server. Zero means unlimited.
3532 : 113429 :
3533 : 113429 : By default, the amount is not restricted (`max_memory_usage_for_user = 0`).
3534 : 113429 :
3535 : 113429 : Also see the description of [`max_memory_usage`](/operations/settings/settings#max_memory_usage).
3536 : 113429 :
3537 : 113429 : For example if you want to set `max_memory_usage_for_user` to 1000 bytes for a user named `clickhouse_read`, you can use the statement
3538 : 113429 :
3539 : 113429 : ```sql
3540 : 113429 : ALTER USER clickhouse_read SETTINGS max_memory_usage_for_user = 1000;
3541 : 113429 : ```
3542 : 113429 :
3543 : 113429 : You can verify it worked by logging out of your client, logging back in, then use the `getSetting` function:
3544 : 113429 :
3545 : 113429 : ```sql
3546 : 113429 : SELECT getSetting('max_memory_usage_for_user');
3547 : 113429 : ```
3548 : 113429 : )", 0) \
3549 : 113429 : DECLARE(UInt64, memory_overcommit_ratio_denominator_for_user, 1_GiB, R"(
3550 : 113429 : It represents the soft memory limit when the hard limit is reached on the user level.
3551 : 113429 : This value is used to compute the overcommit ratio for the query.
3552 : 113429 : Zero means skip the query.
3553 : 113429 : Read more about [memory overcommit](memory-overcommit.md).
3554 : 113429 : )", 0) \
3555 : 113429 : DECLARE(UInt64, max_untracked_memory, (4 * 1024 * 1024), R"(
3556 : 113429 : Small allocations and deallocations are grouped in thread local variable and tracked or profiled only when an amount (in absolute value) becomes larger than the specified value. If the value is higher than 'memory_profiler_step' it will be effectively lowered to 'memory_profiler_step'.
3557 : 113429 : )", 0) \
3558 : 113429 : DECLARE(UInt64, max_reverse_dictionary_lookup_cache_size_bytes, (100 * 1024 * 1024), R"(
3559 : 113429 : Maximum size in bytes of the per-query reverse dictionary lookup cache used by the function `dictGetKeys`. The cache stores serialized key tuples per attribute value to avoid re-scanning the dictionary within the same query. When the limit is reached, entries are evicted using LRU. Set to 0 to disable caching.
3560 : 113429 : )", 0) \
3561 : 113429 : DECLARE(UInt64, memory_profiler_step, (4 * 1024 * 1024), R"(
3562 : 113429 : 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](/operations/system-tables/trace_log).
3563 : 113429 :
3564 : 113429 : Possible values:
3565 : 113429 :
3566 : 113429 : - A positive integer number of bytes.
3567 : 113429 :
3568 : 113429 : - 0 for turning off the memory profiler.
3569 : 113429 : )", 0) \
3570 : 113429 : DECLARE(Float, memory_profiler_sample_probability, 0., R"(
3571 : 113429 : Collect random allocations and deallocations and write them into system.trace_log with 'MemorySample' trace_type. The probability is for every alloc/free regardless of the size of the allocation (can be changed with `memory_profiler_sample_min_allocation_size` and `memory_profiler_sample_max_allocation_size`). Note that sampling happens only when the amount of untracked memory exceeds 'max_untracked_memory'. You may want to set 'max_untracked_memory' to 0 for extra fine-grained sampling.
3572 : 113429 : )", 0) \
3573 : 113429 : DECLARE(UInt64, memory_profiler_sample_min_allocation_size, 0, R"(
3574 : 113429 : Collect random allocations of size greater or equal than the specified value with probability equal to `memory_profiler_sample_probability`. 0 means disabled. You may want to set 'max_untracked_memory' to 0 to make this threshold work as expected.
3575 : 113429 : )", 0) \
3576 : 113429 : DECLARE(UInt64, memory_profiler_sample_max_allocation_size, 0, R"(
3577 : 113429 : Collect random allocations of size less or equal than the specified value with probability equal to `memory_profiler_sample_probability`. 0 means disabled. You may want to set 'max_untracked_memory' to 0 to make this threshold work as expected.
3578 : 113429 : )", 0) \
3579 : 113429 : DECLARE(Bool, trace_profile_events, false, R"(
3580 : 113429 : 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](/operations/system-tables/trace_log).
3581 : 113429 :
3582 : 113429 : Possible values:
3583 : 113429 :
3584 : 113429 : - 1 — Tracing of profile events enabled.
3585 : 113429 : - 0 — Tracing of profile events disabled.
3586 : 113429 : )", 0) \
3587 : 113429 : DECLARE(String, trace_profile_events_list, "", R"(
3588 : 113429 : When the setting `trace_profile_events` is enabled, limit the traced events to the specified list of comma-separated names.
3589 : 113429 : If the `trace_profile_events_list` is an empty string (by default), trace all profile events.
3590 : 113429 :
3591 : 113429 : Example value: 'DiskS3ReadMicroseconds,DiskS3ReadRequestsCount,SelectQueryTimeMicroseconds,ReadBufferFromS3Bytes'
3592 : 113429 :
3593 : 113429 : Using this setting allows more precise collection of data for a large number of queries, because otherwise the vast amount of events can overflow the internal system log queue and some portion of them will be dropped.
3594 : 113429 : )", 0) \
3595 : 113429 : \
3596 : 113429 : DECLARE(UInt64, memory_usage_overcommit_max_wait_microseconds, 5'000'000, R"(
3597 : 113429 : Maximum time thread will wait for memory to be freed in the case of memory overcommit on a user level.
3598 : 113429 : If the timeout is reached and memory is not freed, an exception is thrown.
3599 : 113429 : Read more about [memory overcommit](memory-overcommit.md).
3600 : 113429 : )", 0) \
3601 : 113429 : \
3602 : 113429 : DECLARE(UInt64, max_network_bandwidth, 0, R"(
3603 : 113429 : Limits the speed of the data exchange over the network in bytes per second. This setting applies to every query.
3604 : 113429 :
3605 : 113429 : Possible values:
3606 : 113429 :
3607 : 113429 : - Positive integer.
3608 : 113429 : - 0 — Bandwidth control is disabled.
3609 : 113429 : )", 0) \
3610 : 113429 : DECLARE(UInt64, max_network_bytes, 0, R"(
3611 : 113429 : 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.
3612 : 113429 :
3613 : 113429 : Possible values:
3614 : 113429 :
3615 : 113429 : - Positive integer.
3616 : 113429 : - 0 — Data volume control is disabled.
3617 : 113429 : )", 0) \
3618 : 113429 : DECLARE(UInt64, max_network_bandwidth_for_user, 0, R"(
3619 : 113429 : 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.
3620 : 113429 :
3621 : 113429 : Possible values:
3622 : 113429 :
3623 : 113429 : - Positive integer.
3624 : 113429 : - 0 — Control of the data speed is disabled.
3625 : 113429 : )", 0)\
3626 : 113429 : DECLARE(UInt64, max_network_bandwidth_for_all_users, 0, R"(
3627 : 113429 : 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.
3628 : 113429 :
3629 : 113429 : Possible values:
3630 : 113429 :
3631 : 113429 : - Positive integer.
3632 : 113429 : - 0 — Control of the data speed is disabled.
3633 : 113429 : )", 0) \
3634 : 113429 : \
3635 : 113429 : DECLARE(UInt64, max_temporary_data_on_disk_size_for_user, 0, R"(
3636 : 113429 : The maximum amount of data consumed by temporary files on disk in bytes for all
3637 : 113429 : concurrently running user queries.
3638 : 113429 :
3639 : 113429 : Possible values:
3640 : 113429 :
3641 : 113429 : - Positive integer.
3642 : 113429 : - `0` — unlimited (default)
3643 : 113429 : )", 0)\
3644 : 113429 : DECLARE(UInt64, max_temporary_data_on_disk_size_for_query, 0, R"(
3645 : 113429 : The maximum amount of data consumed by temporary files on disk in bytes for all
3646 : 113429 : concurrently running queries.
3647 : 113429 :
3648 : 113429 : Possible values:
3649 : 113429 :
3650 : 113429 : - Positive integer.
3651 : 113429 : - `0` — unlimited (default)
3652 : 113429 : )", 0)\
3653 : 113429 : \
3654 : 113429 : DECLARE(UInt64, backup_restore_keeper_max_retries, 1000, R"(
3655 : 113429 : Max retries for [Zoo]Keeper operations in the middle of a BACKUP or RESTORE operation.
3656 : 113429 : Should be big enough so the whole operation won't fail because of a temporary [Zoo]Keeper failure.
3657 : 113429 : )", 0) \
3658 : 113429 : DECLARE(UInt64, backup_restore_keeper_retry_initial_backoff_ms, 100, R"(
3659 : 113429 : Initial backoff timeout for [Zoo]Keeper operations during backup or restore
3660 : 113429 : )", 0) \
3661 : 113429 : DECLARE(UInt64, backup_restore_keeper_retry_max_backoff_ms, 5000, R"(
3662 : 113429 : Max backoff timeout for [Zoo]Keeper operations during backup or restore
3663 : 113429 :
3664 : 113429 : Cloud default value: `60000`.
3665 : 113429 : )", 0) \
3666 : 113429 : DECLARE(UInt64, backup_restore_failure_after_host_disconnected_for_seconds, 3600, R"(
3667 : 113429 : If a host during a BACKUP ON CLUSTER or RESTORE ON CLUSTER operation doesn't recreate its ephemeral 'alive' node in ZooKeeper for this amount of time then the whole backup or restore is considered as failed.
3668 : 113429 : This value should be bigger than any reasonable time for a host to reconnect to ZooKeeper after a failure.
3669 : 113429 : Zero means unlimited.
3670 : 113429 : )", 0) \
3671 : 113429 : DECLARE(UInt64, backup_restore_keeper_max_retries_while_initializing, 20, R"(
3672 : 113429 : Max retries for [Zoo]Keeper operations during the initialization of a BACKUP ON CLUSTER or RESTORE ON CLUSTER operation.
3673 : 113429 : )", 0) \
3674 : 113429 : DECLARE(UInt64, backup_restore_keeper_max_retries_while_handling_error, 20, R"(
3675 : 113429 : Max retries for [Zoo]Keeper operations while handling an error of a BACKUP ON CLUSTER or RESTORE ON CLUSTER operation.
3676 : 113429 : )", 0) \
3677 : 113429 : DECLARE(UInt64, backup_restore_finish_timeout_after_error_sec, 180, R"(
3678 : 113429 : How long the initiator should wait for other host to react to the 'error' node and stop their work on the current BACKUP ON CLUSTER or RESTORE ON CLUSTER operation.
3679 : 113429 : )", 0) \
3680 : 113429 : DECLARE(UInt64, backup_restore_keeper_value_max_size, 1048576, R"(
3681 : 113429 : Maximum size of data of a [Zoo]Keeper's node during backup
3682 : 113429 : )", 0) \
3683 : 113429 : DECLARE(UInt64, backup_restore_batch_size_for_keeper_multi, 1000, R"(
3684 : 113429 : Maximum size of batch for multi request to [Zoo]Keeper during backup or restore
3685 : 113429 : )", 0) \
3686 : 113429 : DECLARE(UInt64, backup_restore_batch_size_for_keeper_multiread, 10000, R"(
3687 : 113429 : Maximum size of batch for multiread request to [Zoo]Keeper during backup or restore
3688 : 113429 : )", 0) \
3689 : 113429 : DECLARE(Float, backup_restore_keeper_fault_injection_probability, 0.0f, R"(
3690 : 113429 : Approximate probability of failure for a keeper request during backup or restore. Valid value is in interval [0.0f, 1.0f]
3691 : 113429 : )", 0) \
3692 : 113429 : DECLARE(UInt64, backup_restore_keeper_fault_injection_seed, 0, R"(
3693 : 113429 : 0 - random seed, otherwise the setting value
3694 : 113429 : )", 0) \
3695 : 113429 : DECLARE(UInt64, backup_restore_s3_retry_attempts, 1000, R"(
3696 : 113429 : Setting for Aws::Client::RetryStrategy, Aws::Client does retries itself, 0 means no retries. It takes place only for backup/restore.
3697 : 113429 : )", 0) \
3698 : 113429 : DECLARE(UInt64, backup_restore_s3_retry_initial_backoff_ms, 25, R"(
3699 : 113429 : Initial backoff delay in milliseconds before the first retry attempt during backup and restore. Each subsequent retry increases the delay exponentially, up to the maximum specified by `backup_restore_s3_retry_max_backoff_ms`
3700 : 113429 : )", 0) \
3701 : 113429 : DECLARE(UInt64, backup_restore_s3_retry_max_backoff_ms, 5000, R"(
3702 : 113429 : Maximum delay in milliseconds between retries during backup and restore operations.
3703 : 113429 : )", 0) \
3704 : 113429 : DECLARE(Float, backup_restore_s3_retry_jitter_factor, .1f, R"(
3705 : 113429 : Jitter factor applied to the retry backoff delay in Aws::Client::RetryStrategy during backup and restore operations. The computed backoff delay is multiplied by a random factor in the range [1.0, 1.0 + jitter], up to the maximum `backup_restore_s3_retry_max_backoff_ms`. Must be in [0.0, 1.0] interval
3706 : 113429 : )", 0) \
3707 : 113429 : DECLARE(UInt64, max_backup_bandwidth, 0, R"(
3708 : 113429 : The maximum read speed in bytes per second for particular backup on server. Zero means unlimited.
3709 : 113429 : )", 0) \
3710 : 113429 : DECLARE(Bool, restore_replicated_merge_tree_to_shared_merge_tree, false, R"(
3711 : 113429 : Replace table engine from Replicated*MergeTree -> Shared*MergeTree during RESTORE.
3712 : 113429 :
3713 : 113429 : Cloud default value: `1`.
3714 : 113429 : )", 0) \
3715 : 113429 : \
3716 : 113429 : DECLARE(Bool, log_profile_events, true, R"(
3717 : 113429 : Log query performance statistics into the query_log, query_thread_log and query_views_log.
3718 : 113429 : )", 0) \
3719 : 113429 : DECLARE(Bool, log_query_settings, true, R"(
3720 : 113429 : Log query settings into the query_log and OpenTelemetry span log.
3721 : 113429 : )", 0) \
3722 : 113429 : DECLARE(Bool, log_query_threads, false, R"(
3723 : 113429 : Setting up query threads logging.
3724 : 113429 :
3725 : 113429 : Query threads log into the [system.query_thread_log](../../operations/system-tables/query_thread_log.md) table. This setting has effect only when [log_queries](#log_queries) is true. Queries' threads run by ClickHouse with this setup are logged according to the rules in the [query_thread_log](/operations/server-configuration-parameters/settings#query_thread_log) server configuration parameter.
3726 : 113429 :
3727 : 113429 : Possible values:
3728 : 113429 :
3729 : 113429 : - 0 — Disabled.
3730 : 113429 : - 1 — Enabled.
3731 : 113429 :
3732 : 113429 : **Example**
3733 : 113429 :
3734 : 113429 : ```text
3735 : 113429 : log_query_threads=1
3736 : 113429 : ```
3737 : 113429 : )", 0) \
3738 : 113429 : DECLARE(Bool, log_query_views, true, R"(
3739 : 113429 : Setting up query views logging.
3740 : 113429 :
3741 : 113429 : 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](/operations/server-configuration-parameters/settings#query_views_log) server configuration parameter.
3742 : 113429 :
3743 : 113429 : Example:
3744 : 113429 :
3745 : 113429 : ```text
3746 : 113429 : log_query_views=1
3747 : 113429 : ```
3748 : 113429 : )", 0) \
3749 : 113429 : DECLARE(String, log_comment, "", R"(
3750 : 113429 : Specifies the value for the `log_comment` field of the [system.query_log](../system-tables/query_log.md) table and comment text for the server log.
3751 : 113429 :
3752 : 113429 : 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](../../development/tests.md).
3753 : 113429 :
3754 : 113429 : Possible values:
3755 : 113429 :
3756 : 113429 : - Any string no longer than [max_query_size](#max_query_size). If the max_query_size is exceeded, the server throws an exception.
3757 : 113429 :
3758 : 113429 : **Example**
3759 : 113429 :
3760 : 113429 : Query:
3761 : 113429 :
3762 : 113429 : ```sql
3763 : 113429 : SET log_comment = 'log_comment test', log_queries = 1;
3764 : 113429 : SELECT 1;
3765 : 113429 : SYSTEM FLUSH LOGS;
3766 : 113429 : SELECT type, query FROM system.query_log WHERE log_comment = 'log_comment test' AND event_date >= yesterday() ORDER BY event_time DESC LIMIT 2;
3767 : 113429 : ```
3768 : 113429 :
3769 : 113429 : Result:
3770 : 113429 :
3771 : 113429 : ```text
3772 : 113429 : ┌─type────────┬─query─────┐
3773 : 113429 : │ QueryStart │ SELECT 1; │
3774 : 113429 : │ QueryFinish │ SELECT 1; │
3775 : 113429 : └─────────────┴───────────┘
3776 : 113429 : ```
3777 : 113429 : )", 0) \
3778 : 113429 : DECLARE(Int64, query_metric_log_interval, -1, R"(
3779 : 113429 : The interval in milliseconds at which the [query_metric_log](../../operations/system-tables/query_metric_log.md) for individual queries is collected.
3780 : 113429 :
3781 : 113429 : If set to any negative value, it will take the value `collect_interval_milliseconds` from the [query_metric_log setting](/operations/server-configuration-parameters/settings#query_metric_log) or default to 1000 if not present.
3782 : 113429 :
3783 : 113429 : To disable the collection of a single query, set `query_metric_log_interval` to 0.
3784 : 113429 :
3785 : 113429 : Default value: -1
3786 : 113429 : )", 0) \
3787 : 113429 : DECLARE(Bool, regexp_dict_allow_hyperscan, true, R"(
3788 : 113429 : Allow regexp_tree dictionary using Hyperscan library.
3789 : 113429 : )", 0) \
3790 : 113429 : DECLARE(Bool, regexp_dict_flag_case_insensitive, false, R"(
3791 : 113429 : Use case-insensitive matching for a regexp_tree dictionary. Can be overridden in individual expressions with (?i) and (?-i).
3792 : 113429 : )", 0) \
3793 : 113429 : DECLARE(Bool, regexp_dict_flag_dotall, false, R"(
3794 : 113429 : Allow '.' to match newline characters for a regexp_tree dictionary.
3795 : 113429 : )", 0) \
3796 : 113429 : DECLARE(Bool, dictionary_use_async_executor, false, R"(
3797 : 113429 : Execute a pipeline for reading dictionary source in several threads. It's supported only by dictionaries with local CLICKHOUSE source.
3798 : 113429 : )", 0) \
3799 : 113429 : DECLARE(LogsLevel, send_logs_level, LogsLevel::fatal, R"(
3800 : 113429 : Send server text logs with specified minimum level to client. Valid values: 'trace', 'debug', 'information', 'warning', 'error', 'fatal', 'none'
3801 : 113429 : )", 0) \
3802 : 113429 : DECLARE(String, send_logs_source_regexp, "", R"(
3803 : 113429 : Send server text logs with specified regexp to match log source name. Empty means all sources.
3804 : 113429 : )", 0) \
3805 : 113429 : DECLARE(Bool, enable_optimize_predicate_expression, true, R"(
3806 : 113429 : Turns on predicate pushdown in `SELECT` queries.
3807 : 113429 :
3808 : 113429 : Predicate pushdown may significantly reduce network traffic for distributed queries.
3809 : 113429 :
3810 : 113429 : Possible values:
3811 : 113429 :
3812 : 113429 : - 0 — Disabled.
3813 : 113429 : - 1 — Enabled.
3814 : 113429 :
3815 : 113429 : Usage
3816 : 113429 :
3817 : 113429 : Consider the following queries:
3818 : 113429 :
3819 : 113429 : 1. `SELECT count() FROM test_table WHERE date = '2018-10-10'`
3820 : 113429 : 2. `SELECT count() FROM (SELECT * FROM test_table) WHERE date = '2018-10-10'`
3821 : 113429 :
3822 : 113429 : 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.
3823 : 113429 :
3824 : 113429 : 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.
3825 : 113429 : )", 0) \
3826 : 113429 : DECLARE(Bool, enable_optimize_predicate_expression_to_final_subquery, true, R"(
3827 : 113429 : Allow push predicate to final subquery.
3828 : 113429 : )", 0) \
3829 : 113429 : DECLARE(Bool, allow_push_predicate_when_subquery_contains_with, true, R"(
3830 : 113429 : Allows push predicate when subquery contains WITH clause
3831 : 113429 : )", 0) \
3832 : 113429 : DECLARE(Bool, allow_push_predicate_ast_for_distributed_subqueries, true, R"(
3833 : 113429 : Allows push predicate on AST level for distributed subqueries with enabled anlyzer
3834 : 113429 : )", 0) \
3835 : 113429 : \
3836 : 113429 : DECLARE(UInt64, low_cardinality_max_dictionary_size, 8192, R"(
3837 : 113429 : Sets a maximum size in rows of a shared global dictionary for the [LowCardinality](../../sql-reference/data-types/lowcardinality.md) 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.
3838 : 113429 :
3839 : 113429 : Possible values:
3840 : 113429 :
3841 : 113429 : - Any positive integer.
3842 : 113429 : )", 0) \
3843 : 113429 : DECLARE(Bool, low_cardinality_use_single_dictionary_for_part, false, R"(
3844 : 113429 : Turns on or turns off using of single dictionary for the data part.
3845 : 113429 :
3846 : 113429 : 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`.
3847 : 113429 :
3848 : 113429 : Possible values:
3849 : 113429 :
3850 : 113429 : - 1 — Creating several dictionaries for the data part is prohibited.
3851 : 113429 : - 0 — Creating several dictionaries for the data part is not prohibited.
3852 : 113429 : )", 0) \
3853 : 113429 : DECLARE(Bool, decimal_check_overflow, true, R"(
3854 : 113429 : Check overflow of decimal arithmetic/comparison operations
3855 : 113429 : )", 0) \
3856 : 113429 : DECLARE(Bool, allow_custom_error_code_in_throwif, false, R"(
3857 : 113429 : Enable custom error code in function throwIf(). If true, thrown exceptions may have unexpected error codes.
3858 : 113429 : )", 0) \
3859 : 113429 : \
3860 : 113429 : DECLARE(Bool, prefer_localhost_replica, true, R"(
3861 : 113429 : Enables/disables preferable using the localhost replica when processing distributed queries.
3862 : 113429 :
3863 : 113429 : Possible values:
3864 : 113429 :
3865 : 113429 : - 1 — ClickHouse always sends a query to the localhost replica if it exists.
3866 : 113429 : - 0 — ClickHouse uses the balancing strategy specified by the [load_balancing](#load_balancing) setting.
3867 : 113429 :
3868 : 113429 : :::note
3869 : 113429 : Disable this setting if you use [max_parallel_replicas](#max_parallel_replicas) without [parallel_replicas_custom_key](#parallel_replicas_custom_key).
3870 : 113429 : If [parallel_replicas_custom_key](#parallel_replicas_custom_key) is set, disable this setting only if it's used on a cluster with multiple shards containing multiple replicas.
3871 : 113429 : If it's used on a cluster with a single shard and multiple replicas, disabling this setting will have negative effects.
3872 : 113429 : :::
3873 : 113429 : )", 0) \
3874 : 113429 : DECLARE(UInt64, max_fetch_partition_retries_count, 5, R"(
3875 : 113429 : Amount of retries while fetching partition from another host.
3876 : 113429 : )", 0) \
3877 : 113429 : DECLARE(UInt64, http_max_multipart_form_data_size, 1024 * 1024 * 1024, R"(
3878 : 113429 : Limit on size of multipart/form-data content. This setting cannot be parsed from URL parameters and should be set in a user profile. Note that content is parsed and external tables are created in memory before the start of query execution. And this is the only limit that has an effect on that stage (limits on max memory usage and max execution time have no effect while reading HTTP form data).
3879 : 113429 : )", 0) \
3880 : 113429 : DECLARE(Bool, calculate_text_stack_trace, true, R"(
3881 : 113429 : Calculate text stack trace in case of exceptions during query execution. This is the default. It requires symbol lookups that may slow down fuzzing tests when a huge amount of wrong queries are executed. In normal cases, you should not disable this option.
3882 : 113429 : )", 0) \
3883 : 113429 : DECLARE(Bool, enable_job_stack_trace, false, R"(
3884 : 113429 : Output stack trace of a job creator when job results in exception. Disabled by default to avoid performance overhead.
3885 : 113429 : )", 0) \
3886 : 113429 : DECLARE(Bool, allow_ddl, true, R"(
3887 : 113429 : If it is set to true, then a user is allowed to executed DDL queries.
3888 : 113429 : )", 0) \
3889 : 113429 : DECLARE(Bool, parallel_view_processing, false, R"(
3890 : 113429 : Enables pushing to attached views concurrently instead of sequentially.
3891 : 113429 : )", 0) \
3892 : 113429 : DECLARE(Bool, enable_unaligned_array_join, false, R"(
3893 : 113429 : Allow ARRAY JOIN with multiple arrays that have different sizes. When this settings is enabled, arrays will be resized to the longest one.
3894 : 113429 : )", 0) \
3895 : 113429 : DECLARE(Bool, optimize_read_in_order, true, R"(
3896 : 113429 : Enables [ORDER BY](/sql-reference/statements/select/order-by#optimization-of-data-reading) optimization in [SELECT](../../sql-reference/statements/select/index.md) queries for reading data from [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md) tables.
3897 : 113429 :
3898 : 113429 : Possible values:
3899 : 113429 :
3900 : 113429 : - 0 — `ORDER BY` optimization is disabled.
3901 : 113429 : - 1 — `ORDER BY` optimization is enabled.
3902 : 113429 :
3903 : 113429 : **See Also**
3904 : 113429 :
3905 : 113429 : - [ORDER BY Clause](/sql-reference/statements/select/order-by#optimization-of-data-reading)
3906 : 113429 : )", 0) \
3907 : 113429 : DECLARE(Bool, read_in_order_use_virtual_row, false, R"(
3908 : 113429 : Use virtual row while reading in order of primary key or its monotonic function fashion. It is useful when searching over multiple parts as only relevant ones are touched.
3909 : 113429 : )", 0) \
3910 : 113429 : DECLARE(Bool, read_in_order_use_virtual_row_per_block, false, R"(
3911 : 113429 : When enabled together with `read_in_order_use_virtual_row`, emit a virtual row after each block read (not only at the beginning of each part).
3912 : 113429 : This allows `MergingSortedTransform` to reprioritize sources more frequently, which is useful when downstream filters discard many rows and data is distributed unevenly across parts.
3913 : 113429 : Note that it disables `read_in_order_use_buffering` optimization and preliminary merge (`read_in_order_two_level_merge_threshold`) for reading.
3914 : 113429 : )", 0) \
3915 : 113429 : DECLARE(Bool, optimize_aggregation_in_order, false, R"(
3916 : 113429 : Enables [GROUP BY](/sql-reference/statements/select/group-by) optimization in [SELECT](../../sql-reference/statements/select/index.md) queries for aggregating data in corresponding order in [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md) tables.
3917 : 113429 :
3918 : 113429 : Possible values:
3919 : 113429 :
3920 : 113429 : - 0 — `GROUP BY` optimization is disabled.
3921 : 113429 : - 1 — `GROUP BY` optimization is enabled.
3922 : 113429 :
3923 : 113429 : **See Also**
3924 : 113429 :
3925 : 113429 : - [GROUP BY optimization](/sql-reference/statements/select/group-by#group-by-optimization-depending-on-table-sorting-key)
3926 : 113429 : )", 0) \
3927 : 113429 : DECLARE(Bool, read_in_order_use_buffering, true, R"(
3928 : 113429 : Use buffering before merging while reading in order of primary key. It increases the parallelism of query execution
3929 : 113429 : )", 0) \
3930 : 113429 : DECLARE(UInt64, aggregation_in_order_max_block_bytes, 50000000, R"(
3931 : 113429 : Maximal size of block in bytes accumulated during aggregation in order of primary key. Lower block size allows to parallelize more final merge stage of aggregation.
3932 : 113429 : )", 0) \
3933 : 113429 : DECLARE(UInt64, read_in_order_two_level_merge_threshold, 100, R"(
3934 : 113429 : Minimal number of parts to read to run preliminary merge step during multithread reading in order of primary key.
3935 : 113429 : )", 0) \
3936 : 113429 : DECLARE(Bool, low_cardinality_allow_in_native_format, true, R"(
3937 : 113429 : Allows or restricts using the [LowCardinality](../../sql-reference/data-types/lowcardinality.md) data type with the [Native](/interfaces/formats/Native) format.
3938 : 113429 :
3939 : 113429 : 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.
3940 : 113429 :
3941 : 113429 : This setting is required mainly for third-party clients which do not support `LowCardinality` data type.
3942 : 113429 :
3943 : 113429 : Possible values:
3944 : 113429 :
3945 : 113429 : - 1 — Usage of `LowCardinality` is not restricted.
3946 : 113429 : - 0 — Usage of `LowCardinality` is restricted.
3947 : 113429 : )", 0) \
3948 : 113429 : DECLARE(Bool, cancel_http_readonly_queries_on_client_close, false, R"(
3949 : 113429 : Cancels HTTP read-only queries (e.g. SELECT) when a client closes the connection without waiting for the response.
3950 : 113429 :
3951 : 113429 : Cloud default value: `1`.
3952 : 113429 : )", 0) \
3953 : 113429 : DECLARE(Bool, external_table_functions_use_nulls, true, R"(
3954 : 113429 : Defines how [mysql](../../sql-reference/table-functions/mysql.md), [postgresql](../../sql-reference/table-functions/postgresql.md) and [odbc](../../sql-reference/table-functions/odbc.md) table functions use Nullable columns.
3955 : 113429 :
3956 : 113429 : Possible values:
3957 : 113429 :
3958 : 113429 : - 0 — The table function explicitly uses Nullable columns.
3959 : 113429 : - 1 — The table function implicitly uses Nullable columns.
3960 : 113429 :
3961 : 113429 : **Usage**
3962 : 113429 :
3963 : 113429 : If the setting is set to `0`, the table function does not make Nullable columns and inserts default values instead of NULL. This is also applicable for NULL values inside arrays.
3964 : 113429 : )", 0) \
3965 : 113429 : DECLARE(Bool, external_table_strict_query, false, R"(
3966 : 113429 : If it is set to true, transforming expression to local filter is forbidden for queries to external tables.
3967 : 113429 : )", 0) \
3968 : 113429 : \
3969 : 113429 : DECLARE(Bool, allow_hyperscan, true, R"(
3970 : 113429 : Allow functions that use Hyperscan library. Disable to avoid potentially long compilation times and excessive resource usage.
3971 : 113429 : )", 0) \
3972 : 113429 : DECLARE(UInt64, max_hyperscan_regexp_length, 0, R"(
3973 : 113429 : Defines the maximum length for each regular expression in the [hyperscan multi-match functions](/sql-reference/functions/string-search-functions#multiMatchAny).
3974 : 113429 :
3975 : 113429 : Possible values:
3976 : 113429 :
3977 : 113429 : - Positive integer.
3978 : 113429 : - 0 - The length is not limited.
3979 : 113429 :
3980 : 113429 : **Example**
3981 : 113429 :
3982 : 113429 : Query:
3983 : 113429 :
3984 : 113429 : ```sql
3985 : 113429 : SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 3;
3986 : 113429 : ```
3987 : 113429 :
3988 : 113429 : Result:
3989 : 113429 :
3990 : 113429 : ```text
3991 : 113429 : ┌─multiMatchAny('abcd', ['ab', 'bcd', 'c', 'd'])─┐
3992 : 113429 : │ 1 │
3993 : 113429 : └────────────────────────────────────────────────┘
3994 : 113429 : ```
3995 : 113429 :
3996 : 113429 : Query:
3997 : 113429 :
3998 : 113429 : ```sql
3999 : 113429 : SELECT multiMatchAny('abcd', ['ab','bcd','c','d']) SETTINGS max_hyperscan_regexp_length = 2;
4000 : 113429 : ```
4001 : 113429 :
4002 : 113429 : Result:
4003 : 113429 :
4004 : 113429 : ```text
4005 : 113429 : Exception: Regexp length too large.
4006 : 113429 : ```
4007 : 113429 :
4008 : 113429 : **See Also**
4009 : 113429 :
4010 : 113429 : - [max_hyperscan_regexp_total_length](#max_hyperscan_regexp_total_length)
4011 : 113429 : )", 0) \
4012 : 113429 : DECLARE(UInt64, max_hyperscan_regexp_total_length, 0, R"(
4013 : 113429 : Sets the maximum length total of all regular expressions in each [hyperscan multi-match function](/sql-reference/functions/string-search-functions#multiMatchAny).
4014 : 113429 :
4015 : 113429 : Possible values:
4016 : 113429 :
4017 : 113429 : - Positive integer.
4018 : 113429 : - 0 - The length is not limited.
4019 : 113429 :
4020 : 113429 : **Example**
4021 : 113429 :
4022 : 113429 : Query:
4023 : 113429 :
4024 : 113429 : ```sql
4025 : 113429 : SELECT multiMatchAny('abcd', ['a','b','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5;
4026 : 113429 : ```
4027 : 113429 :
4028 : 113429 : Result:
4029 : 113429 :
4030 : 113429 : ```text
4031 : 113429 : ┌─multiMatchAny('abcd', ['a', 'b', 'c', 'd'])─┐
4032 : 113429 : │ 1 │
4033 : 113429 : └─────────────────────────────────────────────┘
4034 : 113429 : ```
4035 : 113429 :
4036 : 113429 : Query:
4037 : 113429 :
4038 : 113429 : ```sql
4039 : 113429 : SELECT multiMatchAny('abcd', ['ab','bc','c','d']) SETTINGS max_hyperscan_regexp_total_length = 5;
4040 : 113429 : ```
4041 : 113429 :
4042 : 113429 : Result:
4043 : 113429 :
4044 : 113429 : ```text
4045 : 113429 : Exception: Total regexp lengths too large.
4046 : 113429 : ```
4047 : 113429 :
4048 : 113429 : **See Also**
4049 : 113429 :
4050 : 113429 : - [max_hyperscan_regexp_length](#max_hyperscan_regexp_length)
4051 : 113429 : )", 0) \
4052 : 113429 : DECLARE(Bool, reject_expensive_hyperscan_regexps, true, R"(
4053 : 113429 : Reject patterns which will likely be expensive to evaluate with hyperscan (due to NFA state explosion)
4054 : 113429 : )", 0) \
4055 : 113429 : DECLARE(Bool, allow_simdjson, true, R"(
4056 : 113429 : Allow using simdjson library in 'JSON*' functions if AVX2 instructions are available. If disabled rapidjson will be used.
4057 : 113429 : )", 0) \
4058 : 113429 : DECLARE(Bool, allow_introspection_functions, false, R"(
4059 : 113429 : Enables or disables [introspection functions](../../sql-reference/functions/introspection.md) for query profiling.
4060 : 113429 :
4061 : 113429 : Possible values:
4062 : 113429 :
4063 : 113429 : - 1 — Introspection functions enabled.
4064 : 113429 : - 0 — Introspection functions disabled.
4065 : 113429 :
4066 : 113429 : **See Also**
4067 : 113429 :
4068 : 113429 : - [Sampling Query Profiler](../../operations/optimizing-performance/sampling-query-profiler.md)
4069 : 113429 : - System table [trace_log](/operations/system-tables/trace_log)
4070 : 113429 : )", 0) \
4071 : 113429 : DECLARE(Bool, splitby_max_substrings_includes_remaining_string, false, R"(
4072 : 113429 : Controls whether function [splitBy*()](../../sql-reference/functions/splitting-merging-functions.md) with argument `max_substrings` > 0 will include the remaining string in the last element of the result array.
4073 : 113429 :
4074 : 113429 : Possible values:
4075 : 113429 :
4076 : 113429 : - `0` - The remaining string will not be included in the last element of the result array.
4077 : 113429 : - `1` - The remaining string will be included in the last element of the result array. This is the behavior of Spark's [`split()`](https://spark.apache.org/docs/3.1.2/api/python/reference/api/pyspark.sql.functions.split.html) function and Python's ['string.split()'](https://docs.python.org/3/library/stdtypes.html#str.split) method.
4078 : 113429 : )", 0) \
4079 : 113429 : \
4080 : 113429 : DECLARE(Bool, allow_execute_multiif_columnar, true, R"(
4081 : 113429 : Allow execute multiIf function columnar
4082 : 113429 : )", 0) \
4083 : 113429 : DECLARE(Bool, formatdatetime_f_prints_single_zero, false, R"(
4084 : 113429 : Formatter '%f' in function 'formatDateTime' prints a single zero instead of six zeros if the formatted value has no fractional seconds.
4085 : 113429 : )", 0) \
4086 : 113429 : DECLARE(Bool, formatdatetime_f_prints_scale_number_of_digits, false, R"(
4087 : 113429 : Formatter '%f' in function 'formatDateTime' prints only the scale amount of digits for a DateTime64 instead of fixed 6 digits.
4088 : 113429 : )", 0) \
4089 : 113429 : DECLARE(Bool, formatdatetime_parsedatetime_m_is_month_name, true, R"(
4090 : 113429 : Formatter '%M' in functions 'formatDateTime' and 'parseDateTime' print/parse the month name instead of minutes.
4091 : 113429 : )", 0) \
4092 : 113429 : DECLARE(Bool, parsedatetime_parse_without_leading_zeros, true, R"(
4093 : 113429 : Formatters '%c', '%l' and '%k' in function 'parseDateTime' parse months and hours without leading zeros.
4094 : 113429 : )", 0) \
4095 : 113429 : DECLARE(Bool, parsedatetime_e_requires_space_padding, false, R"(
4096 : 113429 : Formatter '%e' in function 'parseDateTime' expects that single-digit days are space-padded, e.g., ' 2' is accepted but '2' raises an error.
4097 : 113429 : )", 0) \
4098 : 113429 : DECLARE(Bool, formatdatetime_format_without_leading_zeros, false, R"(
4099 : 113429 : Formatters '%c', '%l' and '%k' in function 'formatDateTime' print months and hours without leading zeros.
4100 : 113429 : )", 0) \
4101 : 113429 : DECLARE(Bool, formatdatetime_e_with_space_padding, false, R"(
4102 : 113429 : Formatter '%e' in function 'formatDateTime' prints single-digit days with a leading space, e.g. ' 2' instead of '2'.
4103 : 113429 : )", 0) \
4104 : 113429 : DECLARE(Bool, least_greatest_legacy_null_behavior, false, R"(
4105 : 113429 : If enabled, functions 'least' and 'greatest' return NULL if one of their arguments is NULL.
4106 : 113429 : )", 0) \
4107 : 113429 : DECLARE(Bool, h3togeo_lon_lat_result_order, false, R"(
4108 : 113429 : Function 'h3ToGeo' returns (lon, lat) if true, otherwise (lat, lon).
4109 : 113429 : )", 0) \
4110 : 113429 : DECLARE(GeoToH3ArgumentOrder, geotoh3_argument_order, GeoToH3ArgumentOrder::LAT_LON, R"(
4111 : 113429 : Function 'geoToH3' accepts (lon, lat) if set to 'lon_lat' and (lat, lon) if set to 'lat_lon'.
4112 : 113429 : )", BETA) \
4113 : 113429 : DECLARE(Bool, functions_h3_default_if_invalid, false, "If false, h3 functions, e.g. h3CellAreaM2, throw an exception if input is invalid. If true, they return 0 or default value.", 0) \
4114 : 113429 : DECLARE(UInt64, max_wkb_geometry_elements, 1'000'000, R"(
4115 : 113429 : Maximum number of points, rings, or polygons allowed in a single WKB geometry element during parsing by `readWKB` and related functions. This protects against excessive memory allocations from malformed WKB data. Set to 0 to use the hard-coded limit (100 million).
4116 : 113429 : )", 0) \
4117 : 113429 : DECLARE(UInt64, max_rand_distribution_trials, 1'000'000'000, R"(
4118 : 113429 : Maximum number of trials allowed for random distribution functions such as `randBinomial` and `randNegativeBinomial`. This prevents extremely long computation times with large trial counts.
4119 : 113429 : )", 0) \
4120 : 113429 : DECLARE(Float, max_rand_distribution_parameter, 1e6, R"(
4121 : 113429 : Maximum value for distribution shape parameters in random distribution functions such as `randChiSquared`, `randStudentT`, and `randFisherF`. This prevents extremely long computation times with extreme parameter values.
4122 : 113429 : )", 0) \
4123 : 113429 : DECLARE(UInt64, max_partitions_per_insert_block, 100, R"(
4124 : 113429 : Limits the maximum number of partitions in a single inserted block
4125 : 113429 : and an exception is thrown if the block contains too many partitions.
4126 : 113429 :
4127 : 113429 : - Positive integer.
4128 : 113429 : - `0` — Unlimited number of partitions.
4129 : 113429 :
4130 : 113429 : **Details**
4131 : 113429 :
4132 : 113429 : When inserting data, ClickHouse calculates the number of partitions in the
4133 : 113429 : inserted block. If the number of partitions is more than
4134 : 113429 : `max_partitions_per_insert_block`, ClickHouse either logs a warning or throws an
4135 : 113429 : exception based on `throw_on_max_partitions_per_insert_block`. Exceptions have
4136 : 113429 : the following text:
4137 : 113429 :
4138 : 113429 : > "Too many partitions for a single INSERT block (`partitions_count` partitions, limit is " + toString(max_partitions) + ").
4139 : 113429 : The limit is controlled by the 'max_partitions_per_insert_block' setting.
4140 : 113429 : A large number of partitions is a common misconception. It will lead to severe
4141 : 113429 : negative performance impact, including slow server startup, slow INSERT queries
4142 : 113429 : and slow SELECT queries. Recommended total number of partitions for a table is
4143 : 113429 : under 1000..10000. Please note, that partitioning is not intended to speed up
4144 : 113429 : SELECT queries (ORDER BY key is sufficient to make range queries fast).
4145 : 113429 : Partitions are intended for data manipulation (DROP PARTITION, etc)."
4146 : 113429 :
4147 : 113429 : :::note
4148 : 113429 : This setting is a safety threshold because using a large number of partitions is a common misconception.
4149 : 113429 : :::
4150 : 113429 : )", 0) \
4151 : 113429 : DECLARE(Bool, throw_on_max_partitions_per_insert_block, true, R"(
4152 : 113429 : Allows you to control the behaviour when `max_partitions_per_insert_block` is reached.
4153 : 113429 :
4154 : 113429 : Possible values:
4155 : 113429 : - `true` - When an insert block reaches `max_partitions_per_insert_block`, an exception is raised.
4156 : 113429 : - `false` - Logs a warning when `max_partitions_per_insert_block` is reached.
4157 : 113429 :
4158 : 113429 : :::tip
4159 : 113429 : This can be useful if you're trying to understand the impact on users when changing [`max_partitions_per_insert_block`](/operations/settings/settings#max_partitions_per_insert_block).
4160 : 113429 : :::
4161 : 113429 : )", 0) \
4162 : 113429 : DECLARE(Int64, max_partitions_to_read, -1, R"(
4163 : 113429 : Limits the maximum number of partitions that can be accessed in a single query.
4164 : 113429 :
4165 : 113429 : The setting value specified when the table is created can be overridden via query-level setting.
4166 : 113429 :
4167 : 113429 : Possible values:
4168 : 113429 :
4169 : 113429 : - Positive integer
4170 : 113429 : - `-1` - unlimited (default)
4171 : 113429 :
4172 : 113429 : :::note
4173 : 113429 : You can also specify the MergeTree setting [`max_partitions_to_read`](/operations/settings/settings#max_partitions_to_read) in tables' setting.
4174 : 113429 : :::
4175 : 113429 : )", 0) \
4176 : 113429 : DECLARE(Bool, check_query_single_value_result, false, R"(
4177 : 113429 : Defines the level of detail for the [CHECK TABLE](/sql-reference/statements/check-table) query result for `MergeTree` family engines .
4178 : 113429 :
4179 : 113429 : Possible values:
4180 : 113429 :
4181 : 113429 : - 0 — the query shows a check status for every individual data part of a table.
4182 : 113429 : - 1 — the query shows the general table check status.
4183 : 113429 : )", 0) \
4184 : 113429 : DECLARE(Bool, allow_drop_detached, false, R"(
4185 : 113429 : Allow ALTER TABLE ... DROP DETACHED PART[ITION] ... queries
4186 : 113429 : )", 0) \
4187 : 113429 : DECLARE(UInt64, max_parts_to_move, 1000, "Limit the number of parts that can be moved in one query. Zero means unlimited.", 0) \
4188 : 113429 : \
4189 : 113429 : DECLARE(UInt64, max_table_size_to_drop, default_max_size_to_drop, R"(
4190 : 113429 : Restriction on deleting tables in query time. The value `0` means that you can delete all tables without any restrictions.
4191 : 113429 :
4192 : 113429 : Cloud default value: 1 TB.
4193 : 113429 :
4194 : 113429 : :::note
4195 : 113429 : This query setting overwrites its server setting equivalent, see [max_table_size_to_drop](/operations/server-configuration-parameters/settings#max_table_size_to_drop)
4196 : 113429 : :::
4197 : 113429 : )", 0) \
4198 : 113429 : DECLARE(UInt64, max_partition_size_to_drop, default_max_size_to_drop, R"(
4199 : 113429 : Restriction on dropping partitions in query time. The value `0` means that you can drop partitions without any restrictions.
4200 : 113429 :
4201 : 113429 : Cloud default value: 1 TB.
4202 : 113429 :
4203 : 113429 : :::note
4204 : 113429 : This query setting overwrites its server setting equivalent, see [max_partition_size_to_drop](/operations/server-configuration-parameters/settings#max_partition_size_to_drop)
4205 : 113429 : :::
4206 : 113429 : )", 0) \
4207 : 113429 : \
4208 : 113429 : DECLARE(UInt64, postgresql_connection_pool_size, 16, R"(
4209 : 113429 : Connection pool size for PostgreSQL table engine and database engine.
4210 : 113429 : )", 0) \
4211 : 113429 : DECLARE(UInt64, postgresql_connection_attempt_timeout, 2, R"(
4212 : 113429 : Connection timeout in seconds of a single attempt to connect PostgreSQL end-point.
4213 : 113429 : The value is passed as a `connect_timeout` parameter of the connection URL.
4214 : 113429 : )", 0) \
4215 : 113429 : DECLARE(UInt64, postgresql_connection_pool_wait_timeout, 5000, R"(
4216 : 113429 : Connection pool push/pop timeout on empty pool for PostgreSQL table engine and database engine. By default it will block on empty pool.
4217 : 113429 : )", 0) \
4218 : 113429 : DECLARE(UInt64, postgresql_connection_pool_retries, 2, R"(
4219 : 113429 : Connection pool push/pop retries number for PostgreSQL table engine and database engine.
4220 : 113429 : )", 0) \
4221 : 113429 : DECLARE(Bool, postgresql_connection_pool_auto_close_connection, false, R"(
4222 : 113429 : Close connection before returning connection to the pool.
4223 : 113429 : )", 0) \
4224 : 113429 : DECLARE(Float, postgresql_fault_injection_probability, 0.0f, R"(
4225 : 113429 : Approximate probability of failing internal (for replication) PostgreSQL queries. Valid value is in interval [0.0f, 1.0f]
4226 : 113429 : )", 0) \
4227 : 113429 : DECLARE(UInt64, glob_expansion_max_elements, 1000, R"(
4228 : 113429 : Maximum number of allowed addresses (For external storages, table functions, etc).
4229 : 113429 : )", 0) \
4230 : 113429 : DECLARE(UInt64, odbc_bridge_connection_pool_size, 16, R"(
4231 : 113429 : Connection pool size for each connection settings string in ODBC bridge.
4232 : 113429 : )", 0) \
4233 : 113429 : DECLARE(Bool, odbc_bridge_use_connection_pooling, true, R"(
4234 : 113429 : Use connection pooling in ODBC bridge. If set to false, a new connection is created every time.
4235 : 113429 : )", 0) \
4236 : 113429 : \
4237 : 113429 : DECLARE(Seconds, distributed_replica_error_half_life, DBMS_CONNECTION_POOL_WITH_FAILOVER_DEFAULT_DECREASE_ERROR_PERIOD, R"(
4238 : 113429 : - Type: seconds
4239 : 113429 : - Default value: 60 seconds
4240 : 113429 :
4241 : 113429 : 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.
4242 : 113429 :
4243 : 113429 : See also:
4244 : 113429 :
4245 : 113429 : - [load_balancing](#load_balancing-round_robin)
4246 : 113429 : - [Table engine Distributed](../../engines/table-engines/special/distributed.md)
4247 : 113429 : - [distributed_replica_error_cap](#distributed_replica_error_cap)
4248 : 113429 : - [distributed_replica_max_ignored_errors](#distributed_replica_max_ignored_errors)
4249 : 113429 : )", 0) \
4250 : 113429 : DECLARE(UInt64, distributed_replica_error_cap, DBMS_CONNECTION_POOL_WITH_FAILOVER_MAX_ERROR_COUNT, R"(
4251 : 113429 : - Type: unsigned int
4252 : 113429 : - Default value: 1000
4253 : 113429 :
4254 : 113429 : The error count of each replica is capped at this value, preventing a single replica from accumulating too many errors.
4255 : 113429 :
4256 : 113429 : See also:
4257 : 113429 :
4258 : 113429 : - [load_balancing](#load_balancing-round_robin)
4259 : 113429 : - [Table engine Distributed](../../engines/table-engines/special/distributed.md)
4260 : 113429 : - [distributed_replica_error_half_life](#distributed_replica_error_half_life)
4261 : 113429 : - [distributed_replica_max_ignored_errors](#distributed_replica_max_ignored_errors)
4262 : 113429 : )", 0) \
4263 : 113429 : DECLARE(UInt64, distributed_replica_max_ignored_errors, 0, R"(
4264 : 113429 : - Type: unsigned int
4265 : 113429 : - Default value: 0
4266 : 113429 :
4267 : 113429 : The number of errors that will be ignored while choosing replicas (according to `load_balancing` algorithm).
4268 : 113429 :
4269 : 113429 : See also:
4270 : 113429 :
4271 : 113429 : - [load_balancing](#load_balancing-round_robin)
4272 : 113429 : - [Table engine Distributed](../../engines/table-engines/special/distributed.md)
4273 : 113429 : - [distributed_replica_error_cap](#distributed_replica_error_cap)
4274 : 113429 : - [distributed_replica_error_half_life](#distributed_replica_error_half_life)
4275 : 113429 : )", 0) \
4276 : 113429 : \
4277 : 113429 : DECLARE(UInt64, min_free_disk_space_for_temporary_data, 0, R"(
4278 : 113429 : The minimum disk space to keep while writing temporary data used in external sorting and aggregation.
4279 : 113429 : )", 0) \
4280 : 113429 : \
4281 : 113429 : DECLARE(DefaultTableEngine, default_temporary_table_engine, DefaultTableEngine::Memory, R"(
4282 : 113429 : Same as [default_table_engine](#default_table_engine) but for temporary tables.
4283 : 113429 :
4284 : 113429 : In this example, any new temporary table that does not specify an `Engine` will use the `Log` table engine:
4285 : 113429 :
4286 : 113429 : Query:
4287 : 113429 :
4288 : 113429 : ```sql
4289 : 113429 : SET default_temporary_table_engine = 'Log';
4290 : 113429 :
4291 : 113429 : CREATE TEMPORARY TABLE my_table (
4292 : 113429 : x UInt32,
4293 : 113429 : y UInt32
4294 : 113429 : );
4295 : 113429 :
4296 : 113429 : SHOW CREATE TEMPORARY TABLE my_table;
4297 : 113429 : ```
4298 : 113429 :
4299 : 113429 : Result:
4300 : 113429 :
4301 : 113429 : ```response
4302 : 113429 : ┌─statement────────────────────────────────────────────────────────────────┐
4303 : 113429 : │ CREATE TEMPORARY TABLE default.my_table
4304 : 113429 : (
4305 : 113429 : `x` UInt32,
4306 : 113429 : `y` UInt32
4307 : 113429 : )
4308 : 113429 : ENGINE = Log
4309 : 113429 : └──────────────────────────────────────────────────────────────────────────┘
4310 : 113429 : ```
4311 : 113429 : )", 0) \
4312 : 113429 : DECLARE(DefaultTableEngine, default_table_engine, DefaultTableEngine::MergeTree, R"(
4313 : 113429 : Default table engine to use when `ENGINE` is not set in a `CREATE` statement.
4314 : 113429 :
4315 : 113429 : Possible values:
4316 : 113429 :
4317 : 113429 : - a string representing any valid table engine name
4318 : 113429 :
4319 : 113429 : Cloud default value: `SharedMergeTree`.
4320 : 113429 :
4321 : 113429 : **Example**
4322 : 113429 :
4323 : 113429 : Query:
4324 : 113429 :
4325 : 113429 : ```sql
4326 : 113429 : SET default_table_engine = 'Log';
4327 : 113429 :
4328 : 113429 : SELECT name, value, changed FROM system.settings WHERE name = 'default_table_engine';
4329 : 113429 : ```
4330 : 113429 :
4331 : 113429 : Result:
4332 : 113429 :
4333 : 113429 : ```response
4334 : 113429 : ┌─name─────────────────┬─value─┬─changed─┐
4335 : 113429 : │ default_table_engine │ Log │ 1 │
4336 : 113429 : └──────────────────────┴───────┴─────────┘
4337 : 113429 : ```
4338 : 113429 :
4339 : 113429 : In this example, any new table that does not specify an `Engine` will use the `Log` table engine:
4340 : 113429 :
4341 : 113429 : Query:
4342 : 113429 :
4343 : 113429 : ```sql
4344 : 113429 : CREATE TABLE my_table (
4345 : 113429 : x UInt32,
4346 : 113429 : y UInt32
4347 : 113429 : );
4348 : 113429 :
4349 : 113429 : SHOW CREATE TABLE my_table;
4350 : 113429 : ```
4351 : 113429 :
4352 : 113429 : Result:
4353 : 113429 :
4354 : 113429 : ```response
4355 : 113429 : ┌─statement────────────────────────────────────────────────────────────────┐
4356 : 113429 : │ CREATE TABLE default.my_table
4357 : 113429 : (
4358 : 113429 : `x` UInt32,
4359 : 113429 : `y` UInt32
4360 : 113429 : )
4361 : 113429 : ENGINE = Log
4362 : 113429 : └──────────────────────────────────────────────────────────────────────────┘
4363 : 113429 : ```
4364 : 113429 : )", 0) \
4365 : 113429 : DECLARE(Bool, show_table_uuid_in_table_create_query_if_not_nil, false, R"(
4366 : 113429 : Sets the `SHOW TABLE` query display.
4367 : 113429 :
4368 : 113429 : Possible values:
4369 : 113429 :
4370 : 113429 : - 0 — The query will be displayed without table UUID.
4371 : 113429 : - 1 — The query will be displayed with table UUID.
4372 : 113429 : )", 0) \
4373 : 113429 : DECLARE(Bool, database_atomic_wait_for_drop_and_detach_synchronously, false, R"(
4374 : 113429 : Adds a modifier `SYNC` to all `DROP` and `DETACH` queries.
4375 : 113429 :
4376 : 113429 : Possible values:
4377 : 113429 :
4378 : 113429 : - 0 — Queries will be executed with delay.
4379 : 113429 : - 1 — Queries will be executed without delay.
4380 : 113429 : )", 0) \
4381 : 113429 : DECLARE(Bool, enable_scalar_subquery_optimization, true, R"(
4382 : 113429 : If it is set to true, prevent scalar subqueries from (de)serializing large scalar values and possibly avoid running the same subquery more than once.
4383 : 113429 : )", 0) \
4384 : 113429 : DECLARE(Bool, optimize_trivial_count_query, true, R"(
4385 : 113429 : 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.
4386 : 113429 :
4387 : 113429 : Possible values:
4388 : 113429 :
4389 : 113429 : - 0 — Optimization disabled.
4390 : 113429 : - 1 — Optimization enabled.
4391 : 113429 :
4392 : 113429 : See also:
4393 : 113429 :
4394 : 113429 : - [optimize_functions_to_subcolumns](#optimize_functions_to_subcolumns)
4395 : 113429 : )", 0) \
4396 : 113429 : DECLARE(Bool, optimize_trivial_approximate_count_query, false, R"(
4397 : 113429 : Use an approximate value for trivial count optimization of storages that support such estimation, for example, EmbeddedRocksDB.
4398 : 113429 :
4399 : 113429 : Possible values:
4400 : 113429 :
4401 : 113429 : - 0 — Optimization disabled.
4402 : 113429 : - 1 — Optimization enabled.
4403 : 113429 : )", 0) \
4404 : 113429 : DECLARE(Bool, optimize_count_from_files, true, R"(
4405 : 113429 : 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`.
4406 : 113429 :
4407 : 113429 : Possible values:
4408 : 113429 :
4409 : 113429 : - 0 — Optimization disabled.
4410 : 113429 : - 1 — Optimization enabled.
4411 : 113429 : )", 0) \
4412 : 113429 : DECLARE(Bool, use_cache_for_count_from_files, true, R"(
4413 : 113429 : Enables caching of rows number during count from files in table functions `file`/`s3`/`url`/`hdfs`/`azureBlobStorage`.
4414 : 113429 :
4415 : 113429 : Enabled by default.
4416 : 113429 : )", 0) \
4417 : 113429 : DECLARE(Bool, optimize_respect_aliases, true, R"(
4418 : 113429 : 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
4419 : 113429 : )", 0) \
4420 : 113429 : DECLARE(UInt64, mutations_sync, 0, R"(
4421 : 113429 : Allows to execute `ALTER TABLE ... UPDATE|DELETE|MATERIALIZE INDEX|MATERIALIZE PROJECTION|MATERIALIZE COLUMN|MATERIALIZE STATISTICS` queries ([mutations](../../sql-reference/statements/alter/index.md/#mutations)) synchronously.
4422 : 113429 :
4423 : 113429 : Possible values:
4424 : 113429 :
4425 : 113429 : | Value | Description |
4426 : 113429 : |-------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
4427 : 113429 : | `0` | Mutations execute asynchronously. |
4428 : 113429 : | `1` | The query waits for all mutations to complete on the current server. |
4429 : 113429 : | `2` | The query waits for all mutations to complete on all replicas (if they exist). |
4430 : 113429 : | `3` | The query waits only for active replicas. Supported only for `SharedMergeTree`. For `ReplicatedMergeTree` it behaves the same as `mutations_sync = 2`.|
4431 : 113429 : )", 0) \
4432 : 113429 : DECLARE_WITH_ALIAS(Bool, enable_lightweight_delete, true, R"(
4433 : 113429 : Enable lightweight DELETE mutations for mergetree tables.
4434 : 113429 : )", 0, allow_experimental_lightweight_delete) \
4435 : 113429 : DECLARE(LightweightDeleteMode, lightweight_delete_mode, LightweightDeleteMode::ALTER_UPDATE, R"(
4436 : 113429 : A mode of internal update query that is executed as a part of lightweight delete.
4437 : 113429 :
4438 : 113429 : Possible values:
4439 : 113429 : - `alter_update` - run `ALTER UPDATE` query that creates a heavyweight mutation.
4440 : 113429 : - `lightweight_update` - run lightweight update if possible, run `ALTER UPDATE` otherwise.
4441 : 113429 : - `lightweight_update_force` - run lightweight update if possible, throw otherwise.
4442 : 113429 : )", 0) \
4443 : 113429 : DECLARE(UInt64, lightweight_deletes_sync, 2, R"(
4444 : 113429 : The same as [`mutations_sync`](#mutations_sync), but controls only execution of lightweight deletes.
4445 : 113429 :
4446 : 113429 : Possible values:
4447 : 113429 :
4448 : 113429 : | Value | Description |
4449 : 113429 : |-------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
4450 : 113429 : | `0` | Mutations execute asynchronously. |
4451 : 113429 : | `1` | The query waits for the lightweight deletes to complete on the current server. |
4452 : 113429 : | `2` | The query waits for the lightweight deletes to complete on all replicas (if they exist). |
4453 : 113429 : | `3` | The query waits only for active replicas. Supported only for `SharedMergeTree`. For `ReplicatedMergeTree` it behaves the same as `mutations_sync = 2`.|
4454 : 113429 :
4455 : 113429 : **See Also**
4456 : 113429 :
4457 : 113429 : - [Synchronicity of ALTER Queries](../../sql-reference/statements/alter/index.md/#synchronicity-of-alter-queries)
4458 : 113429 : - [Mutations](../../sql-reference/statements/alter/index.md/#mutations)
4459 : 113429 :
4460 : 113429 : Cloud default value: `1`.
4461 : 113429 : )", 0) \
4462 : 113429 : DECLARE(Bool, apply_deleted_mask, true, R"(
4463 : 113429 : 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
4464 : 113429 : )", 0) \
4465 : 113429 : DECLARE(Bool, optimize_normalize_count_variants, true, R"(
4466 : 113429 : Rewrite aggregate functions that semantically equals to count() as count().
4467 : 113429 : )", 0) \
4468 : 113429 : DECLARE(Bool, optimize_injective_functions_inside_uniq, true, R"(
4469 : 113429 : Delete injective functions of one argument inside uniq*() functions.
4470 : 113429 : )", 0) \
4471 : 113429 : DECLARE(Bool, count_matches_stop_at_empty_match, false, R"(
4472 : 113429 : Stop counting once a pattern matches zero-length in the `countMatches` function.
4473 : 113429 : )", 0) \
4474 : 113429 : DECLARE(Bool, rewrite_count_distinct_if_with_count_distinct_implementation, false, R"(
4475 : 113429 : Allows you to rewrite `countDistcintIf` with [count_distinct_implementation](#count_distinct_implementation) setting.
4476 : 113429 :
4477 : 113429 : Possible values:
4478 : 113429 :
4479 : 113429 : - true — Allow.
4480 : 113429 : - false — Disallow.
4481 : 113429 : )", 0) \
4482 : 113429 : DECLARE(Bool, convert_query_to_cnf, false, R"(
4483 : 113429 : 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](https://github.com/ClickHouse/ClickHouse/issues/11749) for an explanation).
4484 : 113429 :
4485 : 113429 : For example, notice how the following `SELECT` query is not modified (the default behavior):
4486 : 113429 :
4487 : 113429 : ```sql
4488 : 113429 : EXPLAIN SYNTAX
4489 : 113429 : SELECT *
4490 : 113429 : FROM
4491 : 113429 : (
4492 : 113429 : SELECT number AS x
4493 : 113429 : FROM numbers(20)
4494 : 113429 : ) AS a
4495 : 113429 : WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))
4496 : 113429 : SETTINGS convert_query_to_cnf = false;
4497 : 113429 : ```
4498 : 113429 :
4499 : 113429 : The result is:
4500 : 113429 :
4501 : 113429 : ```response
4502 : 113429 : ┌─explain────────────────────────────────────────────────────────┐
4503 : 113429 : │ SELECT x │
4504 : 113429 : │ FROM │
4505 : 113429 : │ ( │
4506 : 113429 : │ SELECT number AS x │
4507 : 113429 : │ FROM numbers(20) │
4508 : 113429 : │ WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15)) │
4509 : 113429 : │ ) AS a │
4510 : 113429 : │ WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15)) │
4511 : 113429 : │ SETTINGS convert_query_to_cnf = 0 │
4512 : 113429 : └────────────────────────────────────────────────────────────────┘
4513 : 113429 : ```
4514 : 113429 :
4515 : 113429 : Let's set `convert_query_to_cnf` to `true` and see what changes:
4516 : 113429 :
4517 : 113429 : ```sql
4518 : 113429 : EXPLAIN SYNTAX
4519 : 113429 : SELECT *
4520 : 113429 : FROM
4521 : 113429 : (
4522 : 113429 : SELECT number AS x
4523 : 113429 : FROM numbers(20)
4524 : 113429 : ) AS a
4525 : 113429 : WHERE ((x >= 1) AND (x <= 5)) OR ((x >= 10) AND (x <= 15))
4526 : 113429 : SETTINGS convert_query_to_cnf = true;
4527 : 113429 : ```
4528 : 113429 :
4529 : 113429 : Notice the `WHERE` clause is rewritten in CNF, but the result set is the identical - the Boolean logic is unchanged:
4530 : 113429 :
4531 : 113429 : ```response
4532 : 113429 : ┌─explain───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
4533 : 113429 : │ SELECT x │
4534 : 113429 : │ FROM │
4535 : 113429 : │ ( │
4536 : 113429 : │ SELECT number AS x │
4537 : 113429 : │ FROM numbers(20) │
4538 : 113429 : │ WHERE ((x <= 15) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x >= 10) OR (x >= 1)) │
4539 : 113429 : │ ) AS a │
4540 : 113429 : │ WHERE ((x >= 10) OR (x >= 1)) AND ((x >= 10) OR (x <= 5)) AND ((x <= 15) OR (x >= 1)) AND ((x <= 15) OR (x <= 5)) │
4541 : 113429 : │ SETTINGS convert_query_to_cnf = 1 │
4542 : 113429 : └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
4543 : 113429 : ```
4544 : 113429 :
4545 : 113429 : Possible values: true, false
4546 : 113429 : )", 0) \
4547 : 113429 : DECLARE(Bool, optimize_or_like_chain, false, R"(
4548 : 113429 : Optimize multiple OR LIKE into multiMatchAny. This optimization should not be enabled by default, because it defies index analysis in some cases.
4549 : 113429 : )", 0) \
4550 : 113429 : DECLARE(Bool, optimize_arithmetic_operations_in_aggregate_functions, true, R"(
4551 : 113429 : Move arithmetic operations out of aggregation functions
4552 : 113429 : )", 0) \
4553 : 113429 : DECLARE(Bool, optimize_redundant_functions_in_order_by, true, R"(
4554 : 113429 : Remove functions from ORDER BY if its argument is also in ORDER BY
4555 : 113429 : )", 0) \
4556 : 113429 : DECLARE(Bool, optimize_truncate_order_by_after_group_by_keys, true, R"(
4557 : 113429 : Remove trailing ORDER BY elements once all GROUP BY keys are covered in the ORDER BY prefix.
4558 : 113429 : )", 0) \
4559 : 113429 : DECLARE(Bool, optimize_if_chain_to_multiif, false, R"(
4560 : 113429 : Replace if(cond1, then1, if(cond2, ...)) chains to multiIf. Currently it's not beneficial for numeric types.
4561 : 113429 : )", 0) \
4562 : 113429 : DECLARE(Bool, optimize_multiif_to_if, true, R"(
4563 : 113429 : Replace 'multiIf' with only one condition to 'if'.
4564 : 113429 : )", 0) \
4565 : 113429 : DECLARE(Bool, optimize_if_transform_strings_to_enum, false, R"(
4566 : 113429 : Replaces string-type arguments in If and Transform to enum. Disabled by default cause it could make inconsistent change in distributed query that would lead to its fail.
4567 : 113429 : )", 0) \
4568 : 113429 : DECLARE(Bool, optimize_functions_to_subcolumns, true, R"(
4569 : 113429 : Enables or disables optimization by transforming some functions to reading subcolumns. This reduces the amount of data to read.
4570 : 113429 :
4571 : 113429 : These functions can be transformed:
4572 : 113429 :
4573 : 113429 : - [length](/sql-reference/functions/array-functions#length) to read the [size0](../../sql-reference/data-types/array.md/#array-size) subcolumn.
4574 : 113429 : - [empty](/sql-reference/functions/array-functions#empty) to read the [size0](../../sql-reference/data-types/array.md/#array-size) subcolumn.
4575 : 113429 : - [notEmpty](/sql-reference/functions/array-functions#notEmpty) to read the [size0](../../sql-reference/data-types/array.md/#array-size) subcolumn.
4576 : 113429 : - [isNull](/sql-reference/functions/functions-for-nulls#isNull) to read the [null](../../sql-reference/data-types/nullable.md/#finding-null) subcolumn.
4577 : 113429 : - [isNotNull](/sql-reference/functions/functions-for-nulls#isNotNull) to read the [null](../../sql-reference/data-types/nullable.md/#finding-null) subcolumn.
4578 : 113429 : - [count](/sql-reference/aggregate-functions/reference/count) to read the [null](../../sql-reference/data-types/nullable.md/#finding-null) subcolumn.
4579 : 113429 : - [mapKeys](/sql-reference/functions/tuple-map-functions#mapKeys) to read the [keys](/sql-reference/data-types/map#reading-subcolumns-of-map) subcolumn.
4580 : 113429 : - [mapValues](/sql-reference/functions/tuple-map-functions#mapValues) to read the [values](/sql-reference/data-types/map#reading-subcolumns-of-map) subcolumn.
4581 : 113429 :
4582 : 113429 : Possible values:
4583 : 113429 :
4584 : 113429 : - 0 — Optimization disabled.
4585 : 113429 : - 1 — Optimization enabled.
4586 : 113429 : )", 0) \
4587 : 113429 : DECLARE(Bool, optimize_using_constraints, false, R"(
4588 : 113429 : Use [constraints](../../sql-reference/statements/create/table.md/#constraints) for query optimization. The default is `false`.
4589 : 113429 :
4590 : 113429 : Possible values:
4591 : 113429 :
4592 : 113429 : - true, false
4593 : 113429 : )", 0) \
4594 : 113429 : DECLARE(Bool, optimize_substitute_columns, false, R"(
4595 : 113429 : Use [constraints](../../sql-reference/statements/create/table.md/#constraints) for column substitution. The default is `false`.
4596 : 113429 :
4597 : 113429 : Possible values:
4598 : 113429 :
4599 : 113429 : - true, false
4600 : 113429 : )", 0) \
4601 : 113429 : DECLARE(Bool, optimize_append_index, false, R"(
4602 : 113429 : Use [constraints](../../sql-reference/statements/create/table.md/#constraints) in order to append index condition. The default is `false`.
4603 : 113429 :
4604 : 113429 : Possible values:
4605 : 113429 :
4606 : 113429 : - true, false
4607 : 113429 : )", 0) \
4608 : 113429 : DECLARE(Bool, optimize_time_filter_with_preimage, true, R"(
4609 : 113429 : 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'`)
4610 : 113429 : )", 0) \
4611 : 113429 : DECLARE(Bool, normalize_function_names, true, R"(
4612 : 113429 : Normalize function names to their canonical names
4613 : 113429 : )", 0) \
4614 : 113429 : DECLARE(Bool, enable_early_constant_folding, true, R"(
4615 : 113429 : Enable query optimization where we analyze function and subqueries results and rewrite query if there are constants there
4616 : 113429 : )", 0) \
4617 : 113429 : DECLARE(Bool, deduplicate_blocks_in_dependent_materialized_views, true, R"(
4618 : 113429 : Enables or disables the deduplication check for materialized views that receive data from Replicated\* tables.
4619 : 113429 :
4620 : 113429 : Possible values:
4621 : 113429 :
4622 : 113429 : 0 — Disabled.
4623 : 113429 : 1 — Enabled.
4624 : 113429 :
4625 : 113429 : When enabled, ClickHouse performs deduplication of blocks in materialized views that depend on Replicated\* tables.
4626 : 113429 : This setting is useful for ensuring that materialized views do not contain duplicate data when the insertion operation is being retried due to a failure.
4627 : 113429 :
4628 : 113429 : **See Also**
4629 : 113429 :
4630 : 113429 : - [NULL Processing in IN Operators](/guides/developer/deduplicating-inserts-on-retries#insert-deduplication-with-materialized-views)
4631 : 113429 : )", 0) \
4632 : 113429 : DECLARE(Bool, materialized_views_ignore_errors, false, R"(
4633 : 113429 : Allows to ignore errors for MATERIALIZED VIEW, and deliver original block to the table regardless of MVs
4634 : 113429 : )", 0) \
4635 : 113429 : DECLARE(Bool, ignore_materialized_views_with_dropped_target_table, false, R"(
4636 : 113429 : Ignore MVs with dropped target table during pushing to views
4637 : 113429 : )", 0) \
4638 : 113429 : DECLARE(Bool, allow_materialized_view_with_bad_select, false, R"(
4639 : 113429 : 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.
4640 : 113429 : )", 0) \
4641 : 113429 : DECLARE(Bool, materialized_views_squash_parallel_inserts, true, R"(Squash inserts to materialized views destination table of a single INSERT query from parallel inserts to reduce amount of generated parts.
4642 : 113429 : If set to false and `parallel_view_processing` is enabled, INSERT query will generate part in the destination table for each `max_insert_thread`.
4643 : 113429 : )", 0) \
4644 : 113429 : DECLARE(Bool, use_compact_format_in_distributed_parts_names, true, R"(
4645 : 113429 : Uses compact format for storing blocks for background (`distributed_foreground_insert`) INSERT into tables with `Distributed` engine.
4646 : 113429 :
4647 : 113429 : Possible values:
4648 : 113429 :
4649 : 113429 : - 0 — Uses `user[:password]@host:port#default_database` directory format.
4650 : 113429 : - 1 — Uses `[shard{shard_index}[_replica{replica_index}]]` directory format.
4651 : 113429 :
4652 : 113429 : :::note
4653 : 113429 : - with `use_compact_format_in_distributed_parts_names=0` changes from cluster definition will not be applied for background INSERT.
4654 : 113429 : - 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.
4655 : 113429 : :::
4656 : 113429 : )", 0) \
4657 : 113429 : DECLARE(Bool, validate_polygons, true, R"(
4658 : 113429 : Enables or disables throwing an exception in the [pointInPolygon](/sql-reference/functions/geo/coordinates#pointinpolygon) function, if the polygon is self-intersecting or self-tangent.
4659 : 113429 :
4660 : 113429 : Possible values:
4661 : 113429 :
4662 : 113429 : - 0 — Throwing an exception is disabled. `pointInPolygon` accepts invalid polygons and returns possibly incorrect results for them.
4663 : 113429 : - 1 — Throwing an exception is enabled.
4664 : 113429 : )", 0) \
4665 : 113429 : DECLARE(UInt64, max_parser_depth, DBMS_DEFAULT_MAX_PARSER_DEPTH, R"(
4666 : 113429 : Limits maximum recursion depth in the recursive descent parser. Allows controlling the stack size.
4667 : 113429 :
4668 : 113429 : Possible values:
4669 : 113429 :
4670 : 113429 : - Positive integer.
4671 : 113429 : - 0 — Recursion depth is unlimited.
4672 : 113429 : )", 0) \
4673 : 113429 : DECLARE(UInt64, max_parser_backtracks, DBMS_DEFAULT_MAX_PARSER_BACKTRACKS, R"(
4674 : 113429 : Maximum parser backtracking (how many times it tries different alternatives in the recursive descend parsing process).
4675 : 113429 : )", 0) \
4676 : 113429 : DECLARE(UInt64, max_recursive_cte_evaluation_depth, DBMS_RECURSIVE_CTE_MAX_EVALUATION_DEPTH, R"(
4677 : 113429 : Maximum limit on recursive CTE evaluation depth
4678 : 113429 : )", 0) \
4679 : 113429 : DECLARE(Bool, allow_settings_after_format_in_insert, false, R"(
4680 : 113429 : 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.
4681 : 113429 :
4682 : 113429 : Example:
4683 : 113429 :
4684 : 113429 : ```sql
4685 : 113429 : INSERT INTO FUNCTION null('foo String') SETTINGS max_threads=1 VALUES ('bar');
4686 : 113429 : ```
4687 : 113429 :
4688 : 113429 : But the following query will work only with `allow_settings_after_format_in_insert`:
4689 : 113429 :
4690 : 113429 : ```sql
4691 : 113429 : SET allow_settings_after_format_in_insert=1;
4692 : 113429 : INSERT INTO FUNCTION null('foo String') VALUES ('bar') SETTINGS max_threads=1;
4693 : 113429 : ```
4694 : 113429 :
4695 : 113429 : Possible values:
4696 : 113429 :
4697 : 113429 : - 0 — Disallow.
4698 : 113429 : - 1 — Allow.
4699 : 113429 :
4700 : 113429 : :::note
4701 : 113429 : Use this setting only for backward compatibility if your use cases depend on old syntax.
4702 : 113429 : :::
4703 : 113429 : )", 0) \
4704 : 113429 : DECLARE(Bool, transform_null_in, false, R"(
4705 : 113429 : Enables equality of [NULL](/sql-reference/syntax#null) values for [IN](../../sql-reference/operators/in.md) operator.
4706 : 113429 :
4707 : 113429 : 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.
4708 : 113429 :
4709 : 113429 : Possible values:
4710 : 113429 :
4711 : 113429 : - 0 — Comparison of `NULL` values in `IN` operator returns `false`.
4712 : 113429 : - 1 — Comparison of `NULL` values in `IN` operator returns `true`.
4713 : 113429 :
4714 : 113429 : **Example**
4715 : 113429 :
4716 : 113429 : Consider the `null_in` table:
4717 : 113429 :
4718 : 113429 : ```text
4719 : 113429 : ┌──idx─┬─────i─┐
4720 : 113429 : │ 1 │ 1 │
4721 : 113429 : │ 2 │ NULL │
4722 : 113429 : │ 3 │ 3 │
4723 : 113429 : └──────┴───────┘
4724 : 113429 : ```
4725 : 113429 :
4726 : 113429 : Query:
4727 : 113429 :
4728 : 113429 : ```sql
4729 : 113429 : SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 0;
4730 : 113429 : ```
4731 : 113429 :
4732 : 113429 : Result:
4733 : 113429 :
4734 : 113429 : ```text
4735 : 113429 : ┌──idx─┬────i─┐
4736 : 113429 : │ 1 │ 1 │
4737 : 113429 : └──────┴──────┘
4738 : 113429 : ```
4739 : 113429 :
4740 : 113429 : Query:
4741 : 113429 :
4742 : 113429 : ```sql
4743 : 113429 : SELECT idx, i FROM null_in WHERE i IN (1, NULL) SETTINGS transform_null_in = 1;
4744 : 113429 : ```
4745 : 113429 :
4746 : 113429 : Result:
4747 : 113429 :
4748 : 113429 : ```text
4749 : 113429 : ┌──idx─┬─────i─┐
4750 : 113429 : │ 1 │ 1 │
4751 : 113429 : │ 2 │ NULL │
4752 : 113429 : └──────┴───────┘
4753 : 113429 : ```
4754 : 113429 :
4755 : 113429 : **See Also**
4756 : 113429 :
4757 : 113429 : - [NULL Processing in IN Operators](/sql-reference/operators/in#null-processing)
4758 : 113429 : )", 0) \
4759 : 113429 : DECLARE(Bool, allow_nondeterministic_mutations, false, R"(
4760 : 113429 : User-level setting that allows mutations on replicated tables to make use of non-deterministic functions such as `dictGet`.
4761 : 113429 :
4762 : 113429 : 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.
4763 : 113429 :
4764 : 113429 : **Example**
4765 : 113429 :
4766 : 113429 : ```xml
4767 : 113429 : <profiles>
4768 : 113429 : <default>
4769 : 113429 : <allow_nondeterministic_mutations>1</allow_nondeterministic_mutations>
4770 : 113429 :
4771 : 113429 : <!-- ... -->
4772 : 113429 : </default>
4773 : 113429 :
4774 : 113429 : <!-- ... -->
4775 : 113429 :
4776 : 113429 : </profiles>
4777 : 113429 : ```
4778 : 113429 : )", 0) \
4779 : 113429 : DECLARE(Bool, validate_mutation_query, true, R"(
4780 : 113429 : Validate mutation queries before accepting them. Mutations are executed in the background, and running an invalid query will cause mutations to get stuck, requiring manual intervention.
4781 : 113429 :
4782 : 113429 : Only change this setting if you encounter a backward-incompatible bug.
4783 : 113429 : )", 0) \
4784 : 113429 : DECLARE(Seconds, lock_acquire_timeout, DBMS_DEFAULT_LOCK_ACQUIRE_TIMEOUT_SEC, R"(
4785 : 113429 : Defines how many seconds a locking request waits before failing.
4786 : 113429 :
4787 : 113429 : 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`.
4788 : 113429 :
4789 : 113429 : Possible values:
4790 : 113429 :
4791 : 113429 : - Positive integer (in seconds).
4792 : 113429 : - 0 — No locking timeout.
4793 : 113429 : )", 0) \
4794 : 113429 : DECLARE(Bool, materialize_ttl_after_modify, true, R"(
4795 : 113429 : Apply TTL for old data, after ALTER MODIFY TTL query
4796 : 113429 : )", 0) \
4797 : 113429 : DECLARE(String, function_implementation, "", R"(
4798 : 113429 : Choose function implementation for specific target or variant (experimental). If empty enable all of them.
4799 : 113429 : )", 0) \
4800 : 113429 : DECLARE(Bool, data_type_default_nullable, false, R"(
4801 : 113429 : Allows data types without explicit modifiers [NULL or NOT NULL](/sql-reference/statements/create/table#null-or-not-null-modifiers) in column definition will be [Nullable](/sql-reference/data-types/nullable).
4802 : 113429 :
4803 : 113429 : Possible values:
4804 : 113429 :
4805 : 113429 : - 1 — The data types in column definitions are set to `Nullable` by default.
4806 : 113429 : - 0 — The data types in column definitions are set to not `Nullable` by default.
4807 : 113429 : )", 0) \
4808 : 113429 : DECLARE(Bool, cast_keep_nullable, false, R"(
4809 : 113429 : Enables or disables keeping of the `Nullable` data type in [CAST](/sql-reference/functions/type-conversion-functions#CAST) operations.
4810 : 113429 :
4811 : 113429 : 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.
4812 : 113429 :
4813 : 113429 : Possible values:
4814 : 113429 :
4815 : 113429 : - 0 — The `CAST` result has exactly the destination type specified.
4816 : 113429 : - 1 — If the argument type is `Nullable`, the `CAST` result is transformed to `Nullable(DestinationDataType)`.
4817 : 113429 :
4818 : 113429 : **Examples**
4819 : 113429 :
4820 : 113429 : The following query results in the destination data type exactly:
4821 : 113429 :
4822 : 113429 : ```sql
4823 : 113429 : SET cast_keep_nullable = 0;
4824 : 113429 : SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x);
4825 : 113429 : ```
4826 : 113429 :
4827 : 113429 : Result:
4828 : 113429 :
4829 : 113429 : ```text
4830 : 113429 : ┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐
4831 : 113429 : │ 0 │ Int32 │
4832 : 113429 : └───┴───────────────────────────────────────────────────┘
4833 : 113429 : ```
4834 : 113429 :
4835 : 113429 : The following query results in the `Nullable` modification on the destination data type:
4836 : 113429 :
4837 : 113429 : ```sql
4838 : 113429 : SET cast_keep_nullable = 1;
4839 : 113429 : SELECT CAST(toNullable(toInt32(0)) AS Int32) as x, toTypeName(x);
4840 : 113429 : ```
4841 : 113429 :
4842 : 113429 : Result:
4843 : 113429 :
4844 : 113429 : ```text
4845 : 113429 : ┌─x─┬─toTypeName(CAST(toNullable(toInt32(0)), 'Int32'))─┐
4846 : 113429 : │ 0 │ Nullable(Int32) │
4847 : 113429 : └───┴───────────────────────────────────────────────────┘
4848 : 113429 : ```
4849 : 113429 :
4850 : 113429 : **See Also**
4851 : 113429 :
4852 : 113429 : - [CAST](/sql-reference/functions/type-conversion-functions#CAST) function
4853 : 113429 : )", 0) \
4854 : 113429 : DECLARE(Bool, cast_ipv4_ipv6_default_on_conversion_error, false, R"(
4855 : 113429 : CAST operator into IPv4, CAST operator into IPV6 type, toIPv4, toIPv6 functions will return default value instead of throwing exception on conversion error.
4856 : 113429 : )", 0) \
4857 : 113429 : DECLARE(Bool, alter_partition_verbose_result, false, R"(
4858 : 113429 : Enables or disables the display of information about the parts to which the manipulation operations with partitions and parts have been successfully applied.
4859 : 113429 : Applicable to [ATTACH PARTITION|PART](/sql-reference/statements/alter/partition#attach-partitionpart) and to [FREEZE PARTITION](/sql-reference/statements/alter/partition#freeze-partition).
4860 : 113429 :
4861 : 113429 : Possible values:
4862 : 113429 :
4863 : 113429 : - 0 — disable verbosity.
4864 : 113429 : - 1 — enable verbosity.
4865 : 113429 :
4866 : 113429 : **Example**
4867 : 113429 :
4868 : 113429 : ```sql
4869 : 113429 : CREATE TABLE test(a Int64, d Date, s String) ENGINE = MergeTree PARTITION BY toYYYYMDECLARE(d) ORDER BY a;
4870 : 113429 : INSERT INTO test VALUES(1, '2021-01-01', '');
4871 : 113429 : INSERT INTO test VALUES(1, '2021-01-01', '');
4872 : 113429 : ALTER TABLE test DETACH PARTITION ID '202101';
4873 : 113429 :
4874 : 113429 : ALTER TABLE test ATTACH PARTITION ID '202101' SETTINGS alter_partition_verbose_result = 1;
4875 : 113429 :
4876 : 113429 : ┌─command_type─────┬─partition_id─┬─part_name────┬─old_part_name─┐
4877 : 113429 : │ ATTACH PARTITION │ 202101 │ 202101_7_7_0 │ 202101_5_5_0 │
4878 : 113429 : │ ATTACH PARTITION │ 202101 │ 202101_8_8_0 │ 202101_6_6_0 │
4879 : 113429 : └──────────────────┴──────────────┴──────────────┴───────────────┘
4880 : 113429 :
4881 : 113429 : ALTER TABLE test FREEZE SETTINGS alter_partition_verbose_result = 1;
4882 : 113429 :
4883 : 113429 : ┌─command_type─┬─partition_id─┬─part_name────┬─backup_name─┬─backup_path───────────────────┬─part_backup_path────────────────────────────────────────────┐
4884 : 113429 : │ 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 │
4885 : 113429 : │ 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 │
4886 : 113429 : └──────────────┴──────────────┴──────────────┴─────────────┴───────────────────────────────┴─────────────────────────────────────────────────────────────┘
4887 : 113429 : ```
4888 : 113429 : )", 0) \
4889 : 113429 : DECLARE(Bool, system_events_show_zero_values, false, R"(
4890 : 113429 : Allows to select zero-valued events from [`system.events`](../../operations/system-tables/events.md).
4891 : 113429 :
4892 : 113429 : Some monitoring systems require passing all the metrics values to them for each checkpoint, even if the metric value is zero.
4893 : 113429 :
4894 : 113429 : Possible values:
4895 : 113429 :
4896 : 113429 : - 0 — Disabled.
4897 : 113429 : - 1 — Enabled.
4898 : 113429 :
4899 : 113429 : **Examples**
4900 : 113429 :
4901 : 113429 : Query
4902 : 113429 :
4903 : 113429 : ```sql
4904 : 113429 : SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded';
4905 : 113429 : ```
4906 : 113429 :
4907 : 113429 : Result
4908 : 113429 :
4909 : 113429 : ```text
4910 : 113429 : Ok.
4911 : 113429 : ```
4912 : 113429 :
4913 : 113429 : Query
4914 : 113429 : ```sql
4915 : 113429 : SET system_events_show_zero_values = 1;
4916 : 113429 : SELECT * FROM system.events WHERE event='QueryMemoryLimitExceeded';
4917 : 113429 : ```
4918 : 113429 :
4919 : 113429 : Result
4920 : 113429 :
4921 : 113429 : ```text
4922 : 113429 : ┌─event────────────────────┬─value─┬─description───────────────────────────────────────────┐
4923 : 113429 : │ QueryMemoryLimitExceeded │ 0 │ Number of times when memory limit exceeded for query. │
4924 : 113429 : └──────────────────────────┴───────┴───────────────────────────────────────────────────────┘
4925 : 113429 : ```
4926 : 113429 : )", 0) \
4927 : 113429 : DECLARE(MySQLDataTypesSupport, mysql_datatypes_support_level, "decimal,datetime64,date2Date32", R"(
4928 : 113429 : Defines how MySQL types are converted to corresponding ClickHouse types. A comma separated list in any combination of `decimal`, `datetime64`, `date2Date32` or `date2String`. All modern mappings (`decimal`, `datetime64`, `date2Date32`) are enabled by default.
4929 : 113429 : - `decimal`: convert `NUMERIC` and `DECIMAL` types to `Decimal` when precision allows it.
4930 : 113429 : - `datetime64`: convert `DATETIME` and `TIMESTAMP` types to `DateTime64` instead of `DateTime` when precision is not `0`.
4931 : 113429 : - `date2Date32`: convert `DATE` to `Date32` instead of `Date`. Takes precedence over `date2String`.
4932 : 113429 : - `date2String`: convert `DATE` to `String` instead of `Date`. Overridden by `datetime64`.
4933 : 113429 : )", 0) \
4934 : 113429 : DECLARE(Bool, optimize_trivial_insert_select, false, R"(
4935 : 113429 : Optimize trivial 'INSERT INTO table SELECT ... FROM TABLES' query
4936 : 113429 : )", 0) \
4937 : 113429 : DECLARE(Bool, allow_non_metadata_alters, true, R"(
4938 : 113429 : Allow to execute alters which affects not only tables metadata, but also data on disk
4939 : 113429 : )", 0) \
4940 : 113429 : DECLARE(Bool, enable_global_with_statement, true, R"(
4941 : 113429 : Propagate WITH statements to UNION queries and all subqueries
4942 : 113429 : )", 0) \
4943 : 113429 : DECLARE(Bool, enable_materialized_cte, false, R"(
4944 : 113429 : Enable materialized common table expressions, it will be preferred over enable_global_with_statement
4945 : 113429 : )", EXPERIMENTAL) \
4946 : 113429 : DECLARE(Bool, analyzer_inline_views, false, R"(
4947 : 113429 : When enabled, the analyzer substitutes ordinary (non-materialized, non-parameterized) views with their defining subqueries, enabling cross-boundary optimizations such as predicate pushdown and column pruning.
4948 : 113429 : )", EXPERIMENTAL) \
4949 : 113429 : DECLARE(Bool, enable_scopes_for_with_statement, true, R"(
4950 : 113429 : If disabled, declarations in parent WITH cluases will behave the same scope as they declared in the current scope.
4951 : 113429 :
4952 : 113429 : Note that this is a compatibility setting for the analyzer to allow running some invalid queries that old analyzer could execute.
4953 : 113429 : )", 0) \
4954 : 113429 : DECLARE(Bool, aggregate_functions_null_for_empty, false, R"(
4955 : 113429 : Enables or disables rewriting all aggregate functions in a query, adding [-OrNull](/sql-reference/aggregate-functions/combinators#-ornull) suffix to them. Enable it for SQL standard compatibility.
4956 : 113429 : It is implemented via query rewrite (similar to [count_distinct_implementation](#count_distinct_implementation) setting) to get consistent results for distributed queries.
4957 : 113429 :
4958 : 113429 : Possible values:
4959 : 113429 :
4960 : 113429 : - 0 — Disabled.
4961 : 113429 : - 1 — Enabled.
4962 : 113429 :
4963 : 113429 : **Example**
4964 : 113429 :
4965 : 113429 : Consider the following query with aggregate functions:
4966 : 113429 : ```sql
4967 : 113429 : SELECT SUM(-1), MAX(0) FROM system.one WHERE 0;
4968 : 113429 : ```
4969 : 113429 :
4970 : 113429 : With `aggregate_functions_null_for_empty = 0` it would produce:
4971 : 113429 : ```text
4972 : 113429 : ┌─SUM(-1)─┬─MAX(0)─┐
4973 : 113429 : │ 0 │ 0 │
4974 : 113429 : └─────────┴────────┘
4975 : 113429 : ```
4976 : 113429 :
4977 : 113429 : With `aggregate_functions_null_for_empty = 1` the result would be:
4978 : 113429 : ```text
4979 : 113429 : ┌─SUMOrNull(-1)─┬─MAXOrNull(0)─┐
4980 : 113429 : │ NULL │ NULL │
4981 : 113429 : └───────────────┴──────────────┘
4982 : 113429 : ```
4983 : 113429 : )", 0) \
4984 : 113429 : DECLARE(AggregateFunctionInputFormat, aggregate_function_input_format, "state", R"(
4985 : 113429 : Format for AggregateFunction input during INSERT operations.
4986 : 113429 :
4987 : 113429 : Possible values:
4988 : 113429 :
4989 : 113429 : - `state` — Binary string with the serialized state (the default). This is the default behavior where AggregateFunction values are expected as binary data.
4990 : 113429 : - `value` — The format expects a single value of the argument of the aggregate function, or in the case of multiple arguments, a tuple of them. They will be deserialized using the corresponding IDataType or DataTypeTuple and then aggregated to form the state.
4991 : 113429 : - `array` — The format expects an Array of values, as described in the `value` option above. All elements of the array will be aggregated to form the state.
4992 : 113429 :
4993 : 113429 : **Examples**
4994 : 113429 :
4995 : 113429 : For a table with structure:
4996 : 113429 : ```sql
4997 : 113429 : CREATE TABLE example (
4998 : 113429 : user_id UInt64,
4999 : 113429 : avg_session_length AggregateFunction(avg, UInt32)
5000 : 113429 : );
5001 : 113429 : ```
5002 : 113429 :
5003 : 113429 :
5004 : 113429 : With `aggregate_function_input_format = 'value'`:
5005 : 113429 : ```sql
5006 : 113429 : INSERT INTO example FORMAT CSV
5007 : 113429 : 123,456
5008 : 113429 : ```
5009 : 113429 :
5010 : 113429 :
5011 : 113429 : With `aggregate_function_input_format = 'array'`:
5012 : 113429 : ```sql
5013 : 113429 : INSERT INTO example FORMAT CSV
5014 : 113429 : 123,"[456,789,101]"
5015 : 113429 : ```
5016 : 113429 :
5017 : 113429 : Note: The `value` and `array` formats are slower than the default `state` format as they require creating and aggregating values during insertion.
5018 : 113429 : )", 0) \
5019 : 113429 : DECLARE(Bool, optimize_syntax_fuse_functions, true, R"(
5020 : 113429 : Enables to fuse aggregate functions with identical argument. It rewrites query contains at least two aggregate functions from [sum](/sql-reference/aggregate-functions/reference/sum), [count](/sql-reference/aggregate-functions/reference/count) or [avg](/sql-reference/aggregate-functions/reference/avg) with identical argument to [sumCount](/sql-reference/aggregate-functions/reference/sumcount).
5021 : 113429 :
5022 : 113429 : Possible values:
5023 : 113429 :
5024 : 113429 : - 0 — Functions with identical argument are not fused.
5025 : 113429 : - 1 — Functions with identical argument are fused.
5026 : 113429 :
5027 : 113429 : **Example**
5028 : 113429 :
5029 : 113429 : Query:
5030 : 113429 :
5031 : 113429 : ```sql
5032 : 113429 : CREATE TABLE fuse_tbl(a Int8, b Int8) Engine = Log;
5033 : 113429 : SET optimize_syntax_fuse_functions = 1;
5034 : 113429 : EXPLAIN SYNTAX run_query_tree_passes = 1 SELECT sum(a), sum(b), count(b), avg(b) from fuse_tbl FORMAT TSV;
5035 : 113429 : ```
5036 : 113429 :
5037 : 113429 : Result:
5038 : 113429 :
5039 : 113429 : ```text
5040 : 113429 : SELECT
5041 : 113429 : sum(__table1.a) AS `sum(a)`,
5042 : 113429 : tupleElement(sumCount(__table1.b), 1) AS `sum(b)`,
5043 : 113429 : tupleElement(sumCount(__table1.b), 2) AS `count(b)`,
5044 : 113429 : divide(tupleElement(sumCount(__table1.b), 1), toFloat64(tupleElement(sumCount(__table1.b), 2))) AS `avg(b)`
5045 : 113429 : FROM default.fuse_tbl AS __table1
5046 : 113429 : ```
5047 : 113429 : )", 0) \
5048 : 113429 : DECLARE(Bool, flatten_nested, true, R"(
5049 : 113429 : Sets the data format of a [nested](../../sql-reference/data-types/nested-data-structures/index.md) columns.
5050 : 113429 :
5051 : 113429 : Possible values:
5052 : 113429 :
5053 : 113429 : - 1 — Nested column is flattened to separate arrays.
5054 : 113429 : - 0 — Nested column stays a single array of tuples.
5055 : 113429 :
5056 : 113429 : **Usage**
5057 : 113429 :
5058 : 113429 : If the setting is set to `0`, it is possible to use an arbitrary level of nesting.
5059 : 113429 :
5060 : 113429 : **Examples**
5061 : 113429 :
5062 : 113429 : Query:
5063 : 113429 :
5064 : 113429 : ```sql
5065 : 113429 : SET flatten_nested = 1;
5066 : 113429 : CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();
5067 : 113429 :
5068 : 113429 : SHOW CREATE TABLE t_nest;
5069 : 113429 : ```
5070 : 113429 :
5071 : 113429 : Result:
5072 : 113429 :
5073 : 113429 : ```text
5074 : 113429 : ┌─statement───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
5075 : 113429 : │ CREATE TABLE default.t_nest
5076 : 113429 : (
5077 : 113429 : `n.a` Array(UInt32),
5078 : 113429 : `n.b` Array(UInt32)
5079 : 113429 : )
5080 : 113429 : ENGINE = MergeTree
5081 : 113429 : ORDER BY tuple()
5082 : 113429 : SETTINGS index_granularity = 8192 │
5083 : 113429 : └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
5084 : 113429 : ```
5085 : 113429 :
5086 : 113429 : Query:
5087 : 113429 :
5088 : 113429 : ```sql
5089 : 113429 : SET flatten_nested = 0;
5090 : 113429 :
5091 : 113429 : CREATE TABLE t_nest (`n` Nested(a UInt32, b UInt32)) ENGINE = MergeTree ORDER BY tuple();
5092 : 113429 :
5093 : 113429 : SHOW CREATE TABLE t_nest;
5094 : 113429 : ```
5095 : 113429 :
5096 : 113429 : Result:
5097 : 113429 :
5098 : 113429 : ```text
5099 : 113429 : ┌─statement──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
5100 : 113429 : │ CREATE TABLE default.t_nest
5101 : 113429 : (
5102 : 113429 : `n` Nested(a UInt32, b UInt32)
5103 : 113429 : )
5104 : 113429 : ENGINE = MergeTree
5105 : 113429 : ORDER BY tuple()
5106 : 113429 : SETTINGS index_granularity = 8192 │
5107 : 113429 : └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
5108 : 113429 : ```
5109 : 113429 : )", 0) \
5110 : 113429 : DECLARE(Bool, asterisk_include_materialized_columns, false, R"(
5111 : 113429 : Include [MATERIALIZED](/sql-reference/statements/create/view#materialized-view) columns for wildcard query (`SELECT *`).
5112 : 113429 :
5113 : 113429 : Possible values:
5114 : 113429 :
5115 : 113429 : - 0 - disabled
5116 : 113429 : - 1 - enabled
5117 : 113429 : )", 0) \
5118 : 113429 : DECLARE(Bool, asterisk_include_alias_columns, false, R"(
5119 : 113429 : Include [ALIAS](../../sql-reference/statements/create/table.md/#alias) columns for wildcard query (`SELECT *`).
5120 : 113429 :
5121 : 113429 : Possible values:
5122 : 113429 :
5123 : 113429 : - 0 - disabled
5124 : 113429 : - 1 - enabled
5125 : 113429 : )", 0) \
5126 : 113429 : DECLARE(Bool, asterisk_include_virtual_columns, false, R"(
5127 : 113429 : Include virtual columns for wildcard query (`SELECT *`).
5128 : 113429 :
5129 : 113429 : Possible values:
5130 : 113429 :
5131 : 113429 : - 0 - disabled
5132 : 113429 : - 1 - enabled
5133 : 113429 : )", 0) \
5134 : 113429 : DECLARE(Bool, optimize_skip_merged_partitions, false, R"(
5135 : 113429 : Enables or disables optimization for [OPTIMIZE TABLE ... FINAL](../../sql-reference/statements/optimize.md) query if there is only one part with level > 0 and it doesn't have expired TTL.
5136 : 113429 :
5137 : 113429 : - `OPTIMIZE TABLE ... FINAL SETTINGS optimize_skip_merged_partitions=1`
5138 : 113429 :
5139 : 113429 : By default, `OPTIMIZE TABLE ... FINAL` query rewrites the one part even if there is only a single part.
5140 : 113429 :
5141 : 113429 : Possible values:
5142 : 113429 :
5143 : 113429 : - 1 - Enable optimization.
5144 : 113429 : - 0 - Disable optimization.
5145 : 113429 : )", 0) \
5146 : 113429 : DECLARE(Bool, optimize_on_insert, true, R"(
5147 : 113429 : Enables or disables data transformation before the insertion, as if merge was done on this block (according to table engine).
5148 : 113429 :
5149 : 113429 : Possible values:
5150 : 113429 :
5151 : 113429 : - 0 — Disabled.
5152 : 113429 : - 1 — Enabled.
5153 : 113429 :
5154 : 113429 : **Example**
5155 : 113429 :
5156 : 113429 : The difference between enabled and disabled:
5157 : 113429 :
5158 : 113429 : Query:
5159 : 113429 :
5160 : 113429 : ```sql
5161 : 113429 : SET optimize_on_insert = 1;
5162 : 113429 :
5163 : 113429 : CREATE TABLE test1 (`FirstTable` UInt32) ENGINE = ReplacingMergeTree ORDER BY FirstTable;
5164 : 113429 :
5165 : 113429 : INSERT INTO test1 SELECT number % 2 FROM numbers(5);
5166 : 113429 :
5167 : 113429 : SELECT * FROM test1;
5168 : 113429 :
5169 : 113429 : SET optimize_on_insert = 0;
5170 : 113429 :
5171 : 113429 : CREATE TABLE test2 (`SecondTable` UInt32) ENGINE = ReplacingMergeTree ORDER BY SecondTable;
5172 : 113429 :
5173 : 113429 : INSERT INTO test2 SELECT number % 2 FROM numbers(5);
5174 : 113429 :
5175 : 113429 : SELECT * FROM test2;
5176 : 113429 : ```
5177 : 113429 :
5178 : 113429 : Result:
5179 : 113429 :
5180 : 113429 : ```text
5181 : 113429 : ┌─FirstTable─┐
5182 : 113429 : │ 0 │
5183 : 113429 : │ 1 │
5184 : 113429 : └────────────┘
5185 : 113429 :
5186 : 113429 : ┌─SecondTable─┐
5187 : 113429 : │ 0 │
5188 : 113429 : │ 0 │
5189 : 113429 : │ 0 │
5190 : 113429 : │ 1 │
5191 : 113429 : │ 1 │
5192 : 113429 : └─────────────┘
5193 : 113429 : ```
5194 : 113429 :
5195 : 113429 : Note that this setting influences [Materialized view](/sql-reference/statements/create/view#materialized-view) behaviour.
5196 : 113429 : )", 0) \
5197 : 113429 : DECLARE_WITH_ALIAS(Bool, optimize_use_projections, true, R"(
5198 : 113429 : Enables or disables [projection](../../engines/table-engines/mergetree-family/mergetree.md/#projections) optimization when processing `SELECT` queries.
5199 : 113429 :
5200 : 113429 : Possible values:
5201 : 113429 :
5202 : 113429 : - 0 — Projection optimization disabled.
5203 : 113429 : - 1 — Projection optimization enabled.
5204 : 113429 : )", 0, allow_experimental_projection_optimization) \
5205 : 113429 : DECLARE(Bool, optimize_use_implicit_projections, true, R"(
5206 : 113429 : Automatically choose implicit projections to perform SELECT query
5207 : 113429 : )", 0) \
5208 : 113429 : DECLARE(Bool, optimize_use_projection_filtering, true, R"(
5209 : 113429 : Enables using projections to filter part ranges even when projections are not selected to perform SELECT query.
5210 : 113429 : )", 0) \
5211 : 113429 : DECLARE(Bool, force_optimize_projection, false, R"(
5212 : 113429 : Enables or disables the obligatory use of [projections](../../engines/table-engines/mergetree-family/mergetree.md/#projections) in `SELECT` queries, when projection optimization is enabled (see [optimize_use_projections](#optimize_use_projections) setting).
5213 : 113429 :
5214 : 113429 : Possible values:
5215 : 113429 :
5216 : 113429 : - 0 — Projection optimization is not obligatory.
5217 : 113429 : - 1 — Projection optimization is obligatory.
5218 : 113429 : )", 0) \
5219 : 113429 : DECLARE(String, force_optimize_projection_name, "", R"(
5220 : 113429 : If it is set to a non-empty string, check that this projection is used in the query at least once.
5221 : 113429 :
5222 : 113429 : Possible values:
5223 : 113429 :
5224 : 113429 : - string: name of projection that used in a query
5225 : 113429 : )", 0) \
5226 : 113429 : DECLARE(String, preferred_optimize_projection_name, "", R"(
5227 : 113429 : If it is set to a non-empty string, ClickHouse will try to apply specified projection in query.
5228 : 113429 :
5229 : 113429 :
5230 : 113429 : Possible values:
5231 : 113429 :
5232 : 113429 : - string: name of preferred projection
5233 : 113429 : )", 0) \
5234 : 113429 : DECLARE(UInt64, max_projection_rows_to_use_projection_index, 1'000'000, R"(
5235 : 113429 : If the number of rows to read from the projection index is less than or equal to this threshold, ClickHouse will try to apply the projection index during query execution.
5236 : 113429 : )", 0) \
5237 : 113429 : DECLARE(UInt64, min_table_rows_to_use_projection_index, 1'000'000, R"(
5238 : 113429 : If the estimated number of rows to read from the table is greater than or equal to this threshold, ClickHouse will try to use the projection index during query execution.
5239 : 113429 : )", 0) \
5240 : 113429 : DECLARE(Bool, async_socket_for_remote, true, R"(
5241 : 113429 : Enables asynchronous read from socket while executing remote query.
5242 : 113429 :
5243 : 113429 : Enabled by default.
5244 : 113429 : )", 0) \
5245 : 113429 : DECLARE(Bool, async_query_sending_for_remote, true, R"(
5246 : 113429 : Enables asynchronous connection creation and query sending while executing remote query.
5247 : 113429 :
5248 : 113429 : Enabled by default.
5249 : 113429 : )", 0) \
5250 : 113429 : DECLARE(Bool, insert_null_as_default, true, R"(
5251 : 113429 : Enables or disables the insertion of [default values](/sql-reference/statements/create/table#default_values) instead of [NULL](/sql-reference/syntax#null) into columns with not [nullable](/sql-reference/data-types/nullable) data type.
5252 : 113429 : 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.
5253 : 113429 :
5254 : 113429 : This setting is applicable to [INSERT ... SELECT](../../sql-reference/statements/insert-into.md/#inserting-the-results-of-select) queries. Note that `SELECT` subqueries may be concatenated with `UNION ALL` clause.
5255 : 113429 :
5256 : 113429 : Possible values:
5257 : 113429 :
5258 : 113429 : - 0 — Inserting `NULL` into a not nullable column causes an exception.
5259 : 113429 : - 1 — Default column value is inserted instead of `NULL`.
5260 : 113429 : )", 0) \
5261 : 113429 : DECLARE(Bool, describe_include_subcolumns, false, R"(
5262 : 113429 : Enables describing subcolumns for a [DESCRIBE](../../sql-reference/statements/describe-table.md) query. For example, members of a [Tuple](../../sql-reference/data-types/tuple.md) or subcolumns of a [Map](/sql-reference/data-types/map#reading-subcolumns-of-map), [Nullable](../../sql-reference/data-types/nullable.md/#finding-null) or an [Array](../../sql-reference/data-types/array.md/#array-size) data type.
5263 : 113429 :
5264 : 113429 : Possible values:
5265 : 113429 :
5266 : 113429 : - 0 — Subcolumns are not included in `DESCRIBE` queries.
5267 : 113429 : - 1 — Subcolumns are included in `DESCRIBE` queries.
5268 : 113429 :
5269 : 113429 : **Example**
5270 : 113429 :
5271 : 113429 : See an example for the [DESCRIBE](../../sql-reference/statements/describe-table.md) statement.
5272 : 113429 : )", 0) \
5273 : 113429 : DECLARE(Bool, describe_include_virtual_columns, false, R"(
5274 : 113429 : If true, virtual columns of table will be included into result of DESCRIBE query
5275 : 113429 : )", 0) \
5276 : 113429 : DECLARE(Bool, describe_compact_output, false, R"(
5277 : 113429 : If true, include only column names and types into result of DESCRIBE query
5278 : 113429 : )", 0) \
5279 : 113429 : DECLARE(Bool, apply_mutations_on_fly, false, R"(
5280 : 113429 : If true, mutations (UPDATEs and DELETEs) which are not materialized in data part will be applied on SELECTs.
5281 : 113429 : )", 0) \
5282 : 113429 : DECLARE_WITH_ALIAS(Bool, enable_lightweight_update, true, R"(
5283 : 113429 : Allow to use lightweight updates.
5284 : 113429 : )", BETA, allow_experimental_lightweight_update) \
5285 : 113429 : DECLARE(Bool, apply_patch_parts, true, R"(
5286 : 113429 : If true, patch parts (that represent lightweight updates) are applied on SELECTs.
5287 : 113429 : )", 0) \
5288 : 113429 : DECLARE(NonZeroUInt64, apply_patch_parts_join_cache_buckets, 8, R"(
5289 : 113429 : The number of buckets in the temporary cache for applying patch parts in Join mode.
5290 : 113429 : )", 0) \
5291 : 113429 : DECLARE(AlterUpdateMode, alter_update_mode, AlterUpdateMode::HEAVY, R"(
5292 : 113429 : A mode for `ALTER` queries that have the `UPDATE` commands.
5293 : 113429 :
5294 : 113429 : Possible values:
5295 : 113429 : - `heavy` - run regular mutation.
5296 : 113429 : - `lightweight` - run lightweight update if possible, run regular mutation otherwise.
5297 : 113429 : - `lightweight_force` - run lightweight update if possible, throw otherwise.
5298 : 113429 : )", 0) \
5299 : 113429 : DECLARE(Bool, mutations_execute_nondeterministic_on_initiator, false, R"(
5300 : 113429 : If true constant nondeterministic functions (e.g. function `now()`) are executed on initiator and replaced to literals in `UPDATE` and `DELETE` queries. It helps to keep data in sync on replicas while executing mutations with constant nondeterministic functions. Default value: `false`.
5301 : 113429 : )", 0) \
5302 : 113429 : DECLARE(Bool, mutations_execute_subqueries_on_initiator, false, R"(
5303 : 113429 : If true scalar subqueries are executed on initiator and replaced to literals in `UPDATE` and `DELETE` queries. Default value: `false`.
5304 : 113429 : )", 0) \
5305 : 113429 : DECLARE(UInt64, mutations_max_literal_size_to_replace, 16384, R"(
5306 : 113429 : The maximum size of serialized literal in bytes to replace in `UPDATE` and `DELETE` queries. Takes effect only if at least one the two settings above is enabled. Default value: 16384 (16 KiB).
5307 : 113429 : )", 0) \
5308 : 113429 : \
5309 : 113429 : DECLARE(Float, create_replicated_merge_tree_fault_injection_probability, 0.0f, R"(
5310 : 113429 : The probability of a fault injection during table creation after creating metadata in ZooKeeper
5311 : 113429 : )", 0) \
5312 : 113429 : DECLARE(Bool, delta_lake_log_metadata, false, R"(
5313 : 113429 : Enables logging delta lake metadata files into system table.
5314 : 113429 : )", 0) \
5315 : 113429 : DECLARE(Bool, delta_lake_reload_schema_for_consistency, false, R"(
5316 : 113429 : If enabled, schema is reloaded from the DeltaLake metadata before each query execution to ensure
5317 : 113429 : consistency between the schema used during query analysis and the schema used during execution.
5318 : 113429 : )", 0) \
5319 : 113429 : DECLARE(IcebergMetadataLogLevel, iceberg_metadata_log_level, IcebergMetadataLogLevel::None, R"(
5320 : 113429 : Controls the level of metadata logging for Iceberg tables to system.iceberg_metadata_log.
5321 : 113429 : Usually this setting can be modified for debugging purposes.
5322 : 113429 :
5323 : 113429 : Possible values:
5324 : 113429 : - none - No metadata log.
5325 : 113429 : - metadata - Root metadata.json file.
5326 : 113429 : - manifest_list_metadata - Everything above + metadata from avro manifest list which corresponds to a snapshot.
5327 : 113429 : - manifest_list_entry - Everything above + avro manifest list entries.
5328 : 113429 : - manifest_file_metadata - Everything above + metadata from traversed avro manifest files.
5329 : 113429 : - manifest_file_entry - Everything above + traversed avro manifest files entries.
5330 : 113429 : )", 0) \
5331 : 113429 : \
5332 : 113429 : DECLARE(Bool, iceberg_delete_data_on_drop, false, R"(
5333 : 113429 : Whether to delete all iceberg files on drop or not.
5334 : 113429 : )", 0) \
5335 : 113429 : DECLARE(Int64, iceberg_expire_default_min_snapshots_to_keep, 1, R"(
5336 : 113429 : Default value for Iceberg table property `history.expire.min-snapshots-to-keep` used by `expire_snapshots` when that property is absent.
5337 : 113429 : )", 0) \
5338 : 113429 : DECLARE(Int64, iceberg_expire_default_max_snapshot_age_ms, 432000000, R"(
5339 : 113429 : Default value for Iceberg table property `history.expire.max-snapshot-age-ms` used by `expire_snapshots` when that property is absent.
5340 : 113429 : )", 0) \
5341 : 113429 : DECLARE(Int64, iceberg_expire_default_max_ref_age_ms, std::numeric_limits<Int64>::max(), R"(
5342 : 113429 : Default value for Iceberg table property `history.expire.max-ref-age-ms` used by `expire_snapshots` when that property is absent.
5343 : 113429 : )", 0) \
5344 : 113429 : DECLARE(Bool, use_iceberg_metadata_files_cache, true, R"(
5345 : 113429 : If turned on, iceberg table function and iceberg storage may utilize the iceberg metadata files cache.
5346 : 113429 :
5347 : 113429 : Possible values:
5348 : 113429 :
5349 : 113429 : - 0 - Disabled
5350 : 113429 : - 1 - Enabled
5351 : 113429 : )", 0) \
5352 : 113429 : DECLARE(UInt64, iceberg_metadata_staleness_ms, 0, R"(
5353 : 113429 : If non-zero, skip fetching iceberg metadata from remote catalog if there is a cached metadata snapshot, more recent than the given staleness window. Zero means to always fetch the latest metadata version from the remote catalog. Setting this a non-zero trades staleness to a lower latency of read operations.
5354 : 113429 : )", 0) \
5355 : 113429 : DECLARE(Bool, use_parquet_metadata_cache, true, R"(
5356 : 113429 : If turned on, parquet format may utilize the parquet metadata cache.
5357 : 113429 :
5358 : 113429 : Possible values:
5359 : 113429 :
5360 : 113429 : - 0 - Disabled
5361 : 113429 : - 1 - Enabled
5362 : 113429 : )", 0) \
5363 : 113429 : DECLARE(Bool, use_query_cache, false, R"(
5364 : 113429 : If turned on, `SELECT` queries may utilize the [query cache](../query-cache.md). Parameters [enable_reads_from_query_cache](#enable_reads_from_query_cache)
5365 : 113429 : and [enable_writes_to_query_cache](#enable_writes_to_query_cache) control in more detail how the cache is used.
5366 : 113429 :
5367 : 113429 : Possible values:
5368 : 113429 :
5369 : 113429 : - 0 - Disabled
5370 : 113429 : - 1 - Enabled
5371 : 113429 : )", 0) \
5372 : 113429 : DECLARE(Bool, enable_writes_to_query_cache, true, R"(
5373 : 113429 : If turned on, results of `SELECT` queries are stored in the [query cache](../query-cache.md).
5374 : 113429 :
5375 : 113429 : Possible values:
5376 : 113429 :
5377 : 113429 : - 0 - Disabled
5378 : 113429 : - 1 - Enabled
5379 : 113429 : )", 0) \
5380 : 113429 : DECLARE(Bool, enable_reads_from_query_cache, true, R"(
5381 : 113429 : If turned on, results of `SELECT` queries are retrieved from the [query cache](../query-cache.md).
5382 : 113429 :
5383 : 113429 : Possible values:
5384 : 113429 :
5385 : 113429 : - 0 - Disabled
5386 : 113429 : - 1 - Enabled
5387 : 113429 : )", 0) \
5388 : 113429 : DECLARE(QueryResultCacheNondeterministicFunctionHandling, query_cache_nondeterministic_function_handling, QueryResultCacheNondeterministicFunctionHandling::Throw, R"(
5389 : 113429 : Controls how the [query cache](../query-cache.md) handles `SELECT` queries with non-deterministic functions like `rand()` or `now()`.
5390 : 113429 :
5391 : 113429 : Possible values:
5392 : 113429 :
5393 : 113429 : - `'throw'` - Throw an exception and don't cache the query result.
5394 : 113429 : - `'save'` - Cache the query result.
5395 : 113429 : - `'ignore'` - Don't cache the query result and don't throw an exception.
5396 : 113429 : )", 0) \
5397 : 113429 : DECLARE(QueryResultCacheSystemTableHandling, query_cache_system_table_handling, QueryResultCacheSystemTableHandling::Throw, R"(
5398 : 113429 : Controls how the [query cache](../query-cache.md) handles `SELECT` queries against system tables, i.e. tables in databases `system.*` and `information_schema.*`.
5399 : 113429 :
5400 : 113429 : Possible values:
5401 : 113429 :
5402 : 113429 : - `'throw'` - Throw an exception and don't cache the query result.
5403 : 113429 : - `'save'` - Cache the query result.
5404 : 113429 : - `'ignore'` - Don't cache the query result and don't throw an exception.
5405 : 113429 : )", 0) \
5406 : 113429 : DECLARE(UInt64, query_cache_max_size_in_bytes, 0, R"(
5407 : 113429 : The maximum amount of memory (in bytes) the current user may allocate in the [query cache](../query-cache.md). 0 means unlimited.
5408 : 113429 :
5409 : 113429 : Possible values:
5410 : 113429 :
5411 : 113429 : - Positive integer >= 0.
5412 : 113429 : )", 0) \
5413 : 113429 : DECLARE(UInt64, query_cache_max_entries, 0, R"(
5414 : 113429 : The maximum number of query results the current user may store in the [query cache](../query-cache.md). 0 means unlimited.
5415 : 113429 :
5416 : 113429 : Possible values:
5417 : 113429 :
5418 : 113429 : - Positive integer >= 0.
5419 : 113429 : )", 0) \
5420 : 113429 : DECLARE(UInt64, query_cache_min_query_runs, 0, R"(
5421 : 113429 : Minimum number of times a `SELECT` query must run before its result is stored in the [query cache](../query-cache.md).
5422 : 113429 :
5423 : 113429 : Possible values:
5424 : 113429 :
5425 : 113429 : - Positive integer >= 0.
5426 : 113429 : )", 0) \
5427 : 113429 : DECLARE(Milliseconds, query_cache_min_query_duration, 0, R"(
5428 : 113429 : Minimum duration in milliseconds a query needs to run for its result to be stored in the [query cache](../query-cache.md).
5429 : 113429 :
5430 : 113429 : Possible values:
5431 : 113429 :
5432 : 113429 : - Positive integer >= 0.
5433 : 113429 : )", 0) \
5434 : 113429 : DECLARE(Bool, query_cache_compress_entries, true, R"(
5435 : 113429 : Compress entries in the [query cache](../query-cache.md). Lessens the memory consumption of the query cache at the cost of slower inserts into / reads from it.
5436 : 113429 :
5437 : 113429 : Possible values:
5438 : 113429 :
5439 : 113429 : - 0 - Disabled
5440 : 113429 : - 1 - Enabled
5441 : 113429 : )", 0) \
5442 : 113429 : DECLARE(Bool, query_cache_squash_partial_results, true, R"(
5443 : 113429 : Squash partial result blocks to blocks of size [max_block_size](#max_block_size). Reduces performance of inserts into the [query cache](../query-cache.md) but improves the compressability of cache entries (see [query_cache_compress-entries](#query_cache_compress_entries)).
5444 : 113429 :
5445 : 113429 : Possible values:
5446 : 113429 :
5447 : 113429 : - 0 - Disabled
5448 : 113429 : - 1 - Enabled
5449 : 113429 : )", 0) \
5450 : 113429 : DECLARE(Seconds, query_cache_ttl, 60, R"(
5451 : 113429 : After this time in seconds entries in the [query cache](../query-cache.md) become stale.
5452 : 113429 :
5453 : 113429 : Possible values:
5454 : 113429 :
5455 : 113429 : - Positive integer >= 0.
5456 : 113429 : )", 0) \
5457 : 113429 : DECLARE(Bool, query_cache_share_between_users, false, R"(
5458 : 113429 : If turned on, the result of `SELECT` queries cached in the [query cache](../query-cache.md) can be read by other users.
5459 : 113429 : It is not recommended to enable this setting due to security reasons.
5460 : 113429 :
5461 : 113429 : Possible values:
5462 : 113429 :
5463 : 113429 : - 0 - Disabled
5464 : 113429 : - 1 - Enabled
5465 : 113429 : )", 0) \
5466 : 113429 : DECLARE(String, query_cache_tag, "", R"(
5467 : 113429 : A string which acts as a label for [query cache](../query-cache.md) entries.
5468 : 113429 : The same queries with different tags are considered different by the query cache.
5469 : 113429 :
5470 : 113429 : Possible values:
5471 : 113429 :
5472 : 113429 : - Any string
5473 : 113429 : )", 0) \
5474 : 113429 : DECLARE(Bool, enable_sharing_sets_for_mutations, true, R"(
5475 : 113429 : Allow sharing set objects build for IN subqueries between different tasks of the same mutation. This reduces memory usage and CPU consumption
5476 : 113429 : )", 0) \
5477 : 113429 : DECLARE(Bool, use_query_condition_cache, true, R"(
5478 : 113429 : Enable the [query condition cache](/operations/query-condition-cache). The cache stores ranges of granules in data parts which do not satisfy the condition in the `WHERE` clause,
5479 : 113429 : and reuse this information as an ephemeral index for subsequent queries.
5480 : 113429 :
5481 : 113429 : Possible values:
5482 : 113429 :
5483 : 113429 : - 0 - Disabled
5484 : 113429 : - 1 - Enabled
5485 : 113429 : )", 0) \
5486 : 113429 : DECLARE(Bool, enable_shared_storage_snapshot_in_query, true, R"(
5487 : 113429 : If enabled, all subqueries within a single query will share the same StorageSnapshot for each table.
5488 : 113429 : This ensures a consistent view of the data across the entire query, even if the same table is accessed multiple times.
5489 : 113429 :
5490 : 113429 : This is required for queries where internal consistency of data parts is important. Example:
5491 : 113429 :
5492 : 113429 : ```sql
5493 : 113429 : SELECT
5494 : 113429 : count()
5495 : 113429 : FROM events
5496 : 113429 : WHERE (_part, _part_offset) IN (
5497 : 113429 : SELECT _part, _part_offset
5498 : 113429 : FROM events
5499 : 113429 : WHERE user_id = 42
5500 : 113429 : )
5501 : 113429 : ```
5502 : 113429 :
5503 : 113429 : Without this setting, the outer and inner queries may operate on different data snapshots, leading to incorrect results.
5504 : 113429 :
5505 : 113429 : :::note
5506 : 113429 : Enabling this setting disables the optimization which removes unnecessary data parts from snapshots once the planning stage is complete.
5507 : 113429 : As a result, long-running queries may hold onto obsolete parts for their entire duration, delaying part cleanup and increasing storage pressure.
5508 : 113429 :
5509 : 113429 : This setting currently applies only to tables from the MergeTree family.
5510 : 113429 : :::
5511 : 113429 :
5512 : 113429 : Possible values:
5513 : 113429 :
5514 : 113429 : - 0 - Disabled
5515 : 113429 : - 1 - Enabled
5516 : 113429 : )", 0) \
5517 : 113429 : DECLARE(UInt64, merge_tree_storage_snapshot_sleep_ms, 0, R"(
5518 : 113429 : Inject artificial delay (in milliseconds) when creating a storage snapshot for MergeTree tables.
5519 : 113429 : Used for testing and debugging purposes only.
5520 : 113429 :
5521 : 113429 : Possible values:
5522 : 113429 : - 0 - No delay (default)
5523 : 113429 : - N - Delay in milliseconds
5524 : 113429 : )", 0) \
5525 : 113429 : DECLARE(Bool, optimize_rewrite_sum_if_to_count_if, true, R"(
5526 : 113429 : Rewrite sumIf() and sum(if()) function countIf() function when logically equivalent
5527 : 113429 : )", 0) \
5528 : 113429 : DECLARE(Bool, optimize_empty_string_comparisons, true, R"(
5529 : 113429 : Convert expressions like col = '' or '' = col into empty(col), and col != '' or '' != col into notEmpty(col),
5530 : 113429 : only when col is of String or FixedString type.
5531 : 113429 : )", 0) \
5532 : 113429 : DECLARE(Bool, optimize_rewrite_aggregate_function_with_if, true, R"(
5533 : 113429 : Rewrite aggregate functions with if expression as argument when logically equivalent.
5534 : 113429 : For example, `avg(if(cond, col, null))` can be rewritten to `avgOrNullIf(cond, col)`. It may improve performance.
5535 : 113429 :
5536 : 113429 : :::note
5537 : 113429 : Supported only with the analyzer (`enable_analyzer = 1`).
5538 : 113429 : :::
5539 : 113429 : )", 0) \
5540 : 113429 : DECLARE(Bool, optimize_rewrite_array_exists_to_has, true, R"(
5541 : 113429 : Rewrite arrayExists() functions to has() when logically equivalent. For example, arrayExists(x -> x = 1, arr) can be rewritten to has(arr, 1)
5542 : 113429 : )", 0) \
5543 : 113429 : DECLARE(Bool, optimize_rewrite_like_perfect_affix, true, R"(
5544 : 113429 : Rewrite LIKE expressions with perfect prefix or suffix (e.g. `col LIKE 'ClickHouse%'`) to startsWith or endsWith functions (e.g. `startsWith(col, 'ClickHouse')`).
5545 : 113429 : )", 0) \
5546 : 113429 : DECLARE(Bool, execute_exists_as_scalar_subquery, true, R"(
5547 : 113429 : Execute non-correlated EXISTS subqueries as scalar subqueries. As for scalar subqueries, the cache is used, and the constant folding applies to the result.
5548 : 113429 :
5549 : 113429 : Cloud default value: `0`.
5550 : 113429 : )", 0) \
5551 : 113429 : DECLARE(Bool, optimize_rewrite_regexp_functions, true, R"(
5552 : 113429 : Rewrite regular expression related functions into simpler and more efficient forms
5553 : 113429 : )", 0) \
5554 : 113429 : DECLARE(UInt64, insert_shard_id, 0, R"(
5555 : 113429 : If not `0`, specifies the shard of [Distributed](/engines/table-engines/special/distributed) table into which the data will be inserted synchronously.
5556 : 113429 :
5557 : 113429 : If `insert_shard_id` value is incorrect, the server will throw an exception.
5558 : 113429 :
5559 : 113429 : To get the number of shards on `requested_cluster`, you can check server config or use this query:
5560 : 113429 :
5561 : 113429 : ```sql
5562 : 113429 : SELECT uniq(shard_num) FROM system.clusters WHERE cluster = 'requested_cluster';
5563 : 113429 : ```
5564 : 113429 :
5565 : 113429 : Possible values:
5566 : 113429 :
5567 : 113429 : - 0 — Disabled.
5568 : 113429 : - Any number from `1` to `shards_num` of corresponding [Distributed](/engines/table-engines/special/distributed) table.
5569 : 113429 :
5570 : 113429 : **Example**
5571 : 113429 :
5572 : 113429 : Query:
5573 : 113429 :
5574 : 113429 : ```sql
5575 : 113429 : CREATE TABLE x AS system.numbers ENGINE = MergeTree ORDER BY number;
5576 : 113429 : CREATE TABLE x_dist AS x ENGINE = Distributed('test_cluster_two_shards_localhost', currentDatabase(), x);
5577 : 113429 : INSERT INTO x_dist SELECT * FROM numbers(5) SETTINGS insert_shard_id = 1;
5578 : 113429 : SELECT * FROM x_dist ORDER BY number ASC;
5579 : 113429 : ```
5580 : 113429 :
5581 : 113429 : Result:
5582 : 113429 :
5583 : 113429 : ```text
5584 : 113429 : ┌─number─┐
5585 : 113429 : │ 0 │
5586 : 113429 : │ 0 │
5587 : 113429 : │ 1 │
5588 : 113429 : │ 1 │
5589 : 113429 : │ 2 │
5590 : 113429 : │ 2 │
5591 : 113429 : │ 3 │
5592 : 113429 : │ 3 │
5593 : 113429 : │ 4 │
5594 : 113429 : │ 4 │
5595 : 113429 : └────────┘
5596 : 113429 : ```
5597 : 113429 : )", 0) \
5598 : 113429 : \
5599 : 113429 : DECLARE(Bool, collect_hash_table_stats_during_aggregation, true, R"(
5600 : 113429 : Enable collecting hash table statistics to optimize memory allocation
5601 : 113429 : )", 0) \
5602 : 113429 : DECLARE(UInt64, max_size_to_preallocate_for_aggregation, 1'000'000'000'000, R"(
5603 : 113429 : For how many elements it is allowed to preallocate space in all hash tables in total before aggregation
5604 : 113429 : )", 0) \
5605 : 113429 : \
5606 : 113429 : DECLARE(Bool, collect_hash_table_stats_during_joins, true, R"(
5607 : 113429 : Enable collecting hash table statistics to optimize memory allocation
5608 : 113429 : )", 0) \
5609 : 113429 : DECLARE(Bool, use_hash_table_stats_for_join_reordering, true, R"(
5610 : 113429 : Enable using collected hash table statistics for cardinality estimation during join reordering
5611 : 113429 : )", 0) \
5612 : 113429 : DECLARE(UInt64, max_size_to_preallocate_for_joins, 1'000'000'000'000, R"(
5613 : 113429 : For how many elements it is allowed to preallocate space in all hash tables in total before join
5614 : 113429 : )", 0) \
5615 : 113429 : \
5616 : 113429 : DECLARE(Bool, kafka_disable_num_consumers_limit, false, R"(
5617 : 113429 : Disable limit on kafka_num_consumers that depends on the number of available CPU cores.
5618 : 113429 : )", 0) \
5619 : 113429 : DECLARE(Bool, allow_experimental_kafka_offsets_storage_in_keeper, false, R"(
5620 : 113429 : Allow experimental feature to store Kafka related offsets in ClickHouse Keeper. When enabled a ClickHouse Keeper path and replica name can be specified to the Kafka table engine. As a result instead of the regular Kafka engine, a new type of storage engine will be used that stores the committed offsets primarily in ClickHouse Keeper
5621 : 113429 : )", EXPERIMENTAL) \
5622 : 113429 : DECLARE(Bool, enable_software_prefetch_in_aggregation, true, R"(
5623 : 113429 : Enable use of software prefetch in aggregation
5624 : 113429 : )", 0) \
5625 : 113429 : DECLARE(Bool, allow_aggregate_partitions_independently, false, R"(
5626 : 113429 : Enable independent aggregation of partitions on separate threads when partition key suits group by key. Beneficial when number of partitions close to number of cores and partitions have roughly the same size
5627 : 113429 : )", 0) \
5628 : 113429 : DECLARE(Bool, force_aggregate_partitions_independently, false, R"(
5629 : 113429 : Force the use of optimization when it is applicable, but heuristics decided not to use it
5630 : 113429 : )", 0) \
5631 : 113429 : DECLARE(UInt64, max_number_of_partitions_for_independent_aggregation, 128, R"(
5632 : 113429 : Maximal number of partitions in table to apply optimization
5633 : 113429 : )", 0) \
5634 : 113429 : DECLARE(Float, min_hit_rate_to_use_consecutive_keys_optimization, 0.5, R"(
5635 : 113429 : Minimal hit rate of a cache which is used for consecutive keys optimization in aggregation to keep it enabled
5636 : 113429 : )", 0) \
5637 : 113429 : \
5638 : 113429 : DECLARE(Bool, engine_file_empty_if_not_exists, false, R"(
5639 : 113429 : Allows to select data from a file engine table without file.
5640 : 113429 :
5641 : 113429 : Possible values:
5642 : 113429 : - 0 — `SELECT` throws exception.
5643 : 113429 : - 1 — `SELECT` returns empty result.
5644 : 113429 : )", 0) \
5645 : 113429 : DECLARE(Bool, engine_file_truncate_on_insert, false, R"(
5646 : 113429 : Enables or disables truncate before insert in [File](../../engines/table-engines/special/file.md) engine tables.
5647 : 113429 :
5648 : 113429 : Possible values:
5649 : 113429 : - 0 — `INSERT` query appends new data to the end of the file.
5650 : 113429 : - 1 — `INSERT` query replaces existing content of the file with the new data.
5651 : 113429 : )", 0) \
5652 : 113429 : DECLARE(Bool, engine_file_allow_create_multiple_files, false, R"(
5653 : 113429 : 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:
5654 : 113429 :
5655 : 113429 : `data.Parquet` -> `data.1.Parquet` -> `data.2.Parquet`, etc.
5656 : 113429 :
5657 : 113429 : Possible values:
5658 : 113429 : - 0 — `INSERT` query appends new data to the end of the file.
5659 : 113429 : - 1 — `INSERT` query creates a new file.
5660 : 113429 : )", 0) \
5661 : 113429 : DECLARE(Bool, engine_file_skip_empty_files, false, R"(
5662 : 113429 : Enables or disables skipping empty files in [File](../../engines/table-engines/special/file.md) engine tables.
5663 : 113429 :
5664 : 113429 : Possible values:
5665 : 113429 : - 0 — `SELECT` throws an exception if empty file is not compatible with requested format.
5666 : 113429 : - 1 — `SELECT` returns empty result for empty file.
5667 : 113429 : )", 0) \
5668 : 113429 : DECLARE(Bool, engine_url_skip_empty_files, false, R"(
5669 : 113429 : Enables or disables skipping empty files in [URL](../../engines/table-engines/special/url.md) engine tables.
5670 : 113429 :
5671 : 113429 : Possible values:
5672 : 113429 : - 0 — `SELECT` throws an exception if empty file is not compatible with requested format.
5673 : 113429 : - 1 — `SELECT` returns empty result for empty file.
5674 : 113429 : )", 0) \
5675 : 113429 : DECLARE(Bool, enable_url_encoding, false, R"(
5676 : 113429 : Allows to enable/disable decoding/encoding path in uri in [URL](../../engines/table-engines/special/url.md) engine tables.
5677 : 113429 :
5678 : 113429 : Disabled by default.
5679 : 113429 : )", 0) \
5680 : 113429 : DECLARE(UInt64, database_replicated_initial_query_timeout_sec, 300, R"(
5681 : 113429 : Sets how long initial DDL query should wait for Replicated database to process previous DDL queue entries in seconds.
5682 : 113429 :
5683 : 113429 : Possible values:
5684 : 113429 :
5685 : 113429 : - Positive integer.
5686 : 113429 : - 0 — Unlimited.
5687 : 113429 : )", 0) \
5688 : 113429 : DECLARE(Bool, database_replicated_enforce_synchronous_settings, false, R"(
5689 : 113429 : Enforces synchronous waiting for some queries (see also database_atomic_wait_for_drop_and_detach_synchronously, mutations_sync, alter_sync). Not recommended to enable these settings.
5690 : 113429 : )", 0) \
5691 : 113429 : DECLARE(UInt64, max_distributed_depth, 5, R"(
5692 : 113429 : Limits the maximum depth of recursive queries for [Distributed](../../engines/table-engines/special/distributed.md) tables.
5693 : 113429 :
5694 : 113429 : If the value is exceeded, the server throws an exception.
5695 : 113429 :
5696 : 113429 : Possible values:
5697 : 113429 :
5698 : 113429 : - Positive integer.
5699 : 113429 : - 0 — Unlimited depth.
5700 : 113429 : )", 0) \
5701 : 113429 : DECLARE(Bool, database_replicated_always_detach_permanently, false, R"(
5702 : 113429 : Execute DETACH TABLE as DETACH TABLE PERMANENTLY if database engine is Replicated
5703 : 113429 : )", 0) \
5704 : 113429 : DECLARE(Bool, database_replicated_allow_only_replicated_engine, false, R"(
5705 : 113429 : Allow to create only Replicated tables in database with engine Replicated
5706 : 113429 :
5707 : 113429 : Cloud default value: `1`.
5708 : 113429 : )", 0) \
5709 : 113429 : DECLARE(UInt64, database_replicated_allow_replicated_engine_arguments, 0, R"(
5710 : 113429 : 0 - Don't allow to explicitly specify ZooKeeper path and replica name for *MergeTree tables in Replicated databases. 1 - Allow. 2 - Allow, but ignore the specified path and use default one instead. 3 - Allow and don't log a warning.
5711 : 113429 : )", 0) \
5712 : 113429 : DECLARE(UInt64, database_replicated_allow_explicit_uuid, 0, R"(
5713 : 113429 : 0 - Don't allow to explicitly specify UUIDs for tables in Replicated databases. 1 - Allow. 2 - Allow, but ignore the specified UUID and generate a random one instead.
5714 : 113429 : )", 0) \
5715 : 113429 : DECLARE(Bool, database_replicated_allow_heavy_create, false, R"(
5716 : 113429 : Allow long-running DDL queries (CREATE AS SELECT and POPULATE) in Replicated database engine. Note that it can block DDL queue for a long time.
5717 : 113429 : )", 0) \
5718 : 113429 : DECLARE(UInt64, database_shared_drop_table_delay_seconds, 8 * 60 * 60, R"(
5719 : 113429 : The delay in seconds before a dropped table is actually removed from a Shared database. This allows to recover the table within this time using `UNDROP TABLE` statement.
5720 : 113429 : )", 0) \
5721 : 113429 : DECLARE(Bool, cloud_mode, false, R"(
5722 : 113429 : Cloud mode
5723 : 113429 :
5724 : 113429 : Cloud default value: `1`.
5725 : 113429 : )", 0) \
5726 : 113429 : DECLARE(UInt64, cloud_mode_engine, 1, R"(
5727 : 113429 : The engine family allowed in Cloud.
5728 : 113429 :
5729 : 113429 : - 0 - allow everything
5730 : 113429 : - 1 - rewrite DDLs to use *ReplicatedMergeTree
5731 : 113429 : - 2 - rewrite DDLs to use SharedMergeTree
5732 : 113429 : - 3 - rewrite DDLs to use SharedMergeTree except when explicitly passed remote disk is specified
5733 : 113429 : - 4 - same as 3, plus additionally use Alias instead of Distributed (the Alias table will point to the destination table of the Distributed table, so it will use the corresponding local table)
5734 : 113429 :
5735 : 113429 : UInt64 to minimize public part
5736 : 113429 :
5737 : 113429 : Cloud default value: `2`.
5738 : 113429 : )", 0) \
5739 : 113429 : DECLARE(UInt64, cloud_mode_database_engine, 1, R"(
5740 : 113429 : The database engine allowed in Cloud. 1 - rewrite DDLs to use Replicated database, 2 - rewrite DDLs to use Shared database
5741 : 113429 :
5742 : 113429 : Cloud default value: `2`.
5743 : 113429 : )", 0) \
5744 : 113429 : DECLARE(DistributedDDLOutputMode, distributed_ddl_output_mode, DistributedDDLOutputMode::THROW, R"(
5745 : 113429 : Sets format of distributed DDL query result.
5746 : 113429 :
5747 : 113429 : Possible values:
5748 : 113429 :
5749 : 113429 : - `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](#distributed_ddl_task_timeout) exceeded, then it throws `TIMEOUT_EXCEEDED` exception.
5750 : 113429 : - `none` — Is similar to throw, but distributed DDL query returns no result set.
5751 : 113429 : - `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.
5752 : 113429 : - `never_throw` — Do not throw `TIMEOUT_EXCEEDED` and do not rethrow exceptions if query has failed on some hosts.
5753 : 113429 : - `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.
5754 : 113429 : - `null_status_on_timeout_only_active` — similar to `null_status_on_timeout`, but doesn't wait for inactive replicas of the `Replicated` database
5755 : 113429 : - `throw_only_active` — similar to `throw`, but doesn't wait for inactive replicas of the `Replicated` database
5756 : 113429 :
5757 : 113429 : Cloud default value: `none_only_active`.
5758 : 113429 : )", 0) \
5759 : 113429 : DECLARE(UInt64, distributed_ddl_entry_format_version, 5, R"(
5760 : 113429 : Compatibility version of distributed DDL (ON CLUSTER) queries
5761 : 113429 :
5762 : 113429 : Cloud default value: `6`.
5763 : 113429 : )", 0) \
5764 : 113429 : \
5765 : 113429 : DECLARE(UInt64, external_storage_max_read_rows, 0, R"(
5766 : 113429 : Limit maximum number of rows when table with external engine should flush history data. Now supported only for MySQL table engine, database engine, and dictionary. If equal to 0, this setting is disabled
5767 : 113429 : )", 0) \
5768 : 113429 : DECLARE(UInt64, external_storage_max_read_bytes, 0, R"(
5769 : 113429 : Limit maximum number of bytes when table with external engine should flush history data. Now supported only for MySQL table engine, database engine, and dictionary. If equal to 0, this setting is disabled
5770 : 113429 : )", 0) \
5771 : 113429 : DECLARE(UInt64, external_storage_connect_timeout_sec, DBMS_DEFAULT_CONNECT_TIMEOUT_SEC, R"(
5772 : 113429 : Connect timeout in seconds. Now supported only for MySQL
5773 : 113429 : )", 0) \
5774 : 113429 : DECLARE(UInt64, external_storage_rw_timeout_sec, DBMS_DEFAULT_RECEIVE_TIMEOUT_SEC, R"(
5775 : 113429 : Read/write timeout in seconds. Now supported only for MySQL
5776 : 113429 : )", 0) \
5777 : 113429 : \
5778 : 113429 : DECLARE(Bool, allow_experimental_correlated_subqueries, true, R"(
5779 : 113429 : Allow to execute correlated subqueries.
5780 : 113429 : )", BETA) \
5781 : 113429 : \
5782 : 113429 : DECLARE(SetOperationMode, union_default_mode, SetOperationMode::Unspecified, R"(
5783 : 113429 : Sets a mode for combining `SELECT` query results. The setting is only used when shared with [UNION](../../sql-reference/statements/select/union.md) without explicitly specifying the `UNION ALL` or `UNION DISTINCT`.
5784 : 113429 :
5785 : 113429 : Possible values:
5786 : 113429 :
5787 : 113429 : - `'DISTINCT'` — ClickHouse outputs rows as a result of combining queries removing duplicate rows.
5788 : 113429 : - `'ALL'` — ClickHouse outputs all rows as a result of combining queries including duplicate rows.
5789 : 113429 : - `''` — ClickHouse generates an exception when used with `UNION`.
5790 : 113429 :
5791 : 113429 : See examples in [UNION](../../sql-reference/statements/select/union.md).
5792 : 113429 : )", 0) \
5793 : 113429 : DECLARE(SetOperationMode, intersect_default_mode, SetOperationMode::ALL, R"(
5794 : 113429 : Set default mode in INTERSECT query. Possible values: empty string, 'ALL', 'DISTINCT'. If empty, query without mode will throw exception.
5795 : 113429 : )", 0) \
5796 : 113429 : DECLARE(SetOperationMode, except_default_mode, SetOperationMode::ALL, R"(
5797 : 113429 : Set default mode in EXCEPT query. Possible values: empty string, 'ALL', 'DISTINCT'. If empty, query without mode will throw exception.
5798 : 113429 : )", 0) \
5799 : 113429 : DECLARE(Bool, optimize_aggregators_of_group_by_keys, true, R"(
5800 : 113429 : Eliminates min/max/any/anyLast aggregators of GROUP BY keys in SELECT section
5801 : 113429 : )", 0) \
5802 : 113429 : DECLARE(Bool, optimize_injective_functions_in_group_by, true, R"(
5803 : 113429 : Replaces injective functions by it's arguments in GROUP BY section
5804 : 113429 : )", 0) \
5805 : 113429 : DECLARE(Bool, optimize_group_by_function_keys, true, R"(
5806 : 113429 : Eliminates functions of other keys in GROUP BY section
5807 : 113429 : )", 0) \
5808 : 113429 : DECLARE(Bool, optimize_group_by_constant_keys, true, R"(
5809 : 113429 : Optimize GROUP BY when all keys in block are constant
5810 : 113429 : )", 0) \
5811 : 113429 : DECLARE(Bool, legacy_column_name_of_tuple_literal, false, R"(
5812 : 113429 : List all names of element of large tuple literals in their column names instead of hash. This settings exists only for compatibility reasons. It makes sense to set to 'true', while doing rolling update of cluster from version lower than 21.7 to higher.
5813 : 113429 : )", 0) \
5814 : 113429 : DECLARE(Bool, enable_named_columns_in_function_tuple, false, R"(
5815 : 113429 : Generate named tuples in function tuple() when all names are unique and can be treated as unquoted identifiers.
5816 : 113429 : )", 0) \
5817 : 113429 : \
5818 : 113429 : DECLARE(Bool, query_plan_enable_optimizations, true, R"(
5819 : 113429 : Toggles query optimization at the query plan level.
5820 : 113429 :
5821 : 113429 : :::note
5822 : 113429 : 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.
5823 : 113429 : :::
5824 : 113429 :
5825 : 113429 : Possible values:
5826 : 113429 :
5827 : 113429 : - 0 - Disable all optimizations at the query plan level
5828 : 113429 : - 1 - Enable optimizations at the query plan level (but individual optimizations may still be disabled via their individual settings)
5829 : 113429 : )", 0) \
5830 : 113429 : DECLARE(UInt64, query_plan_max_optimizations_to_apply, 10'000, R"(
5831 : 113429 : Limits the total number of optimizations applied to query plan, see setting [query_plan_enable_optimizations](#query_plan_enable_optimizations).
5832 : 113429 : Useful to avoid long optimization times for complex queries.
5833 : 113429 : In the EXPLAIN PLAN query, stop applying optimizations after this limit is reached and return the plan as is.
5834 : 113429 : For regular query execution if the actual number of optimizations exceeds this setting, an exception is thrown.
5835 : 113429 :
5836 : 113429 : :::note
5837 : 113429 : 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.
5838 : 113429 : :::
5839 : 113429 : )", 0) \
5840 : 113429 : DECLARE(Bool, query_plan_lift_up_array_join, true, R"(
5841 : 113429 : Toggles a query-plan-level optimization which moves ARRAY JOINs up in the execution plan.
5842 : 113429 : Only takes effect if setting [query_plan_enable_optimizations](#query_plan_enable_optimizations) is 1.
5843 : 113429 :
5844 : 113429 : :::note
5845 : 113429 : 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.
5846 : 113429 : :::
5847 : 113429 :
5848 : 113429 : Possible values:
5849 : 113429 :
5850 : 113429 : - 0 - Disable
5851 : 113429 : - 1 - Enable
5852 : 113429 : )", 0) \
5853 : 113429 : DECLARE(Bool, query_plan_push_down_limit, true, R"(
5854 : 113429 : Toggles a query-plan-level optimization which moves LIMITs down in the execution plan.
5855 : 113429 : Only takes effect if setting [query_plan_enable_optimizations](#query_plan_enable_optimizations) is 1.
5856 : 113429 :
5857 : 113429 : :::note
5858 : 113429 : 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.
5859 : 113429 : :::
5860 : 113429 :
5861 : 113429 : Possible values:
5862 : 113429 :
5863 : 113429 : - 0 - Disable
5864 : 113429 : - 1 - Enable
5865 : 113429 : )", 0) \
5866 : 113429 : DECLARE(Bool, query_plan_split_filter, true, R"(
5867 : 113429 : :::note
5868 : 113429 : 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.
5869 : 113429 : :::
5870 : 113429 :
5871 : 113429 : Toggles a query-plan-level optimization which splits filters into expressions.
5872 : 113429 : Only takes effect if setting [query_plan_enable_optimizations](#query_plan_enable_optimizations) is 1.
5873 : 113429 :
5874 : 113429 : Possible values:
5875 : 113429 :
5876 : 113429 : - 0 - Disable
5877 : 113429 : - 1 - Enable
5878 : 113429 : )", 0) \
5879 : 113429 : DECLARE(Bool, query_plan_merge_expressions, true, R"(
5880 : 113429 : Toggles a query-plan-level optimization which merges consecutive filters.
5881 : 113429 : Only takes effect if setting [query_plan_enable_optimizations](#query_plan_enable_optimizations) is 1.
5882 : 113429 :
5883 : 113429 : :::note
5884 : 113429 : 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.
5885 : 113429 : :::
5886 : 113429 :
5887 : 113429 : Possible values:
5888 : 113429 :
5889 : 113429 : - 0 - Disable
5890 : 113429 : - 1 - Enable
5891 : 113429 : )", 0) \
5892 : 113429 : DECLARE(Bool, query_plan_merge_filters, true, R"(
5893 : 113429 : Allow to merge filters in the query plan.
5894 : 113429 : )", 0) \
5895 : 113429 : DECLARE(Bool, query_plan_filter_push_down, true, R"(
5896 : 113429 : Toggles a query-plan-level optimization which moves filters down in the execution plan.
5897 : 113429 : Only takes effect if setting [query_plan_enable_optimizations](#query_plan_enable_optimizations) is 1.
5898 : 113429 :
5899 : 113429 : :::note
5900 : 113429 : 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.
5901 : 113429 : :::
5902 : 113429 :
5903 : 113429 : Possible values:
5904 : 113429 :
5905 : 113429 : - 0 - Disable
5906 : 113429 : - 1 - Enable
5907 : 113429 : )", 0) \
5908 : 113429 : DECLARE(Bool, query_plan_convert_outer_join_to_inner_join, true, R"(
5909 : 113429 : Allow to convert `OUTER JOIN` to `INNER JOIN` if filter after `JOIN` always filters default values
5910 : 113429 : )", 0) \
5911 : 113429 : DECLARE(Bool, query_plan_convert_any_join_to_semi_or_anti_join, true, R"(
5912 : 113429 : Allow to convert ANY JOIN to SEMI or ANTI JOIN if filter after JOIN always evaluates to false for not-matched or matched rows
5913 : 113429 : )", 0) \
5914 : 113429 : DECLARE(Bool, query_plan_merge_filter_into_join_condition, true, R"(
5915 : 113429 : Allow to merge filter into `JOIN` condition and convert `CROSS JOIN` to `INNER`.
5916 : 113429 : )", 0) \
5917 : 113429 : DECLARE(Bool, query_plan_convert_join_to_in, false, R"(
5918 : 113429 : Allow to convert `JOIN` to subquery with `IN` if output columns tied to only left table. May cause wrong results with non-ANY JOINs (e.g. ALL JOINs which is the default).
5919 : 113429 : )", 0) \
5920 : 113429 : DECLARE(Bool, query_plan_optimize_prewhere, true, R"(
5921 : 113429 : Allow to push down filter to PREWHERE expression for supported storages
5922 : 113429 : )", 0) \
5923 : 113429 : DECLARE(Bool, query_plan_execute_functions_after_sorting, true, R"(
5924 : 113429 : Toggles a query-plan-level optimization which moves expressions after sorting steps.
5925 : 113429 : Only takes effect if setting [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) is 1.
5926 : 113429 :
5927 : 113429 : :::note
5928 : 113429 : 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.
5929 : 113429 : :::
5930 : 113429 :
5931 : 113429 : Possible values:
5932 : 113429 :
5933 : 113429 : - 0 - Disable
5934 : 113429 : - 1 - Enable
5935 : 113429 : )", 0) \
5936 : 113429 : DECLARE_WITH_ALIAS(Bool, query_plan_reuse_storage_ordering_for_window_functions, false, R"(
5937 : 113429 : Toggles a query-plan-level optimization which uses storage sorting when sorting for window functions.
5938 : 113429 : Only takes effect if setting [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) is 1.
5939 : 113429 :
5940 : 113429 : :::note
5941 : 113429 : 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.
5942 : 113429 : :::
5943 : 113429 :
5944 : 113429 : Possible values:
5945 : 113429 :
5946 : 113429 : - 0 - Disable
5947 : 113429 : - 1 - Enable
5948 : 113429 : )", 0, optimize_read_in_window_order) \
5949 : 113429 : DECLARE(Bool, query_plan_lift_up_union, true, R"(
5950 : 113429 : Toggles a query-plan-level optimization which moves larger subtrees of the query plan into union to enable further optimizations.
5951 : 113429 : Only takes effect if setting [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) is 1.
5952 : 113429 :
5953 : 113429 : :::note
5954 : 113429 : 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.
5955 : 113429 : :::
5956 : 113429 :
5957 : 113429 : Possible values:
5958 : 113429 :
5959 : 113429 : - 0 - Disable
5960 : 113429 : - 1 - Enable
5961 : 113429 : )", 0) \
5962 : 113429 : DECLARE(Bool, query_plan_read_in_order, true, R"(
5963 : 113429 : Toggles the read in-order optimization query-plan-level optimization.
5964 : 113429 : Only takes effect if setting [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) is 1.
5965 : 113429 :
5966 : 113429 : :::note
5967 : 113429 : 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.
5968 : 113429 : :::
5969 : 113429 :
5970 : 113429 : Possible values:
5971 : 113429 :
5972 : 113429 : - 0 - Disable
5973 : 113429 : - 1 - Enable
5974 : 113429 : )", 0) \
5975 : 113429 : DECLARE(Bool, query_plan_read_in_order_through_join, true, "Keep reading in order from the left table in JOIN operations, which can be utilized by subsequent steps.", 0) \
5976 : 113429 : DECLARE(Bool, query_plan_aggregation_in_order, true, R"(
5977 : 113429 : Toggles the aggregation in-order query-plan-level optimization.
5978 : 113429 : Only takes effect if setting [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) is 1.
5979 : 113429 :
5980 : 113429 : :::note
5981 : 113429 : 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.
5982 : 113429 : :::
5983 : 113429 :
5984 : 113429 : Possible values:
5985 : 113429 :
5986 : 113429 : - 0 - Disable
5987 : 113429 : - 1 - Enable
5988 : 113429 : )", 0) \
5989 : 113429 : DECLARE(Bool, query_plan_remove_redundant_sorting, true, R"(
5990 : 113429 : Toggles a query-plan-level optimization which removes redundant sorting steps, e.g. in subqueries.
5991 : 113429 : Only takes effect if setting [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) is 1.
5992 : 113429 :
5993 : 113429 : :::note
5994 : 113429 : 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.
5995 : 113429 : :::
5996 : 113429 :
5997 : 113429 : Possible values:
5998 : 113429 :
5999 : 113429 : - 0 - Disable
6000 : 113429 : - 1 - Enable
6001 : 113429 : )", 0) \
6002 : 113429 : DECLARE(Bool, query_plan_remove_redundant_distinct, true, R"(
6003 : 113429 : Toggles a query-plan-level optimization which removes redundant DISTINCT steps.
6004 : 113429 : Only takes effect if setting [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) is 1.
6005 : 113429 :
6006 : 113429 : :::note
6007 : 113429 : 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.
6008 : 113429 : :::
6009 : 113429 :
6010 : 113429 : Possible values:
6011 : 113429 :
6012 : 113429 : - 0 - Disable
6013 : 113429 : - 1 - Enable
6014 : 113429 : )", 0) \
6015 : 113429 : DECLARE(Bool, query_plan_try_use_vector_search, true, R"(
6016 : 113429 : Toggles a query-plan-level optimization which tries to use the vector similarity index.
6017 : 113429 : Only takes effect if setting [`query_plan_enable_optimizations`](#query_plan_enable_optimizations) is 1.
6018 : 113429 :
6019 : 113429 : :::note
6020 : 113429 : 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.
6021 : 113429 : :::
6022 : 113429 :
6023 : 113429 : Possible values:
6024 : 113429 :
6025 : 113429 : - 0 - Disable
6026 : 113429 : - 1 - Enable
6027 : 113429 : )", 0) \
6028 : 113429 : DECLARE(Bool, query_plan_enable_multithreading_after_window_functions, true, R"(
6029 : 113429 : Enable multithreading after evaluating window functions to allow parallel stream processing
6030 : 113429 : )", 0) \
6031 : 113429 : DECLARE(Bool, query_plan_optimize_lazy_materialization, true, R"(
6032 : 113429 : Use query plan for lazy materialization optimization.
6033 : 113429 : )", 0) \
6034 : 113429 : DECLARE(UInt64, query_plan_max_limit_for_lazy_materialization, 10000, R"(Control maximum limit value that allows to use query plan for lazy materialization optimization. If zero, there is no limit.
6035 : 113429 : )", 0) \
6036 : 113429 : DECLARE(Bool, query_plan_optimize_lazy_final, false, R"(
6037 : 113429 : Optimize reading with FINAL from ReplacingMergeTree by building a set of primary keys and using it for index analysis.
6038 : 113429 : )", 0) \
6039 : 113429 : DECLARE(UInt64, max_rows_for_lazy_final, 10000000, R"(
6040 : 113429 : Maximum number of rows in the set for lazy FINAL optimization. If exceeded, falls back to normal FINAL.
6041 : 113429 : )", 0) \
6042 : 113429 : DECLARE(UInt64, max_bytes_for_lazy_final, 256000000, R"(
6043 : 113429 : Maximum number of bytes in the set for lazy FINAL optimization. If exceeded, falls back to normal FINAL.
6044 : 113429 : )", 0) \
6045 : 113429 : DECLARE(Float, min_filtered_ratio_for_lazy_final, 0.5, R"(
6046 : 113429 : Minimum ratio of marks filtered by index analysis for lazy FINAL optimization. If less than this fraction of marks is filtered, falls back to normal FINAL. Value 0 disables this check.
6047 : 113429 : )", 0) \
6048 : 113429 : DECLARE(Bool, enable_lazy_columns_replication, true, R"(
6049 : 113429 : Enables lazy columns replication in JOIN and ARRAY JOIN, it allows to avoid unnecessary copy of the same rows multiple times in memory.
6050 : 113429 : )", 0) \
6051 : 113429 : DECLARE_WITH_ALIAS(Bool, query_plan_use_new_logical_join_step, true, R"(
6052 : 113429 : Use logical join step in query plan.
6053 : 113429 : Note: setting `query_plan_use_new_logical_join_step` is deprecated, use `query_plan_use_logical_join_step` instead.
6054 : 113429 : )", 0, query_plan_use_logical_join_step) \
6055 : 113429 : DECLARE(Bool, serialize_query_plan, false, R"(
6056 : 113429 : Serialize query plan for distributed processing
6057 : 113429 : )", 0) \
6058 : 113429 : DECLARE(Bool, correlated_subqueries_substitute_equivalent_expressions, true, R"(
6059 : 113429 : Use filter expressions to inference equivalent expressions and substitute them instead of creating a CROSS JOIN.
6060 : 113429 : )", 0) \
6061 : 113429 : DECLARE(DecorrelationJoinKind, correlated_subqueries_default_join_kind, DecorrelationJoinKind::RIGHT, R"(
6062 : 113429 : Controls the kind of joins in the decorrelated query plan. The default value is `right`, which means that decorrelated plan will contain RIGHT JOINs with subquery input on the right side.
6063 : 113429 :
6064 : 113429 : Possible values:
6065 : 113429 :
6066 : 113429 : - `left` - Decorrelation process will produce LEFT JOINs and input table will appear on the left side.
6067 : 113429 : - `right` - Decorrelation process will produce RIGHT JOINs and input table will appear on the right side.
6068 : 113429 : )", 0) \
6069 : 113429 : DECLARE(Bool, correlated_subqueries_use_in_memory_buffer, true, R"(
6070 : 113429 : Use in-memory buffer for correlated subquery input to avoid its repeated evaluation.
6071 : 113429 : )", 0) \
6072 : 113429 : DECLARE(Bool, optimize_qbit_distance_function_reads, true, R"(
6073 : 113429 : Replace distance functions on `QBit` data type with equivalent ones that only read the columns necessary for the calculation from the storage.
6074 : 113429 : )", 0) \
6075 : 113429 : \
6076 : 113429 : DECLARE(UInt64, regexp_max_matches_per_row, 1000, R"(
6077 : 113429 : 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](/sql-reference/functions/string-search-functions#extractAllGroupsHorizontal) function.
6078 : 113429 :
6079 : 113429 : Possible values:
6080 : 113429 :
6081 : 113429 : - Positive integer.
6082 : 113429 : )", 0) \
6083 : 113429 : \
6084 : 113429 : DECLARE(UInt64, highlight_max_matches_per_row, 10000, R"(
6085 : 113429 : Sets the maximum number of highlight matches per row in the [highlight](/sql-reference/functions/string-search-functions#highlight) function. Use it to protect against excessive memory usage when highlighting highly repetitive patterns in large texts.
6086 : 113429 :
6087 : 113429 : Possible values:
6088 : 113429 :
6089 : 113429 : - Positive integer.
6090 : 113429 : )", 0) \
6091 : 113429 : \
6092 : 113429 : DECLARE(UInt64, limit, 0, R"(
6093 : 113429 : Sets the maximum number of rows to get from the query result. It adjusts the value set by the [LIMIT](/sql-reference/statements/select/limit) clause, so that the limit, specified in the query, cannot exceed the limit, set by this setting.
6094 : 113429 :
6095 : 113429 : Possible values:
6096 : 113429 :
6097 : 113429 : - 0 — The number of rows is not limited.
6098 : 113429 : - Positive integer.
6099 : 113429 : )", 0) \
6100 : 113429 : DECLARE(UInt64, offset, 0, R"(
6101 : 113429 : Sets the number of rows to skip before starting to return rows from the query. It adjusts the offset set by the [OFFSET](/sql-reference/statements/select/offset) clause, so that these two values are summarized.
6102 : 113429 :
6103 : 113429 : Possible values:
6104 : 113429 :
6105 : 113429 : - 0 — No rows are skipped .
6106 : 113429 : - Positive integer.
6107 : 113429 :
6108 : 113429 : **Example**
6109 : 113429 :
6110 : 113429 : Input table:
6111 : 113429 :
6112 : 113429 : ```sql
6113 : 113429 : CREATE TABLE test (i UInt64) ENGINE = MergeTree() ORDER BY i;
6114 : 113429 : INSERT INTO test SELECT number FROM numbers(500);
6115 : 113429 : ```
6116 : 113429 :
6117 : 113429 : Query:
6118 : 113429 :
6119 : 113429 : ```sql
6120 : 113429 : SET limit = 5;
6121 : 113429 : SET offset = 7;
6122 : 113429 : SELECT * FROM test LIMIT 10 OFFSET 100;
6123 : 113429 : ```
6124 : 113429 : Result:
6125 : 113429 :
6126 : 113429 : ```text
6127 : 113429 : ┌───i─┐
6128 : 113429 : │ 107 │
6129 : 113429 : │ 108 │
6130 : 113429 : │ 109 │
6131 : 113429 : └─────┘
6132 : 113429 : ```
6133 : 113429 : )", 0) \
6134 : 113429 : \
6135 : 113429 : DECLARE(UInt64, function_range_max_elements_in_block, 500000000, R"(
6136 : 113429 : Sets the safety threshold for data volume generated by function [range](/sql-reference/functions/array-functions#range). Defines the maximum number of values generated by function per block of data (sum of array sizes for every row in a block).
6137 : 113429 :
6138 : 113429 : Possible values:
6139 : 113429 :
6140 : 113429 : - Positive integer.
6141 : 113429 :
6142 : 113429 : **See Also**
6143 : 113429 :
6144 : 113429 : - [`max_block_size`](#max_block_size)
6145 : 113429 : - [`min_insert_block_size_rows`](#min_insert_block_size_rows)
6146 : 113429 : )", 0) \
6147 : 113429 : DECLARE(UInt64, function_sleep_max_microseconds_per_block, 3000000, R"(
6148 : 113429 : Maximum number of microseconds the function `sleep` is allowed to sleep for each block. If a user called it with a larger value, it throws an exception. It is a safety threshold.
6149 : 113429 : )", 0) \
6150 : 113429 : DECLARE(UInt64, function_visible_width_behavior, 1, R"(
6151 : 113429 : The version of `visibleWidth` behavior. 0 - only count the number of code points; 1 - correctly count zero-width and combining characters, count full-width characters as two, estimate the tab width, count delete characters.
6152 : 113429 : )", 0) \
6153 : 113429 : DECLARE(ShortCircuitFunctionEvaluation, short_circuit_function_evaluation, ShortCircuitFunctionEvaluation::ENABLE, R"(
6154 : 113429 : Allows calculating the [if](../../sql-reference/functions/conditional-functions.md/#if), [multiIf](../../sql-reference/functions/conditional-functions.md/#multiIf), [and](/sql-reference/functions/logical-functions#and), and [or](/sql-reference/functions/logical-functions#or) functions according to a [short scheme](https://en.wikipedia.org/wiki/Short-circuit_evaluation). 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).
6155 : 113429 :
6156 : 113429 : Possible values:
6157 : 113429 :
6158 : 113429 : - `enable` — Enables short-circuit function evaluation for functions that are suitable for it (can throw an exception or computationally heavy).
6159 : 113429 : - `force_enable` — Enables short-circuit function evaluation for all functions.
6160 : 113429 : - `disable` — Disables short-circuit function evaluation.
6161 : 113429 : )", 0) \
6162 : 113429 : \
6163 : 113429 : DECLARE(LocalFSReadMethod, storage_file_read_method, LocalFSReadMethod::pread, R"(
6164 : 113429 : 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).
6165 : 113429 : )", 0) \
6166 : 113429 : DECLARE(String, local_filesystem_read_method, "pread_threadpool", R"(
6167 : 113429 : Method of reading data from local filesystem, one of: read, pread, mmap, io_uring, pread_threadpool.
6168 : 113429 :
6169 : 113429 : 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.
6170 : 113429 : If you read various articles about 'io_uring' on the Internet, don't be blinded by them. It is not a better method of reading files, unless the case of a large amount of small IO requests, which is not the case in ClickHouse. There are no reasons to enable 'io_uring'.
6171 : 113429 : )", 0) \
6172 : 113429 : DECLARE(String, remote_filesystem_read_method, "threadpool", R"(
6173 : 113429 : Method of reading data from remote filesystem, one of: read, threadpool.
6174 : 113429 : )", 0) \
6175 : 113429 : DECLARE(Bool, local_filesystem_read_prefetch, false, R"(
6176 : 113429 : Should use prefetching when reading data from local filesystem.
6177 : 113429 : )", 0) \
6178 : 113429 : DECLARE(Bool, remote_filesystem_read_prefetch, true, R"(
6179 : 113429 : Should use prefetching when reading data from remote filesystem.
6180 : 113429 : )", 0) \
6181 : 113429 : DECLARE(Int64, read_priority, 0, R"(
6182 : 113429 : Priority to read data from local filesystem or remote filesystem. Only supported for 'pread_threadpool' method for local filesystem and for `threadpool` method for remote filesystem.
6183 : 113429 : )", 0) \
6184 : 113429 : DECLARE(UInt64, merge_tree_min_rows_for_concurrent_read_for_remote_filesystem, 0, R"(
6185 : 113429 : The minimum number of lines to read from one file before the [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md) engine can parallelize reading, when reading from remote filesystem. We do not recommend using this setting.
6186 : 113429 :
6187 : 113429 : Possible values:
6188 : 113429 :
6189 : 113429 : - Positive integer.
6190 : 113429 : )", 0) \
6191 : 113429 : DECLARE(UInt64, merge_tree_min_bytes_for_concurrent_read_for_remote_filesystem, 0, R"(
6192 : 113429 : The minimum number of bytes to read from one file before [MergeTree](../../engines/table-engines/mergetree-family/mergetree.md) engine can parallelize reading, when reading from remote filesystem. We do not recommend using this setting.
6193 : 113429 :
6194 : 113429 : Possible values:
6195 : 113429 :
6196 : 113429 : - Positive integer.
6197 : 113429 : )", 0) \
6198 : 113429 : DECLARE(UInt64, remote_read_min_bytes_for_seek, 4 * DBMS_DEFAULT_BUFFER_SIZE, R"(
6199 : 113429 : Min bytes required for remote read (url, s3) to do seek, instead of read with ignore.
6200 : 113429 : )", 0) \
6201 : 113429 : DECLARE_WITH_ALIAS(UInt64, merge_tree_min_bytes_per_task_for_remote_reading, 2 * DBMS_DEFAULT_BUFFER_SIZE, R"(
6202 : 113429 : Min bytes to read per task.
6203 : 113429 : )", 0, filesystem_prefetch_min_bytes_for_single_read_task) \
6204 : 113429 : DECLARE(Bool, merge_tree_use_const_size_tasks_for_remote_reading, true, R"(
6205 : 113429 : Whether to use constant size tasks for reading from a remote table.
6206 : 113429 : )", 0) \
6207 : 113429 : DECLARE(Bool, merge_tree_determine_task_size_by_prewhere_columns, true, R"(
6208 : 113429 : Whether to use only prewhere columns size to determine reading task size.
6209 : 113429 : )", 0) \
6210 : 113429 : DECLARE(NonZeroUInt64, merge_tree_min_read_task_size, 8, R"(
6211 : 113429 : Hard lower limit on the task size (even when the number of granules is low and the number of available threads is high we won't allocate smaller tasks
6212 : 113429 : )", 0) \
6213 : 113429 : DECLARE(UInt64, merge_tree_compact_parts_min_granules_to_multibuffer_read, 16, R"(
6214 : 113429 : Only has an effect 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.
6215 : 113429 : )", 0) \
6216 : 113429 : \
6217 : 113429 : DECLARE(Bool, async_insert, true, R"(
6218 : 113429 : If true, data from INSERT query is stored in queue and later flushed to table in background. If wait_for_async_insert is false, INSERT query is processed almost instantly, otherwise client will wait until data will be flushed to table
6219 : 113429 : )", 0) \
6220 : 113429 : DECLARE(Bool, wait_for_async_insert, true, R"(
6221 : 113429 : If true wait for processing of asynchronous insertion
6222 : 113429 : )", 0) \
6223 : 113429 : DECLARE(Seconds, wait_for_async_insert_timeout, DBMS_DEFAULT_LOCK_ACQUIRE_TIMEOUT_SEC, R"(
6224 : 113429 : Timeout for waiting for processing asynchronous insertion
6225 : 113429 : )", 0) \
6226 : 113429 : DECLARE(UInt64, async_insert_max_data_size, 10485760, R"(
6227 : 113429 : Maximum size in bytes of unparsed data collected per query before being inserted
6228 : 113429 :
6229 : 113429 : Cloud default value: `104857600` (100 MiB).
6230 : 113429 : )", 0) \
6231 : 113429 : DECLARE(UInt64, async_insert_max_query_number, 450, R"(
6232 : 113429 : Maximum number of insert queries before being inserted.
6233 : 113429 : Only takes effect if setting [`async_insert_deduplicate`](#async_insert_deduplicate) is 1.
6234 : 113429 : )", 0) \
6235 : 113429 : DECLARE(Milliseconds, async_insert_poll_timeout_ms, 10, R"(
6236 : 113429 : Timeout for polling data from asynchronous insert queue
6237 : 113429 : )", 0) \
6238 : 113429 : DECLARE(Bool, async_insert_use_adaptive_busy_timeout, true, R"(
6239 : 113429 : If it is set to true, use adaptive busy timeout for asynchronous inserts
6240 : 113429 : )", 0) \
6241 : 113429 : DECLARE(Milliseconds, async_insert_busy_timeout_min_ms, 50, R"(
6242 : 113429 : If auto-adjusting is enabled through async_insert_use_adaptive_busy_timeout, minimum time to wait before dumping collected data per query since the first data appeared. It also serves as the initial value for the adaptive algorithm
6243 : 113429 : )", 0) \
6244 : 113429 : DECLARE_WITH_ALIAS(Milliseconds, async_insert_busy_timeout_max_ms, 200, R"(
6245 : 113429 : Maximum time to wait before dumping collected data per query since the first data appeared.
6246 : 113429 :
6247 : 113429 : Cloud default value: `1000` (1s).
6248 : 113429 : )", 0, async_insert_busy_timeout_ms) \
6249 : 113429 : DECLARE(Double, async_insert_busy_timeout_increase_rate, 0.2, R"(
6250 : 113429 : The exponential growth rate at which the adaptive asynchronous insert timeout increases
6251 : 113429 : )", 0) \
6252 : 113429 : DECLARE(Double, async_insert_busy_timeout_decrease_rate, 0.2, R"(
6253 : 113429 : The exponential growth rate at which the adaptive asynchronous insert timeout decreases
6254 : 113429 : )", 0) \
6255 : 113429 : \
6256 : 113429 : DECLARE(UInt64, remote_fs_read_max_backoff_ms, 10000, R"(
6257 : 113429 : Max wait time when trying to read data for remote disk
6258 : 113429 : )", 0) \
6259 : 113429 : DECLARE(UInt64, remote_fs_read_backoff_max_tries, 5, R"(
6260 : 113429 : Max attempts to read with backoff
6261 : 113429 : )", 0) \
6262 : 113429 : DECLARE(Bool, cluster_function_process_archive_on_multiple_nodes, true, R"(
6263 : 113429 : If set to `true`, increases performance of processing archives in cluster functions. Should be set to `false` for compatibility and to avoid errors during upgrade to 25.7+ if using cluster functions with archives on earlier versions.
6264 : 113429 : )", 0) \
6265 : 113429 : DECLARE(UInt64, max_streams_for_files_processing_in_cluster_functions, 0, R"(
6266 : 113429 : If is not zero, limit the number of threads reading data from files in *Cluster table functions.
6267 : 113429 : )", 0) \
6268 : 113429 : DECLARE(Bool, enable_filesystem_cache, true, R"(
6269 : 113429 : Use cache for remote filesystem. This setting does not turn on/off cache for disks (must be done via disk config), but allows to bypass cache for some queries if intended
6270 : 113429 : )", 0) \
6271 : 113429 : DECLARE(String, filesystem_cache_name, "", R"(
6272 : 113429 : Filesystem cache name to use for stateless table engines or data lakes
6273 : 113429 : )", 0) \
6274 : 113429 : DECLARE(Bool, enable_filesystem_cache_on_write_operations, false, R"(
6275 : 113429 : Enables or disables `write-through` cache. If set to `false`, the `write-through` cache is disabled for write operations. If set to `true`, `write-through` cache is enabled as long as `cache_on_write_operations` is turned on in the server config's cache disk configuration section.
6276 : 113429 : See ["Using local cache"](/operations/storing-data#using-local-cache) for more details.
6277 : 113429 :
6278 : 113429 : Cloud default value: `1`.
6279 : 113429 : )", 0) \
6280 : 113429 : DECLARE(Bool, enable_filesystem_cache_log, false, R"(
6281 : 113429 : Allows to record the filesystem caching log for each query
6282 : 113429 : )", 0) \
6283 : 113429 : DECLARE(Bool, read_from_filesystem_cache_if_exists_otherwise_bypass_cache, false, R"(
6284 : 113429 : Allow to use the filesystem cache in passive mode - benefit from the existing cache entries, but don't put more entries into the cache. If you set this setting for heavy ad-hoc queries and leave it disabled for short real-time queries, this will allows to avoid cache threshing by too heavy queries and to improve the overall system efficiency.
6285 : 113429 : )", 0) \
6286 : 113429 : DECLARE_WITH_ALIAS(Bool, filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit, true, R"(
6287 : 113429 : Skip download from remote filesystem if exceeds query cache size
6288 : 113429 : )", 0, skip_download_if_exceeds_query_cache) \
6289 : 113429 : DECLARE(UInt64, filesystem_cache_max_download_size, (128UL * 1024 * 1024 * 1024), R"(
6290 : 113429 : Max remote filesystem cache size that can be downloaded by a single query
6291 : 113429 : )", 0) \
6292 : 113429 : DECLARE(Bool, throw_on_error_from_cache_on_write_operations, false, R"(
6293 : 113429 : Ignore error from cache when caching on write operations (INSERT, merges)
6294 : 113429 : )", 0) \
6295 : 113429 : DECLARE(UInt64, filesystem_cache_segments_batch_size, 20, R"(
6296 : 113429 : Limit on size of a single batch of file segments that a read buffer can request from cache. Too low value will lead to excessive requests to cache, too large may slow down eviction from cache
6297 : 113429 : )", 0) \
6298 : 113429 : DECLARE(UInt64, filesystem_cache_reserve_space_wait_lock_timeout_milliseconds, 1000, R"(
6299 : 113429 : Wait time to lock cache for space reservation in filesystem cache
6300 : 113429 : )", 0) \
6301 : 113429 : DECLARE(Bool, filesystem_cache_prefer_bigger_buffer_size, true, R"(
6302 : 113429 : Prefer bigger buffer size if filesystem cache is enabled to avoid writing small file segments which deteriorate cache performance. On the other hand, enabling this setting might increase memory usage.
6303 : 113429 : )", 0) \
6304 : 113429 : DECLARE(UInt64, filesystem_cache_boundary_alignment, 0, R"(
6305 : 113429 : Filesystem cache boundary alignment. This setting is applied only for non-disk read (e.g. for cache of remote table engines / table functions, but not for storage configuration of MergeTree tables). Value 0 means no alignment.
6306 : 113429 : )", 0) \
6307 : 113429 : DECLARE(UInt64, temporary_data_in_cache_reserve_space_wait_lock_timeout_milliseconds, (10 * 60 * 1000), R"(
6308 : 113429 : Wait time to lock cache for space reservation for temporary data in filesystem cache
6309 : 113429 : )", 0) \
6310 : 113429 : \
6311 : 113429 : DECLARE(Bool, use_page_cache_for_disks_without_file_cache, false, R"(
6312 : 113429 : Use userspace page cache for remote disks that don't have filesystem cache enabled.
6313 : 113429 : )", 0) \
6314 : 113429 : DECLARE(Bool, use_page_cache_with_distributed_cache, false, R"(
6315 : 113429 : Use userspace page cache when distributed cache is used.
6316 : 113429 : )", 0) \
6317 : 113429 : DECLARE(Bool, use_page_cache_for_local_disks, false, R"(
6318 : 113429 : Use userspace page cache when reading from local disks. Used for testing, unlikely to improve performance in practice. Requires local_filesystem_read_method = 'pread' or 'read'. Doesn't disable the OS page cache; min_bytes_to_use_direct_io can be used for that. Only affects regular tables, not file() table function or File() table engine.
6319 : 113429 : )", 0) \
6320 : 113429 : DECLARE(Bool, use_page_cache_for_object_storage, false, R"(
6321 : 113429 : Use userspace page cache when reading from object storage table functions (s3, azure, hdfs) and table engines (S3, Azure, HDFS).
6322 : 113429 : )", 0) \
6323 : 113429 : DECLARE(Bool, read_from_page_cache_if_exists_otherwise_bypass_cache, false, R"(
6324 : 113429 : Use userspace page cache in passive mode, similar to read_from_filesystem_cache_if_exists_otherwise_bypass_cache.
6325 : 113429 : )", 0) \
6326 : 113429 : DECLARE(Bool, page_cache_inject_eviction, false, R"(
6327 : 113429 : Userspace page cache will sometimes invalidate some pages at random. Intended for testing.
6328 : 113429 : )", 0) \
6329 : 113429 : DECLARE(UInt64, page_cache_block_size, 1048576, R"(
6330 : 113429 : Size of file chunks to store in the userspace page cache, in bytes. All reads that go through the cache will be rounded up to a multiple of this size.
6331 : 113429 :
6332 : 113429 : This setting can be adjusted on a per-query level basis, but cache entries with different block sizes cannot be reused. Changing this setting effectively invalidates existing entries in the cache.
6333 : 113429 :
6334 : 113429 : A higher value, like 1 MiB is good for high-throughput queries, and a lower value, like 64 KiB is good for low-latency point queries.
6335 : 113429 : )", 0) \
6336 : 113429 : DECLARE(UInt64, page_cache_lookahead_blocks, 16, R"(
6337 : 113429 : On userspace page cache miss, read up to this many consecutive blocks at once from the underlying storage, if they're also not in the cache. Each block is page_cache_block_size bytes.
6338 : 113429 :
6339 : 113429 : A higher value is good for high-throughput queries, while low-latency point queries will work better without readahead.
6340 : 113429 : )", 0) \
6341 : 113429 : \
6342 : 113429 : DECLARE(Bool, load_marks_asynchronously, false, R"(
6343 : 113429 : Load MergeTree marks asynchronously
6344 : 113429 :
6345 : 113429 : Cloud default value: `1`.
6346 : 113429 : )", 0) \
6347 : 113429 : DECLARE(Bool, enable_filesystem_read_prefetches_log, false, R"(
6348 : 113429 : Log to system.filesystem prefetch_log during query. Should be used only for testing or debugging, not recommended to be turned on by default
6349 : 113429 : )", 0) \
6350 : 113429 : DECLARE(Bool, allow_prefetched_read_pool_for_remote_filesystem, true, R"(
6351 : 113429 : Prefer prefetched threadpool if all parts are on remote filesystem
6352 : 113429 : )", 0) \
6353 : 113429 : DECLARE(Bool, allow_prefetched_read_pool_for_local_filesystem, false, R"(
6354 : 113429 : Prefer prefetched threadpool if all parts are on local filesystem
6355 : 113429 : )", 0) \
6356 : 113429 : \
6357 : 113429 : DECLARE(UInt64, prefetch_buffer_size, DBMS_DEFAULT_BUFFER_SIZE, R"(
6358 : 113429 : The maximum size of the prefetch buffer to read from the filesystem.
6359 : 113429 : )", 0) \
6360 : 113429 : DECLARE(UInt64, filesystem_prefetch_step_bytes, 0, R"(
6361 : 113429 : Prefetch step in bytes. Zero means `auto` - approximately the best prefetch step will be auto deduced, but might not be 100% the best. The actual value might be different because of setting filesystem_prefetch_min_bytes_for_single_read_task
6362 : 113429 : )", 0) \
6363 : 113429 : DECLARE(UInt64, filesystem_prefetch_step_marks, 0, R"(
6364 : 113429 : Prefetch step in marks. Zero means `auto` - approximately the best prefetch step will be auto deduced, but might not be 100% the best. The actual value might be different because of setting filesystem_prefetch_min_bytes_for_single_read_task
6365 : 113429 : )", 0) \
6366 : 113429 : DECLARE(NonZeroUInt64, filesystem_prefetch_max_memory_usage, "1Gi", R"(
6367 : 113429 : Maximum memory usage for prefetches.
6368 : 113429 :
6369 : 113429 : Cloud default value: 10% of total memory.
6370 : 113429 : )", 0) \
6371 : 113429 : DECLARE(UInt64, filesystem_prefetches_limit, 200, R"(
6372 : 113429 : Maximum number of prefetches. Zero means unlimited. A setting `filesystem_prefetches_max_memory_usage` is more recommended if you want to limit the number of prefetches
6373 : 113429 : )", 0) \
6374 : 113429 : \
6375 : 113429 : DECLARE(Bool, allow_calculating_subcolumns_sizes_for_merge_tree_reading, true, R"(
6376 : 113429 : When enabled, ClickHouse will calculate the size of files required for each subcolumn reading for better task and block sizes calculation.
6377 : 113429 : )", 0) \
6378 : 113429 : \
6379 : 113429 : DECLARE(UInt64, use_structure_from_insertion_table_in_table_functions, 2, R"(
6380 : 113429 : Use structure from insertion table instead of schema inference from data. Possible values: 0 - disabled, 1 - enabled, 2 - auto
6381 : 113429 : )", 0) \
6382 : 113429 : \
6383 : 113429 : DECLARE(UInt64, http_max_tries, 10, R"(
6384 : 113429 : Max attempts to read via http.
6385 : 113429 : )", 0) \
6386 : 113429 : DECLARE(UInt64, http_retry_initial_backoff_ms, 100, R"(
6387 : 113429 : Min milliseconds for backoff, when retrying read via http
6388 : 113429 : )", 0) \
6389 : 113429 : DECLARE(UInt64, http_retry_max_backoff_ms, 10000, R"(
6390 : 113429 : Max milliseconds for backoff, when retrying read via http
6391 : 113429 : )", 0) \
6392 : 113429 : \
6393 : 113429 : DECLARE(Bool, force_remove_data_recursively_on_drop, false, R"(
6394 : 113429 : Recursively remove data on DROP query. Avoids 'Directory not empty' error, but may silently remove detached data
6395 : 113429 : )", 0) \
6396 : 113429 : DECLARE(Bool, check_table_dependencies, true, R"(
6397 : 113429 : Check that DDL query (such as DROP TABLE or RENAME) will not break dependencies
6398 : 113429 : )", 0) \
6399 : 113429 : DECLARE(Bool, check_referential_table_dependencies, false, R"(
6400 : 113429 : Check that DDL query (such as DROP TABLE or RENAME) will not break referential dependencies
6401 : 113429 : )", 0) \
6402 : 113429 : DECLARE(Bool, check_named_collection_dependencies, true, R"(
6403 : 113429 : Check that DROP NAMED COLLECTION will not break tables that depend on it
6404 : 113429 : )", 0) \
6405 : 113429 : \
6406 : 113429 : DECLARE(Bool, allow_unrestricted_reads_from_keeper, false, R"(
6407 : 113429 : Allow unrestricted (without condition on path) reads from system.zookeeper table, can be handy, but is not safe for zookeeper
6408 : 113429 : )", 0) \
6409 : 113429 : DECLARE(Bool, allow_deprecated_database_ordinary, false, R"(
6410 : 113429 : Allow to create databases with deprecated Ordinary engine
6411 : 113429 : )", 0) \
6412 : 113429 : DECLARE(Bool, allow_deprecated_syntax_for_merge_tree, false, R"(
6413 : 113429 : Allow to create *MergeTree tables with deprecated engine definition syntax
6414 : 113429 : )", 0) \
6415 : 113429 : DECLARE(Bool, allow_asynchronous_read_from_io_pool_for_merge_tree, false, R"(
6416 : 113429 : Use background I/O pool to read from MergeTree tables. This setting may increase performance for I/O bound queries
6417 : 113429 : )", 0) \
6418 : 113429 : DECLARE(UInt64, max_streams_for_merge_tree_reading, 0, R"(
6419 : 113429 : If is not zero, limit the number of reading streams for MergeTree table.
6420 : 113429 : )", 0) \
6421 : 113429 : \
6422 : 113429 : DECLARE(Bool, force_grouping_standard_compatibility, true, R"(
6423 : 113429 : Make GROUPING function to return 1 when argument is not used as an aggregation key
6424 : 113429 : )", 0) \
6425 : 113429 : \
6426 : 113429 : DECLARE(Bool, schema_inference_use_cache_for_file, true, R"(
6427 : 113429 : Use cache in schema inference while using file table function
6428 : 113429 : )", 0) \
6429 : 113429 : DECLARE(Bool, schema_inference_use_cache_for_s3, true, R"(
6430 : 113429 : Use cache in schema inference while using s3 table function
6431 : 113429 : )", 0) \
6432 : 113429 : DECLARE(Bool, schema_inference_use_cache_for_azure, true, R"(
6433 : 113429 : Use cache in schema inference while using azure table function
6434 : 113429 : )", 0) \
6435 : 113429 : DECLARE(Bool, schema_inference_use_cache_for_hdfs, true, R"(
6436 : 113429 : Use cache in schema inference while using hdfs table function
6437 : 113429 : )", 0) \
6438 : 113429 : DECLARE(Bool, schema_inference_use_cache_for_url, true, R"(
6439 : 113429 : Use cache in schema inference while using url table function
6440 : 113429 : )", 0) \
6441 : 113429 : DECLARE(Bool, schema_inference_cache_require_modification_time_for_url, true, R"(
6442 : 113429 : Use schema from cache for URL with last modification time validation (for URLs with Last-Modified header)
6443 : 113429 : )", 0) \
6444 : 113429 : \
6445 : 113429 : DECLARE(String, compatibility, "", R"(
6446 : 113429 : The `compatibility` setting causes ClickHouse to use the default settings of a previous version of ClickHouse, where the previous version is provided as the setting.
6447 : 113429 :
6448 : 113429 : If settings are set to non-default values, then those settings are honored (only settings that have not been modified are affected by the `compatibility` setting).
6449 : 113429 :
6450 : 113429 : This setting takes a ClickHouse version number as a string, like `22.3`, `22.8`. An empty value means that this setting is disabled.
6451 : 113429 :
6452 : 113429 : Disabled by default.
6453 : 113429 :
6454 : 113429 : :::note
6455 : 113429 : In ClickHouse Cloud, the service-level default compatibility setting must be set by ClickHouse Cloud support. Please [open a case](https://clickhouse.cloud/support) to have it set.
6456 : 113429 : However, the compatibility setting can be overridden at the user, role, profile, query, or session level using standard ClickHouse setting mechanisms such as `SET compatibility = '22.3'` in a session or `SETTINGS compatibility = '22.3'` in a query.
6457 : 113429 : :::
6458 : 113429 : )", 0) \
6459 : 113429 : \
6460 : 113429 : DECLARE(Map, additional_table_filters, "", R"(
6461 : 113429 : An additional filter expression that is applied after reading
6462 : 113429 : from the specified table.
6463 : 113429 :
6464 : 113429 : **Example**
6465 : 113429 :
6466 : 113429 : ```sql
6467 : 113429 : INSERT INTO table_1 VALUES (1, 'a'), (2, 'bb'), (3, 'ccc'), (4, 'dddd');
6468 : 113429 : SELECT * FROM table_1;
6469 : 113429 : ```
6470 : 113429 : ```response
6471 : 113429 : ┌─x─┬─y────┐
6472 : 113429 : │ 1 │ a │
6473 : 113429 : │ 2 │ bb │
6474 : 113429 : │ 3 │ ccc │
6475 : 113429 : │ 4 │ dddd │
6476 : 113429 : └───┴──────┘
6477 : 113429 : ```
6478 : 113429 : ```sql
6479 : 113429 : SELECT *
6480 : 113429 : FROM table_1
6481 : 113429 : SETTINGS additional_table_filters = {'table_1': 'x != 2'}
6482 : 113429 : ```
6483 : 113429 : ```response
6484 : 113429 : ┌─x─┬─y────┐
6485 : 113429 : │ 1 │ a │
6486 : 113429 : │ 3 │ ccc │
6487 : 113429 : │ 4 │ dddd │
6488 : 113429 : └───┴──────┘
6489 : 113429 : ```
6490 : 113429 : )", 0) \
6491 : 113429 : DECLARE(String, additional_result_filter, "", R"(
6492 : 113429 : An additional filter expression to apply to the result of `SELECT` query.
6493 : 113429 : This setting is not applied to any subquery.
6494 : 113429 :
6495 : 113429 : **Example**
6496 : 113429 :
6497 : 113429 : ```sql
6498 : 113429 : INSERT INTO table_1 VALUES (1, 'a'), (2, 'bb'), (3, 'ccc'), (4, 'dddd');
6499 : 113429 : SElECT * FROM table_1;
6500 : 113429 : ```
6501 : 113429 : ```response
6502 : 113429 : ┌─x─┬─y────┐
6503 : 113429 : │ 1 │ a │
6504 : 113429 : │ 2 │ bb │
6505 : 113429 : │ 3 │ ccc │
6506 : 113429 : │ 4 │ dddd │
6507 : 113429 : └───┴──────┘
6508 : 113429 : ```
6509 : 113429 : ```sql
6510 : 113429 : SELECT *
6511 : 113429 : FROM table_1
6512 : 113429 : SETTINGS additional_result_filter = 'x != 2'
6513 : 113429 : ```
6514 : 113429 : ```response
6515 : 113429 : ┌─x─┬─y────┐
6516 : 113429 : │ 1 │ a │
6517 : 113429 : │ 3 │ ccc │
6518 : 113429 : │ 4 │ dddd │
6519 : 113429 : └───┴──────┘
6520 : 113429 : ```
6521 : 113429 : )", 0) \
6522 : 113429 : \
6523 : 113429 : DECLARE(String, workload, "default", R"(
6524 : 113429 : Name of workload to be used to access resources
6525 : 113429 : )", 0) \
6526 : 113429 : DECLARE(Milliseconds, storage_system_stack_trace_pipe_read_timeout_ms, 100, R"(
6527 : 113429 : 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.
6528 : 113429 : )", 0) \
6529 : 113429 : \
6530 : 113429 : DECLARE(String, rename_files_after_processing, "", R"(
6531 : 113429 : - **Type:** String
6532 : 113429 :
6533 : 113429 : - **Default value:** Empty string
6534 : 113429 :
6535 : 113429 : 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.
6536 : 113429 :
6537 : 113429 : ### Placeholders
6538 : 113429 :
6539 : 113429 : - `%a` — Full original filename (e.g., "sample.csv").
6540 : 113429 : - `%f` — Original filename without extension (e.g., "sample").
6541 : 113429 : - `%e` — Original file extension with dot (e.g., ".csv").
6542 : 113429 : - `%t` — Timestamp (in microseconds).
6543 : 113429 : - `%%` — Percentage sign ("%").
6544 : 113429 :
6545 : 113429 : ### Example
6546 : 113429 : - Option: `--rename_files_after_processing="processed_%f_%t%e"`
6547 : 113429 :
6548 : 113429 : - Query: `SELECT * FROM file('sample.csv')`
6549 : 113429 :
6550 : 113429 :
6551 : 113429 : If reading `sample.csv` is successful, file will be renamed to `processed_sample_1683473210851438.csv`
6552 : 113429 : )", 0) \
6553 : 113429 : \
6554 : 113429 : /* CLOUD ONLY */ \
6555 : 113429 : DECLARE(Bool, read_through_distributed_cache, false, R"(
6556 : 113429 : Only has an effect in ClickHouse Cloud. Allow reading from distributed cache
6557 : 113429 : )", 0) \
6558 : 113429 : DECLARE(Bool, write_through_distributed_cache, false, R"(
6559 : 113429 : Only has an effect in ClickHouse Cloud. Allow writing to distributed cache (writing to s3 will also be done by distributed cache)
6560 : 113429 : )", 0) \
6561 : 113429 : DECLARE(Bool, distributed_cache_throw_on_error, false, R"(
6562 : 113429 : Only has an effect in ClickHouse Cloud. Rethrow exception happened during communication with distributed cache or exception received from distributed cache. Otherwise fallback to skipping distributed cache on error
6563 : 113429 : )", 0) \
6564 : 113429 : DECLARE(DistributedCacheLogMode, distributed_cache_log_mode, DistributedCacheLogMode::LOG_ON_ERROR, R"(
6565 : 113429 : Only has an effect in ClickHouse Cloud. Mode for writing to system.distributed_cache_log
6566 : 113429 : )", 0) \
6567 : 113429 : DECLARE(Bool, distributed_cache_fetch_metrics_only_from_current_az, true, R"(
6568 : 113429 : Only has an effect in ClickHouse Cloud. Fetch metrics only from current availability zone in system.distributed_cache_metrics, system.distributed_cache_events
6569 : 113429 : )", 0) \
6570 : 113429 : DECLARE(UInt64, distributed_cache_connect_max_tries, default_distributed_cache_connect_max_tries, R"(
6571 : 113429 : Only has an effect in ClickHouse Cloud. Number of tries to connect to distributed cache if unsuccessful
6572 : 113429 : )", 0) \
6573 : 113429 : DECLARE(UInt64, distributed_cache_read_request_max_tries, default_distributed_cache_read_request_max_tries, R"(
6574 : 113429 : Only has an effect in ClickHouse Cloud. Number of tries to do distributed cache read request if unsuccessful
6575 : 113429 : )", 0) \
6576 : 113429 : DECLARE(UInt64, distributed_cache_write_request_max_tries, default_distributed_cache_write_request_max_tries, R"(
6577 : 113429 : Only has an effect in ClickHouse Cloud. Number of tries to do distributed cache write request if unsuccessful
6578 : 113429 : )", 0) \
6579 : 113429 : DECLARE(UInt64, distributed_cache_receive_response_wait_milliseconds, 60000, R"(
6580 : 113429 : Only has an effect in ClickHouse Cloud. Wait time in milliseconds to receive data for request from distributed cache
6581 : 113429 : )", 0) \
6582 : 113429 : DECLARE(UInt64, distributed_cache_receive_timeout_milliseconds, 10000, R"(
6583 : 113429 : Only has an effect in ClickHouse Cloud. Wait time in milliseconds to receive any kind of response from distributed cache
6584 : 113429 :
6585 : 113429 : Cloud default value: `20000`.
6586 : 113429 : )", 0) \
6587 : 113429 : DECLARE(UInt64, distributed_cache_wait_connection_from_pool_milliseconds, 100, R"(
6588 : 113429 : Only has an effect in ClickHouse Cloud. Wait time in milliseconds to receive connection from connection pool if distributed_cache_pool_behaviour_on_limit is wait
6589 : 113429 : )", 0) \
6590 : 113429 : DECLARE(Bool, distributed_cache_bypass_connection_pool, false, R"(
6591 : 113429 : Only has an effect in ClickHouse Cloud. Allow to bypass distributed cache connection pool
6592 : 113429 : )", 0) \
6593 : 113429 : DECLARE(DistributedCachePoolBehaviourOnLimit, distributed_cache_pool_behaviour_on_limit, DistributedCachePoolBehaviourOnLimit::WAIT, R"(
6594 : 113429 : Only has an effect in ClickHouse Cloud. Identifies behaviour of distributed cache connection on pool limit reached
6595 : 113429 : )", 0) \
6596 : 113429 : DECLARE(UInt64, distributed_cache_alignment, 0, R"(
6597 : 113429 : Only has an effect in ClickHouse Cloud. A setting for testing purposes, do not change it
6598 : 113429 : )", 0) \
6599 : 113429 : DECLARE(UInt64, distributed_cache_max_unacked_inflight_packets, DistributedCache::MAX_UNACKED_INFLIGHT_PACKETS, R"(
6600 : 113429 : Only has an effect in ClickHouse Cloud. A maximum number of unacknowledged in-flight packets in a single distributed cache read request
6601 : 113429 : )", 0) \
6602 : 113429 : DECLARE(UInt64, distributed_cache_data_packet_ack_window, DistributedCache::ACK_DATA_PACKET_WINDOW, R"(
6603 : 113429 : Only has an effect in ClickHouse Cloud. A window for sending ACK for DataPacket sequence in a single distributed cache read request
6604 : 113429 : )", 0) \
6605 : 113429 : DECLARE(Bool, distributed_cache_discard_connection_if_unread_data, true, R"(
6606 : 113429 : Only has an effect in ClickHouse Cloud. Discard connection if some data is unread.
6607 : 113429 : )", 0) \
6608 : 113429 : DECLARE(UInt64, distributed_cache_min_bytes_for_seek, 0, R"(
6609 : 113429 : Only has an effect in ClickHouse Cloud. Minimum number of bytes to do seek in distributed cache.
6610 : 113429 : )", 0) \
6611 : 113429 : DECLARE(UInt64, distributed_cache_credentials_refresh_period_seconds, default_distributed_cache_credentials_refresh_period_seconds, R"(
6612 : 113429 : Only has an effect in ClickHouse Cloud. A period of credentials refresh.
6613 : 113429 : )", 0) \
6614 : 113429 : DECLARE(Bool, distributed_cache_read_only_from_current_az, true, R"(
6615 : 113429 : Only has an effect in ClickHouse Cloud. Allow to read only from current availability zone. If disabled, will read from all cache servers in all availability zones.
6616 : 113429 : )", 0) \
6617 : 113429 : DECLARE(UInt64, write_through_distributed_cache_buffer_size, 0, R"(
6618 : 113429 : Only has an effect in ClickHouse Cloud. Set buffer size for write-through distributed cache. If 0, will use buffer size which would have been used if there was not distributed cache.
6619 : 113429 : )", 0) \
6620 : 113429 : DECLARE(Bool, table_engine_read_through_distributed_cache, false, R"(
6621 : 113429 : Only has an effect in ClickHouse Cloud. Allow reading from distributed cache via table engines / table functions (s3, azure, etc)
6622 : 113429 : )", 0) \
6623 : 113429 : DECLARE(UInt64, distributed_cache_connect_backoff_min_ms, default_distributed_cache_connect_backoff_min_ms, R"(
6624 : 113429 : Only has an effect in ClickHouse Cloud. Minimum backoff milliseconds for distributed cache connection creation.
6625 : 113429 : )", 0) \
6626 : 113429 : DECLARE(UInt64, distributed_cache_connect_backoff_max_ms, default_distributed_cache_connect_backoff_max_ms, R"(
6627 : 113429 : Only has an effect in ClickHouse Cloud. Maximum backoff milliseconds for distributed cache connection creation.
6628 : 113429 : )", 0) \
6629 : 113429 : DECLARE(Bool, distributed_cache_prefer_bigger_buffer_size, false, R"(
6630 : 113429 : Only has an effect in ClickHouse Cloud. Same as filesystem_cache_prefer_bigger_buffer_size, but for distributed cache.
6631 : 113429 : )", 0) \
6632 : 113429 : DECLARE(Bool, read_from_distributed_cache_if_exists_otherwise_bypass_cache, false, R"(
6633 : 113429 : Only has an effect in ClickHouse Cloud. Same as read_from_filesystem_cache_if_exists_otherwise_bypass_cache, but for distributed cache.
6634 : 113429 : )", 0) \
6635 : 113429 : DECLARE(UInt64, distributed_cache_connect_timeout_ms, default_distributed_cache_connect_timeout_ms, R"(
6636 : 113429 : Only has an effect in ClickHouse Cloud. Connection timeout when connecting to distributed cache server.
6637 : 113429 : )", 0) \
6638 : 113429 : DECLARE(UInt64, distributed_cache_receive_timeout_ms, default_distributed_cache_receive_timeout_ms, R"(
6639 : 113429 : Only has an effect in ClickHouse Cloud. Timeout for receiving data from distributed cache server, in milliseconds. If no bytes were received in this interval, the exception is thrown.
6640 : 113429 : )", 0) \
6641 : 113429 : DECLARE(UInt64, distributed_cache_send_timeout_ms, default_distributed_cache_send_timeout_ms, R"(
6642 : 113429 : Only has an effect in ClickHouse Cloud. Timeout for sending data to istributed cache server, in milliseconds. If a client needs to send some data but is not able to send any bytes in this interval, the exception is thrown.
6643 : 113429 : )", 0) \
6644 : 113429 : DECLARE(UInt64, distributed_cache_tcp_keep_alive_timeout_ms, default_distributed_cache_tcp_keep_alive_timeout_ms, R"(
6645 : 113429 : Only has an effect in ClickHouse Cloud. The time in milliseconds the connection to distributed cache server needs to remain idle before TCP starts sending keepalive probes.
6646 : 113429 : )", 0) \
6647 : 113429 : DECLARE(Bool, distributed_cache_use_clients_cache_for_write, default_distributed_cache_use_clients_cache_for_write, R"(
6648 : 113429 : Only has an effect in ClickHouse Cloud. Use clients cache for write requests.
6649 : 113429 : )", 0) \
6650 : 113429 : DECLARE(Bool, distributed_cache_use_clients_cache_for_read, default_distributed_cache_use_clients_cache_for_read, R"(
6651 : 113429 : Only has an effect in ClickHouse Cloud. Use clients cache for read requests.
6652 : 113429 : )", 0) \
6653 : 113429 : DECLARE(String, distributed_cache_file_cache_name, "", R"(
6654 : 113429 : Only has an effect in ClickHouse Cloud. A setting used only for CI tests - filesystem cache name to use on distributed cache.
6655 : 113429 : )", 0) \
6656 : 113429 : DECLARE(Bool, filesystem_cache_allow_background_download, true, R"(
6657 : 113429 : Allow filesystem cache to enqueue background downloads for data read from remote storage. Disable to keep downloads in the foreground for the current query/session.
6658 : 113429 : )", 0) \
6659 : 113429 : DECLARE(Bool, filesystem_cache_enable_background_download_for_metadata_files_in_packed_storage, true, R"(
6660 : 113429 : Only has an effect in ClickHouse Cloud. Wait time to lock cache for space reservation in filesystem cache
6661 : 113429 : )", 0) \
6662 : 113429 : DECLARE(Bool, filesystem_cache_enable_background_download_during_fetch, true, R"(
6663 : 113429 : Only has an effect in ClickHouse Cloud. Wait time to lock cache for space reservation in filesystem cache
6664 : 113429 : )", 0) \
6665 : 113429 : \
6666 : 113429 : DECLARE(Bool, parallelize_output_from_storages, true, R"(
6667 : 113429 : Parallelize output for reading step from storage. It allows parallelization of query processing right after reading from storage if possible
6668 : 113429 : )", 0) \
6669 : 113429 : DECLARE(String, insert_deduplication_token, "", R"(
6670 : 113429 : The setting allows a user to provide own deduplication semantic in MergeTree/ReplicatedMergeTree
6671 : 113429 : For example, by providing a unique value for the setting in each INSERT statement,
6672 : 113429 : user can avoid the same inserted data being deduplicated.
6673 : 113429 :
6674 : 113429 :
6675 : 113429 : Possible values:
6676 : 113429 :
6677 : 113429 : - Any string
6678 : 113429 :
6679 : 113429 : `insert_deduplication_token` is used for deduplication _only_ when not empty.
6680 : 113429 :
6681 : 113429 : For the replicated tables by default the only 100 of the most recent inserts for each partition are deduplicated (see [replicated_deduplication_window](merge-tree-settings.md/#replicated_deduplication_window), [replicated_deduplication_window_seconds](merge-tree-settings.md/#replicated_deduplication_window_seconds)).
6682 : 113429 : For not replicated tables see [non_replicated_deduplication_window](merge-tree-settings.md/#non_replicated_deduplication_window).
6683 : 113429 :
6684 : 113429 : :::note
6685 : 113429 : `insert_deduplication_token` works on a partition level (the same as `insert_deduplication` checksum). Multiple partitions can have the same `insert_deduplication_token`.
6686 : 113429 : :::
6687 : 113429 :
6688 : 113429 : Example:
6689 : 113429 :
6690 : 113429 : ```sql
6691 : 113429 : CREATE TABLE test_table
6692 : 113429 : ( A Int64 )
6693 : 113429 : ENGINE = MergeTree
6694 : 113429 : ORDER BY A
6695 : 113429 : SETTINGS non_replicated_deduplication_window = 100;
6696 : 113429 :
6697 : 113429 : INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (1);
6698 : 113429 :
6699 : 113429 : -- the next insert won't be deduplicated because insert_deduplication_token is different
6700 : 113429 : INSERT INTO test_table SETTINGS insert_deduplication_token = 'test1' VALUES (1);
6701 : 113429 :
6702 : 113429 : -- the next insert will be deduplicated because insert_deduplication_token
6703 : 113429 : -- is the same as one of the previous
6704 : 113429 : INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (2);
6705 : 113429 :
6706 : 113429 : SELECT * FROM test_table
6707 : 113429 :
6708 : 113429 : ┌─A─┐
6709 : 113429 : │ 1 │
6710 : 113429 : └───┘
6711 : 113429 : ┌─A─┐
6712 : 113429 : │ 1 │
6713 : 113429 : └───┘
6714 : 113429 : ```
6715 : 113429 : )", 0) \
6716 : 113429 : DECLARE(Bool, count_distinct_optimization, false, R"(
6717 : 113429 : Rewrite count distinct to subquery of group by
6718 : 113429 : )", 0) \
6719 : 113429 : DECLARE(Bool, optimize_inverse_dictionary_lookup, true, R"(
6720 : 113429 : Avoid repeated inverse dictionary lookup by doing faster lookups into a precomputed set of possible key values.
6721 : 113429 : )", 0) \
6722 : 113429 : DECLARE(Bool, throw_if_no_data_to_insert, true, R"(
6723 : 113429 : Allows or forbids empty INSERTs, enabled by default (throws an error on an empty insert). Only applies to INSERTs using [`clickhouse-client`](/interfaces/cli) or using the [gRPC interface](/interfaces/grpc).
6724 : 113429 : )", 0) \
6725 : 113429 : DECLARE(Bool, compatibility_ignore_auto_increment_in_create_table, false, R"(
6726 : 113429 : Ignore AUTO_INCREMENT keyword in column declaration if true, otherwise return error. It simplifies migration from MySQL
6727 : 113429 : )", 0) \
6728 : 113429 : DECLARE(Bool, multiple_joins_try_to_keep_original_names, false, R"(
6729 : 113429 : Do not add aliases to top level expression list on multiple joins rewrite
6730 : 113429 : )", 0) \
6731 : 113429 : DECLARE(Bool, optimize_sorting_by_input_stream_properties, true, R"(
6732 : 113429 : Optimize sorting by sorting properties of input stream
6733 : 113429 : )", 0) \
6734 : 113429 : DECLARE(UInt64, keeper_max_retries, 10, R"(
6735 : 113429 : Max retries for general keeper operations
6736 : 113429 : )", 0) \
6737 : 113429 : DECLARE(UInt64, keeper_retry_initial_backoff_ms, 100, R"(
6738 : 113429 : Initial backoff timeout for general keeper operations
6739 : 113429 : )", 0) \
6740 : 113429 : DECLARE(UInt64, keeper_retry_max_backoff_ms, 5000, R"(
6741 : 113429 : Max backoff timeout for general keeper operations
6742 : 113429 : )", 0) \
6743 : 113429 : DECLARE(UInt64, insert_keeper_max_retries, 20, R"(
6744 : 113429 : 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.
6745 : 113429 :
6746 : 113429 : Possible values:
6747 : 113429 :
6748 : 113429 : - Positive integer.
6749 : 113429 : - 0 — Retries are disabled
6750 : 113429 :
6751 : 113429 : Cloud default value: `20`.
6752 : 113429 :
6753 : 113429 : 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`.
6754 : 113429 : The first retry is done after `insert_keeper_retry_initial_backoff_ms` timeout. The consequent timeouts will be calculated as follows:
6755 : 113429 : ```
6756 : 113429 : timeout = min(insert_keeper_retry_max_backoff_ms, latest_timeout * 2)
6757 : 113429 : ```
6758 : 113429 :
6759 : 113429 : 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`.
6760 : 113429 :
6761 : 113429 : 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.
6762 : 113429 : )", 0) \
6763 : 113429 : DECLARE(UInt64, insert_keeper_retry_initial_backoff_ms, 100, R"(
6764 : 113429 : Initial timeout(in milliseconds) to retry a failed Keeper request during INSERT query execution
6765 : 113429 :
6766 : 113429 : Possible values:
6767 : 113429 :
6768 : 113429 : - Positive integer.
6769 : 113429 : - 0 — No timeout
6770 : 113429 : )", 0) \
6771 : 113429 : DECLARE(UInt64, insert_keeper_retry_max_backoff_ms, 10000, R"(
6772 : 113429 : Maximum timeout (in milliseconds) to retry a failed Keeper request during INSERT query execution
6773 : 113429 :
6774 : 113429 : Possible values:
6775 : 113429 :
6776 : 113429 : - Positive integer.
6777 : 113429 : - 0 — Maximum timeout is not limited
6778 : 113429 : )", 0) \
6779 : 113429 : DECLARE(Float, insert_keeper_fault_injection_probability, 0.0f, R"(
6780 : 113429 : Approximate probability of failure for a keeper request during insert. Valid value is in interval [0.0f, 1.0f]
6781 : 113429 : )", 0) \
6782 : 113429 : DECLARE(UInt64, insert_keeper_fault_injection_seed, 0, R"(
6783 : 113429 : 0 - random seed, otherwise the setting value
6784 : 113429 : )", 0) \
6785 : 113429 : DECLARE(Bool, force_aggregation_in_order, false, R"(
6786 : 113429 : 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).
6787 : 113429 : )", IMPORTANT) \
6788 : 113429 : DECLARE(UInt64, http_max_request_param_data_size, 10_MiB, R"(
6789 : 113429 : Limit on size of request data used as a query parameter in predefined HTTP requests.
6790 : 113429 : )", 0) \
6791 : 113429 : DECLARE(Bool, function_json_value_return_type_allow_nullable, false, R"(
6792 : 113429 : Control whether allow to return `NULL` when value is not exist for JSON_VALUE function.
6793 : 113429 :
6794 : 113429 : ```sql
6795 : 113429 : SELECT JSON_VALUE('{"hello":"world"}', '$.b') settings function_json_value_return_type_allow_nullable=true;
6796 : 113429 :
6797 : 113429 : ┌─JSON_VALUE('{"hello":"world"}', '$.b')─┐
6798 : 113429 : │ ᴺᵁᴸᴸ │
6799 : 113429 : └────────────────────────────────────────┘
6800 : 113429 :
6801 : 113429 : 1 row in set. Elapsed: 0.001 sec.
6802 : 113429 : ```
6803 : 113429 :
6804 : 113429 : Possible values:
6805 : 113429 :
6806 : 113429 : - true — Allow.
6807 : 113429 : - false — Disallow.
6808 : 113429 : )", 0) \
6809 : 113429 : DECLARE(Bool, function_json_value_return_type_allow_complex, false, R"(
6810 : 113429 : Control whether allow to return complex type (such as: struct, array, map) for json_value function.
6811 : 113429 :
6812 : 113429 : ```sql
6813 : 113429 : SELECT JSON_VALUE('{"hello":{"world":"!"}}', '$.hello') settings function_json_value_return_type_allow_complex=true
6814 : 113429 :
6815 : 113429 : ┌─JSON_VALUE('{"hello":{"world":"!"}}', '$.hello')─┐
6816 : 113429 : │ {"world":"!"} │
6817 : 113429 : └──────────────────────────────────────────────────┘
6818 : 113429 :
6819 : 113429 : 1 row in set. Elapsed: 0.001 sec.
6820 : 113429 : ```
6821 : 113429 :
6822 : 113429 : Possible values:
6823 : 113429 :
6824 : 113429 : - true — Allow.
6825 : 113429 : - false — Disallow.
6826 : 113429 : )", 0) \
6827 : 113429 : DECLARE(Bool, use_with_fill_by_sorting_prefix, true, R"(
6828 : 113429 : Columns preceding WITH FILL columns in ORDER BY clause form sorting prefix. Rows with different values in sorting prefix are filled independently
6829 : 113429 : )", 0) \
6830 : 113429 : DECLARE(Bool, optimize_uniq_to_count, true, R"(
6831 : 113429 : Rewrite uniq and its variants(except uniqUpTo) to count if subquery has distinct or group by clause.
6832 : 113429 : )", 0) \
6833 : 113429 : DECLARE(Bool, use_variant_as_common_type, true, R"(
6834 : 113429 : Allows to use `Variant` type as a result type for [if](../../sql-reference/functions/conditional-functions.md/#if)/[multiIf](../../sql-reference/functions/conditional-functions.md/#multiIf)/[array](../../sql-reference/functions/array-functions.md)/[map](../../sql-reference/functions/tuple-map-functions.md) functions when there is no common type for argument types.
6835 : 113429 :
6836 : 113429 : Example:
6837 : 113429 :
6838 : 113429 : ```sql
6839 : 113429 : SET use_variant_as_common_type = 1;
6840 : 113429 : SELECT toTypeName(if(number % 2, number, range(number))) as variant_type FROM numbers(1);
6841 : 113429 : SELECT if(number % 2, number, range(number)) as variant FROM numbers(5);
6842 : 113429 : ```
6843 : 113429 :
6844 : 113429 : ```text
6845 : 113429 : ┌─variant_type───────────────────┐
6846 : 113429 : │ Variant(Array(UInt64), UInt64) │
6847 : 113429 : └────────────────────────────────┘
6848 : 113429 : ┌─variant───┐
6849 : 113429 : │ [] │
6850 : 113429 : │ 1 │
6851 : 113429 : │ [0,1] │
6852 : 113429 : │ 3 │
6853 : 113429 : │ [0,1,2,3] │
6854 : 113429 : └───────────┘
6855 : 113429 : ```
6856 : 113429 :
6857 : 113429 : ```sql
6858 : 113429 : SET use_variant_as_common_type = 1;
6859 : 113429 : 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);
6860 : 113429 : SELECT multiIf((number % 4) = 0, 42, (number % 4) = 1, [1, 2, 3], (number % 4) = 2, 'Hello, World!', NULL) AS variant FROM numbers(4);
6861 : 113429 : ```
6862 : 113429 :
6863 : 113429 : ```text
6864 : 113429 : ─variant_type─────────────────────────┐
6865 : 113429 : │ Variant(Array(UInt8), String, UInt8) │
6866 : 113429 : └──────────────────────────────────────┘
6867 : 113429 :
6868 : 113429 : ┌─variant───────┐
6869 : 113429 : │ 42 │
6870 : 113429 : │ [1,2,3] │
6871 : 113429 : │ Hello, World! │
6872 : 113429 : │ ᴺᵁᴸᴸ │
6873 : 113429 : └───────────────┘
6874 : 113429 : ```
6875 : 113429 :
6876 : 113429 : ```sql
6877 : 113429 : SET use_variant_as_common_type = 1;
6878 : 113429 : SELECT toTypeName(array(range(number), number, 'str_' || toString(number))) as array_of_variants_type from numbers(1);
6879 : 113429 : SELECT array(range(number), number, 'str_' || toString(number)) as array_of_variants FROM numbers(3);
6880 : 113429 : ```
6881 : 113429 :
6882 : 113429 : ```text
6883 : 113429 : ┌─array_of_variants_type────────────────────────┐
6884 : 113429 : │ Array(Variant(Array(UInt64), String, UInt64)) │
6885 : 113429 : └───────────────────────────────────────────────┘
6886 : 113429 :
6887 : 113429 : ┌─array_of_variants─┐
6888 : 113429 : │ [[],0,'str_0'] │
6889 : 113429 : │ [[0],1,'str_1'] │
6890 : 113429 : │ [[0,1],2,'str_2'] │
6891 : 113429 : └───────────────────┘
6892 : 113429 : ```
6893 : 113429 :
6894 : 113429 : ```sql
6895 : 113429 : SET use_variant_as_common_type = 1;
6896 : 113429 : SELECT toTypeName(map('a', range(number), 'b', number, 'c', 'str_' || toString(number))) as map_of_variants_type from numbers(1);
6897 : 113429 : SELECT map('a', range(number), 'b', number, 'c', 'str_' || toString(number)) as map_of_variants FROM numbers(3);
6898 : 113429 : ```
6899 : 113429 :
6900 : 113429 : ```text
6901 : 113429 : ┌─map_of_variants_type────────────────────────────────┐
6902 : 113429 : │ Map(String, Variant(Array(UInt64), String, UInt64)) │
6903 : 113429 : └─────────────────────────────────────────────────────┘
6904 : 113429 :
6905 : 113429 : ┌─map_of_variants───────────────┐
6906 : 113429 : │ {'a':[],'b':0,'c':'str_0'} │
6907 : 113429 : │ {'a':[0],'b':1,'c':'str_1'} │
6908 : 113429 : │ {'a':[0,1],'b':2,'c':'str_2'} │
6909 : 113429 : └───────────────────────────────┘
6910 : 113429 : ```
6911 : 113429 : )", 0) \
6912 : 113429 : DECLARE(Bool, enable_order_by_all, true, R"(
6913 : 113429 : Enables or disables sorting with `ORDER BY ALL` syntax, see [ORDER BY](../../sql-reference/statements/select/order-by.md).
6914 : 113429 :
6915 : 113429 : Possible values:
6916 : 113429 :
6917 : 113429 : - 0 — Disable ORDER BY ALL.
6918 : 113429 : - 1 — Enable ORDER BY ALL.
6919 : 113429 :
6920 : 113429 : **Example**
6921 : 113429 :
6922 : 113429 : Query:
6923 : 113429 :
6924 : 113429 : ```sql
6925 : 113429 : CREATE TABLE TAB(C1 Int, C2 Int, ALL Int) ENGINE=Memory();
6926 : 113429 :
6927 : 113429 : INSERT INTO TAB VALUES (10, 20, 30), (20, 20, 10), (30, 10, 20);
6928 : 113429 :
6929 : 113429 : SELECT * FROM TAB ORDER BY ALL; -- returns an error that ALL is ambiguous
6930 : 113429 :
6931 : 113429 : SELECT * FROM TAB ORDER BY ALL SETTINGS enable_order_by_all = 0;
6932 : 113429 : ```
6933 : 113429 :
6934 : 113429 : Result:
6935 : 113429 :
6936 : 113429 : ```text
6937 : 113429 : ┌─C1─┬─C2─┬─ALL─┐
6938 : 113429 : │ 20 │ 20 │ 10 │
6939 : 113429 : │ 30 │ 10 │ 20 │
6940 : 113429 : │ 10 │ 20 │ 30 │
6941 : 113429 : └────┴────┴─────┘
6942 : 113429 : ```
6943 : 113429 : )", 0) \
6944 : 113429 : DECLARE(Float, ignore_drop_queries_probability, 0, R"(
6945 : 113429 : If enabled, server will ignore all DROP table queries with specified probability (for Memory and JOIN engines it will replace DROP to TRUNCATE). Used for testing purposes
6946 : 113429 : )", 0) \
6947 : 113429 : DECLARE(Bool, traverse_shadow_remote_data_paths, false, R"(
6948 : 113429 : Traverse frozen data (shadow directory) in addition to actual table data when query system.remote_data_paths
6949 : 113429 : )", 0) \
6950 : 113429 : DECLARE(Bool, geo_distance_returns_float64_on_float64_arguments, true, R"(
6951 : 113429 : If all four arguments to `geoDistance`, `greatCircleDistance`, `greatCircleAngle` functions are Float64, return Float64 and use double precision for internal calculations. In previous ClickHouse versions, the functions always returned Float32.
6952 : 113429 : )", 0) \
6953 : 113429 : DECLARE(Bool, allow_get_client_http_header, false, R"(
6954 : 113429 : Allow to use the function `getClientHTTPHeader` which lets to obtain a value of an the current HTTP request's header. It is not enabled by default for security reasons, because some headers, such as `Cookie`, could contain sensitive info. Note that the `X-ClickHouse-*` and `Authentication` headers are always restricted and cannot be obtained with this function.
6955 : 113429 : )", 0) \
6956 : 113429 : DECLARE(Bool, cast_string_to_dynamic_use_inference, false, R"(
6957 : 113429 : Use types inference during String to Dynamic conversion
6958 : 113429 : )", 0) \
6959 : 113429 : DECLARE(Bool, allow_dynamic_type_in_join_keys, false, R"(
6960 : 113429 : Allows using Dynamic type in JOIN keys. Added for compatibility. It's not recommended to use Dynamic type in JOIN keys because comparison with other types may lead to unexpected results.
6961 : 113429 : )", 0) \
6962 : 113429 : DECLARE(Bool, cast_string_to_variant_use_inference, true, R"(
6963 : 113429 : Use types inference during String to Variant conversion.
6964 : 113429 : )", 0) \
6965 : 113429 : DECLARE(DateTimeInputFormat, cast_string_to_date_time_mode, "basic", R"(
6966 : 113429 : Allows choosing a parser of the text representation of date and time during cast from String.
6967 : 113429 :
6968 : 113429 : Possible values:
6969 : 113429 :
6970 : 113429 : - `'best_effort'` — Enables extended parsing.
6971 : 113429 :
6972 : 113429 : ClickHouse can parse the basic `YYYY-MM-DD HH:MM:SS` format and all [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time formats. For example, `'2018-06-08T01:02:03.000Z'`.
6973 : 113429 :
6974 : 113429 : - `'best_effort_us'` — Similar to `best_effort` (see the difference in [parseDateTimeBestEffortUS](../../sql-reference/functions/type-conversion-functions#parseDateTimeBestEffortUS)
6975 : 113429 :
6976 : 113429 : - `'basic'` — Use basic parser.
6977 : 113429 :
6978 : 113429 : ClickHouse can parse only the basic `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DD` format. For example, `2019-08-20 10:18:56` or `2019-08-20`.
6979 : 113429 :
6980 : 113429 : See also:
6981 : 113429 :
6982 : 113429 : - [DateTime data type.](../../sql-reference/data-types/datetime.md)
6983 : 113429 : - [Functions for working with dates and times.](../../sql-reference/functions/date-time-functions.md)
6984 : 113429 : )", 0) \
6985 : 113429 : DECLARE(Bool, enable_blob_storage_log, true, R"(
6986 : 113429 : Write information about blob storage operations to system.blob_storage_log table
6987 : 113429 : )", 0) \
6988 : 113429 : DECLARE(UInt64, predicate_statistics_sample_rate, 0, R"(
6989 : 113429 : Collect predicate selectivity statistics into `system.predicate_statistics_log`. When set to N > 0, approximately 1/N of queries are sampled (by the query ID). 0 means disabled.
6990 : 113429 : )", 0) \
6991 : 113429 : DECLARE(Bool, allow_create_index_without_type, false, R"(
6992 : 113429 : Allow CREATE INDEX query without TYPE. Query will be ignored. Made for SQL compatibility tests.
6993 : 113429 : )", 0) \
6994 : 113429 : DECLARE(Bool, create_index_ignore_unique, false, R"(
6995 : 113429 : Ignore UNIQUE keyword in CREATE UNIQUE INDEX. Made for SQL compatibility tests.
6996 : 113429 : )", 0) \
6997 : 113429 : DECLARE(Bool, print_pretty_type_names, true, R"(
6998 : 113429 : Allows to print deep-nested type names in a pretty way with indents in `DESCRIBE` query and in `toTypeName()` function.
6999 : 113429 :
7000 : 113429 : Example:
7001 : 113429 :
7002 : 113429 : ```sql
7003 : 113429 : 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;
7004 : 113429 : DESCRIBE TABLE test FORMAT TSVRaw SETTINGS print_pretty_type_names=1;
7005 : 113429 : ```
7006 : 113429 :
7007 : 113429 : ```
7008 : 113429 : a Tuple(
7009 : 113429 : b String,
7010 : 113429 : c Tuple(
7011 : 113429 : d Nullable(UInt64),
7012 : 113429 : e Array(UInt32),
7013 : 113429 : f Array(Tuple(
7014 : 113429 : g String,
7015 : 113429 : h Map(
7016 : 113429 : String,
7017 : 113429 : Array(Tuple(
7018 : 113429 : i String,
7019 : 113429 : j UInt64
7020 : 113429 : ))
7021 : 113429 : )
7022 : 113429 : )),
7023 : 113429 : k Date
7024 : 113429 : ),
7025 : 113429 : l Nullable(String)
7026 : 113429 : )
7027 : 113429 : ```
7028 : 113429 : )", 0) \
7029 : 113429 : DECLARE(Bool, create_table_empty_primary_key_by_default, true, R"(
7030 : 113429 : Allow to create *MergeTree tables with empty primary key when ORDER BY and PRIMARY KEY not specified
7031 : 113429 : )", 0) \
7032 : 113429 : DECLARE(Bool, allow_named_collection_override_by_default, true, R"(
7033 : 113429 : Allow named collections' fields override by default.
7034 : 113429 : )", 0) \
7035 : 113429 : DECLARE(SQLSecurityType, default_normal_view_sql_security, SQLSecurityType::INVOKER, R"(
7036 : 113429 : Allows to set default `SQL SECURITY` option while creating a normal view. [More about SQL security](../../sql-reference/statements/create/view.md/#sql_security).
7037 : 113429 :
7038 : 113429 : The default value is `INVOKER`.
7039 : 113429 : )", 0) \
7040 : 113429 : DECLARE(SQLSecurityType, default_materialized_view_sql_security, SQLSecurityType::DEFINER, R"(
7041 : 113429 : Allows to set a default value for SQL SECURITY option when creating a materialized view. [More about SQL security](../../sql-reference/statements/create/view.md/#sql_security).
7042 : 113429 :
7043 : 113429 : The default value is `DEFINER`.
7044 : 113429 : )", 0) \
7045 : 113429 : DECLARE(String, default_view_definer, "CURRENT_USER", R"(
7046 : 113429 : Allows to set default `DEFINER` option while creating a view. [More about SQL security](../../sql-reference/statements/create/view.md/#sql_security).
7047 : 113429 :
7048 : 113429 : The default value is `CURRENT_USER`.
7049 : 113429 : )", 0) \
7050 : 113429 : DECLARE(UInt64, cache_warmer_threads, 4, R"(
7051 : 113429 : Only has an effect in ClickHouse Cloud. Number of background threads for speculatively downloading new data parts into the filesystem cache, when [cache_populated_by_fetch](merge-tree-settings.md/#cache_populated_by_fetch) is enabled. Zero to disable.
7052 : 113429 : )", 0) \
7053 : 113429 : DECLARE(Bool, use_async_executor_for_materialized_views, false, R"(
7054 : 113429 : Use async and potentially multithreaded execution of materialized view query, can speedup views processing during INSERT, but also consume more memory.)", 0) \
7055 : 113429 : DECLARE(Int64, ignore_cold_parts_seconds, 0, R"(
7056 : 113429 : Only has an effect in ClickHouse Cloud. Exclude new data parts from SELECT queries until they're either pre-warmed (see [cache_populated_by_fetch](merge-tree-settings.md/#cache_populated_by_fetch)) or this many seconds old. Only for Replicated-/SharedMergeTree.
7057 : 113429 : )", 0) \
7058 : 113429 : DECLARE(Bool, short_circuit_function_evaluation_for_nulls, true, R"(
7059 : 113429 : Optimizes evaluation of functions that return NULL when any argument is NULL. When the percentage of NULL values in the function's arguments exceeds the short_circuit_function_evaluation_for_nulls_threshold, the system skips evaluating the function row-by-row. Instead, it immediately returns NULL for all rows, avoiding unnecessary computation.
7060 : 113429 : )", 0) \
7061 : 113429 : DECLARE(Double, short_circuit_function_evaluation_for_nulls_threshold, 1.0, R"(
7062 : 113429 : Ratio threshold of NULL values to execute functions with Nullable arguments only on rows with non-NULL values in all arguments. Applies when setting short_circuit_function_evaluation_for_nulls is enabled.
7063 : 113429 : When the ratio of rows containing NULL values to the total number of rows exceeds this threshold, these rows containing NULL values will not be evaluated.
7064 : 113429 : )", 0) \
7065 : 113429 : DECLARE(Int64, prefer_warmed_unmerged_parts_seconds, 0, R"(
7066 : 113429 : Only has an effect in ClickHouse Cloud. If a merged part is less than this many seconds old and is not pre-warmed (see [cache_populated_by_fetch](merge-tree-settings.md/#cache_populated_by_fetch)), but all its source parts are available and pre-warmed, SELECT queries will read from those parts instead. Only for Replicated-/SharedMergeTree. Note that this only checks whether CacheWarmer processed the part; if the part was fetched into cache by something else, it'll still be considered cold until CacheWarmer gets to it; if it was warmed, then evicted from cache, it'll still be considered warm.
7067 : 113429 : )", 0) \
7068 : 113429 : DECLARE(Int64, iceberg_timestamp_ms, 0, R"(
7069 : 113429 : Query Iceberg table using the snapshot that was current at a specific timestamp.
7070 : 113429 : )", 0) \
7071 : 113429 : DECLARE(Int64, iceberg_snapshot_id, 0, R"(
7072 : 113429 : Query Iceberg table using the specific snapshot id.
7073 : 113429 : )", 0) \
7074 : 113429 : DECLARE(Bool, show_data_lake_catalogs_in_system_tables, false, R"(
7075 : 113429 : Enables showing data lake catalogs in system tables.
7076 : 113429 : )", 0) \
7077 : 113429 : DECLARE(Bool, delta_lake_enable_expression_visitor_logging, false, R"(
7078 : 113429 : Enables Test level logs of DeltaLake expression visitor. These logs can be too verbose even for test logging.
7079 : 113429 : )", 0) \
7080 : 113429 : DECLARE(Int64, delta_lake_snapshot_version, -1, R"(
7081 : 113429 : Version of delta lake snapshot to read. Value -1 means to read latest version (value 0 is a valid snapshot version).
7082 : 113429 : )", 0) \
7083 : 113429 : DECLARE(Int64, delta_lake_snapshot_start_version, -1, R"(
7084 : 113429 : Start version of delta lake snapshot to read. Value -1 means to read latest version (value 0 is a valid snapshot version).
7085 : 113429 : )", 0) \
7086 : 113429 : DECLARE(Int64, delta_lake_snapshot_end_version, -1, R"(
7087 : 113429 : End version of delta lake snapshot to read. Value -1 means to read latest version (value 0 is a valid snapshot version).
7088 : 113429 : )", 0) \
7089 : 113429 : DECLARE(Bool, delta_lake_throw_on_engine_predicate_error, false, R"(
7090 : 113429 : Enables throwing an exception if there was an error when analyzing scan predicate in delta-kernel.
7091 : 113429 : )", 0) \
7092 : 113429 : DECLARE(Bool, delta_lake_enable_engine_predicate, true, R"(
7093 : 113429 : Enables delta-kernel internal data pruning.
7094 : 113429 : )", 0) \
7095 : 113429 : DECLARE(NonZeroUInt64, delta_lake_insert_max_rows_in_data_file, 1000000, R"(
7096 : 113429 : Defines a rows limit for a single inserted data file in delta lake.
7097 : 113429 : )", 0) \
7098 : 113429 : DECLARE(NonZeroUInt64, delta_lake_insert_max_bytes_in_data_file, 1_GiB, R"(
7099 : 113429 : Defines a bytes limit for a single inserted data file in delta lake.
7100 : 113429 : )", 0) \
7101 : 113429 : DECLARE(Bool, allow_experimental_delta_lake_writes, false, R"(
7102 : 113429 : Enables delta-kernel writes feature.
7103 : 113429 : )", EXPERIMENTAL) \
7104 : 113429 : DECLARE(Bool, allow_deprecated_error_prone_window_functions, false, R"(
7105 : 113429 : Allow usage of deprecated error prone window functions (neighbor, runningAccumulate, runningDifferenceStartingWithFirstValue, runningDifference)
7106 : 113429 : )", 0) \
7107 : 113429 : DECLARE(Bool, use_iceberg_partition_pruning, true, R"(
7108 : 113429 : Use Iceberg partition pruning for Iceberg tables
7109 : 113429 : )", 0) \
7110 : 113429 : DECLARE(Bool, allow_deprecated_snowflake_conversion_functions, false, R"(
7111 : 113429 : Functions `snowflakeToDateTime`, `snowflakeToDateTime64`, `dateTimeToSnowflake`, and `dateTime64ToSnowflake` are deprecated and disabled by default.
7112 : 113429 : Please use functions `snowflakeIDToDateTime`, `snowflakeIDToDateTime64`, `dateTimeToSnowflakeID`, and `dateTime64ToSnowflakeID` instead.
7113 : 113429 :
7114 : 113429 : To re-enable the deprecated functions (e.g., during a transition period), please set this setting to `true`.
7115 : 113429 : )", 0) \
7116 : 113429 : DECLARE(Bool, optimize_distinct_in_order, true, R"(
7117 : 113429 : 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
7118 : 113429 : )", 0) \
7119 : 113429 : DECLARE(Bool, keeper_map_strict_mode, false, R"(
7120 : 113429 : Enforce additional checks during operations on KeeperMap. E.g. throw an exception on an insert for already existing key
7121 : 113429 : )", 0) \
7122 : 113429 : DECLARE_WITH_ALIAS(UInt64, extract_key_value_pairs_max_pairs_per_row, 1000, R"(
7123 : 113429 : Max number of pairs that can be produced by the `extractKeyValuePairs` function. Used as a safeguard against consuming too much memory.
7124 : 113429 : )", 0, extract_kvp_max_pairs_per_row) \
7125 : 113429 : DECLARE(Bool, restore_replace_external_engines_to_null, false, R"(
7126 : 113429 : For testing purposes. Replaces all external engines to Null to not initiate external connections.
7127 : 113429 : )", 0) \
7128 : 113429 : DECLARE(Bool, restore_replace_external_table_functions_to_null, false, R"(
7129 : 113429 : For testing purposes. Replaces all external table functions to Null to not initiate external connections.
7130 : 113429 : )", 0) \
7131 : 113429 : DECLARE(Bool, restore_replace_external_dictionary_source_to_null, false, R"(
7132 : 113429 : Replace external dictionary sources to Null on restore. Useful for testing purposes
7133 : 113429 : )", 0) \
7134 : 113429 : /* Parallel replicas */ \
7135 : 113429 : DECLARE_WITH_ALIAS(UInt64, allow_experimental_parallel_reading_from_replicas, 0, R"(
7136 : 113429 : Use up to `max_parallel_replicas` the number of replicas from each shard for SELECT query execution. Reading is parallelized and coordinated dynamically. 0 - disabled, 1 - enabled, silently disable them in case of failure, 2 - enabled, throw an exception in case of failure
7137 : 113429 : )", 0, enable_parallel_replicas) \
7138 : 113429 : DECLARE(UInt64, automatic_parallel_replicas_mode, 0, R"(
7139 : 113429 : Enable automatic switching to execution with parallel replicas based on collected statistics. Requires `enable_analyzer = 1`, `enable_parallel_replicas != 0`, `parallel_replicas_local_plan = 1` and providing `cluster_for_parallel_replicas`.
7140 : 113429 : 0 - disabled, 1 - enabled, 2 - only statistics collection is enabled (switching to execution with parallel replicas is disabled).
7141 : 113429 : )", EXPERIMENTAL) \
7142 : 113429 : DECLARE(UInt64, automatic_parallel_replicas_min_bytes_per_replica, 1_MiB, R"(
7143 : 113429 : Threshold of bytes to read per replica to enable parallel replicas automatically (applies only when `automatic_parallel_replicas_mode`=1). 0 means no threshold.
7144 : 113429 : The total number of bytes to read is estimated based on the collected statistics.
7145 : 113429 : )", EXPERIMENTAL) \
7146 : 113429 : DECLARE(NonZeroUInt64, max_parallel_replicas, 1000, R"(
7147 : 113429 : The maximum number of replicas for each shard when executing a query.
7148 : 113429 :
7149 : 113429 : Possible values:
7150 : 113429 :
7151 : 113429 : - Positive integer.
7152 : 113429 :
7153 : 113429 : **Additional Info**
7154 : 113429 :
7155 : 113429 : This options will produce different results depending on the settings used.
7156 : 113429 :
7157 : 113429 : :::note
7158 : 113429 : 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](/operations/settings/settings#max_parallel_replicas) for more details.
7159 : 113429 : :::
7160 : 113429 :
7161 : 113429 : ### Parallel processing using `SAMPLE` key
7162 : 113429 :
7163 : 113429 : 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:
7164 : 113429 :
7165 : 113429 : - The position of the sampling key in the partitioning key does not allow efficient range scans.
7166 : 113429 : - Adding a sampling key to the table makes filtering by other columns less efficient.
7167 : 113429 : - The sampling key is an expression that is expensive to calculate.
7168 : 113429 : - The cluster latency distribution has a long tail, so that querying more servers increases the query overall latency.
7169 : 113429 :
7170 : 113429 : ### Parallel processing using [parallel_replicas_custom_key](#parallel_replicas_custom_key)
7171 : 113429 :
7172 : 113429 : This setting is useful for any replicated table.
7173 : 113429 : )", 0) \
7174 : 113429 : DECLARE(ParallelReplicasMode, parallel_replicas_mode, ParallelReplicasMode::READ_TASKS, R"(
7175 : 113429 : Type of filter to use with custom key for parallel replicas. default - use modulo operation on the custom key, range - use range filter on custom key using all possible values for the value type of custom key.
7176 : 113429 : )", 0) \
7177 : 113429 : DECLARE(UInt64, parallel_replicas_count, 0, R"(
7178 : 113429 : 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.
7179 : 113429 : )", BETA) \
7180 : 113429 : DECLARE(UInt64, parallel_replica_offset, 0, R"(
7181 : 113429 : 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.
7182 : 113429 : )", BETA) \
7183 : 113429 : DECLARE(String, parallel_replicas_custom_key, "", R"(
7184 : 113429 : An arbitrary integer expression that can be used to split work between replicas for a specific table.
7185 : 113429 : The value can be any integer expression.
7186 : 113429 :
7187 : 113429 : Simple expressions using primary keys are preferred.
7188 : 113429 :
7189 : 113429 : 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.
7190 : 113429 : Otherwise, it will behave same as for `SAMPLE` key, it will use multiple replicas of each shard.
7191 : 113429 : )", BETA) \
7192 : 113429 : DECLARE(UInt64, parallel_replicas_custom_key_range_lower, 0, R"(
7193 : 113429 : 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]`.
7194 : 113429 :
7195 : 113429 : When used in conjunction with [parallel_replicas_custom_key_range_upper](#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]`.
7196 : 113429 :
7197 : 113429 : 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.
7198 : 113429 : )", BETA) \
7199 : 113429 : DECLARE(UInt64, parallel_replicas_custom_key_range_upper, 0, R"(
7200 : 113429 : Allows the filter type `range` to split the work evenly between replicas based on the custom range `[0, parallel_replicas_custom_key_range_upper]`. A value of 0 disables the upper bound, setting it the max value of the custom key expression.
7201 : 113429 :
7202 : 113429 : When used in conjunction with [parallel_replicas_custom_key_range_lower](#parallel_replicas_custom_key_range_lower), it lets the filter evenly split the work over replicas for the range `[parallel_replicas_custom_key_range_lower, parallel_replicas_custom_key_range_upper]`.
7203 : 113429 :
7204 : 113429 : 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
7205 : 113429 : )", BETA) \
7206 : 113429 : DECLARE(String, cluster_for_parallel_replicas, "", R"(
7207 : 113429 : Cluster for a shard in which current server is located
7208 : 113429 :
7209 : 113429 : Cloud default value: `default`.
7210 : 113429 : )", 0) \
7211 : 113429 : DECLARE(Bool, parallel_replicas_allow_in_with_subquery, true, R"(
7212 : 113429 : If true, subquery for IN will be executed on every follower replica.
7213 : 113429 : )", 0) \
7214 : 113429 : DECLARE(Bool, parallel_replicas_for_non_replicated_merge_tree, false, R"(
7215 : 113429 : If true, ClickHouse will use parallel replicas algorithm also for non-replicated MergeTree tables
7216 : 113429 : )", 0) \
7217 : 113429 : DECLARE(UInt64, parallel_replicas_min_number_of_rows_per_replica, 0, R"(
7218 : 113429 : Limit the number of replicas used in a query to (estimated rows to read / min_number_of_rows_per_replica). The max is still limited by 'max_parallel_replicas'
7219 : 113429 : )", 0) \
7220 : 113429 : DECLARE(Bool, parallel_replicas_prefer_local_join, true, R"(
7221 : 113429 : If true, and JOIN can be executed with parallel replicas algorithm, and all storages of right JOIN part are *MergeTree, local JOIN will be used instead of GLOBAL JOIN.
7222 : 113429 : )", 0) \
7223 : 113429 : DECLARE(UInt64, parallel_replicas_mark_segment_size, 0, R"(
7224 : 113429 : Parts virtually divided into segments to be distributed between replicas for parallel reading. This setting controls the size of these segments. Not recommended to change until you're absolutely sure in what you're doing. Value should be in range [128; 16384]
7225 : 113429 : )", 0) \
7226 : 113429 : DECLARE(Bool, parallel_replicas_local_plan, true, R"(
7227 : 113429 : Build local plan for local replica
7228 : 113429 : )", 0) \
7229 : 113429 : DECLARE(Bool, parallel_replicas_prefer_local_replica, true, R"(
7230 : 113429 : When enabled (default), the local replica is always included in the set of replicas used for parallel reading.
7231 : 113429 : When disabled, the local replica is not given any preference and replicas are selected purely by the load balancing algorithm.
7232 : 113429 : This allows queries with `max_parallel_replicas = 1` to be directed to another host, which can improve cache locality when many short queries are distributed across a cluster.
7233 : 113429 : )", 0) \
7234 : 113429 : DECLARE(Bool, parallel_replicas_index_analysis_only_on_coordinator, true, R"(
7235 : 113429 : Index analysis done only on replica-coordinator and skipped on other replicas. Effective only with enabled parallel_replicas_local_plan
7236 : 113429 : )", 0) \
7237 : 113429 : DECLARE(Bool, parallel_replicas_support_projection, true, R"(
7238 : 113429 : Optimization of projections can be applied in parallel replicas. Effective only with enabled parallel_replicas_local_plan and aggregation_in_order is inactive.
7239 : 113429 : )", 0) \
7240 : 113429 : DECLARE(Bool, parallel_replicas_only_with_analyzer, true, R"(
7241 : 113429 : The analyzer should be enabled to use parallel replicas. With disabled analyzer query execution fallbacks to local execution, even if parallel reading from replicas is enabled. Using parallel replicas without the analyzer enabled is not supported
7242 : 113429 : )", 0) \
7243 : 113429 : DECLARE(Bool, parallel_replicas_insert_select_local_pipeline, true, R"(
7244 : 113429 : Use local pipeline during distributed INSERT SELECT with parallel replicas
7245 : 113429 : )", 0) \
7246 : 113429 : DECLARE(Milliseconds, parallel_replicas_connect_timeout_ms, 300, R"(
7247 : 113429 : The timeout in milliseconds for connecting to a remote replica during query execution with parallel replicas. If the timeout is expired, the corresponding replicas is not used for query execution
7248 : 113429 : )", 0) \
7249 : 113429 : DECLARE(Bool, parallel_replicas_for_cluster_engines, true, R"(
7250 : 113429 : Replace table function engines with their -Cluster alternatives
7251 : 113429 : )", 0) \
7252 : 113429 : DECLARE(Bool, parallel_replicas_allow_materialized_views, true, R"(
7253 : 113429 : Allow usage of materialized views with parallel replicas
7254 : 113429 : )", 0) \
7255 : 113429 : DECLARE(Bool, parallel_replicas_filter_pushdown, false, R"(
7256 : 113429 : Allow pushing down filters to part of query which parallel replicas choose to execute
7257 : 113429 : )", BETA) \
7258 : 113429 : DECLARE(Bool, parallel_replicas_allow_view_over_mergetree, false, R"(
7259 : 113429 : Allow parallel replicas to execute the outer query of a simple view over `MergeTree` tables (instead of the view's inner query), improving parallelization across nodes. Also applies to `UNION ALL` views whose branches all read from different `MergeTree` tables.
7260 : 113429 : )", BETA) \
7261 : 113429 : DECLARE(Bool, distributed_index_analysis, false, R"(
7262 : 113429 : Index analysis will be distributed across replicas.
7263 : 113429 : Beneficial for shared storage and huge amount of data in cluster.
7264 : 113429 : Uses replicas from cluster_for_parallel_replicas.
7265 : 113429 :
7266 : 113429 : **See also**
7267 : 113429 :
7268 : 113429 : - [distributed_index_analysis_for_non_shared_merge_tree](#distributed_index_analysis_for_non_shared_merge_tree)
7269 : 113429 : - [distributed_index_analysis_min_parts_to_activate](merge-tree-settings.md/#distributed_index_analysis_min_parts_to_activate)
7270 : 113429 : - [distributed_index_analysis_min_indexes_bytes_to_activate](merge-tree-settings.md/#distributed_index_analysis_min_indexes_bytes_to_activate)
7271 : 113429 : )", EXPERIMENTAL) \
7272 : 113429 : DECLARE(Bool, distributed_index_analysis_only_on_coordinator, false, R"(
7273 : 113429 : If enabled, distributed index analysis runs only on the coordinator.
7274 : 113429 : This prevents O(N^2) spawned queries when the predicate contains subqueries (e.g., `IN (SELECT ...)`),
7275 : 113429 : because each follower replica would otherwise independently trigger its own distributed index analysis,
7276 : 113429 : but makes distributed index analysis less efficient if large tables are used in the subqueries.
7277 : 113429 : )", 0) \
7278 : 113429 : DECLARE(Bool, distributed_index_analysis_for_non_shared_merge_tree, false, R"(
7279 : 113429 : Enable distributed index analysis even for non SharedMergeTree (cloud only engine).
7280 : 113429 : )", 0) \
7281 : 113429 : DECLARE_WITH_ALIAS(Bool, allow_experimental_database_iceberg, false, R"(
7282 : 113429 : Allow experimental database engine DataLakeCatalog with catalog_type = 'iceberg'
7283 : 113429 :
7284 : 113429 : Cloud default value: `1`.
7285 : 113429 : )", BETA, allow_database_iceberg) \
7286 : 113429 : DECLARE_WITH_ALIAS(Bool, allow_experimental_database_unity_catalog, false, R"(
7287 : 113429 : Allow experimental database engine DataLakeCatalog with catalog_type = 'unity'
7288 : 113429 :
7289 : 113429 : Cloud default value: `1`.
7290 : 113429 : )", BETA, allow_database_unity_catalog) \
7291 : 113429 : DECLARE_WITH_ALIAS(Bool, allow_experimental_database_glue_catalog, false, R"(
7292 : 113429 : Allow experimental database engine DataLakeCatalog with catalog_type = 'glue'
7293 : 113429 :
7294 : 113429 : Cloud default value: `1`.
7295 : 113429 : )", BETA, allow_database_glue_catalog) \
7296 : 113429 : DECLARE_WITH_ALIAS(Bool, allow_experimental_analyzer, true, R"(
7297 : 113429 : Allow new query analyzer.
7298 : 113429 : )", IMPORTANT, enable_analyzer) \
7299 : 113429 : DECLARE(Bool, analyzer_compatibility_join_using_top_level_identifier, false, R"(
7300 : 113429 : 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`).
7301 : 113429 : )", 0) \
7302 : 113429 : DECLARE(Bool, analyzer_compatibility_allow_compound_identifiers_in_unflatten_nested, true, R"(
7303 : 113429 : Allow to add compound identifiers to nested. This is a compatibility setting because it changes the query result. When disabled, `SELECT a.b.c FROM table ARRAY JOIN a` does not work, and `SELECT a FROM table` does not include `a.b.c` column into `Nested a` result.
7304 : 113429 : )", 0) \
7305 : 113429 : \
7306 : 113429 : DECLARE(Timezone, session_timezone, "", R"(
7307 : 113429 : Sets the implicit time zone of the current session or query.
7308 : 113429 : The implicit time zone is the time zone applied to values of type DateTime/DateTime64 which have no explicitly specified time zone.
7309 : 113429 : The setting takes precedence over the globally configured (server-level) implicit time zone.
7310 : 113429 : A value of '' (empty string) means that the implicit time zone of the current session or query is equal to the [server time zone](../server-configuration-parameters/settings.md/#timezone).
7311 : 113429 :
7312 : 113429 : You can use functions `timeZone()` and `serverTimeZone()` to get the session time zone and server time zone.
7313 : 113429 :
7314 : 113429 : Possible values:
7315 : 113429 :
7316 : 113429 : - Any time zone name from `system.time_zones`, e.g. `Europe/Berlin`, `UTC` or `Zulu`
7317 : 113429 :
7318 : 113429 : Examples:
7319 : 113429 :
7320 : 113429 : ```sql
7321 : 113429 : SELECT timeZone(), serverTimeZone() FORMAT CSV
7322 : 113429 :
7323 : 113429 : "Europe/Berlin","Europe/Berlin"
7324 : 113429 : ```
7325 : 113429 :
7326 : 113429 : ```sql
7327 : 113429 : SELECT timeZone(), serverTimeZone() SETTINGS session_timezone = 'Asia/Novosibirsk' FORMAT CSV
7328 : 113429 :
7329 : 113429 : "Asia/Novosibirsk","Europe/Berlin"
7330 : 113429 : ```
7331 : 113429 :
7332 : 113429 : Assign session time zone 'America/Denver' to the inner DateTime without explicitly specified time zone:
7333 : 113429 :
7334 : 113429 : ```sql
7335 : 113429 : SELECT toDateTime64(toDateTime64('1999-12-12 23:23:23.123', 3), 3, 'Europe/Zurich') SETTINGS session_timezone = 'America/Denver' FORMAT TSV
7336 : 113429 :
7337 : 113429 : 1999-12-13 07:23:23.123
7338 : 113429 : ```
7339 : 113429 :
7340 : 113429 : :::warning
7341 : 113429 : Not all functions that parse DateTime/DateTime64 respect `session_timezone`. This can lead to subtle errors.
7342 : 113429 : See the following example and explanation.
7343 : 113429 : :::
7344 : 113429 :
7345 : 113429 : ```sql
7346 : 113429 : CREATE TABLE test_tz (`d` DateTime('UTC')) ENGINE = Memory AS SELECT toDateTime('2000-01-01 00:00:00', 'UTC');
7347 : 113429 :
7348 : 113429 : SELECT *, timeZone() FROM test_tz WHERE d = toDateTime('2000-01-01 00:00:00') SETTINGS session_timezone = 'Asia/Novosibirsk'
7349 : 113429 : 0 rows in set.
7350 : 113429 :
7351 : 113429 : SELECT *, timeZone() FROM test_tz WHERE d = '2000-01-01 00:00:00' SETTINGS session_timezone = 'Asia/Novosibirsk'
7352 : 113429 : ┌───────────────────d─┬─timeZone()───────┐
7353 : 113429 : │ 2000-01-01 00:00:00 │ Asia/Novosibirsk │
7354 : 113429 : └─────────────────────┴──────────────────┘
7355 : 113429 : ```
7356 : 113429 :
7357 : 113429 : This happens due to different parsing pipelines:
7358 : 113429 :
7359 : 113429 : - `toDateTime()` without explicitly given time zone used in the first `SELECT` query honors setting `session_timezone` and the global time zone.
7360 : 113429 : - In the second query, a DateTime is parsed from a String, and inherits the type and time zone of the existing column`d`. Thus, setting `session_timezone` and the global time zone are not honored.
7361 : 113429 :
7362 : 113429 : **See also**
7363 : 113429 :
7364 : 113429 : - [timezone](../server-configuration-parameters/settings.md/#timezone)
7365 : 113429 : )", BETA) \
7366 : 113429 : DECLARE(Bool, create_if_not_exists, false, R"(
7367 : 113429 : Enable `IF NOT EXISTS` for `CREATE` statement by default. If either this setting or `IF NOT EXISTS` is specified and a table with the provided name already exists, no exception will be thrown.
7368 : 113429 : )", 0) \
7369 : 113429 : DECLARE(Bool, enforce_strict_identifier_format, false, R"(
7370 : 113429 : If enabled, only allow identifiers containing alphanumeric characters and underscores.
7371 : 113429 : )", 0) \
7372 : 113429 : DECLARE(UInt64, max_limit_for_vector_search_queries, 1'000, R"(
7373 : 113429 : SELECT queries with LIMIT bigger than this setting cannot use vector similarity indices. Helps to prevent memory overflows in vector similarity indices.
7374 : 113429 : )", 0) \
7375 : 113429 : DECLARE(UInt64, hnsw_candidate_list_size_for_search, 256, R"(
7376 : 113429 : The size of the dynamic candidate list when searching the vector similarity index, also known as 'ef_search'.
7377 : 113429 : )", 0) \
7378 : 113429 : DECLARE(Bool, vector_search_with_rescoring, false, R"(
7379 : 113429 : If ClickHouse performs rescoring for queries that use the vector similarity index.
7380 : 113429 : Without rescoring, the vector similarity index returns the rows containing the best matches directly.
7381 : 113429 : With rescoring, the rows are extrapolated to granule level and all rows in the granule are checked again.
7382 : 113429 : In most situations, rescoring helps only marginally with accuracy but it deteriorates performance of vector search queries significantly.
7383 : 113429 : Note: A query run without rescoring and with parallel replicas enabled may fall back to rescoring.
7384 : 113429 : )", 0) \
7385 : 113429 : DECLARE(VectorSearchFilterStrategy, vector_search_filter_strategy, VectorSearchFilterStrategy::AUTO, R"(
7386 : 113429 : If a vector search query has a WHERE clause, this setting determines if it is evaluated first (pre-filtering) OR if the vector similarity index is checked first (post-filtering). Possible values:
7387 : 113429 : - 'auto' - Postfiltering (the exact semantics may change in future).
7388 : 113429 : - 'postfilter' - Use vector similarity index to identify the nearest neighbours, then apply other filters
7389 : 113429 : - 'prefilter' - Evaluate other filters first, then perform brute-force search to identify neighbours.
7390 : 113429 : )", 0) \
7391 : 113429 : DECLARE_WITH_ALIAS(Float, vector_search_index_fetch_multiplier, 1.0, R"(
7392 : 113429 : Multiply the number of fetched nearest neighbors from the vector similarity index by this number. Only applied for post-filtering with other predicates or if setting 'vector_search_with_rescoring = 1'.
7393 : 113429 : )", 0, vector_search_postfilter_multiplier) \
7394 : 113429 : DECLARE(Bool, mongodb_throw_on_unsupported_query, true, R"(
7395 : 113429 : If enabled, MongoDB tables will return an error when a MongoDB query cannot be built. Otherwise, ClickHouse reads the full table and processes it locally. This option does not apply when 'allow_experimental_analyzer=0'.
7396 : 113429 : )", 0) \
7397 : 113429 : DECLARE(Bool, implicit_select, false, R"(
7398 : 113429 : Allow writing simple SELECT queries without the leading SELECT keyword, which makes it simple for calculator-style usage, e.g. `1 + 2` becomes a valid query.
7399 : 113429 :
7400 : 113429 : In `clickhouse-local` it is enabled by default and can be explicitly disabled.
7401 : 113429 : )", 0) \
7402 : 113429 : DECLARE(Bool, optimize_extract_common_expressions, true, R"(
7403 : 113429 : Allow extracting common expressions from disjunctions in WHERE, PREWHERE, ON, HAVING and QUALIFY expressions. A logical expression like `(A AND B) OR (A AND C)` can be rewritten to `A AND (B OR C)`, which might help to utilize:
7404 : 113429 : - indices in simple filtering expressions
7405 : 113429 : - cross to inner join optimization
7406 : 113429 : )", 0) \
7407 : 113429 : DECLARE(Bool, optimize_and_compare_chain, true, R"(
7408 : 113429 : Populate constant comparison in AND chains to enhance filtering ability. Support operators `<`, `<=`, `>`, `>=`, `=` and mix of them. For example, `(a < b) AND (b < c) AND (c < 5)` would be `(a < b) AND (b < c) AND (c < 5) AND (b < 5) AND (a < 5)`.
7409 : 113429 : )", 0) \
7410 : 113429 : DECLARE(Bool, push_external_roles_in_interserver_queries, true, R"(
7411 : 113429 : Enable pushing user roles from originator to other nodes while performing a query.
7412 : 113429 : )", 0) \
7413 : 113429 : DECLARE(Bool, use_join_disjunctions_push_down, true, R"(
7414 : 113429 : Enable pushing OR-connected parts of JOIN conditions down to the corresponding input sides ("partial pushdown").
7415 : 113429 : This allows storage engines to filter earlier, which can reduce data read.
7416 : 113429 : The optimization is semantics-preserving and is applied only when each top-level OR branch contributes at least one deterministic
7417 : 113429 : predicate for the target side.
7418 : 113429 : )", 0) \
7419 : 113429 : DECLARE(Bool, shared_merge_tree_sync_parts_on_partition_operations, true, R"(
7420 : 113429 : Automatically synchronize set of data parts after MOVE|REPLACE|ATTACH partition operations in SMT tables. Cloud only
7421 : 113429 : )", 0) \
7422 : 113429 : DECLARE(String, implicit_table_at_top_level, "", R"(
7423 : 113429 : If not empty, queries without FROM at the top level will read from this table instead of system.one.
7424 : 113429 :
7425 : 113429 : This is used in clickhouse-local for input data processing.
7426 : 113429 : The setting could be set explicitly by a user but is not intended for this type of usage.
7427 : 113429 :
7428 : 113429 : Subqueries are not affected by this setting (neither scalar, FROM, or IN subqueries).
7429 : 113429 : SELECTs at the top level of UNION, INTERSECT, EXCEPT chains are treated uniformly and affected by this setting, regardless of their grouping in parentheses.
7430 : 113429 : It is unspecified how this setting affects views and distributed queries.
7431 : 113429 :
7432 : 113429 : The setting accepts a table name (then the table is resolved from the current database) or a qualified name in the form of 'database.table'.
7433 : 113429 : Both database and table names have to be unquoted - only simple identifiers are allowed.
7434 : 113429 : )", 0) \
7435 : 113429 : DECLARE(Bool, allow_general_join_planning, true, R"(
7436 : 113429 : Allows a more general join planning algorithm that can handle more complex conditions, but only works with hash join. If hash join is not enabled, then the usual join planning algorithm is used regardless of the value of this setting.
7437 : 113429 : )", 0) \
7438 : 113429 : DECLARE(ObjectStorageGranularityLevel, cluster_table_function_split_granularity, ObjectStorageGranularityLevel::FILE, R"(
7439 : 113429 : Controls how data is split into tasks when executing a CLUSTER TABLE FUNCTION.
7440 : 113429 :
7441 : 113429 : This setting defines the granularity of work distribution across the cluster:
7442 : 113429 : - `file` — each task processes an entire file.
7443 : 113429 : - `bucket` — tasks are created per internal data block within a file (for example, Parquet row groups).
7444 : 113429 :
7445 : 113429 : Choosing finer granularity (like `bucket`) can improve parallelism when working with a small number of large files.
7446 : 113429 : For instance, if a Parquet file contains multiple row groups, enabling `bucket` granularity allows each group to be processed independently by different workers.
7447 : 113429 : )", 0) \
7448 : 113429 : DECLARE(UInt64, cluster_table_function_buckets_batch_size, 0, R"(
7449 : 113429 : Defines the approximate size of a batch (in bytes) used in distributed processing of tasks in cluster table functions with `bucket` split granularity. The system accumulates data until at least this amount is reached. The actual size may be slightly larger to align with data boundaries.
7450 : 113429 : )", 0) \
7451 : 113429 : DECLARE(UInt64, merge_table_max_tables_to_look_for_schema_inference, 1000, R"(
7452 : 113429 : When creating a `Merge` table without an explicit schema or when using the `merge` table function, infer schema as a union of not more than the specified number of matching tables.
7453 : 113429 : If there is a larger number of tables, the schema will be inferred from the first specified number of tables.
7454 : 113429 : )", 0) \
7455 : 113429 : DECLARE(Bool, validate_enum_literals_in_operators, false, R"(
7456 : 113429 : If enabled, validate enum literals in operators like `IN`, `NOT IN`, `==`, `!=` against the enum type and throw an exception if the literal is not a valid enum value.
7457 : 113429 : )", 0) \
7458 : 113429 : \
7459 : 113429 : DECLARE(UInt64, max_autoincrement_series, 1000, R"(
7460 : 113429 : The limit on the number of series created by the `generateSerialID` function.
7461 : 113429 :
7462 : 113429 : As each series represents a node in Keeper, it is recommended to have no more than a couple of millions of them.
7463 : 113429 : )", 0) \
7464 : 113429 : DECLARE(Bool, use_hive_partitioning, true, R"(
7465 : 113429 : When enabled, ClickHouse will detect Hive-style partitioning in path (`/name=value/`) in file-like table engines [File](/sql-reference/table-functions/file#hive-style-partitioning)/[S3](/sql-reference/table-functions/s3#hive-style-partitioning)/[URL](/sql-reference/table-functions/url#hive-style-partitioning)/[HDFS](/sql-reference/table-functions/hdfs#hive-style-partitioning)/[AzureBlobStorage](/sql-reference/table-functions/azureBlobStorage#hive-style-partitioning) and will allow to use partition columns as virtual columns in the query. These virtual columns will have the same names as in the partitioned path, but starting with `_`.
7466 : 113429 : )", 0) \
7467 : 113429 : DECLARE(UInt64, parallel_hash_join_threshold, 100'000, R"(
7468 : 113429 : When hash-based join algorithm is applied, this threshold helps to decide between using `hash` and `parallel_hash` (only if estimation of the right table size is available).
7469 : 113429 : The former is used when we know that the right table size is below the threshold.
7470 : 113429 : )", 0) \
7471 : 113429 : DECLARE(Bool, apply_settings_from_server, true, R"(
7472 : 113429 : Whether the client should accept settings from server.
7473 : 113429 :
7474 : 113429 : This only affects operations performed on the client side, in particular parsing the INSERT input data and formatting the query result. Most of query execution happens on the server and is not affected by this setting.
7475 : 113429 :
7476 : 113429 : Normally this setting should be set in user profile (users.xml or queries like `ALTER USER`), not through the client (client command line arguments, `SET` query, or `SETTINGS` section of `SELECT` query). Through the client it can be changed to false, but can't be changed to true (because the server won't send the settings if user profile has `apply_settings_from_server = false`).
7477 : 113429 :
7478 : 113429 : Note that initially (24.12) there was a server setting (`send_settings_to_client`), but latter it got replaced with this client setting, for better usability.
7479 : 113429 : )", 0) \
7480 : 113429 : DECLARE(Bool, allow_archive_path_syntax, true, R"(
7481 : 113429 : File/S3 engines/table function will parse paths with '::' as `<archive> :: <file>` if the archive has correct extension.
7482 : 113429 : )", 0) \
7483 : 113429 : DECLARE(S3UriStyle, s3_uri_style, S3UriStyle::AUTO, R"(
7484 : 113429 : Force the s3 endpoint style. Possible values: auto, virtual_hosted, path.
7485 : 113429 : )", 0) \
7486 : 113429 : DECLARE(Milliseconds, low_priority_query_wait_time_ms, 1000, R"(
7487 : 113429 : When the query prioritization mechanism is employed (see setting `priority`), low-priority queries wait for higher-priority queries to finish. This setting specifies the duration of waiting.
7488 : 113429 : )", BETA) \
7489 : 113429 : DECLARE(UInt64, iceberg_insert_max_rows_in_data_file, 1000000, R"(
7490 : 113429 : Max rows of iceberg parquet data file on insert operation.
7491 : 113429 : )", 0) \
7492 : 113429 : DECLARE(UInt64, iceberg_insert_max_bytes_in_data_file, 1_GiB, R"(
7493 : 113429 : Max bytes of iceberg parquet data file on insert operation.
7494 : 113429 : )", 0) \
7495 : 113429 : DECLARE(UInt64, iceberg_insert_max_partitions, 100, R"(
7496 : 113429 : Max allowed partitions count per one insert operation for Iceberg table engine.
7497 : 113429 : )", 0) \
7498 : 113429 : DECLARE(Bool, database_datalake_require_metadata_access, true, R"(
7499 : 113429 : Either to throw error or not if we don't have rights to get table's metadata in database engine DataLakeCatalog.
7500 : 113429 : )", 0) \
7501 : 113429 : DECLARE(Float, min_os_cpu_wait_time_ratio_to_throw, 0.0, "Min ratio between OS CPU wait (OSCPUWaitMicroseconds metric) and busy (OSCPUVirtualTimeMicroseconds metric) times to consider rejecting queries. Linear interpolation between min and max ratio is used to calculate the probability, the probability is 0 at this point.", 0) \
7502 : 113429 : DECLARE(Float, max_os_cpu_wait_time_ratio_to_throw, 0.0, "Max ratio between OS CPU wait (OSCPUWaitMicroseconds metric) and busy (OSCPUVirtualTimeMicroseconds metric) times to consider rejecting queries. Linear interpolation between min and max ratio is used to calculate the probability, the probability is 1 at this point.", 0) \
7503 : 113429 : DECLARE(Bool, enable_producing_buckets_out_of_order_in_aggregation, true, R"(
7504 : 113429 : Allow memory-efficient aggregation (see `distributed_aggregation_memory_efficient`) to produce buckets out of order.
7505 : 113429 : It may improve performance when aggregation bucket sizes are skewed by letting a replica to send buckets with higher id-s to the initiator while it is still processing some heavy buckets with lower id-s.
7506 : 113429 : The downside is potentially higher memory usage.
7507 : 113429 : )", 0) \
7508 : 113429 : DECLARE(Bool, enable_parallel_blocks_marshalling, true, "Affects only distributed queries. If enabled, blocks will be (de)serialized and (de)compressed on pipeline threads (i.e. with higher parallelism that what we have by default) before/after sending to the initiator.", 0) \
7509 : 113429 : DECLARE(UInt64, min_outstreams_per_resize_after_split, 24, R"(
7510 : 113429 : Specifies the minimum number of output streams of a `Resize` or `StrictResize` processor after the split is performed during pipeline generation. If the resulting number of streams is less than this value, the split operation will not occur.
7511 : 113429 :
7512 : 113429 : ### What is a Resize Node
7513 : 113429 : A `Resize` node is a processor in the query pipeline that adjusts the number of data streams flowing through the pipeline. It can either increase or decrease the number of streams to balance the workload across multiple threads or processors. For example, if a query requires more parallelism, the `Resize` node can split a single stream into multiple streams. Conversely, it can merge multiple streams into fewer streams to consolidate data processing.
7514 : 113429 :
7515 : 113429 : The `Resize` node ensures that data is evenly distributed across streams, maintaining the structure of the data blocks. This helps optimize resource utilization and improve query performance.
7516 : 113429 :
7517 : 113429 : ### Why the Resize Node Needs to Be Split
7518 : 113429 : During pipeline execution, ExecutingGraph::Node::status_mutex of the centrally-hubbed `Resize` node is heavily contended especially in high-core-count environments, and this contention leads to:
7519 : 113429 : 1. Increased latency for ExecutingGraph::updateNode, directly impacting query performance.
7520 : 113429 : 2. Excessive CPU cycles are wasted in spin-lock contention (native_queued_spin_lock_slowpath), degrading efficiency.
7521 : 113429 : 3. Reduced CPU utilization, limiting parallelism and throughput.
7522 : 113429 :
7523 : 113429 : ### How the Resize Node Gets Split
7524 : 113429 : 1. The number of output streams is checked to ensure the split could be performed: the output streams of each split processor meet or exceed the `min_outstreams_per_resize_after_split` threshold.
7525 : 113429 : 2. The `Resize` node is divided into smaller `Resize` nodes with equal count of ports, each handling a subset of input and output streams.
7526 : 113429 : 3. Each group is processed independently, reducing the lock contention.
7527 : 113429 :
7528 : 113429 : ### Splitting Resize Node with Arbitrary Inputs/Outputs
7529 : 113429 : In some cases, where the inputs/outputs are indivisible by the number of split `Resize` nodes, some inputs are connected to `NullSource`s and some outputs are connected to `NullSink`s. This allows the split to occur without affecting the overall data flow.
7530 : 113429 :
7531 : 113429 : ### Purpose of the Setting
7532 : 113429 : The `min_outstreams_per_resize_after_split` setting ensures that the splitting of `Resize` nodes is meaningful and avoids creating too few streams, which could lead to inefficient parallel processing. By enforcing a minimum number of output streams, this setting helps maintain a balance between parallelism and overhead, optimizing query execution in scenarios involving stream splitting and merging.
7533 : 113429 :
7534 : 113429 : ### Disabling the Setting
7535 : 113429 : To disable the split of `Resize` nodes, set this setting to 0. This will prevent the splitting of `Resize` nodes during pipeline generation, allowing them to retain their original structure without division into smaller nodes.
7536 : 113429 : )", 0) \
7537 : 113429 : DECLARE(Bool, enable_add_distinct_to_in_subqueries, false, R"(
7538 : 113429 : Enable `DISTINCT` in `IN` subqueries. This is a trade-off setting: enabling it can greatly reduce the size of temporary tables transferred for distributed IN subqueries and significantly speed up data transfer between shards, by ensuring only unique values are sent.
7539 : 113429 : However, enabling this setting adds extra merging effort on each node, as deduplication (DISTINCT) must be performed. Use this setting when network transfer is a bottleneck and the additional merging cost is acceptable.
7540 : 113429 : )", 0) \
7541 : 113429 : DECLARE(UInt64, function_date_trunc_return_type_behavior, 0, R"(
7542 : 113429 : Allows to change the behaviour of the result type of `dateTrunc` function.
7543 : 113429 :
7544 : 113429 : Possible values:
7545 : 113429 :
7546 : 113429 : - 0 - When the second argument is `DateTime64/Date32` the return type will be `DateTime64/Date32` regardless of the time unit in the first argument.
7547 : 113429 : - 1 - For `Date32` the result is always `Date`. For `DateTime64` the result is `DateTime` for time units `second` and higher.
7548 : 113429 : )", 0) \
7549 : 113429 : DECLARE(Bool, query_plan_remove_unused_columns, true, R"(
7550 : 113429 : Toggles a query-plan-level optimization which tries to remove unused columns (both input and output columns) from query plan steps.
7551 : 113429 : Only takes effect if setting [query_plan_enable_optimizations](#query_plan_enable_optimizations) is 1.
7552 : 113429 :
7553 : 113429 : :::note
7554 : 113429 : 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.
7555 : 113429 : :::
7556 : 113429 :
7557 : 113429 : Possible values:
7558 : 113429 :
7559 : 113429 : - 0 - Disable
7560 : 113429 : - 1 - Enable
7561 : 113429 : )", 0) \
7562 : 113429 : DECLARE(Bool, jemalloc_enable_profiler, false, R"(
7563 : 113429 : Enable jemalloc profiler for the query. Jemalloc will sample allocations and all deallocations for sampled allocations.
7564 : 113429 : Profiles can be flushed using SYSTEM JEMALLOC FLUSH PROFILE which can be used for allocation analysis.
7565 : 113429 : Samples can also be stored in system.trace_log using config jemalloc_collect_global_profile_samples_in_trace_log or with query setting jemalloc_collect_profile_samples_in_trace_log.
7566 : 113429 : See [Allocation Profiling](/operations/allocation-profiling))", 0) \
7567 : 113429 : DECLARE(Bool, jemalloc_collect_profile_samples_in_trace_log, false, R"(
7568 : 113429 : Collect jemalloc allocation and deallocation samples in trace log.
7569 : 113429 : )", 0) \
7570 : 113429 : DECLARE(JemallocProfileFormat, jemalloc_profile_text_output_format, JemallocProfileFormat::Collapsed, R"(
7571 : 113429 : Output format for jemalloc heap profile in system.jemalloc_profile_text table. Can be: 'raw' (raw profile), 'symbolized' (jeprof format with symbols), or 'collapsed' (FlameGraph format).
7572 : 113429 : )", 0) \
7573 : 113429 : DECLARE(Bool, jemalloc_profile_text_symbolize_with_inline, true, R"(
7574 : 113429 : Whether to include inline frames when symbolizing jemalloc heap profile. When enabled, inline frames are included which can slow down symbolization process drastically; when disabled, they are skipped. Only affects 'symbolized' and 'collapsed' output formats.
7575 : 113429 : )", 0) \
7576 : 113429 : DECLARE(Bool, jemalloc_profile_text_collapsed_use_count, false, R"(
7577 : 113429 : When using the 'collapsed' output format for jemalloc heap profile, aggregate by allocation count instead of bytes. When false (default), each stack is weighted by live bytes; when true, by live allocation count.
7578 : 113429 : )", 0) \
7579 : 113429 : DECLARE_WITH_ALIAS(Int32, os_threads_nice_value_query, 0, R"(
7580 : 113429 : Linux nice value for query processing threads. Lower values mean higher CPU priority.
7581 : 113429 :
7582 : 113429 : Requires CAP_SYS_NICE capability, otherwise no-op.
7583 : 113429 :
7584 : 113429 : Possible values: -20 to 19.
7585 : 113429 : )", 0, os_thread_priority) \
7586 : 113429 : DECLARE(Int32, os_threads_nice_value_materialized_view, 0, R"(
7587 : 113429 : Linux nice value for materialized view threads. Lower values mean higher CPU priority.
7588 : 113429 :
7589 : 113429 : Requires CAP_SYS_NICE capability, otherwise no-op.
7590 : 113429 :
7591 : 113429 : Possible values: -20 to 19.
7592 : 113429 : )", 0) \
7593 : 113429 : DECLARE(Bool, show_processlist_include_internal, 1, R"(
7594 : 113429 : Show internal auxiliary processes in the `SHOW PROCESSLIST` query output.
7595 : 113429 :
7596 : 113429 : Internal processes include dictionary reloads, refreshable materialized view reloads, auxiliary `SELECT`s executed in `SHOW ...` queries, auxiliary `CREATE DATABASE ...` queries executed internally to accommodate broken tables and more.
7597 : 113429 : )", 0) \
7598 : 113429 : DECLARE(Bool, use_roaring_bitmap_iceberg_positional_deletes, false, R"(
7599 : 113429 : Use roaring bitmap for iceberg positional deletes.
7600 : 113429 : )", 0) \
7601 : 113429 : DECLARE(Bool, inject_random_order_for_select_without_order_by, false, R"(
7602 : 113429 : If enabled, injects 'ORDER BY rand()' into SELECT queries without ORDER BY clause.
7603 : 113429 : Applied only for subquery depth = 0. Subqueries and INSERT INTO ... SELECT are not affected.
7604 : 113429 : If the top-level construct is UNION, 'ORDER BY rand()' is injected into all children independently.
7605 : 113429 : Only useful for testing and development (missing ORDER BY is a source of non-deterministic query results).
7606 : 113429 : )", 0) \
7607 : 113429 : DECLARE(Int64, optimize_const_name_size, 256, R"(
7608 : 113429 : Replace with scalar and use hash as a name for large constants (size is estimated by the name length).
7609 : 113429 :
7610 : 113429 : Possible values:
7611 : 113429 :
7612 : 113429 : - positive integer - max length of the name,
7613 : 113429 : - 0 — always,
7614 : 113429 : - negative integer - never.
7615 : 113429 : )", 0) \
7616 : 113429 : DECLARE(Bool, serialize_string_in_memory_with_zero_byte, true, R"(
7617 : 113429 : Serialize String values during aggregation with zero byte at the end. Enable to keep compatibility when querying cluster of incompatible versions.
7618 : 113429 : )", 0) \
7619 : 113429 : DECLARE(UInt64, s3_path_filter_limit, 1000, R"(
7620 : 113429 : Maximum number of `_path` values that can be extracted from query filters to use for file iteration
7621 : 113429 : instead of glob listing. 0 means disabled.
7622 : 113429 : )", 0) \
7623 : 113429 : DECLARE(Bool, ignore_on_cluster_for_replicated_database, false, R"(
7624 : 113429 : Always ignore ON CLUSTER clause for DDL queries with replicated databases.
7625 : 113429 : )", 0) \
7626 : 113429 : DECLARE(UInt64, archive_adaptive_buffer_max_size_bytes, 8 * DBMS_DEFAULT_BUFFER_SIZE, R"(
7627 : 113429 : Limits the maximum size of the adaptive buffer used when writing to archive files (for example, tar archives)", 0) \
7628 : 113429 : DECLARE(Bool, enable_join_fixed_hash_table_conversion, true, R"(
7629 : 113429 : Enable converting the hash table to a flat array for joins when the key is a single integer with a small value range.
7630 : 113429 : )", 0) \
7631 : 113429 : \
7632 : 113429 : /* ####################################################### */ \
7633 : 113429 : /* ########### START OF EXPERIMENTAL FEATURES ############ */ \
7634 : 113429 : /* ## ADD PRODUCTION / BETA FEATURES BEFORE THIS BLOCK ## */ \
7635 : 113429 : /* ####################################################### */ \
7636 : 113429 : \
7637 : 113429 : DECLARE(Bool, allow_experimental_materialized_postgresql_table, false, R"(
7638 : 113429 : Allows to use the MaterializedPostgreSQL table engine. Disabled by default, because this feature is experimental
7639 : 113429 : )", EXPERIMENTAL) \
7640 : 113429 : DECLARE(Bool, allow_experimental_funnel_functions, false, R"(
7641 : 113429 : Enable experimental functions for funnel analysis.
7642 : 113429 : )", EXPERIMENTAL) \
7643 : 113429 : DECLARE(Bool, allow_experimental_nlp_functions, false, R"(
7644 : 113429 : Enable experimental functions for natural language processing.
7645 : 113429 : )", EXPERIMENTAL) \
7646 : 113429 : DECLARE(Bool, allow_experimental_hash_functions, false, R"(
7647 : 113429 : Enable experimental hash functions
7648 : 113429 : )", EXPERIMENTAL) \
7649 : 113429 : DECLARE(Bool, allow_experimental_time_series_table, false, R"(
7650 : 113429 : Allows creation of tables with the [TimeSeries](../../engines/table-engines/integrations/time-series.md) table engine. Possible values:
7651 : 113429 : - 0 — the [TimeSeries](../../engines/table-engines/integrations/time-series.md) table engine is disabled.
7652 : 113429 : - 1 — the [TimeSeries](../../engines/table-engines/integrations/time-series.md) table engine is enabled.
7653 : 113429 : )", EXPERIMENTAL) \
7654 : 113429 : DECLARE(Bool, allow_experimental_codecs, false, R"(
7655 : 113429 : If it is set to true, allow to specify experimental compression codecs (but we don't have those yet and this option does nothing).
7656 : 113429 : )", EXPERIMENTAL) \
7657 : 113429 : DECLARE(Bool, throw_on_unsupported_query_inside_transaction, true, R"(
7658 : 113429 : Throw exception if unsupported query is used inside transaction
7659 : 113429 : )", EXPERIMENTAL) \
7660 : 113429 : DECLARE(TransactionsWaitCSNMode, wait_changes_become_visible_after_commit_mode, TransactionsWaitCSNMode::WAIT_UNKNOWN, R"(
7661 : 113429 : Wait for committed changes to become actually visible in the latest snapshot
7662 : 113429 : )", EXPERIMENTAL) \
7663 : 113429 : DECLARE(Bool, implicit_transaction, false, R"(
7664 : 113429 : If enabled and not already inside a transaction, wraps the query inside a full transaction (begin + commit or rollback)
7665 : 113429 : )", EXPERIMENTAL) \
7666 : 113429 : DECLARE(NonZeroUInt64, grace_hash_join_initial_buckets, 1, R"(
7667 : 113429 : Initial number of grace hash join buckets
7668 : 113429 : )", EXPERIMENTAL) \
7669 : 113429 : DECLARE(NonZeroUInt64, grace_hash_join_max_buckets, 1024, R"(
7670 : 113429 : Limit on the number of grace hash join buckets
7671 : 113429 : )", EXPERIMENTAL) \
7672 : 113429 : DECLARE(UInt64, join_to_sort_minimum_perkey_rows, 40, R"(
7673 : 113429 : 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
7674 : 113429 : )", EXPERIMENTAL) \
7675 : 113429 : DECLARE(UInt64, join_to_sort_maximum_table_rows, 10000, R"(
7676 : 113429 : The maximum number of rows in the right table to determine whether to rerange the right table by key in left or inner join.
7677 : 113429 : )", EXPERIMENTAL) \
7678 : 113429 : DECLARE(Bool, allow_experimental_join_right_table_sorting, false, R"(
7679 : 113429 : If it is set to true, and the conditions of `join_to_sort_minimum_perkey_rows` and `join_to_sort_maximum_table_rows` are met, rerange the right table by key to improve the performance in left or inner hash join.
7680 : 113429 : )", EXPERIMENTAL) \
7681 : 113429 : DECLARE(Bool, allow_experimental_json_lazy_type_hints, false, R"(
7682 : 113429 : Enable experimental lazy type hints for JSON type. This feature allows optimizing JSON type conversions by deferring type hint evaluation.
7683 : 113429 : )", EXPERIMENTAL) \
7684 : 113429 : \
7685 : 113429 : DECLARE_WITH_ALIAS(Bool, allow_statistics_optimize, true, R"(
7686 : 113429 : Allows using statistics to optimize queries
7687 : 113429 : )", 0, allow_statistic_optimize) \
7688 : 113429 : DECLARE_WITH_ALIAS(Bool, use_statistics, true, R"( /// preferred over 'allow_statistics_optimize' because of consistency with 'use_primary_key' and 'use_skip_indexes'
7689 : 113429 : Allows using statistics to optimize queries
7690 : 113429 : )", 0, allow_statistic_optimize) \
7691 : 113429 : DECLARE_WITH_ALIAS(Bool, allow_statistics, true, R"(
7692 : 113429 : Allows defining columns with [statistics](../../engines/table-engines/mergetree-family/mergetree.md/#table_engine-mergetree-creating-a-table) and [manipulate statistics](../../engines/table-engines/mergetree-family/mergetree.md/#column-statistics).
7693 : 113429 : )", 0, allow_experimental_statistics) \
7694 : 113429 : DECLARE(Bool, use_statistics_cache, true, R"(Use statistics cache in a query to avoid the overhead of loading statistics of every parts)", 0) \
7695 : 113429 : \
7696 : 113429 : DECLARE_WITH_ALIAS(Bool, enable_full_text_index, true, R"(
7697 : 113429 : If set to true, allow using the text index.
7698 : 113429 : )", 0, allow_experimental_full_text_index) \
7699 : 113429 : DECLARE(Bool, query_plan_direct_read_from_text_index, true, R"(
7700 : 113429 : Allow to perform full text search filtering using only the inverted text index in query plan.
7701 : 113429 : )", 0) \
7702 : 113429 : DECLARE(Bool, query_plan_text_index_add_hint, true, R"(
7703 : 113429 : Allow to add hint (additional predicate) for filtering built from the inverted text index in query plan.
7704 : 113429 : )", 0) \
7705 : 113429 : DECLARE(Float, text_index_hint_max_selectivity, 0.2f, R"(
7706 : 113429 : Maximal selectivity of the filter to use the hint built from the inverted text index.
7707 : 113429 : )", 0) \
7708 : 113429 : DECLARE(Bool, use_text_index_like_evaluation_by_dictionary_scan, true, R"(
7709 : 113429 : Enable evaluation of LIKE/ILIKE queries by scanning the inverted text index dictionary.
7710 : 113429 : )", 0) \
7711 : 113429 : DECLARE(UInt64, text_index_like_min_pattern_length, 4, R"(
7712 : 113429 : Minimum length of the alphanumeric needle in a LIKE/ILIKE pattern required to use the text index LIKE evaluation by the dictionary scan.
7713 : 113429 : Patterns shorter than this threshold match too many dictionary tokens and are skipped to avoid expensive scans.
7714 : 113429 :
7715 : 113429 : Requires `use_text_index_like_evaluation_by_dictionary_scan` to be enabled.
7716 : 113429 : )", 0) \
7717 : 113429 : DECLARE(UInt64, text_index_like_max_postings_to_read, 50, R"(
7718 : 113429 : Maximum number of large postings to read when text index LIKE evaluation by the dictionary scan is enabled.
7719 : 113429 :
7720 : 113429 : Requires `use_text_index_like_evaluation_by_dictionary_scan` to be enabled.
7721 : 113429 : )", 0) \
7722 : 113429 : DECLARE(Bool, use_text_index_tokens_cache, false, R"(
7723 : 113429 : Whether to use a cache of deserialized text index token infos.
7724 : 113429 : Using the text index tokens cache can significantly reduce latency and increase throughput when working with a large number of text index queries.
7725 : 113429 : )", 0) \
7726 : 113429 : DECLARE(Bool, use_text_index_header_cache, false, R"(
7727 : 113429 : Whether to use a cache of deserialized text index header.
7728 : 113429 : Using the text index header cache can significantly reduce latency and increase throughput when working with a large number of text index queries.
7729 : 113429 : )", 0) \
7730 : 113429 : DECLARE(Bool, use_text_index_postings_cache, false, R"(
7731 : 113429 : Whether to use a cache of deserialized text index posting lists.
7732 : 113429 : Using the text index postings cache can significantly reduce latency and increase throughput when working with a large number of text index queries.
7733 : 113429 : )", 0) \
7734 : 113429 : DECLARE(Bool, allow_experimental_window_view, false, R"(
7735 : 113429 : Enable WINDOW VIEW. Not mature enough.
7736 : 113429 : )", EXPERIMENTAL) \
7737 : 113429 : DECLARE(Seconds, window_view_clean_interval, 60, R"(
7738 : 113429 : The clean interval of window view in seconds to free outdated data.
7739 : 113429 : )", EXPERIMENTAL) \
7740 : 113429 : DECLARE(Seconds, window_view_heartbeat_interval, 15, R"(
7741 : 113429 : The heartbeat interval in seconds to indicate watch query is alive.
7742 : 113429 : )", EXPERIMENTAL) \
7743 : 113429 : DECLARE(Seconds, wait_for_window_view_fire_signal_timeout, 10, R"(
7744 : 113429 : Timeout for waiting for window view fire signal in event time processing
7745 : 113429 : )", EXPERIMENTAL) \
7746 : 113429 : \
7747 : 113429 : DECLARE(Bool, stop_refreshable_materialized_views_on_startup, false, R"(
7748 : 113429 : 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.
7749 : 113429 : )", EXPERIMENTAL) \
7750 : 113429 : \
7751 : 113429 : DECLARE(Bool, allow_experimental_database_materialized_postgresql, false, R"(
7752 : 113429 : Allow to create database with Engine=MaterializedPostgreSQL(...).
7753 : 113429 : )", EXPERIMENTAL) \
7754 : 113429 : \
7755 : 113429 : DECLARE(Bool, allow_experimental_nullable_tuple_type, false, R"(
7756 : 113429 : Allows creation of [Nullable](../../sql-reference/data-types/nullable) [Tuple](../../sql-reference/data-types/tuple.md) columns in tables.
7757 : 113429 :
7758 : 113429 : This setting does not control whether extracted tuple subcolumns can be `Nullable` (for example, from Dynamic, Variant, JSON, or Tuple columns).
7759 : 113429 : Use `allow_nullable_tuple_in_extracted_subcolumns` to control whether extracted tuple subcolumns can be `Nullable`.
7760 : 113429 : )", EXPERIMENTAL) \
7761 : 113429 : DECLARE(Bool, allow_nullable_tuple_in_extracted_subcolumns, false, R"(
7762 : 113429 : Controls whether extracted subcolumns of type `Tuple(...)` can be typed as `Nullable(Tuple(...))`.
7763 : 113429 :
7764 : 113429 : - `false`: Return `Tuple(...)` and use default tuple values for rows where the subcolumn is missing.
7765 : 113429 : - `true`: Return `Nullable(Tuple(...))` and use `NULL` for rows where the subcolumn is missing.
7766 : 113429 :
7767 : 113429 : This setting controls extracted subcolumn behavior only.
7768 : 113429 : It does not control whether `Nullable(Tuple(...))` columns can be created in tables; that is controlled by `allow_experimental_nullable_tuple_type`.
7769 : 113429 :
7770 : 113429 : ClickHouse uses the value for this setting loaded at server startup.
7771 : 113429 : Changes made with `SET` or query-level `SETTINGS` do not change extracted subcolumn behavior.
7772 : 113429 : To change extracted subcolumn behavior, update `allow_nullable_tuple_in_extracted_subcolumns` in startup profile configuration (for example, users.xml) and restart the server.
7773 : 113429 : )", 0) \
7774 : 113429 : \
7775 : 113429 : /** Experimental feature for moving data between shards. */ \
7776 : 113429 : DECLARE(Bool, allow_experimental_query_deduplication, false, R"(
7777 : 113429 : Experimental data deduplication for SELECT queries based on part UUIDs
7778 : 113429 : )", EXPERIMENTAL) \
7779 : 113429 : DECLARE(Bool, allow_experimental_database_hms_catalog, false, R"(
7780 : 113429 : Allow experimental database engine DataLakeCatalog with catalog_type = 'hms'
7781 : 113429 : )", EXPERIMENTAL) \
7782 : 113429 : DECLARE(Bool, allow_experimental_kusto_dialect, false, R"(
7783 : 113429 : Enable Kusto Query Language (KQL) - an alternative to SQL.
7784 : 113429 : )", EXPERIMENTAL) \
7785 : 113429 : DECLARE(Bool, allow_experimental_prql_dialect, false, R"(
7786 : 113429 : Enable PRQL - an alternative to SQL.
7787 : 113429 : )", EXPERIMENTAL) \
7788 : 113429 : DECLARE(Bool, allow_experimental_polyglot_dialect, false, R"(
7789 : 113429 : Enable polyglot SQL transpiler - transpiles SQL from 30+ dialects (MySQL, PostgreSQL, SQLite, Snowflake, DuckDB, etc.) into ClickHouse SQL.
7790 : 113429 : )", EXPERIMENTAL) \
7791 : 113429 : DECLARE(String, polyglot_dialect, "", R"(
7792 : 113429 : Source SQL dialect for the polyglot transpiler (e.g. 'sqlite', 'mysql', 'postgresql', 'snowflake', 'duckdb').
7793 : 113429 : )", EXPERIMENTAL) \
7794 : 113429 : DECLARE(Bool, enable_adaptive_memory_spill_scheduler, false, R"(
7795 : 113429 : Trigger processor to spill data into external storage adpatively. grace join is supported at present.
7796 : 113429 : )", EXPERIMENTAL) \
7797 : 113429 : DECLARE(Bool, allow_experimental_delta_kernel_rs, true, R"(
7798 : 113429 : Allow experimental delta-kernel-rs implementation.
7799 : 113429 : )", BETA) \
7800 : 113429 : DECLARE_WITH_ALIAS(Bool, allow_insert_into_iceberg, false, R"(
7801 : 113429 : Allow to execute `insert` queries into iceberg.
7802 : 113429 : )", BETA, allow_experimental_insert_into_iceberg) \
7803 : 113429 : DECLARE(Bool, allow_experimental_iceberg_compaction, false, R"(
7804 : 113429 : Allow to explicitly use 'OPTIMIZE' for iceberg tables.
7805 : 113429 : )", EXPERIMENTAL) \
7806 : 113429 : DECLARE(Bool, allow_iceberg_remove_orphan_files, false, R"(
7807 : 113429 : Allow to use 'ALTER TABLE ... EXECUTE remove_orphan_files()' for iceberg tables.
7808 : 113429 : )", EXPERIMENTAL) \
7809 : 113429 : DECLARE(UInt64, iceberg_orphan_files_older_than_seconds, 259200, R"(
7810 : 113429 : Default age threshold in seconds for orphan file removal in Iceberg tables. Files newer than this are not considered orphans. Used when the older_than argument is omitted from the remove_orphan_files() procedure call. Default is 259200 (3 days).
7811 : 113429 : )", EXPERIMENTAL) \
7812 : 113429 : DECLARE(Bool, allow_experimental_expire_snapshots, false, R"(
7813 : 113429 : Allow to execute experimental Iceberg command `ALTER TABLE ... EXECUTE expire_snapshots`.
7814 : 113429 : )", EXPERIMENTAL) \
7815 : 113429 : DECLARE(Bool, write_full_path_in_iceberg_metadata, false, R"(
7816 : 113429 : Write full paths (including s3://) into iceberg metadata files.
7817 : 113429 : )", EXPERIMENTAL) \
7818 : 113429 : DECLARE(String, iceberg_metadata_compression_method, "", R"(
7819 : 113429 : Method to compress `.metadata.json` file.
7820 : 113429 : )", EXPERIMENTAL) \
7821 : 113429 : DECLARE(Bool, make_distributed_plan, false, R"(
7822 : 113429 : Make distributed query plan.
7823 : 113429 : )", EXPERIMENTAL) \
7824 : 113429 : DECLARE(Bool, distributed_plan_execute_locally, false, R"(
7825 : 113429 : Run all tasks of a distributed query plan locally. Useful for testing and debugging.
7826 : 113429 : )", EXPERIMENTAL) \
7827 : 113429 : DECLARE(NonZeroUInt64, distributed_plan_default_shuffle_join_bucket_count, 8, R"(
7828 : 113429 : Default number of buckets for distributed shuffle-hash-join.
7829 : 113429 : )", EXPERIMENTAL) \
7830 : 113429 : DECLARE(UInt64, distributed_plan_default_reader_bucket_count, 8, R"(
7831 : 113429 : Default number of tasks for parallel reading in distributed query. Tasks are spread across between replicas.
7832 : 113429 : )", EXPERIMENTAL) \
7833 : 113429 : DECLARE(Bool, distributed_plan_optimize_exchanges, true, R"(
7834 : 113429 : Removes unnecessary exchanges in distributed query plan. Disable it for debugging.
7835 : 113429 : )", 0) \
7836 : 113429 : DECLARE(String, distributed_plan_force_exchange_kind, "", R"(
7837 : 113429 : Force specified kind of Exchange operators between distributed query stages.
7838 : 113429 :
7839 : 113429 : Possible values:
7840 : 113429 :
7841 : 113429 : - '' - do not force any kind of Exchange operators, let the optimizer choose,
7842 : 113429 : - 'Persisted' - use temporary files in object storage,
7843 : 113429 : - 'Streaming' - stream exchange data over network.
7844 : 113429 : )", EXPERIMENTAL) \
7845 : 113429 : DECLARE(UInt64, distributed_plan_max_rows_to_broadcast, 20000, R"(
7846 : 113429 : Maximum rows to use broadcast join instead of shuffle join in distributed query plan.
7847 : 113429 : )", EXPERIMENTAL) \
7848 : 113429 : DECLARE(Bool, distributed_plan_prefer_replicas_over_workers, false, R"(
7849 : 113429 : Serialize the distributed query plan for execution at replicas.
7850 : 113429 : )", EXPERIMENTAL) \
7851 : 113429 : DECLARE(Bool, allow_experimental_ytsaurus_table_engine, false, R"(
7852 : 113429 : Experimental table engine for integration with YTsaurus.
7853 : 113429 : )", EXPERIMENTAL) \
7854 : 113429 : DECLARE(Bool, allow_experimental_ytsaurus_table_function, false, R"(
7855 : 113429 : Experimental table engine for integration with YTsaurus.
7856 : 113429 : )", EXPERIMENTAL) \
7857 : 113429 : DECLARE(Bool, allow_experimental_ytsaurus_dictionary_source, false, R"(
7858 : 113429 : Experimental dictionary source for integration with YTsaurus.
7859 : 113429 : )", EXPERIMENTAL) \
7860 : 113429 : DECLARE(Bool, distributed_plan_force_shuffle_aggregation, false, R"(
7861 : 113429 : Use Shuffle aggregation strategy instead of PartialAggregation + Merge in distributed query plan.
7862 : 113429 : )", EXPERIMENTAL) \
7863 : 113429 : DECLARE(Bool, enable_join_runtime_filters, true, R"(
7864 : 113429 : Filter left side by set of JOIN keys collected from the right side at runtime.
7865 : 113429 : )", BETA) \
7866 : 113429 : DECLARE(UInt64, join_runtime_filter_exact_values_limit, 10000, R"(
7867 : 113429 : Maximum number of elements in runtime filter that are stored as is in a set, when this threshold is exceeded it switches to bloom filter.
7868 : 113429 : )", EXPERIMENTAL) \
7869 : 113429 : DECLARE(UInt64, join_runtime_bloom_filter_bytes, 512_KiB, R"(
7870 : 113429 : Size in bytes of a bloom filter used as JOIN runtime filter (see enable_join_runtime_filters setting).
7871 : 113429 : )", EXPERIMENTAL) \
7872 : 113429 : DECLARE(UInt64, join_runtime_bloom_filter_hash_functions, 3, R"(
7873 : 113429 : Number of hash functions in a bloom filter used as JOIN runtime filter (see enable_join_runtime_filters setting).
7874 : 113429 : )", EXPERIMENTAL) \
7875 : 113429 : DECLARE(Double, join_runtime_filter_pass_ratio_threshold_for_disabling, 0.7, R"(
7876 : 113429 : If ratio of passed rows to checked rows is greater than this threshold the runtime filter is considered as poorly performing and is disabled for the next `join_runtime_filter_blocks_to_skip_before_reenabling` blocks to reduce the overhead.
7877 : 113429 : )", EXPERIMENTAL) \
7878 : 113429 : DECLARE(UInt64, join_runtime_filter_blocks_to_skip_before_reenabling, 30, R"(
7879 : 113429 : Number of blocks that are skipped before trying to dynamically re-enable a runtime filter that previously was disabled due to poor filtering ratio.
7880 : 113429 : )", EXPERIMENTAL) \
7881 : 113429 : DECLARE(Double, join_runtime_bloom_filter_max_ratio_of_set_bits, 0.7, R"(
7882 : 113429 : If the number of set bits in a runtime bloom filter exceeds this ratio the filter is completely disabled to reduce the overhead.
7883 : 113429 : )", EXPERIMENTAL) \
7884 : 113429 : DECLARE(Bool, rewrite_in_to_join, false, R"(
7885 : 113429 : Rewrite expressions like 'x IN subquery' to JOIN. This might be useful for optimizing the whole query with join reordering.
7886 : 113429 : )", EXPERIMENTAL) \
7887 : 113429 : \
7888 : 113429 : /** Experimental timeSeries* aggregate functions. */ \
7889 : 113429 : DECLARE_WITH_ALIAS(Bool, allow_experimental_time_series_aggregate_functions, false, R"(
7890 : 113429 : Experimental timeSeries* aggregate functions for Prometheus-like timeseries resampling, rate, delta calculation.
7891 : 113429 : )", EXPERIMENTAL, allow_experimental_ts_to_grid_aggregate_function) \
7892 : 113429 : \
7893 : 113429 : DECLARE(String, promql_database, "", R"(
7894 : 113429 : Specifies the database name used by the 'promql' dialect. Empty string means the current database.
7895 : 113429 : )", EXPERIMENTAL) \
7896 : 113429 : \
7897 : 113429 : DECLARE(String, promql_table, "", R"(
7898 : 113429 : Specifies the name of a TimeSeries table used by the 'promql' dialect.
7899 : 113429 : )", EXPERIMENTAL) \
7900 : 113429 : \
7901 : 113429 : DECLARE_WITH_ALIAS(FloatAuto, promql_evaluation_time, Field("auto"), R"(
7902 : 113429 : Sets the evaluation time to be used with promql dialect. 'auto' means the current time.
7903 : 113429 : )", EXPERIMENTAL, evaluation_time) \
7904 : 113429 : DECLARE(Bool, allow_experimental_alias_table_engine, false, R"(
7905 : 113429 : Allow to create table with the Alias engine.
7906 : 113429 : )", EXPERIMENTAL) \
7907 : 113429 : DECLARE(Bool, use_paimon_partition_pruning, false, R"(
7908 : 113429 : Use Paimon partition pruning for Paimon table functions
7909 : 113429 : )", EXPERIMENTAL) \
7910 : 113429 : DECLARE(Bool, allow_experimental_object_storage_queue_hive_partitioning, false, R"(
7911 : 113429 : Allow to use hive partitioning with S3Queue/AzureQueue engines
7912 : 113429 : )", EXPERIMENTAL) \
7913 : 113429 : DECLARE(JoinOrderAlgorithm, query_plan_optimize_join_order_algorithm, "greedy", R"(
7914 : 113429 : Specifies which JOIN order algorithms to attempt during query plan optimization. The following algorithms are available:
7915 : 113429 : - 'greedy' - basic greedy algorithm - works fast but might not produce the best join order
7916 : 113429 : - 'dpsize' - implements DPsize algorithm currently only for Inner joins - considers all possible join orders and finds the most optimal one but might be slow for queries with many tables and join predicates.
7917 : 113429 : Multiple algorithms can be specified, e.g. 'dpsize,greedy'.
7918 : 113429 : )", EXPERIMENTAL) \
7919 : 113429 : DECLARE(Bool, allow_experimental_database_paimon_rest_catalog, false, R"(
7920 : 113429 : Allow experimental database engine DataLakeCatalog with catalog_type = 'paimon_rest'
7921 : 113429 : )", EXPERIMENTAL) \
7922 : 113429 : DECLARE(UInt64, webassembly_udf_max_fuel, 100'000, R"(
7923 : 113429 : Fuel limit per WebAssembly UDF instance execution. Each WebAssembly instruction consumes some amount of fuel.
7924 : 113429 : Set to 0 for no limit.
7925 : 113429 : )", EXPERIMENTAL) \
7926 : 113429 : DECLARE(UInt64, webassembly_udf_max_memory, 128_MiB, R"(
7927 : 113429 : Memory limit in bytes per WebAssembly UDF instance.
7928 : 113429 : )", EXPERIMENTAL) \
7929 : 113429 : DECLARE(UInt64, webassembly_udf_max_input_block_size, 0, R"(
7930 : 113429 : Maximum number of rows passed to a WebAssembly UDF in a single block. Set to 0 to process all rows at once.
7931 : 113429 : )", EXPERIMENTAL) \
7932 : 113429 : DECLARE(UInt64, webassembly_udf_max_instances, 32, R"(
7933 : 113429 : Maximum number of WebAssembly UDF instances that can run in parallel per function.
7934 : 113429 : )", EXPERIMENTAL) \
7935 : 113429 : \
7936 : 113429 : /* ####################################################### */ \
7937 : 113429 : /* AI function settings */ \
7938 : 113429 : DECLARE(Bool, allow_experimental_ai_functions, false, R"(
7939 : 113429 : Enable experimental AI functions (e.g. `aiGenerateContent`). These functions make external HTTP calls to AI providers.
7940 : 113429 : )", EXPERIMENTAL) \
7941 : 113429 : DECLARE(UInt64, ai_function_request_timeout_sec, 60, R"(
7942 : 113429 : Timeout in seconds for individual HTTP requests made by AI functions (AI chat completions and embedding API calls). If a request does not complete within this time, it is considered failed and may be retried according to `ai_function_max_retries`.
7943 : 113429 : )", EXPERIMENTAL) \
7944 : 113429 : DECLARE(UInt64, ai_function_max_retries, 0, R"(
7945 : 113429 : Maximum number of retry attempts for transient errors per individual API request. Each retry uses exponential backoff starting from `ai_function_retry_initial_delay_ms`.
7946 : 113429 : )", EXPERIMENTAL) \
7947 : 113429 : DECLARE(UInt64, ai_function_retry_initial_delay_ms, 1000, R"(
7948 : 113429 : Initial delay in milliseconds before the first retry of a failed AI function API request. The delay doubles on each subsequent attempt (exponential backoff). For example, with default settings: 1000ms, 2000ms, 4000ms.
7949 : 113429 : )", EXPERIMENTAL) \
7950 : 113429 : DECLARE(Bool, ai_function_throw_on_error, true, R"(
7951 : 113429 : If true (default), an AI function call that fails permanently after exhausting all retries aborts the query with an exception. If false, the failed row receives the default value for the column type (empty string for String) and processing continues.
7952 : 113429 : )", EXPERIMENTAL) \
7953 : 113429 : DECLARE(UInt64, ai_function_max_input_tokens_per_query, 1000000, R"(
7954 : 113429 : Maximum total input (prompt) tokens across all AI function API calls in a single query. Tracked cumulatively from provider responses. Note that this limit may be exceeded by one call's worth of input tokens, since the number of input tokens of a call are not known in advance. Set to 0 to disable.
7955 : 113429 : )", EXPERIMENTAL) \
7956 : 113429 : DECLARE(UInt64, ai_function_max_output_tokens_per_query, 500000, R"(
7957 : 113429 : Maximum total output (completion) tokens across all AI function API calls in a single query. Tracked cumulatively from provider responses. Note that this limit may be exceeded by one call's worth of output tokens, since the number of output tokens of a call are not known in advance. Set to 0 to disable.
7958 : 113429 : )", EXPERIMENTAL) \
7959 : 113429 : DECLARE(UInt64, ai_function_max_api_calls_per_query, 0, R"(
7960 : 113429 : Maximum number of HTTP requests that AI functions may dispatch per query. Set to 0 to disable.
7961 : 113429 : )", EXPERIMENTAL) \
7962 : 113429 : DECLARE(Bool, ai_function_throw_on_quota_exceeded, true, R"(
7963 : 113429 : If true (default), exceeding an AI function quota limit (`ai_function_max_input_tokens_per_query`, `ai_function_max_output_tokens_per_query`, or `ai_function_max_api_calls_per_query`) aborts the query with an exception. If false, remaining rows receive the default value for the column type (empty string for String).
7964 : 113429 : )", EXPERIMENTAL) \
7965 : : /* ############ END OF EXPERIMENTAL FEATURES ############# */ \
7966 : : /* ####################################################### */ \
7967 : :
7968 : : // End of COMMON_SETTINGS
7969 : : // Please add settings related to formats in Core/FormatFactorySettings.h, move obsolete settings to OBSOLETE_SETTINGS and obsolete format settings to OBSOLETE_FORMAT_SETTINGS.
7970 : :
7971 : : #define OBSOLETE_SETTINGS(M, ALIAS) \
7972 : : /** Obsolete settings which are kept around for compatibility reasons. They have no effect anymore. */ \
7973 : 113429 : MAKE_OBSOLETE(M, Bool, query_condition_cache_store_conditions_as_plaintext, false) \
7974 : 113429 : MAKE_OBSOLETE(M, Bool, update_insert_deduplication_token_in_dependent_materialized_views, 0) \
7975 : 113429 : MAKE_OBSOLETE(M, UInt64, max_memory_usage_for_all_queries, 0) \
7976 : 113429 : MAKE_OBSOLETE(M, UInt64, multiple_joins_rewriter_version, 0) \
7977 : 113429 : MAKE_OBSOLETE(M, Bool, enable_debug_queries, false) \
7978 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_database_atomic, true) \
7979 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_bigint_types, true) \
7980 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_window_functions, true) \
7981 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_geo_types, true) \
7982 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_query_cache, true) \
7983 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_alter_materialized_view_structure, true) \
7984 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_shared_merge_tree, true) \
7985 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_database_replicated, true) \
7986 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_refreshable_materialized_view, true) \
7987 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_bfloat16_type, true) \
7988 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_inverted_index, false) \
7989 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_vector_similarity_index, true) \
7990 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_statistic, false) \
7991 : 113429 : MAKE_OBSOLETE(M, Bool, enable_vector_similarity_index, true) \
7992 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_qbit_type, true) \
7993 : 113429 : MAKE_OBSOLETE(M, Bool, enable_qbit_type, true) \
7994 : 113429 : \
7995 : 113429 : MAKE_OBSOLETE(M, Milliseconds, async_insert_stale_timeout_ms, 0) \
7996 : 113429 : MAKE_OBSOLETE(M, StreamingHandleErrorMode, handle_kafka_error_mode, StreamingHandleErrorMode::DEFAULT) \
7997 : 113429 : MAKE_OBSOLETE(M, Bool, database_replicated_ddl_output, true) \
7998 : 113429 : MAKE_OBSOLETE(M, UInt64, replication_alter_columns_timeout, 60) \
7999 : 113429 : MAKE_OBSOLETE(M, UInt64, odbc_max_field_size, 0) \
8000 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_map_type, true) \
8001 : 113429 : MAKE_OBSOLETE(M, UInt64, merge_tree_clear_old_temporary_directories_interval_seconds, 60) \
8002 : 113429 : MAKE_OBSOLETE(M, UInt64, merge_tree_clear_old_parts_interval_seconds, 1) \
8003 : 113429 : MAKE_OBSOLETE(M, UInt64, partial_merge_join_optimizations, 0) \
8004 : 113429 : MAKE_OBSOLETE(M, MaxThreads, max_alter_threads, 0) \
8005 : 113429 : MAKE_OBSOLETE(M, Bool, use_mysql_types_in_show_columns, false) \
8006 : 113429 : MAKE_OBSOLETE(M, Bool, s3queue_allow_experimental_sharded_mode, false) \
8007 : 113429 : MAKE_OBSOLETE(M, LightweightMutationProjectionMode, lightweight_mutation_projection_mode, LightweightMutationProjectionMode::THROW) \
8008 : 113429 : MAKE_OBSOLETE(M, Bool, use_local_cache_for_remote_storage, false) \
8009 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_join_condition, false) \
8010 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_variant_type, true) \
8011 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_dynamic_type, true) \
8012 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_json_type, true) \
8013 : 113429 : MAKE_OBSOLETE(M, Bool, enable_variant_type, true) \
8014 : 113429 : MAKE_OBSOLETE(M, Bool, enable_dynamic_type, true) \
8015 : 113429 : MAKE_OBSOLETE(M, Bool, enable_json_type, true) \
8016 : 113429 : MAKE_OBSOLETE(M, Bool, s3_slow_all_threads_after_retryable_error, false) \
8017 : 113429 : MAKE_OBSOLETE(M, Bool, azure_sdk_use_native_client, true) \
8018 : 113429 : MAKE_OBSOLETE(M, Bool, allow_not_comparable_types_in_order_by, false) \
8019 : 113429 : MAKE_OBSOLETE(M, Bool, allow_not_comparable_types_in_comparison_functions, false) \
8020 : 113429 : MAKE_OBSOLETE(M, Bool, enable_zstd_qat_codec, false) \
8021 : 113429 : MAKE_OBSOLETE(M, Bool, enable_deflate_qpl_codec, false) \
8022 : 113429 : MAKE_OBSOLETE(M, Bool, throw_if_deduplication_in_dependent_materialized_views_enabled_with_async_insert, false) \
8023 : 113429 : \
8024 : 113429 : /* moved to config.xml: see also src/Core/ServerSettings.h */ \
8025 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, background_buffer_flush_schedule_pool_size, 16) \
8026 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, background_pool_size, 16) \
8027 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, Float, background_merges_mutations_concurrency_ratio, 2) \
8028 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, background_move_pool_size, 8) \
8029 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, background_fetches_pool_size, 8) \
8030 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, background_common_pool_size, 8) \
8031 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, background_schedule_pool_size, 128) \
8032 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, background_message_broker_schedule_pool_size, 16) \
8033 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, background_distributed_schedule_pool_size, 16) \
8034 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, max_remote_read_network_bandwidth_for_server, 0) \
8035 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, max_remote_write_network_bandwidth_for_server, 0) \
8036 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, async_insert_threads, 16) \
8037 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, max_replicated_fetches_network_bandwidth_for_server, 0) \
8038 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, max_replicated_sends_network_bandwidth_for_server, 0) \
8039 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, max_entries_for_hash_table_stats, 10'000) \
8040 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, s3_max_redirects, S3::DEFAULT_MAX_REDIRECTS) \
8041 : 113429 : MAKE_DEPRECATED_BY_SERVER_CONFIG(M, UInt64, s3_retry_attempts, S3::DEFAULT_RETRY_ATTEMPTS) \
8042 : 113429 : /* ---- */ \
8043 : 113429 : MAKE_OBSOLETE(M, DefaultDatabaseEngine, default_database_engine, DefaultDatabaseEngine::Atomic) \
8044 : 113429 : MAKE_OBSOLETE(M, UInt64, max_pipeline_depth, 0) \
8045 : 113429 : MAKE_OBSOLETE(M, Seconds, temporary_live_view_timeout, 1) \
8046 : 113429 : MAKE_OBSOLETE(M, Seconds, periodic_live_view_refresh, 60) \
8047 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_live_view, false) \
8048 : 113429 : MAKE_OBSOLETE(M, Seconds, live_view_heartbeat_interval, 15) \
8049 : 113429 : MAKE_OBSOLETE(M, UInt64, max_live_view_insert_blocks_before_refresh, 64) \
8050 : 113429 : MAKE_OBSOLETE(M, Milliseconds, async_insert_cleanup_timeout_ms, 1000) \
8051 : 113429 : MAKE_OBSOLETE(M, Bool, optimize_fuse_sum_count_avg, 0) \
8052 : 113429 : MAKE_OBSOLETE(M, Seconds, drain_timeout, 3) \
8053 : 113429 : MAKE_OBSOLETE(M, UInt64, backup_threads, 16) \
8054 : 113429 : MAKE_OBSOLETE(M, UInt64, restore_threads, 16) \
8055 : 113429 : MAKE_OBSOLETE(M, Bool, optimize_duplicate_order_by_and_distinct, false) \
8056 : 113429 : MAKE_OBSOLETE(M, UInt64, parallel_replicas_min_number_of_granules_to_enable, 0) \
8057 : 113429 : MAKE_OBSOLETE(M, ParallelReplicasCustomKeyFilterType, parallel_replicas_custom_key_filter_type, ParallelReplicasCustomKeyFilterType::DEFAULT) \
8058 : 113429 : MAKE_OBSOLETE(M, Bool, query_plan_optimize_projection, true) \
8059 : 113429 : MAKE_OBSOLETE(M, Bool, query_cache_store_results_of_queries_with_nondeterministic_functions, false) \
8060 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_annoy_index, false) \
8061 : 113429 : MAKE_OBSOLETE(M, UInt64, max_threads_for_annoy_index_creation, 4) \
8062 : 113429 : MAKE_OBSOLETE(M, Int64, annoy_index_search_k_nodes, -1) \
8063 : 113429 : MAKE_OBSOLETE(M, Int64, max_limit_for_ann_queries, -1) \
8064 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_usearch_index, false) \
8065 : 113429 : MAKE_OBSOLETE(M, Bool, optimize_move_functions_out_of_any, false) \
8066 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_undrop_table_query, true) \
8067 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_s3queue, true) \
8068 : 113429 : MAKE_OBSOLETE(M, Bool, text_index_use_bloom_filter, true) \
8069 : 113429 : MAKE_OBSOLETE(M, Bool, query_plan_optimize_primary_key, true) \
8070 : 113429 : MAKE_OBSOLETE(M, Bool, optimize_monotonous_functions_in_order_by, false) \
8071 : 113429 : MAKE_OBSOLETE(M, UInt64, http_max_chunk_size, 100_GiB) \
8072 : 113429 : MAKE_OBSOLETE(M, Bool, iceberg_engine_ignore_schema_evolution, false) \
8073 : 113429 : MAKE_OBSOLETE(M, Float, parallel_replicas_single_task_marks_count_multiplier, 2) \
8074 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_database_materialized_mysql, false) \
8075 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_shared_set_join, true) \
8076 : 113429 : MAKE_OBSOLETE(M, UInt64, min_external_sort_block_bytes, 100_MiB) \
8077 : 113429 : MAKE_OBSOLETE(M, UInt64, distributed_cache_read_alignment, 0) \
8078 : 113429 : MAKE_OBSOLETE(M, Bool, use_json_alias_for_old_object_type, false) \
8079 : 113429 : MAKE_OBSOLETE(M, Bool, describe_extend_object_types, false) \
8080 : 113429 : MAKE_OBSOLETE(M, Bool, allow_experimental_object_type, false) \
8081 : 113429 : MAKE_OBSOLETE(M, BoolAuto, insert_select_deduplicate, Field{"auto"}) \
8082 : 113429 : MAKE_OBSOLETE(M, Bool, use_text_index_dictionary_cache, false)
8083 : : /** The section above is for obsolete settings. Do not add anything there. */
8084 : : #endif /// __CLION_IDE__
8085 : :
8086 : : #define LIST_OF_SETTINGS(M, ALIAS) \
8087 : 113429 : COMMON_SETTINGS(M, ALIAS) \
8088 : 113429 : OBSOLETE_SETTINGS(M, ALIAS) \
8089 : 113429 : FORMAT_FACTORY_SETTINGS(M, ALIAS) \
8090 : 113429 : OBSOLETE_FORMAT_SETTINGS(M, ALIAS) \
8091 : :
8092 : : // clang-format on
8093 : :
8094 : : DECLARE_SETTINGS_TRAITS_ALLOW_CUSTOM_SETTINGS(SettingsTraits, LIST_OF_SETTINGS)
8095 : 113429 : IMPLEMENT_SETTINGS_TRAITS(SettingsTraits, LIST_OF_SETTINGS)
8096 : :
8097 : : /** Settings of query execution.
8098 : : * These settings go to users.xml.
8099 : : */
8100 : : struct SettingsImpl : public BaseSettings<SettingsTraits>, public IHints<2>
8101 : : {
8102 : 2612795 : SettingsImpl() = default;
8103 : :
8104 : : /** Set multiple settings from "profile" (in server configuration file (users.xml), profiles contain groups of multiple settings).
8105 : : * The profile can also be set using the `set` functions, like the profile setting.
8106 : : */
8107 : : void setProfile(const String & profile_name, const Poco::Util::AbstractConfiguration & config);
8108 : :
8109 : : /// Load settings from configuration file, at "path" prefix in configuration.
8110 : : void loadSettingsFromConfig(const String & path, const Poco::Util::AbstractConfiguration & config);
8111 : :
8112 : : /// Dumps profile events to column of type Map(String, String)
8113 : : void dumpToMapColumn(IColumn * column, bool changed_only = true);
8114 : :
8115 : : /// Check that there is no user-level settings at the top level in config.
8116 : : /// This is a common source of mistake (user don't know where to write user-level setting).
8117 : : static void checkNoSettingNamesAtTopLevel(const Poco::Util::AbstractConfiguration & config, const String & config_path);
8118 : :
8119 : : std::vector<String> getAllRegisteredNames() const override;
8120 : :
8121 : : void set(std::string_view name, const Field & value) override;
8122 : :
8123 : : private:
8124 : : void applyCompatibilitySetting(const String & compatibility);
8125 : :
8126 : : std::unordered_set<std::string_view> settings_changed_by_compatibility_setting;
8127 : : };
8128 : :
8129 : : /** Set the settings from the profile (in the server configuration, many settings can be listed in one profile).
8130 : : * The profile can also be set using the `set` functions, like the `profile` setting.
8131 : : */
8132 : : void SettingsImpl::setProfile(const String & profile_name, const Poco::Util::AbstractConfiguration & config)
8133 : 0 : {
8134 : 0 : String elem = "profiles." + profile_name;
8135 : :
8136 [ # # ]: 0 : if (!config.has(elem))
8137 : 0 : throw Exception(ErrorCodes::THERE_IS_NO_PROFILE, "There is no profile '{}' in configuration file.", profile_name);
8138 : :
8139 : 0 : Poco::Util::AbstractConfiguration::Keys config_keys;
8140 : 0 : config.keys(elem, config_keys);
8141 : :
8142 [ # # ]: 0 : for (const std::string & key : config_keys)
8143 : 0 : {
8144 [ # # ]: 0 : if (key == "constraints")
8145 : 0 : continue;
8146 [ # # ][ # # ]: 0 : if (key == "profile" || key.starts_with("profile[")) /// Inheritance of profiles from the current one.
8147 : 0 : setProfile(config.getString(elem + "." + key), config);
8148 : 0 : else
8149 : 0 : set(key, config.getString(elem + "." + key));
8150 : 0 : }
8151 : 0 : }
8152 : :
8153 : : void SettingsImpl::loadSettingsFromConfig(const String & path, const Poco::Util::AbstractConfiguration & config)
8154 : 0 : {
8155 [ # # ]: 0 : if (!config.has(path))
8156 : 0 : throw Exception(ErrorCodes::NO_ELEMENTS_IN_CONFIG, "There is no path '{}' in configuration file.", path);
8157 : :
8158 : 0 : Poco::Util::AbstractConfiguration::Keys config_keys;
8159 : 0 : config.keys(path, config_keys);
8160 : :
8161 [ # # ]: 0 : for (const std::string & key : config_keys)
8162 : 0 : {
8163 : 0 : set(key, config.getString(path + "." + key));
8164 : 0 : }
8165 : 0 : }
8166 : :
8167 : : void SettingsImpl::dumpToMapColumn(IColumn * column, bool changed_only)
8168 : 2455661 : {
8169 [ - + ]: 2455661 : if (!column)
8170 : 0 : return;
8171 : :
8172 : 2455661 : auto & column_map = typeid_cast<ColumnMap &>(*column);
8173 : 2455661 : auto & offsets = column_map.getNestedColumn().getOffsets();
8174 : :
8175 : 2455661 : auto & tuple_column = column_map.getNestedData();
8176 : 2455661 : auto & key_column = typeid_cast<ColumnLowCardinality &>(tuple_column.getColumn(0));
8177 : 2455661 : auto & value_column = typeid_cast<ColumnLowCardinality &>(tuple_column.getColumn(1));
8178 : :
8179 : 2455661 : size_t size = 0;
8180 : :
8181 : : /// Iterate over standard settings
8182 : 2455661 : const auto & accessor = Traits::Accessor::instance();
8183 [ + + ]: 3818347616 : for (size_t i = 0; i < accessor.size(); i++)
8184 : 3815891955 : {
8185 [ + + ][ + + ]: 3815891999 : if (changed_only && !accessor.isValueChanged(*this, i))
8186 : 3612948979 : continue;
8187 : :
8188 : 202942976 : const auto & name = accessor.getName(i);
8189 : 202942976 : auto value = accessor.getValueString(*this, i);
8190 : 202942976 : key_column.insertData(name.data(), name.size());
8191 : 202942976 : value_column.insertData(value.data(), value.size());
8192 : 202942976 : ++size;
8193 : 202942976 : }
8194 : :
8195 : : /// Iterate over the custom settings
8196 [ + + ]: 2455661 : for (const auto & custom : custom_settings_map)
8197 : 3800 : {
8198 : 3800 : const auto & setting_field = custom.second;
8199 [ + - ][ - + ]: 3800 : if (changed_only && !setting_field.changed)
8200 : 0 : continue;
8201 : :
8202 : 3800 : const auto & name = custom.first;
8203 : 3800 : auto value = setting_field.toString();
8204 : 3800 : key_column.insertData(name.data(), name.size());
8205 : 3800 : value_column.insertData(value.data(), value.size());
8206 : 3800 : ++size;
8207 : 3800 : }
8208 : :
8209 : 2455661 : offsets.push_back(offsets.back() + size);
8210 : 2455661 : }
8211 : :
8212 : : void SettingsImpl::checkNoSettingNamesAtTopLevel(const Poco::Util::AbstractConfiguration & config, const String & config_path)
8213 : 6210 : {
8214 [ - + ]: 6210 : if (config.getBool("skip_check_for_incorrect_settings", false))
8215 : 0 : return;
8216 : :
8217 : 6210 : SettingsImpl settings;
8218 [ + + ]: 6210 : for (const auto & setting : settings.all())
8219 : 9650340 : {
8220 : 9650340 : const auto & name = setting.getName();
8221 [ + + ][ + + ]: 9650340 : bool should_skip_check = name == "max_table_size_to_drop" || name == "max_partition_size_to_drop";
8222 [ + + ][ + + ]: 9650340 : if (config.has(name) && (setting.getTier() != SettingsTierType::OBSOLETE) && !should_skip_check)
[ - + ]
8223 : 0 : {
8224 : 0 : throw Exception(ErrorCodes::UNKNOWN_ELEMENT_IN_CONFIG, "A setting '{}' appeared at top level in config {}."
8225 : 0 : " But it is user-level setting that should be located in users.xml inside <profiles> section for specific profile."
8226 : 0 : " You can add it to <profiles><default> if you want to change default value of this setting."
8227 : 0 : " You can also disable the check - specify <skip_check_for_incorrect_settings>1</skip_check_for_incorrect_settings>"
8228 : 0 : " in the main configuration file.",
8229 : 0 : name, config_path);
8230 : 0 : }
8231 : 9650340 : }
8232 : 6210 : }
8233 : :
8234 : : std::vector<String> SettingsImpl::getAllRegisteredNames() const
8235 : 17 : {
8236 : 17 : std::vector<String> all_settings;
8237 [ + + ]: 17 : for (const auto & setting_field : all())
8238 : 26418 : all_settings.push_back(setting_field.getName());
8239 : 17 : return all_settings;
8240 : 17 : }
8241 : :
8242 : : void SettingsImpl::set(std::string_view name, const Field & value)
8243 : 99736512 : {
8244 [ + + ]: 99736512 : if (name == "compatibility")
8245 : 865 : {
8246 [ - + ]: 865 : if (value.getType() != Field::Types::Which::String)
8247 : 0 : throw Exception(ErrorCodes::BAD_ARGUMENTS, "Unexpected type of value for setting 'compatibility'. Expected String, got {}", value.getTypeName());
8248 : 865 : applyCompatibilitySetting(value.safeGet<String>());
8249 : 865 : }
8250 : : /// If we change setting that was changed by compatibility setting before
8251 : : /// we should remove it from settings_changed_by_compatibility_setting,
8252 : : /// otherwise the next time we will change compatibility setting
8253 : : /// this setting will be changed too (and we don't want it).
8254 [ + + ]: 99735647 : else if (settings_changed_by_compatibility_setting.contains(name))
8255 : 78884 : settings_changed_by_compatibility_setting.erase(name);
8256 : :
8257 : 99736512 : BaseSettings::set(name, value);
8258 : 99736512 : }
8259 : :
8260 : : void SettingsImpl::applyCompatibilitySetting(const String & compatibility_value)
8261 : 865 : {
8262 : : /// First, revert all changes applied by previous compatibility setting
8263 [ + + ]: 865 : for (const auto & setting_name : settings_changed_by_compatibility_setting)
8264 : 139926 : resetToDefault(setting_name);
8265 : :
8266 : 865 : settings_changed_by_compatibility_setting.clear();
8267 : : /// If setting value is empty, we don't need to change settings
8268 [ - + ]: 865 : if (compatibility_value.empty())
8269 : 0 : return;
8270 : :
8271 : 865 : ClickHouseVersion version(compatibility_value);
8272 : 865 : const auto & settings_changes_history = getSettingsChangesHistory();
8273 : : /// Iterate through ClickHouse version in descending order and apply reversed
8274 : : /// changes for each version that is higher that version from compatibility setting
8275 [ + + ]: 23659 : for (auto it = settings_changes_history.rbegin(); it != settings_changes_history.rend(); ++it)
8276 : 23655 : {
8277 [ + + ]: 23655 : if (version >= it->first)
8278 : 861 : break;
8279 : :
8280 : : /// Apply reversed changes from this version.
8281 [ + + ]: 22794 : for (const auto & change : it->second)
8282 : 573579 : {
8283 : : /// In case the alias is being used (e.g. use enable_analyzer) we must change the original setting
8284 : 573579 : auto final_name = SettingsTraits::resolveName(change.name);
8285 : :
8286 : : /// If this setting was changed manually, we don't change it
8287 [ + + ][ + + ]: 573579 : if (isChanged(final_name) && !settings_changed_by_compatibility_setting.contains(final_name))
8288 : 76353 : continue;
8289 : :
8290 : : /// Don't mark as changed if the value isn't really changed
8291 [ + + ]: 497226 : if (get(final_name) == change.previous_value)
8292 : 257041 : continue;
8293 : :
8294 : 240185 : BaseSettings::set(final_name, change.previous_value);
8295 : 240185 : settings_changed_by_compatibility_setting.insert(final_name);
8296 : 240185 : }
8297 : 22794 : }
8298 : 865 : }
8299 : :
8300 : : #define INITIALIZE_SETTING_EXTERN(TYPE, NAME, DEFAULT, DESCRIPTION, FLAGS, ...) \
8301 : : Settings ## TYPE NAME = & SettingsImpl :: NAME;
8302 : :
8303 : : namespace Setting
8304 : : {
8305 : : LIST_OF_SETTINGS(INITIALIZE_SETTING_EXTERN, INITIALIZE_SETTING_EXTERN) /// NOLINT (misc-use-internal-linkage)
8306 : : }
8307 : :
8308 : : #undef INITIALIZE_SETTING_EXTERN
8309 : :
8310 : : Settings::Settings()
8311 : 2606631 : : impl(std::make_unique<SettingsImpl>())
8312 : 2606631 : {}
8313 : :
8314 : : Settings::Settings(const Settings & settings)
8315 : 10469395 : : impl(std::make_unique<SettingsImpl>(*settings.impl))
8316 : 10469395 : {}
8317 : :
8318 : : Settings::Settings(Settings && settings) noexcept
8319 : 13643 : : impl(std::make_unique<SettingsImpl>(std::move(*settings.impl)))
8320 : 13643 : {}
8321 : :
8322 : 12951436 : Settings::~Settings() = default;
8323 : :
8324 : : Settings & Settings::operator=(const Settings & other)
8325 : 1388645 : {
8326 [ - + ]: 1388645 : if (&other == this)
8327 : 0 : return *this;
8328 : 1388645 : *impl = *other.impl;
8329 : 1388645 : return *this;
8330 : 1388645 : }
8331 : :
8332 : : bool Settings::operator==(const Settings & other) const
8333 : 13 : {
8334 : 13 : return *impl == *other.impl;
8335 : 13 : }
8336 : :
8337 : : COMMON_SETTINGS_SUPPORTED_TYPES(Settings, IMPLEMENT_SETTING_SUBSCRIPT_OPERATOR)
8338 : :
8339 : : bool Settings::has(std::string_view name) const
8340 : 76701349 : {
8341 : 76701349 : return impl->has(name);
8342 : 76701349 : }
8343 : :
8344 : : bool Settings::isChanged(std::string_view name) const
8345 : 106039066 : {
8346 : 106039066 : return impl->isChanged(name);
8347 : 106039066 : }
8348 : :
8349 : : SettingsTierType Settings::getTier(std::string_view name) const
8350 : 5 : {
8351 : 5 : return impl->getTier(name);
8352 : 5 : }
8353 : :
8354 : : bool Settings::tryGet(std::string_view name, Field & value) const
8355 : 76596232 : {
8356 : 76596232 : return impl->tryGet(name, value);
8357 : 76596232 : }
8358 : :
8359 : : Field Settings::get(std::string_view name) const
8360 : 11186680 : {
8361 : 11186680 : return impl->get(name);
8362 : 11186680 : }
8363 : :
8364 : : void Settings::set(std::string_view name, const Field & value)
8365 : 99513482 : {
8366 : 99513482 : impl->set(name, value);
8367 : 99513482 : }
8368 : :
8369 : : void Settings::setDefaultValue(std::string_view name)
8370 : 57833288 : {
8371 : 57833288 : impl->resetToDefault(name);
8372 : 57833288 : }
8373 : :
8374 : : std::vector<String> Settings::getHints(const String & name) const
8375 : 17 : {
8376 : 17 : return impl->getHints(name);
8377 : 17 : }
8378 : :
8379 : : String Settings::toString() const
8380 : 0 : {
8381 : 0 : return impl->toString();
8382 : 0 : }
8383 : :
8384 : : SettingsChanges Settings::changes() const
8385 : 1660417 : {
8386 : 1660417 : return impl->changes();
8387 : 1660417 : }
8388 : :
8389 : : void Settings::applyChanges(const SettingsChanges & changes)
8390 : 1092 : {
8391 : 1092 : impl->applyChanges(changes);
8392 : 1092 : }
8393 : :
8394 : : std::vector<std::string_view> Settings::getAllRegisteredNames() const
8395 : 276 : {
8396 : 276 : std::vector<std::string_view> setting_names;
8397 [ + + ]: 276 : for (const auto & setting : impl->all())
8398 : 428904 : {
8399 : 428904 : setting_names.emplace_back(setting.getName());
8400 : 428904 : }
8401 : 276 : return setting_names;
8402 : 276 : }
8403 : :
8404 : : std::vector<std::string_view> Settings::getAllAliasNames() const
8405 : 148 : {
8406 : 148 : std::vector<std::string_view> alias_names;
8407 : 148 : const auto & settings_to_aliases = SettingsImpl::Traits::settingsToAliases();
8408 [ + + ]: 148 : for (const auto & [_, aliases] : settings_to_aliases)
8409 : 4736 : {
8410 : 4736 : alias_names.insert(alias_names.end(), aliases.begin(), aliases.end());
8411 : 4736 : }
8412 : 148 : return alias_names;
8413 : 148 : }
8414 : :
8415 : : std::vector<std::string_view> Settings::getChangedAndObsoleteNames() const
8416 : 97 : {
8417 : 97 : std::vector<std::string_view> setting_names;
8418 [ + + ]: 97 : for (const auto & setting : impl->allChanged())
8419 : 5217 : {
8420 [ + + ]: 5217 : if (setting.getTier() == SettingsTierType::OBSOLETE)
8421 : 8 : setting_names.emplace_back(setting.getName());
8422 : 5217 : }
8423 : 97 : return setting_names;
8424 : 97 : }
8425 : :
8426 : : std::vector<std::string_view> Settings::getUnchangedNames() const
8427 : 98873 : {
8428 : 98873 : std::vector<std::string_view> setting_names;
8429 [ + + ]: 98873 : for (const auto & setting : impl->allUnchanged())
8430 : 153401318 : {
8431 : 153401318 : setting_names.emplace_back(setting.getName());
8432 : 153401318 : }
8433 : 98873 : return setting_names;
8434 : 98873 : }
8435 : :
8436 : : void Settings::dumpToSystemSettingsColumns(MutableColumnsAndConstraints & params) const
8437 : 1184 : {
8438 : 1184 : MutableColumns & res_columns = params.res_columns;
8439 : :
8440 : 1184 : const auto fill_data_for_setting = [&](std::string_view setting_name, const auto & setting)
8441 : 1878089 : {
8442 : 1878089 : res_columns[1]->insert(setting.getValueString());
8443 : 1878089 : res_columns[2]->insert(setting.isValueChanged());
8444 : :
8445 : : /// Trim starting/ending newline.
8446 : 1878089 : std::string_view doc = setting.getDescription();
8447 [ + + ][ + + ]: 1878089 : if (!doc.empty() && doc[0] == '\n')
8448 : 1732115 : doc = doc.substr(1);
8449 [ + + ][ + + ]: 1878089 : if (!doc.empty() && doc[doc.length() - 1] == '\n')
8450 : 1706070 : doc = doc.substr(0, doc.length() - 1);
8451 : :
8452 : 1878089 : res_columns[3]->insert(doc);
8453 : :
8454 : 1878089 : Field min;
8455 : 1878089 : Field max;
8456 : 1878089 : std::vector<Field> disallowed_values;
8457 : 1878089 : SettingConstraintWritability writability = SettingConstraintWritability::WRITABLE;
8458 : 1878089 : params.constraints.get(*this, setting_name, min, max, disallowed_values, writability);
8459 : :
8460 : : /// These two columns can accept strings only.
8461 [ + + ]: 1878089 : if (!min.isNull())
8462 : 50 : min = Settings::valueToStringUtil(setting_name, min);
8463 [ + + ]: 1878089 : if (!max.isNull())
8464 : 52 : max = Settings::valueToStringUtil(setting_name, max);
8465 : :
8466 : 1878089 : Array disallowed_array;
8467 [ + + ]: 1878089 : for (const auto & value : disallowed_values)
8468 : 72 : disallowed_array.emplace_back(Settings::valueToStringUtil(setting_name, value));
8469 : :
8470 : 1878089 : res_columns[4]->insert(min);
8471 : 1878089 : res_columns[5]->insert(max);
8472 : 1878089 : res_columns[6]->insert(disallowed_array);
8473 : 1878089 : res_columns[7]->insert(writability == SettingConstraintWritability::CONST);
8474 : 1878089 : res_columns[8]->insert(setting.getTypeName());
8475 : 1878089 : res_columns[9]->insert(setting.getDefaultValueString());
8476 : 1878089 : res_columns[11]->insert(setting.getTier() == SettingsTierType::OBSOLETE);
8477 : 1878089 : res_columns[12]->insert(setting.getTier());
8478 : 1878089 : };
8479 : :
8480 : 1184 : const auto & settings_to_aliases = SettingsImpl::Traits::settingsToAliases();
8481 [ + + ]: 1184 : for (const auto & setting : impl->all())
8482 : 1840251 : {
8483 : 1840251 : const auto & setting_name = setting.getName();
8484 : 1840251 : res_columns[0]->insert(setting_name);
8485 : :
8486 : 1840251 : fill_data_for_setting(setting_name, setting);
8487 : 1840251 : res_columns[10]->insert("");
8488 : :
8489 [ + + ]: 1840251 : if (auto it = settings_to_aliases.find(setting_name); it != settings_to_aliases.end())
8490 : 37888 : {
8491 [ + + ]: 37888 : for (const auto alias : it->second)
8492 : 37888 : {
8493 : 37888 : res_columns[0]->insert(alias);
8494 : 37888 : fill_data_for_setting(alias, setting);
8495 : 37888 : res_columns[10]->insert(setting_name);
8496 : 37888 : }
8497 : 37888 : }
8498 : 1840251 : }
8499 : 1184 : }
8500 : :
8501 : : void Settings::dumpToMapColumn(IColumn * column, bool changed_only) const
8502 : 2455661 : {
8503 : 2455661 : impl->dumpToMapColumn(column, changed_only);
8504 : 2455661 : }
8505 : :
8506 : : NameToNameMap Settings::toNameToNameMap() const
8507 : 772415 : {
8508 : 772415 : NameToNameMap query_parameters;
8509 [ + + ]: 772415 : for (const auto & param : *impl)
8510 : 45396 : {
8511 : 45396 : std::string value;
8512 : 45396 : ReadBufferFromOwnString buf(param.getValueString());
8513 : 45396 : readQuoted(value, buf);
8514 : 45396 : query_parameters.emplace(param.getName(), value);
8515 : 45396 : }
8516 : 772415 : return query_parameters;
8517 : 772415 : }
8518 : :
8519 : : void Settings::write(WriteBuffer & out, SettingsWriteFormat format) const
8520 : 1604649 : {
8521 : 1604649 : impl->write(out, format);
8522 : 1604649 : }
8523 : :
8524 : : void Settings::read(ReadBuffer & in, SettingsWriteFormat format)
8525 : 1673380 : {
8526 : 1673380 : impl->read(in, format);
8527 : 1673380 : }
8528 : :
8529 : : void Settings::writeEmpty(WriteBuffer & out)
8530 : 225 : {
8531 : 225 : BaseSettingsHelpers::writeString("", out);
8532 : 225 : }
8533 : :
8534 : : void Settings::addToProgramOptions(boost::program_options::options_description & options)
8535 : 43136 : {
8536 : 43136 : addProgramOptions(*impl, options);
8537 : 43136 : }
8538 : :
8539 : : void Settings::addToProgramOptions(std::string_view setting_name, boost::program_options::options_description & options)
8540 : 2664 : {
8541 : 2664 : const auto & accessor = SettingsImpl::Traits::Accessor::instance();
8542 : 2664 : size_t index = accessor.find(setting_name);
8543 : 2664 : chassert(index != static_cast<size_t>(-1));
8544 : 2664 : auto on_program_option = boost::function1<void, const std::string &>(
8545 : 2664 : [this, setting_name](const std::string & value)
8546 : 2664 : {
8547 : 0 : this->set(setting_name, value);
8548 : 0 : });
8549 : 2664 : options.add(boost::shared_ptr<boost::program_options::option_description>(new boost::program_options::option_description(
8550 : 2664 : setting_name.data(), boost::program_options::value<std::string>()->composing()->notifier(on_program_option), accessor.getDescription(index).data()))); // NOLINT
8551 : 2664 : }
8552 : :
8553 : : void Settings::addToProgramOptionsAsMultitokens(boost::program_options::options_description & options) const
8554 : 66832 : {
8555 : 66832 : addProgramOptionsAsMultitokens(*impl, options);
8556 : 66832 : }
8557 : :
8558 : : void Settings::addToClientOptions(Poco::Util::LayeredConfiguration &config, const boost::program_options::variables_map &options, bool repeated_settings) const
8559 : 98925 : {
8560 [ + + ]: 98925 : for (const auto & setting : impl->all())
8561 : 153729450 : {
8562 : 153729450 : const auto & name = setting.getName();
8563 [ + + ]: 153729450 : if (options.contains(name))
8564 : 216879 : {
8565 [ + + ]: 216879 : if (repeated_settings)
8566 : 155282 : config.setString(name, options[name].as<Strings>().back());
8567 : 61597 : else
8568 : 61597 : config.setString(name, options[name].as<String>());
8569 : 216879 : }
8570 : 153729450 : }
8571 : 98925 : }
8572 : :
8573 : : Field Settings::castValueUtil(std::string_view name, const Field & value)
8574 : 5109205 : {
8575 : 5109205 : return SettingsImpl::castValueUtil(name, value);
8576 : 5109205 : }
8577 : :
8578 : : String Settings::valueToStringUtil(std::string_view name, const Field & value)
8579 : 35905806 : {
8580 : 35905806 : return SettingsImpl::valueToStringUtil(name, value);
8581 : 35905806 : }
8582 : :
8583 : : Field Settings::stringToValueUtil(std::string_view name, const String & str)
8584 : 10678 : {
8585 : 10678 : return SettingsImpl::stringToValueUtil(name, str);
8586 : 10678 : }
8587 : :
8588 : : bool Settings::hasBuiltin(std::string_view name)
8589 : 17325774 : {
8590 : 17325774 : return SettingsImpl::hasBuiltin(name);
8591 : 17325774 : }
8592 : :
8593 : : std::string_view Settings::resolveName(std::string_view name)
8594 : 21921197 : {
8595 : 21921197 : return SettingsImpl::Traits::resolveName(name);
8596 : 21921197 : }
8597 : :
8598 : : void Settings::checkNoSettingNamesAtTopLevel(const Poco::Util::AbstractConfiguration & config, const String & config_path)
8599 : 6210 : {
8600 : 6210 : SettingsImpl::checkNoSettingNamesAtTopLevel(config, config_path);
8601 : 6210 : }
8602 : :
8603 : : }
|
