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

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

165 lines
12 KiB
Markdown
Raw Normal View History

2021-02-28 19:27:22 +00:00
---
2022-08-26 17:37:11 +00:00
slug: /ru/engines/table-engines/integrations/s3
sidebar_position: 4
sidebar_label: S3
2021-02-28 19:27:22 +00:00
---
2021-03-05 08:31:16 +00:00
# Движок таблиц S3 {#table-engine-s3}
2021-02-28 19:27:22 +00:00
2021-03-01 20:07:09 +00:00
Этот движок обеспечивает интеграцию с экосистемой [Amazon S3](https://aws.amazon.com/s3/). Он похож на движок [HDFS](../../../engines/table-engines/special/file.md#table_engines-hdfs), но обеспечивает специфические для S3 возможности.
2021-02-28 19:27:22 +00:00
2021-03-05 08:31:16 +00:00
## Создание таблицы {#creating-a-table}
2021-02-28 19:27:22 +00:00
``` sql
2021-06-01 14:28:34 +00:00
CREATE TABLE s3_engine_table (name String, value UInt32)
ENGINE = S3(path, [aws_access_key_id, aws_secret_access_key,] format, [compression])
[SETTINGS ...]
2021-02-28 19:27:22 +00:00
```
2021-03-01 20:07:09 +00:00
**Параметры движка**
2021-02-28 19:27:22 +00:00
2021-03-21 14:23:16 +00:00
- `path` — URL-адрес бакета с указанием пути к файлу. Поддерживает следующие подстановочные знаки в режиме "только чтение": `*`, `?`, `{abc,def}` и `{N..M}` где `N`, `M` — числа, `'abc'`, `'def'` — строки. Подробнее смотри [ниже](#wildcards-in-path).
2021-02-28 19:27:22 +00:00
- `format` — [формат](../../../interfaces/formats.md#formats) файла.
2021-04-25 19:00:19 +00:00
- `aws_access_key_id`, `aws_secret_access_key` - данные пользователя учетной записи [AWS](https://aws.amazon.com/ru/). Вы можете использовать их для аутентификации ваших запросов. Необязательный параметр. Если параметры учетной записи не указаны, то используются данные из конфигурационного файла. Смотрите подробнее [Использование сервиса S3 для хранения данных](../mergetree-family/mergetree.md#table_engine-mergetree-s3).
2021-06-01 14:28:34 +00:00
- `compression` — тип сжатия. Возможные значения: `none`, `gzip/gz`, `brotli/br`, `xz/LZMA`, `zstd/zst`. Необязательный параметр. Если не указано, то тип сжатия определяется автоматически по расширению файла.
2021-02-28 19:27:22 +00:00
2021-03-05 08:00:49 +00:00
**Пример**
2021-02-28 19:27:22 +00:00
``` 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', 'gzip')
SETTINGS input_format_with_names_use_header = 0;
2021-02-28 19:27:22 +00:00
INSERT INTO s3_engine_table VALUES ('one', 1), ('two', 2), ('three', 3);
2021-02-28 19:27:22 +00:00
SELECT * FROM s3_engine_table LIMIT 2;
```
``` text
┌─name─┬─value─┐
│ one │ 1 │
│ two │ 2 │
└──────┴───────┘
```
2021-03-05 08:31:16 +00:00
## Виртуальные столбцы {#virtual-columns}
2021-02-28 19:27:22 +00:00
2021-03-05 08:31:16 +00:00
- `_path` — путь к файлу.
- `_file` — имя файла.
2021-02-28 19:27:22 +00:00
2021-03-05 08:31:16 +00:00
Подробнее про виртуальные столбцы можно прочитать [здесь](../../../engines/table-engines/index.md#table_engines-virtual_columns).
2021-02-28 19:27:22 +00:00
2021-03-11 10:11:00 +00:00
## Детали реализации {#implementation-details}
2021-02-28 19:27:22 +00:00
2021-03-05 08:31:16 +00:00
- Чтение и запись могут быть параллельными.
- Поддерживается репликация без копирования данных ([zero-copy](../../../operations/storing-data.md#zero-copy)).
2021-03-05 08:31:16 +00:00
- Не поддерживаются:
2021-03-01 20:07:09 +00:00
- запросы `ALTER` и `SELECT...SAMPLE`,
2021-08-02 17:19:21 +00:00
- индексы.
2021-02-28 19:27:22 +00:00
2021-03-21 14:23:16 +00:00
## Символы подстановки {#wildcards-in-path}
2021-02-28 19:27:22 +00:00
Аргумент `path` может указывать на несколько файлов, используя символы подстановки. Для обработки файл должен существовать и соответствовать всему шаблону пути. Список файлов определяется во время выполнения запроса `SELECT` (не в момент выполнения запроса `CREATE`).
2021-02-28 19:27:22 +00:00
- `*` — заменяет любое количество любых символов, кроме `/`, включая пустую строку.
2021-03-01 20:07:09 +00:00
- `?` — заменяет любые одиночные символы.
- `{some_string, another_string, yet_another_one}` — заменяет любые строки `'some_string', 'another_string', 'yet_another_one'`.
- `{N..M}` — заменяет любое число от N до M, включая обе границы. N и M могут иметь ведущие нули, например `000..078`.
2021-02-28 19:27:22 +00:00
2021-03-01 20:07:09 +00:00
Конструкции с `{}` аналогичны функции [remote](../../../sql-reference/table-functions/remote.md).
2021-02-28 19:27:22 +00:00
2023-09-05 12:43:53 +00:00
:::danger Примечание
Если список файлов содержит диапазоны чисел с ведущими нулями, используйте конструкцию с фигурными скобками для каждой цифры отдельно или используйте `?`.
**Пример подстановки 1**
Таблица содержит данные из файлов с именами `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-bucket/my_folder/file-{000..999}.csv', 'CSV');
```
**Пример подстановки 2**
Предположим, есть несколько файлов в формате CSV со следующими URL-адресами в S3:
- 'https://storage.yandexcloud.net/my-bucket/some_folder/some_file_1.csv'
- 'https://storage.yandexcloud.net/my-bucket/some_folder/some_file_2.csv'
- 'https://storage.yandexcloud.net/my-bucket/some_folder/some_file_3.csv'
- 'https://storage.yandexcloud.net/my-bucket/another_folder/some_file_1.csv'
- 'https://storage.yandexcloud.net/my-bucket/another_folder/some_file_2.csv'
- 'https://storage.yandexcloud.net/my-bucket/another_folder/some_file_3.csv'
Существует несколько способов создать таблицу, включающую в себя все шесть файлов:
1. Задайте диапазон для суффиксов в названии файла:
``` sql
CREATE TABLE table_with_range (name String, value UInt32)
ENGINE = S3('https://storage.yandexcloud.net/my-bucket/{some,another}_folder/some_file_{1..3}', 'CSV');
```
2. Таблица содержит все файлы с префиксом `some_file_` (в каталогах не должно быть других файлов с таким префиксом):
``` sql
CREATE TABLE table_with_question_mark (name String, value UInt32)
ENGINE = S3('https://storage.yandexcloud.net/my-bucket/{some,another}_folder/some_file_?', 'CSV');
```
3. Таблица содержит все файлы в обоих каталогах (в каталогах не должно быть других файлов, соответствующих формату и схеме, описанным в запросе):
``` sql
CREATE TABLE table_with_asterisk (name String, value UInt32)
ENGINE = S3('https://storage.yandexcloud.net/my-bucket/{some,another}_folder/*', 'CSV');
```
2021-03-11 10:11:00 +00:00
## Настройки движка S3 {#s3-settings}
2021-06-01 14:28:34 +00:00
Перед выполнением запроса или в конфигурационном файле могут быть установлены следующие настройки:
2021-02-28 19:27:22 +00:00
2021-06-01 14:28:34 +00:00
- `s3_max_single_part_upload_size` — максимальный размер объекта для загрузки с использованием однокомпонентной загрузки в S3. Значение по умолчанию — `64 Mб`.
- `s3_min_upload_part_size` — минимальный размер объекта для загрузки при многокомпонентной загрузке в [S3 Multipart upload](https://docs.aws.amazon.com/AmazonS3/latest/dev/uploadobjusingmpu.html). Значение по умолчанию — `512 Mб`.
2021-06-01 14:28:34 +00:00
- `s3_max_redirects` — максимальное количество разрешенных переадресаций S3. Значение по умолчанию — `10`.
- `s3_single_read_retries` — максимальное количество попыток запроса при единичном чтении. Значение по умолчанию — `4`.
2021-02-28 19:27:22 +00:00
Соображение безопасности: если злонамеренный пользователь попробует указать произвольные URL-адреса S3, параметр `s3_max_redirects` должен быть установлен в ноль, чтобы избежать атак [SSRF](https://en.wikipedia.org/wiki/Server-side_request_forgery). Как альтернатива, в конфигурации сервера должен быть указан `remote_host_filter`.
2021-02-28 19:27:22 +00:00
2021-03-25 14:24:42 +00:00
## Настройки точки приема запроса {#endpoint-settings}
2021-02-28 19:27:22 +00:00
2021-03-25 14:24:42 +00:00
Для точки приема запроса (которая соответствует точному префиксу URL-адреса) в конфигурационном файле могут быть заданы следующие настройки:
2021-02-28 19:27:22 +00:00
2021-03-01 20:07:09 +00:00
Обязательная настройка:
2021-06-01 14:28:34 +00:00
- `endpoint` — указывает префикс точки приема запроса.
2021-02-28 19:27:22 +00:00
2021-03-01 20:07:09 +00:00
Необязательные настройки:
2021-03-25 14:24:42 +00:00
- `access_key_id` и `secret_access_key` — указывают учетные данные для использования с данной точкой приема запроса.
- `use_environment_credentials` — если `true`, S3-клиент будет пытаться получить учетные данные из переменных среды и метаданных [Amazon EC2](https://ru.wikipedia.org/wiki/Amazon_EC2) для данной точки приема запроса. Значение по умолчанию — `false`.
- `use_insecure_imds_request` — признак использования менее безопасного соединения при выполнении запроса к IMDS при получении учётных данных из метаданных Amazon EC2. Значение по умолчанию — `false`.
2021-05-01 17:41:31 +00:00
- `region` — название региона S3.
2021-03-25 14:24:42 +00:00
- `header` — добавляет указанный HTTP-заголовок к запросу на заданную точку приема запроса. Может быть определен несколько раз.
2021-06-01 14:28:34 +00:00
- `server_side_encryption_customer_key_base64` — устанавливает необходимые заголовки для доступа к объектам S3 с шифрованием SSE-C.
2021-06-03 23:45:25 +00:00
- `single_read_retries` — Максимальное количество попыток запроса при единичном чтении. Значение по умолчанию — `4`.
2021-02-28 19:27:22 +00:00
2021-03-30 13:35:02 +00:00
**Пример**
2021-02-28 19:27:22 +00:00
2021-03-05 09:36:05 +00:00
``` xml
2021-03-01 20:07:09 +00:00
<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> -->
2021-05-01 17:41:31 +00:00
<!-- <region>us-west-1</region> -->
2021-03-01 20:07:09 +00:00
<!-- <use_environment_credentials>false</use_environment_credentials> -->
<!-- <use_insecure_imds_request>false</use_insecure_imds_request> -->
2021-03-01 20:07:09 +00:00
<!-- <header>Authorization: Bearer SOME-TOKEN</header> -->
<!-- <server_side_encryption_customer_key_base64>BASE64-ENCODED-KEY</server_side_encryption_customer_key_base64> -->
2021-06-04 11:40:32 +00:00
<!-- <single_read_retries>4</single_read_retries> -->
2021-03-01 20:07:09 +00:00
</endpoint-name>
</s3>
2021-02-28 19:27:22 +00:00
```
**Смотрите также**
2021-03-01 13:35:59 +00:00
2021-09-08 02:52:17 +00:00
- [Табличная функция s3](../../../sql-reference/table-functions/s3.md)