ClickHouse/docs/ru/sql-reference/table-functions/s3.md

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

164 lines
7.3 KiB
Markdown
Raw Normal View History

2021-03-01 13:35:59 +00:00
---
2022-08-26 17:37:11 +00:00
slug: /ru/sql-reference/table-functions/s3
sidebar_position: 45
sidebar_label: s3
2021-03-01 13:35:59 +00:00
---
2021-03-01 20:07:09 +00:00
# Табличная Функция S3 {#s3-table-function}
2021-03-01 13:35:59 +00:00
2021-03-01 20:07:09 +00:00
Предоставляет табличный интерфейс для выбора/вставки файлов в [Amazon S3](https://aws.amazon.com/s3/). Эта табличная функция похожа на [hdfs](../../sql-reference/table-functions/hdfs.md), но обеспечивает специфические для S3 возможности.
2021-03-05 08:31:16 +00:00
**Синтаксис**
2021-03-01 13:35:59 +00:00
``` sql
s3(path [,aws_access_key_id, aws_secret_access_key] [,format] [,structure] [,compression])
2021-03-01 13:35:59 +00:00
```
2021-03-05 08:31:16 +00:00
**Aргументы**
2021-03-01 20:07:09 +00:00
2021-03-21 14:23:16 +00:00
- `path` — URL-адрес бакета с указанием пути к файлу. Поддерживает следующие подстановочные знаки в режиме "только чтение": `*, ?, {abc,def} и {N..M}` где `N, M` — числа, `'abc', 'def'` — строки. Подробнее смотри [здесь](../../engines/table-engines/integrations/s3.md#wildcards-in-path).
2021-03-01 20:07:09 +00:00
- `format` — [формат](../../interfaces/formats.md#formats) файла.
- `structure` — cтруктура таблицы. Формат `'column1_name column1_type, column2_name column2_type, ...'`.
2021-07-29 15:20:55 +00:00
- `compression` — автоматически обнаруживает сжатие по расширению файла. Возможные значения: `none`, `gzip/gz`, `brotli/br`, `xz/LZMA`, `zstd/zst`. Необязательный параметр.
2021-03-01 13:35:59 +00:00
2021-03-01 20:07:09 +00:00
**Возвращаемые значения**
2021-03-01 13:35:59 +00:00
2021-03-01 20:07:09 +00:00
Таблица с указанной структурой для чтения или записи данных в указанный файл.
2021-03-01 13:35:59 +00:00
2021-03-01 20:07:09 +00:00
**Примеры**
2021-03-01 13:35:59 +00:00
2021-03-01 20:07:09 +00:00
Создание таблицы из файла S3 `https://storage.yandexcloud.net/my-test-bucket-768/data.csv` и выбор первых трех столбцов из нее:
2021-03-01 13:35:59 +00:00
Запрос:
2021-03-01 13:35:59 +00:00
``` sql
2021-03-05 09:22:15 +00:00
SELECT *
FROM s3('https://storage.yandexcloud.net/my-test-bucket-768/data.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
LIMIT 2;
2021-03-01 13:35:59 +00:00
```
Результат:
2021-03-01 20:07:09 +00:00
2021-03-01 13:35:59 +00:00
``` text
2021-03-05 09:22:15 +00:00
┌─column1─┬─column2─┬─column3─┐
│ 1 │ 2 │ 3 │
│ 3 │ 2 │ 1 │
└─────────┴─────────┴─────────┘
2021-03-01 13:35:59 +00:00
```
2021-03-01 20:07:09 +00:00
То же самое, но файл со сжатием `gzip`:
Запрос:
2021-03-01 13:35:59 +00:00
``` sql
2021-07-29 15:20:55 +00:00
SELECT *
FROM s3('https://storage.yandexcloud.net/my-test-bucket-768/data.csv.gz', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32', 'gzip')
2021-03-05 09:22:15 +00:00
LIMIT 2;
2021-03-01 13:35:59 +00:00
```
2021-03-01 20:07:09 +00:00
Результат:
2021-03-01 13:35:59 +00:00
``` text
2021-03-05 09:22:15 +00:00
┌─column1─┬─column2─┬─column3─┐
│ 1 │ 2 │ 3 │
│ 3 │ 2 │ 1 │
└─────────┴─────────┴─────────┘
2021-03-01 13:35:59 +00:00
```
2021-03-14 20:19:53 +00:00
2021-03-01 20:07:09 +00:00
## Примеры использования {#usage-examples}
2021-03-01 13:35:59 +00:00
2021-03-01 20:07:09 +00:00
Предположим, у нас есть несколько файлов со следующими URI на S3:
2021-03-01 13:35:59 +00:00
2021-03-05 09:10:35 +00:00
- '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/some_prefix/some_file_4.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'
- 'https://storage.yandexcloud.net/my-test-bucket-768/another_prefix/some_file_4.csv'
2021-03-01 13:35:59 +00:00
Подсчитаем количество строк в файлах, заканчивающихся цифрами от 1 до 3:
2021-03-01 13:35:59 +00:00
``` sql
2021-03-05 09:22:15 +00:00
SELECT count(*)
FROM s3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv', 'CSV', 'name String, value UInt32');
2021-03-01 13:35:59 +00:00
```
``` text
2021-03-05 09:22:15 +00:00
┌─count()─┐
│ 18 │
└─────────┘
2021-03-01 13:35:59 +00:00
```
Подсчитаем общее количество строк во всех файлах этих двух каталогов:
2021-03-01 13:35:59 +00:00
``` sql
2021-03-05 09:22:15 +00:00
SELECT count(*)
FROM s3('https://storage.yandexcloud.net/my-test-bucket-768/{some,another}_prefix/*', 'CSV', 'name String, value UInt32');
2021-03-01 13:35:59 +00:00
```
``` text
2021-03-05 09:22:15 +00:00
┌─count()─┐
│ 24 │
└─────────┘
2021-03-01 13:35:59 +00:00
```
:::danger "Warning"
2021-03-01 20:07:09 +00:00
Если список файлов содержит диапазоны чисел с ведущими нулями, используйте конструкцию с фигурными скобками для каждой цифры отдельно или используйте `?`.
2021-03-01 13:35:59 +00:00
Подсчитаем общее количество строк в файлах с именами `file-000.csv`, `file-001.csv`, … , `file-999.csv`:
2021-03-01 13:35:59 +00:00
``` sql
2021-03-05 09:22:15 +00:00
SELECT count(*)
FROM s3('https://storage.yandexcloud.net/my-test-bucket-768/big_prefix/file-{000..999}.csv', 'CSV', 'name String, value UInt32');
2021-03-01 13:35:59 +00:00
```
``` text
2021-03-05 09:22:15 +00:00
┌─count()─┐
│ 12 │
└─────────┘
2021-03-01 13:35:59 +00:00
```
Запишем данные в файл `test-data.csv.gz`:
2021-03-01 13:35:59 +00:00
``` sql
2021-06-11 04:41:47 +00:00
INSERT INTO FUNCTION s3('https://storage.yandexcloud.net/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
2021-03-05 09:22:15 +00:00
VALUES ('test-data', 1), ('test-data-2', 2);
2021-03-01 13:35:59 +00:00
```
Запишем данные из существующей таблицы в файл `test-data.csv.gz`:
2021-03-01 13:35:59 +00:00
``` sql
2021-06-11 04:41:47 +00:00
INSERT INTO FUNCTION s3('https://storage.yandexcloud.net/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
2021-03-05 09:22:15 +00:00
SELECT name, value FROM existing_table;
2021-03-01 13:35:59 +00:00
```
2021-09-08 02:52:17 +00:00
## Партиционирование при записи данных {#partitioned-write}
2021-09-10 06:31:49 +00:00
Если при добавлении данных в таблицу S3 указать выражение `PARTITION BY`, то для каждого значения ключа партиционирования создается отдельный файл. Это повышает эффективность операций чтения.
2021-09-08 02:52:17 +00:00
**Примеры**
2021-09-10 06:31:49 +00:00
1. При использовании ID партиции в имени ключа создаются отдельные файлы:
2021-09-08 02:52:17 +00:00
```sql
INSERT INTO TABLE FUNCTION
s3('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a UInt32, b UInt32, c UInt32')
2021-09-09 19:33:59 +00:00
PARTITION BY a VALUES ('x', 2, 3), ('x', 4, 5), ('y', 11, 12), ('y', 13, 14), ('z', 21, 22), ('z', 23, 24);
2021-09-08 02:52:17 +00:00
```
2021-09-09 19:33:59 +00:00
В результате данные будут записаны в три файла: `file_x.csv`, `file_y.csv` и `file_z.csv`.
2021-09-08 02:52:17 +00:00
2. При использовании ID партиции в названии бакета создаются файлы в разных бакетах:
```sql
INSERT INTO TABLE FUNCTION
s3('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32')
2021-09-09 19:33:59 +00:00
PARTITION BY a VALUES (1, 2, 3), (1, 4, 5), (10, 11, 12), (10, 13, 14), (20, 21, 22), (20, 23, 24);
2021-09-08 02:52:17 +00:00
```
В результате будут созданы три файла в разных бакетах: `my_bucket_1/file.csv`, `my_bucket_10/file.csv` и `my_bucket_20/file.csv`.
**Смотрите также**
2021-03-01 13:35:59 +00:00
2021-03-01 20:07:09 +00:00
- [Движок таблиц S3](../../engines/table-engines/integrations/s3.md)