--- toc_priority: 4 toc_title: S3 --- # S3 {#table_engines-s3} Движок S3 обеспечивает интеграцию с экосистемой [Amazon S3](https://aws.amazon.com/s3/). Он похож на движок [HDFS](hdfs.md), но обладает специфическими для S3 функциями. ## Использование движка {#ispolzovanie-dvizhka} ``` sql 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` — [формат](../../../interfaces/formats.md#formats) файла. - `structure` — структура таблицы. Указывается в формате `'column1_name column1_type, column2_name column2_type, ...'`. - `compression` — необязательный параметр. Необходим если требуется использовать определенный формат сжатия. Поддерживаемые значения: `none`, `gzip/gz`, `brotli/br`, `xz/LZMA`, `zstd/zst`. По умолчанию формат сжатия определяется автоматически исходя из расширения файла. **Примеры** **1.** Настройте таблицу `s3_engine_table`: ``` sql 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.** Заполните файл данными: ``` sql INSERT INTO s3_engine_table VALUES ('one', 1), ('two', 2), ('three', 3); ``` **3.** Прочитайте данные: Запрос: ``` sql SELECT * FROM s3_engine_table LIMIT 2; ``` Результат: ``` text ┌─name─┬─value─┐ │ one │ 1 │ │ two │ 2 │ └──────┴───────┘ ``` ## Детали реализации {#detali-realizatsii} - Поддерживается многопоточное чтение и запись. - Не поддерживается: - использование операций `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](../../../sql-reference/table-functions/remote.md). **Примеры** 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. Существует несколько способов создать таблицу, объединяющую все шесть файлов: ``` sql 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. Еще один способ: ``` sql 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. Можно создать таблицу, содержащую все файлы из обоих директорий (все файлы должны соответствовать формату и схеме, описанным в запросе): ``` sql 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`: ``` sql 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'); ``` ## Виртуальные столбцы {#virtualnye-stolbtsy} - `_path` — путь к файлу. - `_file` — имя файла. **Смотрите также** - [Виртуальные столбцы](index.md#table_engines-virtual_columns) ## Настройки, связанные с S3 {#settings} Следующие параметры могут быть указаны перед выполнением запроса или в конфигурационном файле: - `s3_max_single_part_upload_size` — значение по умолчанию `64Mb`. Максимальный размер объекта для одиночной загрузки в S3. - `s3_min_upload_part_size` — значение по умолчанию `512Mb`. Минимальный размер части файла для [составной загрузки](https://docs.aws.amazon.com/AmazonS3/latest/dev/uploadobjusingmpu.html). - `s3_max_redirects` — значение по умолчанию `10`. Максимальное количество http-перенаправлений в запросе на хранилище S3. **Соображения безопасности**: чтобы избежать CSRF атак, когда злоумышленник может указать произвольные URL-адреса S3, следует установить `s3_max_redirects` значение `0`; или обязательно указывать `remote_host_filter` в конфигурации сервера. ## Настройки конечных точек {#endpointsettings} В файле конфигурации для определенной конечной точки (которая соответствует точному префиксу 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. Пример: ``` https://storage.yandexcloud.net/my-test-bucket-768/ ``` [Оригинальная статья](https://clickhouse.tech/docs/ru/engines/table-engines/integrations/s3/)