MATERIALIZED VIEW подключается к движку, движок таблицы S3Queue начинает собирать данные в фоновом режиме.
CREATE TABLE
S3Queue совпадают с параметрами, которые поддерживает движок таблицы S3. См. раздел параметров здесь.
Пример
Настройки
system.s3_queue_settings. Доступно с версии 24.10.
Имена настроек (24.7+)Начиная с версии 24.7, настройки S3Queue можно указывать как с префиксом
s3queue_, так и без него:- Современный синтаксис (24.7+):
processing_threads_num,tracked_file_ttl_secи т. д. - Устаревший синтаксис (все версии):
s3queue_processing_threads_num,s3queue_tracked_file_ttl_secи т. д.
Режим
- unordered — В режиме unordered множество уже обработанных файлов отслеживается с помощью постоянных узлов в ZooKeeper.
- ordered — В режиме ordered файлы обрабатываются в лексикографическом порядке. Это означает, что если файл с именем ‘BBB’ был обработан в какой-то момент, а позже в бакет будет добавлен файл с именем ‘AA’, он будет проигнорирован. В ZooKeeper сохраняются только максимальное имя (в лексикографическом смысле) успешно обработанного файла и имена файлов, для которых будут выполняться повторные попытки после неудачной загрузки.
ordered в версиях до 24.6. Начиная с 24.6 значение по умолчанию отсутствует, и этот параметр необходимо указывать вручную. Для таблиц, созданных в более ранних версиях, для совместимости значением по умолчанию останется Ordered.
after_processing
- keep.
- delete.
- move.
- tag.
keep.
Для move требуются дополнительные настройки. Если перемещение выполняется в пределах одного бакета, нужно указать новый префикс пути в after_processing_move_prefix.
Для перемещения в другой S3 бакет требуется URI целевого бакета в after_processing_move_uri, а также учетные данные S3 в after_processing_move_access_key_id и after_processing_move_secret_access_key.
Пример:
after_processing_move_connection_string и имя контейнера в параметре after_processing_move_container. См. настройки AzureQueue.
Для тегирования требуются ключ тега и значение тега, задаваемые параметрами after_processing_tag_key и after_processing_tag_value.
after_processing_retries
- Неотрицательное целое число.
10.
after_processing_move_access_key_id
- String.
after_processing_move_prefix
- String.
after_processing_move_preserve_path
true, при перемещении успешно обработанного файла к after_processing_move_prefix добавляется полный путь к исходному объекту, поэтому исходная структура каталогов в бакете сохраняется в пункте назначения. Если false, используется только имя файла, а исходная структура каталогов становится плоской.
Возможные значения:
true/false.
false.
after_processing_move_secret_access_key
- String.
after_processing_move_uri
- String.
after_processing_tag_key
after_processing='tag'.
Возможные значения:
- String.
after_processing_tag_value
after_processing='tag'.
Возможные значения:
- String.
keeper_path
s3queue_default_zookeeper_path, UUID базы данных и UUID таблицы. Абсолютные значения (начинающиеся с /) используются как есть, а относительные добавляются к настроенному префиксу. Макросы, такие как {database} или {uuid}, разворачиваются до подключения движка к ZooKeeper.
Чтобы указать дополнительный кластер ZooKeeper, добавьте к значению в качестве префикса настроенное имя, например analytics_keeper:/clickhouse/queue/orders. Это имя должно существовать в <auxiliary_zookeepers>; в противном случае движок сообщит об ошибке Unknown auxiliary ZooKeeper name .... Полная строка (включая префикс) сохраняется в SHOW CREATE TABLE, чтобы оператор можно было дословно воспроизвести.
Возможные значения:
- String.
/.
loading_retries
- Неотрицательное целое число.
10.
processing_threads_num
Unordered.
Значение по умолчанию: количество процессоров или 16.
parallel_inserts
processing_threads_num будет создавать один INSERT, поэтому в нескольких потоках будут только скачиваться файлы и разбираться их содержимое.
Но это ограничивает параллелизм, поэтому для более высокой пропускной способности используйте parallel_inserts=true: это позволит выполнять вставку данных параллельно (но имейте в виду, что это приведёт к увеличению числа создаваемых частей данных в семействе MergeTree).
INSERT будут создаваться с учётом настроек max_process*_before_commit.false.
enable_logging_to_queue_log
system.s3queue_log.
Значение по умолчанию: 1.
polling_min_timeout_ms
- Положительное целое число.
1000.
polling_max_timeout_ms
- Положительное целое число.
600000.
polling_backoff_ms
- Положительное целое число.
30000.
tracked_files_limit
- Положительное целое число.
1000.
tracked_file_ttl_sec
- Положительное целое число.
0.
cleanup_interval_min_ms
60000.
cleanup_interval_max_ms
Ordered. Определяет максимальный интервал перепланирования фоновой задачи, отвечающей за поддержание TTL отслеживаемых файлов и максимального количества отслеживаемых файлов.
Значение по умолчанию: 60000.
buckets
24.6. Если у таблицы S3Queue несколько реплик и каждая из них работает с одним и тем же каталогом метаданных в Keeper, значение buckets должно быть как минимум равно числу реплик. Если также используется настройка processing_threads, имеет смысл ещё увеличить значение buckets, так как именно она определяет фактический параллелизм обработки S3Queue.
use_persistent_processing_nodes
use_persistent_processing_nodes = 0, всё равно использует постоянные узлы обработки, а интроспекция настроек, включая SHOW CREATE TABLE, показывает 1 независимо от указанного значения.
persistent_processing_node_ttl_seconds
Ordered, которая может удерживаться дольше, чем отдельный узел обработки, поэтому значение должно учитывать и это.
Значение по умолчанию: 21600 (6 часов).
Настройки, связанные с S3
Ролевой доступ на основе ролей к S3
roleARN можно передать через параметр extra_credentials, как показано ниже:
Упорядоченный режим S3Queue
S3Queue позволяет хранить меньше метаданных в ZooKeeper, но имеет ограничение: файлы, добавленные позже, должны иметь алфавитно-цифровые имена, которые больше по порядку.
Режим S3Queue ordered, как и unordered, поддерживает настройку (s3queue_)processing_threads_num (префикс s3queue_ необязателен), которая позволяет управлять количеством потоков, выполняющих локальную обработку файлов S3 на сервере.
Для режима ordered без партиционирования ClickHouse может возобновлять перечисление объектов S3 с последнего обработанного ключа, чтобы не выполнять повторный обход всей истории префикса. В бакетизированном упорядоченном режиме точка возобновления консервативно выбирается как наименьший обработанный ключ среди всех бакетов, чтобы избежать пропуска необработанных файлов.
Эта оптимизация возобновления перечисления используется только для очередей на базе S3 в режиме ordered без партиционирования (не для AzureQueue и не когда задан partitioning_mode).
Кроме того, режим ordered также вводит ещё одну настройку — (s3queue_)buckets, которая означает «логические потоки». В распределённом сценарии, когда есть несколько серверов с репликами таблицы S3Queue, эта настройка определяет количество единиц обработки. Например, каждый поток обработки на каждой реплике S3Queue будет пытаться заблокировать определённый bucket для обработки, при этом каждый bucket назначается определённым файлам по хэшу имени файла. Поэтому в распределённом сценарии настоятельно рекомендуется, чтобы значение настройки (s3queue_)buckets было как минимум равно числу реплик или больше. Количество бакетов может быть больше числа реплик. Оптимальный вариант — когда значение настройки (s3queue_)buckets равно произведению number_of_replicas и (s3queue_)processing_threads_num.
Использовать настройку (s3queue_)processing_threads_num не рекомендуется до версии 24.6.
Настройка (s3queue_)buckets доступна начиная с версии 24.6.
SELECT из движка таблицы S3Queue
stream_like_engine_allow_direct_select в True.
У движка S3Queue есть специальный параметр для запросов SELECT: commit_on_select. Установите его в False, чтобы сохранить данные в очереди после чтения, или в True, чтобы удалить их.
Описание
SELECT не особенно полезен для потокового импорта (кроме отладки), поскольку каждый файл можно импортировать только один раз. Гораздо практичнее создавать потоки в реальном времени с помощью materialized view. Для этого:
- С помощью движка создайте таблицу для чтения из указанного пути в S3 и рассматривайте её как поток данных.
- Создайте таблицу с нужной структурой.
- Создайте materialized view, который преобразует данные из движка и помещает их в ранее созданную таблицу.
MATERIALIZED VIEW подключается к движку, он начинает собирать данные в фоновом режиме.
Пример:
Виртуальные столбцы
_path— Путь к файлу._file— Имя файла._size— Размер файла._time— Время создания файла.
Подстановочные шаблоны в path
path может задавать несколько файлов с помощью bash-подобных подстановочных шаблонов. Чтобы файл был обработан, он должен существовать и соответствовать шаблону пути целиком. Список файлов определяется во время SELECT (а не в момент CREATE).
*— Заменяет любое количество любых символов, кроме/, включая пустую строку.**— Заменяет любое количество любых символов, включая/, включая пустую строку.?— Заменяет любой отдельный символ.{some_string,another_string,yet_another_one}— Заменяет любую из строк:'some_string','another_string','yet_another_one'.{N..M}— Заменяет любое число в диапазоне от N до M включительно. N и M могут содержать ведущие нули, например000..078.
{} аналогичны конструкции в табличной функции remote.
Ограничения
- Дублирующиеся строки могут возникать в результате:
-
исключения во время парсинга в середине обработки файла, если повторные попытки включены через
s3queue_loading_retries; -
S3Queueнастроен на нескольких серверах, указывающих на один и тот же путь в ZooKeeper, и сеанс Keeper истекает до того, как один из серверов успевает закоммитить обработанный файл. Это может привести к тому, что другой сервер начнёт обрабатывать файл, который уже был частично или полностью обработан первым сервером. Однако этому препятствуют постоянные узлы обработки, доступные с версии 25.8 и теперь используемые всегда (см.use_persistent_processing_nodes). - аварийного завершения работы сервера.
-
Если
S3Queueнастроен на нескольких серверах, указывающих на один и тот же путь в ZooKeeper, и используется режимOrdered, тоs3queue_loading_retriesне будет работать. Это скоро исправят. -
Потеря строк при отключении питания устройства на узле ClickHouse. Файл, данные из которого были считаны, помечается как обработанный в Keeper (а его исходный объект удаляется при
after_processing = 'delete') сразу после завершения вставки, однако вставленные строки становятся устойчивыми только после выполнения fsync для целевой части, что по умолчанию не происходит синхронно (fsync_after_insert = 0). Keeper принудительно синхронизируется и обычно работает на отдельном узле, поэтому переживает отключение питания этого узла. Если питание узла отключается после коммита файла как обработанного, но до выполнения fsync для целевой части, файл не будет повторно прочитан после перезапуска, а его строки будут потеряны (без возможности восстановления приafter_processing = 'delete'). Обычное завершение процесса не выявляет эту проблему, поскольку page cache сохраняется. Для рекомендуемого пути обработки через materialized view (файл коммитится только после завершения всего конвейера вставки) настройкаfsync_after_insert = 1(иfsync_part_directory = 1) в целевой таблицеMergeTreeобеспечивает устойчивость вставленной части до коммита файла как обработанного, что существенно сужает это окно. Это не относится к прямомуINSERT ... SELECTсcommit_on_select = 1, при котором файл коммитится в конце чтения до того, как приемник назначения завершит формирование последней части.
Интроспекция
system.s3queue_metadata_cache и system.s3_queue_metadata, а также постоянную таблицу system.s3queue_log.
- Используйте
system.s3queue_metadata_cacheдля проверки кэша в памяти, содержащего состояние обработки каждого файла (какие файлы сейчас обрабатываются, уже обработаны или завершились ошибкой) на локальном сервере. - Используйте
system.s3_queue_metadataдля проверки состояния, хранящегося непосредственно в Keeper: количества узловprocessed,processingиfailedдля каждого объекта метаданных, а также, при необходимости, их содержимого. Это полезно, если кэш в памяти ещё не отражает состояние Keeper, или для просмотра общего состояния всего кластера. - Используйте
system.s3queue_logдля хранения постоянной истории файлов со статусамиprocessedиfailed.
system.s3queue_metadata_cache. Эта таблица не является постоянной и показывает текущее состояниеS3Queueв памяти: какие файлы обрабатываются в данный момент, какие уже обработаны, а какие завершились ошибкой.
system.s3_queue_metadata. Эта таблица не является постоянной и считывает состояние непосредственно из Keeper: количество узловprocessed,processingиfailedдля каждого объекта метаданных, а также, по запросу, их содержимое.
processed_nodes, processing_nodes, failed_nodes и processed_path выполняют запросы к Keeper и извлекаются только при выборе соответствующего столбца, поэтому выбор только счётчиков *_nodes_count позволяет избежать дополнительного трафика к Keeper.
system.s3_queue_metadata.
system.s3queue_log. Постоянная таблица. Содержит ту же информацию, что иsystem.s3queue_metadata_cache, но для файлов со статусамиprocessedиfailed.
system.s3queue_log, задайте его конфигурацию в конфигурационном файле сервера: