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

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

Этот движок предоставляет интеграцию с экосистемой Amazon S3. Этот движок похож на движок HDFS, но предлагает функции, специфичные для S3.

Пример​

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

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

  • path — URL корзины с путем к файлу. Поддерживаются следующие подстановочные знаки в режиме только для чтения: *, **, ?, {abc,def} и {N..M}, где N, M — числа, 'abc', 'def' — строки. Дополнительную информацию см. ниже.
  • NOSIGN - Если это ключевое слово указано вместо учетных данных, все запросы не будут подписаны.
  • format — формат файла.
  • aws_access_key_id, aws_secret_access_key - Долгосрочные учетные данные для пользователя аккаунта AWS. Вы можете использовать их для аутентификации ваших запросов. Параметр является необязательным. Если учетные данные не указаны, они используются из файла конфигурации. Дополнительную информацию см. Использование S3 для хранения данных.
  • compression — Тип сжатия. Поддерживаемые значения: none, gzip/gz, brotli/br, xz/LZMA, zstd/zst. Параметр является необязательным. По умолчанию сжатие будет автоматически определяться по расширению файла.

Кэш данных​

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

Чтобы включить кэширование, используйте настройку filesystem_cache_name = '<name>' и enable_filesystem_cache = 1.

Существует два способа определить кэш в файле конфигурации.

  1. Добавьте следующий раздел в файл конфигурации ClickHouse:
  1. Повторно используйте конфигурацию кэша (а значит, и хранилище кэша) из раздела storage_configuration ClickHouse, описанного здесь

PARTITION BY​

PARTITION BY — Необязательный. В большинстве случаев вам не нужен ключ партиционирования, и если он нужен, то обычно не нужен более детальный ключ партиционирования, чем по месяцу. Партиционирование не ускоряет запросы (в отличие от выражения ORDER BY). Никогда не используйте слишком детальное партиционирование. Не партиционируйте ваши данные по идентификаторам клиентов или именам (вместо этого сделайте идентификатор клиента или имя первым столбцом в выражении ORDER BY).

Для партиционирования по месяцам используйте выражение toYYYYMM(date_column), где date_column — это колонка с датой типа Date. Имена партиций имеют формат "YYYYMM".

Запрос данных из партиционированных таблиц​

В этом примере используется рецепт docker compose, который интегрирует ClickHouse и MinIO. Вы должны быть в состоянии воспроизвести те же запросы, используя S3, заменив значения конечной точки и аутентификации.

Обратите внимание, что конечная точка S3 в конфигурации ENGINE использует параметр token {_partition_id} как часть объекта S3 (имя файла), и что запросы SELECT работают с этими именами объектов (например, test_3.csv).

примечание

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

Основное применение для записи партиционированных данных в S3 — это возможность переноса этих данных в другую систему ClickHouse (например, перемещение из локальных систем в ClickHouse Cloud). Поскольку наборы данных ClickHouse часто очень большие, а надежность сети иногда несовершенна, имеет смысл переносить наборы данных по частям, таким образом выполняя партиционированные записи.

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

Вставка данных​

Запрос из партиции 3​

подсказка

Этот запрос использует функцию таблицы s3

Запрос из партиции 1​

Запрос из партиции 45​

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

Вы, возможно, попытаетесь выполнить Select * from p, но, как было отмечено выше, этот запрос завершится ошибкой; используйте предыдущий запрос.

Вставка данных​

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

Виртуальные колонки​

  • _path — Путь к файлу. Тип: LowCardinality(String).
  • _file — Имя файла. Тип: LowCardinality(String).
  • _size — Размер файла в байтах. Тип: Nullable(UInt64). Если размер неизвестен, значение будет NULL.
  • _time — Время последнего изменения файла. Тип: Nullable(DateTime). Если время неизвестно, значение будет NULL.
  • _etag — ETag файла. Тип: LowCardinality(String). Если etag неизвестен, значение будет NULL.

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

Детали реализации​

  • Чтения и записи могут выполняться параллельно

  • Не поддерживается:

    Репликация без копирования не готова для продакшена

    Репликация без копирования отключена по умолчанию в ClickHouse версии 22.8 и выше. Эта функция не рекомендуется для использования в продуктивной среде.

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

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

Создайте таблицу с файлами, названными file-000.csv, file-001.csv, ... , file-999.csv:

Пример с подстановочными знаками 2

Предположим, у нас есть несколько файлов в формате CSV с следующими URI на S3:

Существует несколько способов создать таблицу, состоящую из всех шести файлов:

  1. Укажите диапазон постфиксов файлов:
  1. Возьмите все файлы с префиксом some_file_ (в обеих папках не должно быть лишних файлов с таким префиксом):
  1. Возьмите все файлы в обеих папках (все файлы должны соответствовать формату и схеме, описанным в запросе):

Параметры хранения​

  • s3_truncate_on_insert - позволяет обрезать файл перед вставкой в него. Отключен по умолчанию.
  • s3_create_new_file_on_insert - позволяет создавать новый файл при каждой вставке, если формат имеет суффикс. Отключен по умолчанию.
  • s3_skip_empty_files - позволяет пропускать пустые файлы при чтении. Включен по умолчанию.

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

Следующие настройки могут быть установлены перед выполнением запроса или размещены в файле конфигурации.

  • s3_max_single_part_upload_size — Максимальный размер объекта для загрузки с использованием одной загрузки на S3. Значение по умолчанию: 32Mb.
  • s3_min_upload_part_size — Минимальный размер части, которую нужно загрузить при многокомпонентной загрузке на S3 Multipart upload. Значение по умолчанию: 16Mb.
  • s3_max_redirects — Максимальное количество перенаправлений S3, допустимых. Значение по умолчанию: 10.
  • s3_single_read_retries — Максимальное количество попыток во время однократного чтения. Значение по умолчанию: 4.
  • s3_max_put_rps — Максимальная скорость запросов PUT в секунду до ограничения. Значение по умолчанию: 0 (неограничено).
  • s3_max_put_burst — Максимальное количество запросов, которые могут быть сделаны одновременно до достижения лимита запросов в секунду. По умолчанию (0) равно s3_max_put_rps.
  • s3_max_get_rps — Максимальная скорость запросов GET в секунду до ограничения. Значение по умолчанию: 0 (неограничено).
  • s3_max_get_burst — Максимальное количество запросов, которые могут быть сделаны одновременно до достижения лимита запросов в секунду. По умолчанию (0) равно s3_max_get_rps.
  • s3_upload_part_size_multiply_factor - Умножьте s3_min_upload_part_size на этот коэффициент каждый раз, когда s3_upload_part_size_multiply_parts_count_threshold частей были загружены из одной записи в S3. Значение по умолчанию: 2.
  • s3_upload_part_size_multiply_parts_count_threshold - Каждый раз, когда это количество частей было загружено на S3, s3_min_upload_part_size умножается на s3_upload_part_size_multiply_factor. Значение по умолчанию: 500.
  • s3_max_inflight_parts_for_one_file - Ограничивает количество запросов PUT, которые могут выполняться одновременно для одного объекта. Это число должно быть ограничено. Значение 0 обозначает неограниченное количество. Значение по умолчанию: 20. Каждая часть в процессе имеет буфер размером s3_min_upload_part_size для первых s3_upload_part_size_multiply_factor частей и больше, когда файл достаточно велик, см. upload_part_size_multiply_factor. При настройках по умолчанию один загружаемый файл потребляет не более 320Mb для файла, который меньше 8G. Потребление больше для более крупных файлов.

Соображения безопасности: если злонамеренный пользователь может указать произвольные URL S3, необходимо установить s3_max_redirects в ноль, чтобы избежать SSRF атак; или, альтернативно, remote_host_filter должен быть указан в конфигурации сервера.

Настройки на основе конечной точки​

Следующие настройки могут быть указаны в файле конфигурации для данной конечной точки (которая будет соответствовать точному префиксу URL):

  • endpoint — Указывает префикс конечной точки. Обязательный.
  • access_key_id и secret_access_key — Указывают учетные данные для использования с данной конечной точкой. Необязательный.
  • use_environment_credentials — Если установлено в true, клиент S3 попытается получить учетные данные из переменных окружения и метаданных Amazon EC2 для данной конечной точки. Необязательный, значение по умолчанию: false.
  • region — Указывает название региона S3. Необязательный.
  • use_insecure_imds_request — Если установлено в true, клиент S3 будет использовать небезопасный IMDS запрос при получении учетных данных из метаданных Amazon EC2. Необязательный, значение по умолчанию: false.
  • expiration_window_seconds — Период грации для проверки, истекли ли учетные данные, основанные на времени действия. Необязательный, значение по умолчанию: 120.
  • no_sign_request - Игнорировать все учетные данные, чтобы запросы не были подписаны. Полезно для доступа к публичным корзинам.
  • header — Добавляет указанный HTTP заголовок к запросу к данной конечной точке. Необязательный, может быть указан несколько раз.
  • access_header - Добавляет указанный HTTP заголовок к запросу к данной конечной точке, в случаях, когда нет других учетных данных из другого источника.
  • server_side_encryption_customer_key_base64 — Если указано, будут установлены необходимые заголовки для доступа к объектам S3 с шифрованием SSE-C. Необязательный.
  • server_side_encryption_kms_key_id - Если указано, будут установлены необходимые заголовки для доступа к объектам S3 с шифрованием SSE-KMS. Если указана пустая строка, будет использован управляемый AWS ключ S3. Необязательный.
  • server_side_encryption_kms_encryption_context - Если указано вместе с server_side_encryption_kms_key_id, будет установлен данный заголовок контекста шифрования для SSE-KMS. Необязательный.
  • server_side_encryption_kms_bucket_key_enabled - Если указано вместе с server_side_encryption_kms_key_id, будет установлен заголовок для включения ключей корзины S3 для SSE-KMS. Необязательный, может быть значением true или false, по умолчанию ничего не установлено (соответствует настройке на уровне корзины).
  • max_single_read_retries — Максимальное количество попыток во время однократного чтения. Значение по умолчанию: 4. Необязательный.
  • max_put_rps, max_put_burst, max_get_rps и max_get_burst - Параметры ограничения (см. выше) для использования конкретной конечной точки вместо запроса. Необязательный.

Пример:

Работа с архивами​

Допустим, у нас есть несколько архивных файлов с следующими URI на S3:

Извлечение данных из этих архивов возможно с помощью ::. Подстановочные знаки могут использоваться как в части URL, так и в части после :: (отвечающей за имя файла внутри архива).

примечание

ClickHouse поддерживает три формата архивов: ZIP TAR 7Z В то время как архивы ZIP и TAR могут быть доступны из любого поддерживаемого места хранения, архивы 7Z могут быть прочитаны только из локальной файловой системы, где установлен ClickHouse.

Доступ к публичным корзинам​

ClickHouse пытается получить учетные данные из многих различных источников. Иногда это может вызвать проблемы при доступе к некоторым корзинам, которые являются публичными, что приводит к возврату клиентом кода ошибки 403. Эта проблема может быть устранена с помощью ключевого слова NOSIGN, принуждающего клиента игнорировать все учетные данные и не подписывать запросы.

Оптимизация производительности​

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

Смотрите также​