2021-03-01 13:35:59 +00:00
---
toc_priority: 45
toc_title: s3
---
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-05 08:31:16 +00:00
**Aр г у ме нты**
2021-03-01 20:07:09 +00:00
2021-03-05 08:31:16 +00:00
- `path` — URL-адрес бакета с указанием пути к файлу. Поддерживает следующие подстановочные знаки в режиме "только чтение": *, ?, {abc,def} и {N..M} где N, M — числа, `’ abc’ , ‘ def’ — строки.
2021-03-01 20:07:09 +00:00
- `format` — [формат ](../../interfaces/formats.md#formats ) файла.
- `structure` — cтр у кту р а таблицы. Формат `'column1_name column1_type, column2_name column2_type, ...'` .
- `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 20:07:09 +00:00
Query:
2021-03-01 13:35:59 +00:00
``` sql
SELECT *
FROM s3('https://storage.yandexcloud.net/my-test-bucket-768/data.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
2021-03-01 20:07:09 +00:00
LIMIT 2;
2021-03-01 13:35:59 +00:00
```
2021-03-01 20:07:09 +00:00
Result:
2021-03-01 13:35:59 +00:00
``` text
┌─column1─┬─column2─┬─column3─┐
│ 1 │ 2 │ 3 │
│ 3 │ 2 │ 1 │
└─────────┴─────────┴─────────┘
```
2021-03-01 20:07:09 +00:00
Т о же самое, но файл с о сжатием `gzip` :
Запрос:
2021-03-01 13:35:59 +00:00
``` sql
2021-03-01 20:07:09 +00:00
SELECT *
FROM s3('https://storage.yandexcloud.net/my-test-bucket-768/data.csv.gz', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32', 'gzip')
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
┌─column1─┬─column2─┬─column3─┐
│ 1 │ 2 │ 3 │
│ 3 │ 2 │ 1 │
└─────────┴─────────┴─────────┘
```
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
- ‘ 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 20:07:09 +00:00
1. Запрос количества строк в файлах, заканчивающихся цифрами от 1 до 3:
2021-03-01 13:35:59 +00:00
``` sql
SELECT count(*)
2021-03-01 20:07:09 +00:00
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
┌─count()─┐
│ 18 │
└─────────┘
```
2021-03-01 20:07:09 +00:00
2. Запрос количества строк во всех файлах этих двух каталогов:
2021-03-01 13:35:59 +00:00
``` sql
SELECT count(*)
2021-03-01 20:07:09 +00:00
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
┌─count()─┐
│ 24 │
└─────────┘
```
!!! warning "Warning"
2021-03-01 20:07:09 +00:00
Если список файлов содержит диапазоны чисел с ведущими нулями, используйте конструкцию с фигурными скобками для каждой цифры отдельно или используйте `?` .
2021-03-01 13:35:59 +00:00
2021-03-01 20:07:09 +00:00
3. Запрос данных из файлов с именами `file-000.csv` , `file-001.csv` , … , `file-999.csv` :
2021-03-01 13:35:59 +00:00
``` sql
SELECT count(*)
2021-03-01 20:07:09 +00:00
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
┌─count()─┐
│ 12 │
└─────────┘
```
2021-03-01 20:07:09 +00:00
4. Вставка данных в файл `test-data.csv.gz` :
2021-03-01 13:35:59 +00:00
``` sql
INSERT INTO s3('https://storage.yandexcloud.net/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
2021-03-01 20:07:09 +00:00
VALUES ('test-data', 1), ('test-data-2', 2);
2021-03-01 13:35:59 +00:00
```
2021-03-01 20:07:09 +00:00
5. Вставка данных в файл `test-data.csv.gz` из существующей таблицы:
2021-03-01 13:35:59 +00:00
``` sql
INSERT INTO s3('https://storage.yandexcloud.net/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
2021-03-01 20:07:09 +00:00
SELECT name, value FROM existing_table;
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 ](../../engines/table-engines/integrations/s3.md )
2021-03-01 13:35:59 +00:00
2021-03-01 20:07:09 +00:00
[Оригинальная статья ](https://clickhouse.tech/docs/ru/sql-reference/table-functions/s3/ ) <!--hide-->