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

toc_priority	toc_title
4	S3

S3

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

Использование движка

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. По умолчанию формат сжатия определяется автоматически исходя из расширения файла.

Примеры

1. Настройте таблицу s3_engine_table:

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');

2. Заполните файл данными:

INSERT INTO s3_engine_table VALUES ('one', 1), ('two', 2), ('three', 3);

3. Прочитайте данные:

Запрос:

SELECT * FROM s3_engine_table LIMIT 2;

Результат:

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

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

• Поддерживается многопоточное чтение и запись.
• Не поддерживается:
  • использование операций ALTER и SELECT...SAMPLE;
  • индексы;
  • репликация.

Шаблоны в пути

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

• * — заменяет любое количество любых символов кроме /, включая отсутствие символов.
• ? — заменяет любой одиночный символ.
• {some_string,another_string,yet_another_one} — заменяет любую из строк 'some_string', 'another_string', 'yet_another_one'.
• {N..M} — заменяет любое число в интервале от N до M включительно (может содержать ведущие нули, например: 000..078).

Конструкция с {} аналогична табличной функции remote.

Пример

1. Предположим, что у нас есть несколько файлов в формате 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’

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

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');

3. Еще один способ:

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');

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

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

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

Пример

Создайте таблицу из файлов 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');

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

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

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

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

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

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

• s3_max_single_part_upload_size — значение по умолчанию 64Mb. Максимальный размер объекта для одиночной загрузки в S3.
• s3_min_upload_part_size — значение по умолчанию 512Mb. Минимальный размер части файла для составной загрузки.
• s3_max_redirects — значение по умолчанию 10. Максимальное количество http-перенаправлений в запросе на хранилище S3.

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

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

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

• endpoint — обязательный параметр, указывает префикс конечной точки.
• access_key_id and secret_access_key — опциональный параметр. Содержит учетные данные для использования с данной конечной точкой.
• use_environment_credentials — опциональный параметр, значение по умолчанию false. Если установлено значение true, клиент S3 будет использовать учетные сведения из переменных сред и метаданных Amazon EC2, для данной конечной точки.
• 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>

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