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

S3 Table Engine

Этот движок обеспечивает интеграцию с 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, но, как уже упоминалось, этот запрос завершится ошибкой; используйте предыдущий запрос.

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

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

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

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

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

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

    • Операции ALTER и SELECT...SAMPLE.
    • Индексы.
    • Zero-copy репликация возможна, но не поддерживается.
    Zero-copy репликация не готова для продакшена

    Zero-copy репликация отключена по умолчанию в 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. Потребление больше для больших файлов.

Соображения безопасности: если злонамеренный пользователь может указать произвольные S3 URL, 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. Если указана пустая строка, будет использован управляемый S3 ключ AWS. Необязательная.
  • 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 смотрите наш подробный гид.

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