mirror of
https://github.com/ClickHouse/ClickHouse.git
synced 2024-11-26 09:32:01 +00:00
DOCSUP-7086: Add s3 translation.
This commit is contained in:
romanzhukov
parent
467fcbec06
commit
20da5e020a
@ -26,19 +26,19 @@ ENGINE = S3(path, [aws_access_key_id, aws_secret_access_key,] format, structure,
|
||||
**1.** Set up the `s3_engine_table` 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')
|
||||
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.** Fill file:
|
||||
|
||||
``` sql
|
||||
INSERT INTO s3_engine_table VALUES ('one', 1), ('two', 2), ('three', 3)
|
||||
INSERT INTO s3_engine_table VALUES ('one', 1), ('two', 2), ('three', 3);
|
||||
```
|
||||
|
||||
**3.** Query the data:
|
||||
|
||||
``` sql
|
||||
SELECT * FROM s3_engine_table LIMIT 2
|
||||
SELECT * FROM s3_engine_table LIMIT 2;
|
||||
```
|
||||
|
||||
``` text
|
||||
@ -83,19 +83,19 @@ Constructions with `{}` are similar to the [remote](../../../sql-reference/table
|
||||
<!-- -->
|
||||
|
||||
``` 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')
|
||||
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. Another way:
|
||||
|
||||
``` 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')
|
||||
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. Table consists of all the files in both directories (all files should satisfy format and schema described in query):
|
||||
|
||||
``` sql
|
||||
CREATE TABLE table_with_asterisk (name String, value UInt32) ENGINE = S3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/*', 'CSV')
|
||||
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"
|
||||
@ -106,7 +106,7 @@ CREATE TABLE table_with_asterisk (name String, value UInt32) ENGINE = S3('https:
|
||||
Create table with files named `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')
|
||||
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');
|
||||
```
|
||||
|
||||
## Virtual Columns {#virtual-columns}
|
||||
|
||||
158
docs/ru/engines/table-engines/integrations/s3.md
Normal file
158
docs/ru/engines/table-engines/integrations/s3.md
Normal file
@ -0,0 +1,158 @@
|
||||
---
|
||||
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. По умолчанию, it will autodetect compression by file extension. По умолчанию формат сжатия определяется автоматически исходя из расширения файла.
|
||||
|
||||
**Примеры**
|
||||
|
||||
**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.
|
||||
|
||||
Пример:
|
||||
|
||||
```
|
||||
<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>
|
||||
```
|
||||
|
||||
[Оригинальная статья](https://clickhouse.tech/docs/ru/operations/table_engines/s3/) <!--hide-->
|
||||
Loading…
Reference in New Issue
Block a user