Кэш условий запроса работает с analyzer, который начиная с версии
26.9 является единственным механизмом анализа запросов и используется по умолчанию начиная с 24.3.WHERE col = 'xyz') на одних и тех же данных всегда дает один и тот же результат.
Точнее, кэш условий запроса запоминает для каждого вычисленного фильтра и каждой гранулы (= блока из 8192 строк по умолчанию), есть ли в грануле строки, удовлетворяющие условию фильтрации.
Эта информация записывается в виде одного бита: бит 0 означает, что ни одна строка не соответствует фильтру, а бит 1 — что существует хотя бы одна подходящая строка.
В первом случае ClickHouse может пропустить соответствующую гранулу при вычислении фильтра, во втором гранулу необходимо загрузить и проверить.
Кэш условий запроса эффективен, если выполняются три обязательных условия:
- Во-первых, рабочая нагрузка должна многократно вычислять одни и те же условия фильтрации. Это естественным образом происходит, если запрос повторяется несколько раз, но также возможно, если два запроса используют одни и те же фильтры, например
SELECT product FROM products WHERE quality > 3иSELECT vendor, count() FROM products WHERE quality > 3. - Во-вторых, большая часть данных должна быть неизменяемой, то есть не меняться между запросами. В ClickHouse это обычно так, поскольку части неизменяемы и создаются только операциями INSERT.
- В-третьих, фильтры должны быть селективными, то есть условию фильтрации должно удовлетворять сравнительно небольшое число строк. Чем меньше строк соответствует условию фильтрации, тем больше гранул будет записано с битом 0 (нет подходящих строк), и тем больше данных можно будет “отсечь” при последующих вычислениях фильтра。
Потребление памяти
Поскольку кэш условий запроса хранит только один бит для каждой комбинации условия фильтрации и гранулы, он потребляет очень мало памяти. Максимальный размер кэша условий запроса можно настроить с помощью настройки сервераquery_condition_cache_size (по умолчанию: 100 MB).
Размер кэша в 100 MB соответствует 100 * 1024 * 1024 * 8 = 838,860,800 записей.
Поскольку каждая запись представляет метку (по умолчанию 8192 строк), кэш может охватывать до 6,871,947,673,600 (6,8 триллиона) строк одного столбца.
На практике фильтры вычисляются более чем по одному столбцу, поэтому это число нужно разделить на количество столбцов, по которым выполняется фильтрация.
Настройки конфигурации и использование
Параметр use_query_condition_cache определяет, должен ли конкретный запрос или все запросы в текущем сеансе использовать кэш условий запроса. Например, при первом выполнении запросаuse_query_condition_cache = true, будет использоваться кэш условий запроса, чтобы сканировать меньше данных.
Файлы Parquet
Кэш условий запроса работает и для файлов Parquet, читаемых через движки таблицFile, S3, AzureBlobStorage, URL и движки таблиц озера данных (но не через табличные функции, поскольку записи кэша принадлежат таблице).
Для таких файлов кэш запоминает не гранулы, а группы строк.
Записи файла привязаны к его версии, поэтому изменённый файл читается заново. Версия определяется по ETag для объектного хранилища, а для локальных файлов и для URL — по времени изменения и размеру.
Поскольку веб-сервер сообщает время изменения (Last-Modified) с точностью лишь до секунды, файл, читаемый через URL, использует кэш только при двух условиях: он был изменён более минуты назад по часам веб-сервера (значение Date в его ответе), а сервер сообщает время изменения файла, его размер и дату.
Условия, зависящие от текущего времени
Условие видаWHERE time >= now() - INTERVAL 10 DAY является недетерминированным: свёрнутое значение now() меняется с каждым запросом, поэтому такие условия нельзя кэшировать напрямую.
Вместо этого ClickHouse выводит из них детерминированное условие, округляя константу текущего времени до точки временной сетки. Например, time >= '2026-08-09 12:34:56' кэшируется как time >= '2026-08-09 00:00:00' (при чтении кэша значение округляется вниз, а при записи — вверх, благодаря чему кэшированная информация остаётся корректной).
Шаг сетки пропорционален расстоянию между константой и текущим временем — один день для условия, охватывающего последние десять дней, один час для условия, охватывающего последние девяносто минут, — и ограничен диапазоном от одной секунды до одного дня; коэффициент пропорциональности задаётся настройкой query_condition_cache_time_condition_grid_factor (по умолчанию: 1.0).
Если константа уже выровнена по сетке, например в WHERE time >= today() - 10 или WHERE time >= toStartOfDay(now()) - INTERVAL 10 DAY, кэш может быть повторно использован уже следующим запросом и остаётся эффективным до изменения константы (например, до конца дня).
Для невыровненной константы, как в WHERE time >= now() - INTERVAL 10 DAY, записи кэша, созданные в течение одной ячейки сетки, обслуживают запросы следующей: вчерашние запросы заполняют кэш для сегодняшних.
Такое повторное использование работает только для нижних границ времени. Верхняя граница вида WHERE time < now() — как сама по себе, так и в скользящем окне, ограниченном текущим временем с обеих сторон, например WHERE time >= now() - INTERVAL 10 DAY AND time < now(), — используется повторно, только если её константы выровнены по сетке (например, WHERE time < today() или WHERE time >= today() - 10 AND time < today()): при невыровненных константах условие более позднего запроса не содержится в условии более раннего, поэтому записи кэша более раннего запроса нельзя корректно применить, какой бы ни была сетка.
Это преобразование можно отключить с помощью настройки use_query_condition_cache_for_time_conditions (по умолчанию: включена), которая действует, только если также включена use_query_condition_cache.
Оно применяется к таблицам MergeTree; при чтении из файлов и объектного хранилища (file, s3 и аналогичных) кэш условий запроса по-прежнему используется только для детерминированных условий.
Запросы вида ORDER BY ... LIMIT N, использующие динамическую фильтрацию (use_top_k_dynamic_filtering), повторно используют записи, созданные другими запросами с тем же условием.
Если динамический фильтр добавляется в PREWHERE или условие остаётся в предложении WHERE, такие запросы сами не создают записей для условий, зависящих от текущего времени: пропускаемые ими строки зависят от первых N строк, удовлетворяющих условию, а они различаются для двух условий, отображаемых на одну и ту же точку сетки.
Если динамический фильтр нельзя добавить в PREWHERE (например, для некоторых типов столбца сортировки), гранулы, пропускаемые PREWHERE с условием, зависящим от текущего времени, не зависят от первых N строк, поэтому они сохраняются под выведенным условием в записях, которые повторно используются только запросами с тем же планом TopK (см. ниже).
Запросы ORDER BY ... LIMIT n (TopK)
Запросы, использующие оптимизацию TopK (ORDER BY <column> LIMIT n, ускоряемые динамической фильтрацией или индексом пропуска данных minmax по столбцу сортировки), также используют кэш условий запроса.
При чтении TopK гранулы могут пропускаться на основе порогового значения, которое меняется в ходе выполнения запроса, поэтому записи кэша для таких запросов разделяются по параметрам плана TopK и набору считываемых частей: повторно использовать их может только запрос с тем же планом по тем же частям.
Это относится и к чтению TopK из файлов Parquet через движок таблицы File: в этом случае кэш запоминает группы строк, в которых нет ни одной строки результата, а записи разделяются по параметрам плана TopK, условию фильтрации (если оно задано) и набору считываемых файлов с учётом их версий, поэтому при изменении любого из файлов создаётся новая запись.
То же справедливо и для чтения TopK из таблиц озера данных с файлами данных Parquet (например, Iceberg, DeltaLake, Paimon): их записи разделяются по параметрам плана TopK, условию фильтрации (если оно задано) и снимку таблицы, поэтому для каждого нового снимка создаётся новая запись.
В отличие от других операций чтения, такое чтение TopK использует кэш даже при отсутствии условия фильтрации, например SELECT * FROM hits ORDER BY EventTime LIMIT 10.
Такие операции чтения можно полностью исключить из кэша с помощью настройки use_query_condition_cache_for_top_k (по умолчанию включена), которая действует только при включённой use_query_condition_cache.
Администрирование
Кэш условий запроса не сохраняется после перезапуска ClickHouse. Чтобы очистить кэш условий запроса, выполнитеSYSTEM CLEAR QUERY CONDITION CACHE.
Содержимое кэша отображается в системной таблице system.query_condition_cache.
Чтобы рассчитать текущий размер кэша условий запроса в МБ, выполните SELECT formatReadableSize(sum(entry_size)) FROM system.query_condition_cache.
Если вы хотите изучить отдельные условия фильтрации, можете посмотреть поле condition в system.query_condition_cache. Обратите внимание: это поле доступно только в отладочных сборках.
Количество попаданий и промахов кэша условий запроса с момента запуска базы данных отображается как события “QueryConditionCacheHits” и “QueryConditionCacheMisses” в системной таблице system.events.
Оба счётчика обновляются только для SELECT-запросов, выполняемых с настройкой use_query_condition_cache = true; другие запросы не влияют на “QueryCacheMisses”.