ClickHouse/docs/ru/engines/table-engines/integrations/s3.md

toc_priority	toc_title
4	S3

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

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

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

CREATE TABLE s3_engine_table (name String, value UInt32) 
ENGINE = S3(path, [aws_access_key_id, aws_secret_access_key,] format, structure, [compression])

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

• path — URL-адрес корзины с указанием пути к файлу. Поддерживает следующие подстановочные знаки в режиме "только чтение": *, ?, {abc,def} и {N..M} где N, M — числа, 'abc', 'def' — строки.
• format — формат файла.
• structure — структура таблицы в формате 'column1_name column1_type, column2_name column2_type, ...'.
• compression — тип сжатия. Возможные значения: none, gzip/gz, brotli/br, xz/LZMA, zstd/zst. Необязательный параметр. Если не указано, то тип сжатия определяется автоматически по расширению файла.

Пример

CREATE TABLE s3_engine_table (name String, value UInt32) 
ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip');
INSERT INTO s3_engine_table VALUES ('one', 1), ('two', 2), ('three', 3);
SELECT * FROM s3_engine_table LIMIT 2;

┌─name─┬─value─┐
│ one  │     1 │
│ two  │     2 │
└──────┴───────┘

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

• _path — путь к файлу.
• _file — имя файла.

Подробнее про виртуальные столбцы можно прочитать здесь.

Особенности и рекомендации

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

• Чтение и запись могут быть параллельными.
• Не поддерживаются:
  • запросы ALTER и SELECT...SAMPLE,
  • индексы,
  • репликация.

Символы подстановки

Несколько компонентов пути могут содержать символы подстановки. Для обработки файл должен существовать и соответствовать всему шаблону пути. Список файлов определяется во время выполнения запроса 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.

S3-связанные настройки

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

• s3_max_single_part_upload_size — максимальный размер объекта для загрузки с использованием однокомпонентной загрузки в S3. Значение по умолчанию — 64Mb.
• s3_min_upload_part_size — минимальный размер объекта для загрузки при многокомпонентной загрузке в S3 Multipart upload. Значение по умолчанию — 512Mb.
• s3_max_redirects — максимальное количество разрешенных переадресаций S3. Значение по умолчанию — 10.

Соображение безопасности: если злонамеренный пользователь попробует указать произвольные URL-адреса S3, параметр s3_max_redirects должен быть установлен в ноль, чтобы избежать атак [SSRF] (https://en.wikipedia.org/wiki/Server-side_request_forgery). Как альтернатива, в конфигурации сервера должен быть указан remote_host_filter.

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

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

Обязательная настройка:

• endpoint — указывает префикс конечной точки.

Необязательные настройки:

• access_key_id и secret_access_key — указывает учетные данные для использования с данной конечной точкой.
• use_environment_credentials — если true, S3-клиент будет пытаться получить учетные данные из переменных среды и метаданных Amazon EC2 для данной конечной точки. Значение по умолчанию - false.
• header — добавляет указанный HTTP-заголовок к запросу на заданную конечную точку. Может быть определен несколько раз.
• server_side_encryption_customer_key_base64 — устанавливает необходимые заголовки для доступа к объектам S3 с шифрованием SSE-C.

Пример

<s3>
    <endpoint-name>
        <endpoint>https://storage.yandexcloud.net/my-test-bucket-768/</endpoint>
        <!-- <access_key_id>ACCESS_KEY_ID</access_key_id> -->
        <!-- <secret_access_key>SECRET_ACCESS_KEY</secret_access_key> -->
        <!-- <use_environment_credentials>false</use_environment_credentials> -->
        <!-- <header>Authorization: Bearer SOME-TOKEN</header> -->
        <!-- <server_side_encryption_customer_key_base64>BASE64-ENCODED-KEY</server_side_encryption_customer_key_base64> -->
    </endpoint-name>
</s3>

Примеры использования

Предположим, у нас есть несколько файлов в формате TSV со следующими URL-адресами в HDFS:

• 'https://storage.yandexcloud.net/my-test-bucket-768/some_prefix/some_file_1.csv'
• 'https://storage.yandexcloud.net/my-test-bucket-768/some_prefix/some_file_2.csv'
• 'https://storage.yandexcloud.net/my-test-bucket-768/some_prefix/some_file_3.csv'
• 'https://storage.yandexcloud.net/my-test-bucket-768/another_prefix/some_file_1.csv'
• 'https://storage.yandexcloud.net/my-test-bucket-768/another_prefix/some_file_2.csv'
• 'https://storage.yandexcloud.net/my-test-bucket-768/another_prefix/some_file_3.csv'

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

CREATE TABLE table_with_range (name String, value UInt32) 
ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}', 'CSV');

2. Другой способ:

CREATE TABLE table_with_question_mark (name String, value UInt32) 
ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/some_file_?', 'CSV');

3. Таблица содержит все файлы в обоих директориях (все файлы должны соответствовать формату и схеме, описанным в запросе):

CREATE TABLE table_with_asterisk (name String, value UInt32) 
ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/*', 'CSV');

!!! warning "Warning" Если список файлов содержит диапазоны чисел с ведущими нулями, используйте конструкцию с фигурными скобками для каждой цифры отдельно или используйте ?.

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

CREATE TABLE big_table (name String, value UInt32) 
ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/big_prefix/file-{000..999}.csv', 'CSV');

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

• Табличная функция S3

Оригинальная статья