Перейти к основному содержимому
Перейти к основному содержимому

Движок таблиц S3Queue

Этот движок обеспечивает интеграцию с Amazon S3 и позволяет потоковую загрузку. Этот движок похож на движки Kafka, RabbitMQ, но предоставляет специфичные для S3 функции.

Создание таблицы​

осторожно

До 24.7 необходимо использовать префикс s3queue_ для всех настроек, кроме mode, after_processing и keeper_path.

Параметры движка

Параметры S3Queue такие же, как и поддерживаемые движком S3. См. раздел параметров здесь.

Пример

Использование именованных коллекций:

Настройки​

Чтобы получить список настроек, сконфигурированных для таблицы, используйте таблицу system.s3_queue_settings. Доступна с 24.10.

mode​

Возможные значения:

  • unordered — В режиме unordered набор всех уже обработанных файлов отслеживается с помощью постоянных узлов в ZooKeeper.
  • ordered — В режиме ordered файлы обрабатываются в лексикографическом порядке. Это означает, что если файл с именем 'BBB' был обработан в какой-то момент, и позже в корзину добавляется файл с именем 'AA', он будет проигнорирован. В ZooKeeper хранятся только максимальное имя (в лексикографическом смысле) успешно потребленного файла и имена файлов, которые будут повторно загружены после неудачной попытки загрузки.

Значение по умолчанию: ordered в версиях до 24.6. Начиная с 24.6, значение по умолчанию отсутствует, настройка должна быть указана вручную. Для таблиц, созданных в более ранних версиях, значение по умолчанию останется Ordered для совместимости.

after_processing​

Удалить или сохранить файл после успешной обработки. Возможные значения:

  • keep.
  • delete.

Значение по умолчанию: keep.

keeper_path​

Путь в ZooKeeper можно указать как настройку движка таблицы или формировать путь по умолчанию из глобальной конфигурации и UUID таблицы. Возможные значения:

  • String.

Значение по умолчанию: /.

s3queue_loading_retries​

Повторить загрузку файла до указанного количества раз. По умолчанию повторы отсутствуют. Возможные значения:

  • Положительное целое число.

Значение по умолчанию: 0.

s3queue_processing_threads_num​

Количество потоков для выполнения обработки. Применяется только для режима Unordered.

Значение по умолчанию: 1.

s3queue_enable_logging_to_s3queue_log​

Включить ведение журналов в system.s3queue_log.

Значение по умолчанию: 0.

s3queue_polling_min_timeout_ms​

Указывает минимальное время, в миллисекундах, которое ClickHouse ожидает перед следующей попыткой опроса.

Возможные значения:

  • Положительное целое число.

Значение по умолчанию: 1000.

s3queue_polling_max_timeout_ms​

Определяет максимальное время, в миллисекундах, которое ClickHouse ожидает перед началом следующей попытки опроса.

Возможные значения:

  • Положительное целое число.

Значение по умолчанию: 10000.

s3queue_polling_backoff_ms​

Определяет дополнительное время ожидания, добавляемое к предыдущему интервалу опроса, когда новые файлы не найдены. Следующий опрос происходит после суммы предыдущего интервала и этого значения отступа или максимального интервала, в зависимости от того, что меньше.

Возможные значения:

  • Положительное целое число.

Значение по умолчанию: 0.

s3queue_tracked_files_limit​

Позволяет ограничить количество узлов ZooKeeper, если используется режим 'unordered', не влияет на режим 'ordered'. При достижении лимита самые старые обработанные файлы будут удалены из узла ZooKeeper и обработаны заново.

Возможные значения:

  • Положительное целое число.

Значение по умолчанию: 1000.

s3queue_tracked_file_ttl_sec​

Максимальное количество секунд для хранения обработанных файлов в узле ZooKeeper (по умолчанию хранится вечно) для режима 'unordered', не влияет на режим 'ordered'. После указанного количества секунд файл будет повторно импортирован.

Возможные значения:

  • Положительное целое число.

Значение по умолчанию: 0.

s3queue_cleanup_interval_min_ms​

Для режима 'Ordered'. Определяет минимальную границу для интервала перераспределения для фоновой задачи, которая отвечает за поддержание TTL отслеживаемого файла и максимального набора отслеживаемых файлов.

Значение по умолчанию: 10000.

s3queue_cleanup_interval_max_ms​

Для режима 'Ordered'. Определяет максимальную границу для интервала перераспределения для фоновой задачи, которая отвечает за поддержание TTL отслеживаемого файла и максимального набора отслеживаемых файлов.

Значение по умолчанию: 30000.

s3queue_buckets​

Для режима 'Ordered'. Доступно с 24.6. Если есть несколько реплик таблицы S3Queue, каждая из которых работает с одним и тем же каталогом метаданных в Keeper, значение s3queue_buckets должно быть равно как минимум количеству реплик. Если также используется настройка s3queue_processing_threads, имеет смысл увеличить значение настройки s3queue_buckets, так как оно определяет фактический параллелизм обработки S3Queue.

Настройки, связанные с S3​

Движок поддерживает все настройки, связанные с S3. Для получения дополнительной информации о настройках S3 смотрите здесь.

Контроль доступа на основе ролей S3​

Scale plan feature

S3 Role-Based Access is available in the Scale and Enterprise plans. To upgrade, visit the Plans page in the cloud console.

Движок таблиц s3Queue поддерживает контроль доступа на основе ролей. См. документацию здесь для получения шагов по настройке роли для доступа к вашему бакету.

После настройки роли можно передать roleARN через параметр extra_credentials, как показано ниже:

Режим Ordered для S3Queue​

Режим обработки S3Queue позволяет сохранять меньше метаданных в ZooKeeper, но имеет ограничение, что файлы, которые добавляются позже по времени, должны иметь алфавитно большие имена.

Режим ordered S3Queue, как и unordered, поддерживает настройку (s3queue_)processing_threads_num (префикс s3queue_ является необязательным), которая позволяет контролировать количество потоков, обрабатывающих файлы S3 локально на сервере. В дополнение, режим 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 не особенно полезен для потоковой загрузки (за исключением отладки), потому что каждый файл можно импортировать только один раз. Более практично создавать потоки в реальном времени с использованием материализованных представлений. Для этого:

  1. Используйте движок для создания таблицы для потребления из заданного пути в S3 и рассматривайте её как поток данных.
  2. Создайте таблицу с желаемой структурой.
  3. Создайте материализованное представление, которое преобразует данные из движка и помещает их в ранее созданную таблицу.

Когда MATERIALIZED VIEW присоединяется к движку, оно начинает собирать данные в фоновом режиме.

Пример:

Виртуальные столбцы​

  • _path — Путь к файлу.
  • _file — Имя файла.

Для получения дополнительной информации о виртуальных столбцах смотрите здесь.

Подстановочные знаки в пути​

Аргумент 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.

Ограничения​

  1. Дублированные строки могут быть результатом:

  • исключения, возникающего во время разбора в середине обработки файла и повторные попытки включены через s3queue_loading_retries;

  • S3Queue настроен на нескольких серверах, указывающих на тот же путь в ZooKeeper, и сессия Keeper истекает до того, как один сервер смог закоммитить обработанный файл, что может привести к тому, что другой сервер начнет обрабатывать файл, который мог быть частично или полностью обработан первым сервером;

  • ненормальное завершение сервера.

  1. Если S3Queue настроен на нескольких серверах, указывающих на тот же путь в ZooKeeper и используется режим Ordered, тогда s3queue_loading_retries не будет работать. Это будет исправлено в ближайшее время.

Интроспекция​

Для интроспекции используйте статическую таблицу system.s3queue и постоянную таблицу system.s3queue_log.

  1. system.s3queue. Эта таблица не является постоянной и показывает состояние в памяти S3Queue: какие файлы в данный момент обрабатываются, какие файлы были обработаны или потерпели неудачу.

Пример:

  1. system.s3queue_log. Постоянная таблица. Содержит ту же информацию, что и system.s3queue, но для processed и failed файлов.

Таблица имеет следующую структуру:

Для использования system.s3queue_log определите его конфигурацию в файле конфигурации сервера:

Пример: