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

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

См. также​