> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Предоставляет табличный интерфейс для выборки и вставки файлов в Amazon S3 и Google Cloud Storage. Эта табличная функция похожа на функцию hdfs, но предоставляет специфичные для S3 возможности.

# Табличная функция s3

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Not supported in ClickHouse Cloud
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental feature. <u><a href="/docs/beta-and-experimental-features#experimental-features">Learn more.</a></u>
        </div>;
};

Предоставляет интерфейс, подобный таблице, для выборки/вставки файлов в [Amazon S3](https://aws.amazon.com/s3/) и [Google Cloud Storage](https://cloud.google.com/storage/). Эта табличная функция похожа на [функцию hdfs](/ru/reference/functions/table-functions/hdfs), но предоставляет возможности, специфичные для S3.

Если в вашем кластере несколько реплик, вместо этого можно использовать [функцию s3Cluster](/ru/reference/functions/table-functions/s3Cluster), чтобы распараллелить вставку.

При использовании `s3 table function` с [`INSERT INTO...SELECT`](/ru/reference/statements/insert-into#inserting-the-results-of-select) данные считываются и вставляются в потоковом режиме. В памяти одновременно находится лишь несколько блоков данных, пока они непрерывно считываются из S3 и записываются в целевую таблицу.

<div id="syntax">
  ## Синтаксис
</div>

```sql theme={null}
s3(url [, NOSIGN | access_key_id, secret_access_key, [session_token]] [,format] [,structure] [,compression_method],[,headers], [,extra_credentials], [,partition_strategy], [,partition_columns_in_data_file])
s3(named_collection[, option=value [,..]])
```

<Tip>
  **GCS**

  Табличная функция S3 интегрируется с Google Cloud Storage через XML API GCS и HMAC-ключи. Подробнее о конечной точке и HMAC см. в [документации Google по совместимости](https://cloud.google.com/storage/docs/interoperability).

  Для GCS подставьте свои HMAC-ключ и HMAC-секрет там, где указаны `access_key_id` и `secret_access_key`.
</Tip>

**Параметры**

Табличная функция `s3` поддерживает следующие простые параметры:

| Параметр                                | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`                                   | URL бакета с путём к файлу. В режиме только для чтения поддерживаются следующие подстановочные шаблоны: `*`, `**`, `?`, `{abc,def}` и `{N..M}`, где `N`, `M` — числа, `'abc'`, `'def'` — строки. Подробнее см. [здесь](/ru/reference/engines/table-engines/integrations/s3#wildcards-in-path).                                                                                                                                           |
| `NOSIGN`                                | Если указать это ключевое слово вместо учетных данных, запросы не будут подписываться.                                                                                                                                                                                                                                                                                                                                                   |
| `access_key_id` and `secret_access_key` | Ключи, задающие учетные данные для использования с указанной конечной точкой. Необязательно.                                                                                                                                                                                                                                                                                                                                             |
| `session_token`                         | Токен сеанса для использования с указанными ключами. Необязателен при передаче ключей.                                                                                                                                                                                                                                                                                                                                                   |
| `format`                                | [Формат](/ru/reference/formats) файла.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `structure`                             | Структура таблицы. Формат: `'column1_name column1_type, column2_name column2_type, ...'`.                                                                                                                                                                                                                                                                                                                                                |
| `compression_method`                    | Параметр необязателен. Поддерживаемые значения: `none`, `gzip` или `gz`, `brotli` или `br`, `xz` или `LZMA`, `zstd` или `zst`. По умолчанию метод сжатия определяется автоматически по расширению файла.                                                                                                                                                                                                                                 |
| `headers`                               | Параметр необязателен. Позволяет передавать заголовки в запросе S3. Передавайте в формате `headers(key=value)`, например `headers('x-amz-request-payer' = 'requester')`.                                                                                                                                                                                                                                                                 |
| `partition_strategy`                    | Параметр необязателен. Поддерживаемые значения: `WILDCARD` или `HIVE`. Для `WILDCARD` в пути требуется `{_partition_id}`, который заменяется ключом партиционирования. `HIVE` не допускает подстановочные шаблоны, предполагает, что путь является корнем таблицы, и создаёт директории с партициями в стиле Hive, где в качестве имён файлов используются Snowflake ID, а в качестве расширения — формат файла. По умолчанию `WILDCARD` |
| `partition_columns_in_data_file`        | Параметр необязателен. Используется только со стратегией партиционирования `HIVE`. Указывает ClickHouse, следует ли ожидать, что столбцы партиции будут записаны в файл данных. Значение по умолчанию — `false`.                                                                                                                                                                                                                         |
| `extra_credentials`                     | Параметр необязателен. Используется для передачи `role_arn` для ролевого доступа в ClickHouse Cloud. Шаги настройки см. в [Secure S3](/ru/products/cloud/guides/data-sources/accessing-s3-data-securely).                                                                                                                                                                                                                                |
| `storage_class_name`                    | Параметр необязателен. Поддерживаемые значения: `STANDARD` или `INTELLIGENT_TIERING`. Позволяет указать [AWS S3 Intelligent Tiering](https://aws.amazon.com/s3/storage-classes/intelligent-tiering/). По умолчанию — `STANDARD`.                                                                                                                                                                                                         |

<Info>
  **GCS**

  URL GCS имеет следующий формат, так как конечная точка Google XML API отличается от JSON API:

  ```text theme={null}
    https://storage.googleapis.com/<bucket>/<folder>/<filename(s)>
  ```

  а не ~~[https://storage.cloud.google.com](https://storage.cloud.google.com)~~.
</Info>

Аргументы также можно передавать с помощью [именованных коллекций](/ru/concepts/features/configuration/server-config/named-collections). В этом случае `url`, `access_key_id`, `secret_access_key`, `format`, `structure`, `compression_method` работают так же, и поддерживаются некоторые дополнительные параметры:

| Аргумент                      | Описание                                                                                                                                                                                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `filename`                    | добавляется к URL, если указан.                                                                                                                                                                                                                  |
| `use_environment_credentials` | включен по умолчанию; позволяет передавать дополнительные параметры через переменные окружения `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`, `AWS_CONTAINER_CREDENTIALS_FULL_URI`, `AWS_CONTAINER_AUTHORIZATION_TOKEN`, `AWS_EC2_METADATA_DISABLED`. |
| `no_sign_request`             | по умолчанию отключен.                                                                                                                                                                                                                           |
| `expiration_window_seconds`   | значение по умолчанию — 120.                                                                                                                                                                                                                     |

<div id="returned_value">
  ## Возвращаемое значение
</div>

Таблица с указанной структурой для чтения данных из указанного файла или записи данных в него.

<div id="examples">
  ## Примеры
</div>

Выбор первых 5 строк из таблицы в файле S3 `https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv`:

```sql theme={null}
SELECT *
FROM s3(
   'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv',
   'CSVWithNames'
)
LIMIT 5;
```

```response theme={null}
┌───────Date─┬────Open─┬────High─┬─────Low─┬───Close─┬───Volume─┬─OpenInt─┐
│ 1984-09-07 │ 0.42388 │ 0.42902 │ 0.41874 │ 0.42388 │ 23220030 │       0 │
│ 1984-09-10 │ 0.42388 │ 0.42516 │ 0.41366 │ 0.42134 │ 18022532 │       0 │
│ 1984-09-11 │ 0.42516 │ 0.43668 │ 0.42516 │ 0.42902 │ 42498199 │       0 │
│ 1984-09-12 │ 0.42902 │ 0.43157 │ 0.41618 │ 0.41618 │ 37125801 │       0 │
│ 1984-09-13 │ 0.43927 │ 0.44052 │ 0.43927 │ 0.43927 │ 57822062 │       0 │
└────────────┴─────────┴─────────┴─────────┴─────────┴──────────┴─────────┘
```

<Note>
  ClickHouse использует расширения файлов, чтобы определить формат данных. Например, предыдущую команду можно было выполнить и без `CSVWithNames`:

  ```sql theme={null}
  SELECT *
  FROM s3(
     'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv'
  )
  LIMIT 5;
  ```

  ClickHouse также может определить метод сжатия файла. Например, если файл сжат и имеет расширение `.csv.gz`, ClickHouse автоматически его распакует.
</Note>

<Note>
  Файлы Parquet с именами вроде `*.parquet.snappy` или `*.parquet.zstd` могут сбить ClickHouse с толку и вызвать ошибки `TOO_LARGE_COMPRESSED_BLOCK` или `ZSTD_DECODER_FAILED`.
  Это связано с тем, что ClickHouse попытается прочитать весь файл как данные, сжатые Snappy или ZSTD, хотя в Parquet сжатие применяется на уровне групп строк и столбцов.

  Метаданные Parquet уже содержат информацию о сжатии для каждого столбца, поэтому расширение файла здесь избыточно.
  В таких случаях можно просто использовать `compression_method = 'none'`:

  ```sql theme={null}
  SELECT *
  FROM s3(
    'https://<my-bucket>.s3.<my-region>.amazonaws.com/path/to/my-data.parquet.snappy',
    compression_format = 'none'
  );
  ```
</Note>

<div id="usage">
  ## Использование
</div>

Предположим, что на S3 у нас есть несколько файлов со следующими URI:

* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some\&#95;prefix/some\&#95;file\&#95;1.csv\&#39](https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some\&#95;prefix/some\&#95;file\&#95;1.csv\&#39);
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some\&#95;prefix/some\&#95;file\&#95;2.csv\&#39](https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some\&#95;prefix/some\&#95;file\&#95;2.csv\&#39);
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some\&#95;prefix/some\&#95;file\&#95;3.csv\&#39](https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some\&#95;prefix/some\&#95;file\&#95;3.csv\&#39);
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some\&#95;prefix/some\&#95;file\&#95;4.csv\&#39](https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some\&#95;prefix/some\&#95;file\&#95;4.csv\&#39);
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another\&#95;prefix/some\&#95;file\&#95;1.csv\&#39](https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another\&#95;prefix/some\&#95;file\&#95;1.csv\&#39);
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another\&#95;prefix/some\&#95;file\&#95;2.csv\&#39](https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another\&#95;prefix/some\&#95;file\&#95;2.csv\&#39);
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another\&#95;prefix/some\&#95;file\&#95;3.csv\&#39](https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another\&#95;prefix/some\&#95;file\&#95;3.csv\&#39);
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another\&#95;prefix/some\&#95;file\&#95;4.csv\&#39](https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another\&#95;prefix/some\&#95;file\&#95;4.csv\&#39);

Подсчитайте количество строк в файлах, названия которых оканчиваются на числа от 1 до 3:

```sql theme={null}
SELECT count(*)
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
```

```text theme={null}
┌─count()─┐
│      18 │
└─────────┘
```

Подсчитайте общее количество строк во всех файлах в этих двух каталогах:

```sql theme={null}
SELECT count(*)
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/my-test-bucket-768/{some,another}_prefix/*', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32')
```

```text theme={null}
┌─count()─┐
│      24 │
└─────────┘
```

<Tip>
  Если в списке файлов есть диапазоны чисел с ведущими нулями, используйте конструкцию с фигурными скобками для каждой цифры отдельно или символ `?`.
</Tip>

Подсчитайте общее количество строк в файлах с именами `file-000.csv`, `file-001.csv`, ... , `file-999.csv`:

```sql theme={null}
SELECT count(*)
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/my-test-bucket-768/big_prefix/file-{000..999}.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32');
```

```text theme={null}
┌─count()─┐
│      12 │
└─────────┘
```

Вставьте данные в файл `test-data.csv.gz`:

```sql theme={null}
INSERT INTO FUNCTION s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
VALUES ('test-data', 1), ('test-data-2', 2);
```

Вставьте данные из существующей таблицы в файл `test-data.csv.gz`:

```sql theme={null}
INSERT INTO FUNCTION s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip')
SELECT name, value FROM existing_table;
```

Glob \*\* можно использовать для рекурсивного обхода каталогов. Рассмотрим пример ниже — он рекурсивно извлечёт все файлы из каталога `my-test-bucket-768`:

```sql theme={null}
SELECT * FROM s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/**', 'CSV', 'name String, value UInt32', 'gzip');
```

Следующий запрос рекурсивно извлекает данные из всех файлов `test-data.csv.gz` в любой папке внутри каталога `my-test-bucket`:

```sql theme={null}
SELECT * FROM s3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip');
```

Примечание. В конфигурационном файле сервера можно указать пользовательские URL-маппер. Пример:

```sql theme={null}
SELECT * FROM s3('s3://clickhouse-public-datasets/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip');
```

URL `'s3://clickhouse-public-datasets/my-test-bucket-768/**/test-data.csv.gz'` будет преобразован в `'http://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/**/test-data.csv.gz'`

Пользовательский маппер можно добавить в `config.xml`:

```xml theme={null}
<url_scheme_mappers>
   <s3>
      <to>https://{bucket}.s3.amazonaws.com</to>
   </s3>
   <gs>
      <to>https://{bucket}.storage.googleapis.com</to>
   </gs>
   <oss>
      <to>https://{bucket}.oss.aliyuncs.com</to>
   </oss>
</url_scheme_mappers>
```

Для использования в производственной среде рекомендуется использовать [именованные коллекции](/ru/concepts/features/configuration/server-config/named-collections). Вот пример:

```sql theme={null}

CREATE NAMED COLLECTION creds AS
        access_key_id = '***',
        secret_access_key = '***';
SELECT count(*)
FROM s3(creds, url='https://s3-object-url.csv')
```

<div id="partitioned-write">
  ## Запись с партиционированием
</div>

<div id="partition-strategy">
  ### Стратегия партиционирования
</div>

Поддерживается только для запросов INSERT.

`WILDCARD` (по умолчанию): заменяет подстановочный шаблон `{_partition_id}` в пути к файлу на фактическое значение ключа партиционирования.

`HIVE` реализует секционирование в стиле Hive для чтения и записи. Файлы создаются в следующем формате: `<prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>`.

**Пример стратегии партиционирования `HIVE`**

```sql theme={null}
INSERT INTO FUNCTION s3(s3_conn, filename='t_03363_function', format=Parquet, partition_strategy='hive') PARTITION BY (year, country) SELECT 2020 as year, 'Russia' as country, 1 as id;
```

```result theme={null}
SELECT _path, * FROM s3(s3_conn, filename='t_03363_function/**.parquet');

   ┌─_path──────────────────────────────────────────────────────────────────────┬─id─┬─country─┬─year─┐
1. │ test/t_03363_function/year=2020/country=Russia/7351295896279887872.parquet │  1 │ Russia  │ 2020 │
   └────────────────────────────────────────────────────────────────────────────┴────┴─────────┴──────┘
```

**Примеры стратегии партиционирования `WILDCARD`**

1. Использование идентификатора партиции в ключе создаёт отдельные файлы:

```sql theme={null}
INSERT INTO TABLE FUNCTION
    s3('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a String, b UInt32, c UInt32')
    PARTITION BY a VALUES ('x', 2, 3), ('x', 4, 5), ('y', 11, 12), ('y', 13, 14), ('z', 21, 22), ('z', 23, 24);
```

В результате данные записываются в три файла: `file_x.csv`, `file_y.csv` и `file_z.csv`.

2. Использование идентификатора партиции в имени бакета приводит к созданию файлов в разных бакетах:

```sql theme={null}
INSERT INTO TABLE FUNCTION
    s3('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32')
    PARTITION BY a VALUES (1, 2, 3), (1, 4, 5), (10, 11, 12), (10, 13, 14), (20, 21, 22), (20, 23, 24);
```

В результате данные записываются в три файла в разных бакетах: `my_bucket_1/file.csv`, `my_bucket_10/file.csv` и `my_bucket_20/file.csv`.

<div id="accessing-public-buckets">
  ## Доступ к публичным бакетам
</div>

ClickHouse пытается получить учетные данные из самых разных источников.
Иногда это может вызывать проблемы при доступе к некоторым публичным бакетам, из-за чего клиент возвращает ошибку с кодом `403`.
Этой проблемы можно избежать, используя ключевое слово `NOSIGN`, которое заставляет клиент игнорировать все учетные данные и не подписывать запросы.

```sql theme={null}
SELECT *
FROM s3(
   'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv',
   NOSIGN,
   'CSVWithNames'
)
LIMIT 5;
```

<div id="using-s3-credentials-clickhouse-cloud">
  ## Использование учетных данных S3 (ClickHouse Cloud)
</div>

Для закрытых бакетов можно передать в функцию `aws_access_key_id` и `aws_secret_access_key`. Например:

```sql theme={null}
SELECT count() FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/mta/*.tsv', '<KEY>', '<SECRET>','TSVWithNames')
```

Это подходит для разового доступа или для случаев, когда учётные данные можно легко сменить. Однако в качестве долгосрочного решения для регулярного доступа или при работе с конфиденциальными учётными данными это не рекомендуется. В таких случаях мы рекомендуем использовать ролевой доступ.

Ролевой доступ к S3 в ClickHouse Cloud описан [здесь](/ru/products/cloud/guides/data-sources/accessing-s3-data-securely).

После настройки `roleARN` можно передать в функцию s3 через параметр `extra_credentials`. Например:

```sql theme={null}
SELECT count() FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/mta/*.tsv','CSVWithNames',extra_credentials(role_arn = 'arn:aws:iam::111111111111:role/ClickHouseAccessRole-001'))
```

Другие примеры можно найти [здесь](/ru/products/cloud/guides/data-sources/accessing-s3-data-securely#access-your-s3-bucket-with-the-clickhouseaccess-role)

<div id="working-with-archives">
  ## Работа с архивами
</div>

Предположим, что у нас есть несколько архивных файлов со следующими URI в S3:

* '[https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-10.csv.zip\&#39](https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-10.csv.zip\&#39);
* '[https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-11.csv.zip\&#39](https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-11.csv.zip\&#39);
* '[https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-12.csv.zip\&#39](https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-12.csv.zip\&#39);

Извлечь данные из этих архивов можно с помощью ::. Глоб-шаблоны можно использовать как в части URL, так и в части после :: (которая отвечает за имя файла внутри архива).

```sql theme={null}
SELECT *
FROM s3(
   'https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-1{0..2}.csv.zip :: *.csv'
);
```

<Note>
  ClickHouse поддерживает три формата архивов:
  ZIP
  TAR
  7Z
  Хотя к архивам ZIP и TAR можно обращаться из любого поддерживаемого хранилища, архивы 7Z можно читать только из локальной файловой системы, где установлен ClickHouse.
</Note>

<div id="inserting-data">
  ## Вставка данных
</div>

Обратите внимание: строки можно вставлять только в новые файлы. Циклы слияния и операции разбиения файлов не поддерживаются. После записи файла все последующие вставки завершатся ошибкой. Подробнее см. [здесь](/ru/integrations/connectors/data-ingestion/AWS/integrating-s3-with-clickhouse#inserting-data).

<div id="virtual-columns">
  ## Виртуальные столбцы
</div>

* `_path` — Путь к файлу. Тип: `LowCardinality(String)`. Для архива показывает путь в формате: `"{path_to_archive}::{path_to_file_inside_archive}"`
* `_file` — Имя файла. Тип: `LowCardinality(String)`. Для архива показывает имя файла внутри архива.
* `_size` — Размер файла в байтах. Тип: `Nullable(UInt64)`. Если размер файла неизвестен, значение — `NULL`. Для архива показывает несжатый размер файла внутри архива.
* `_time` — Время последнего изменения файла. Тип: `Nullable(DateTime)`. Если время неизвестно, значение — `NULL`.

<div id="hive-style-partitioning">
  ## Настройка use\_hive\_partitioning
</div>

Это указание для ClickHouse разбирать при чтении файлы, разбитые на секции в стиле Hive. На запись оно не влияет. Для симметричного чтения и записи используйте аргумент `partition_strategy`.

Если для настройки `use_hive_partitioning` установлено значение 1, ClickHouse будет распознавать секционирование в стиле Hive в пути (`/name=value/`) и позволит использовать столбцы партиции в запросе как виртуальные столбцы. Эти виртуальные столбцы будут иметь те же имена, что и в пути с партициями.

**Пример**

```sql theme={null}
SELECT * FROM s3('s3://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;
```

<div id="accessing-requester-pays-buckets">
  ## Доступ к requester-pays бакетам
</div>

Чтобы получить доступ к requester-pays бакету, во все запросы необходимо добавлять заголовок `x-amz-request-payer = requester`. Для этого в функцию `s3` передаётся параметр `headers('x-amz-request-payer' = 'requester')`. Например:

```sql theme={null}
SELECT
    count() AS num_rows,
    uniqExact(_file) AS num_files
FROM s3('https://coiled-datasets-rp.s3.us-east-1.amazonaws.com/1trc/measurements-100*.parquet', 'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', headers('x-amz-request-payer' = 'requester'))

┌───num_rows─┬─num_files─┐
│ 1110000000 │       111 │
└────────────┴───────────┘

1 row in set. Elapsed: 3.089 sec. Processed 1.09 billion rows, 0.00 B (353.55 million rows/s., 0.00 B/s.)
Peak memory usage: 192.27 KiB.
```

<div id="storage-settings">
  ## Настройки хранилища
</div>

* [s3\_truncate\_on\_insert](/ru/reference/settings/session-settings#s3_truncate_on_insert) - позволяет очищать файл перед вставкой в него. По умолчанию отключено.
* [s3\_create\_new\_file\_on\_insert](/ru/reference/settings/session-settings#s3_create_new_file_on_insert) - позволяет создавать новый файл при каждой вставке, если формат имеет суффикс. По умолчанию отключено.
* [s3\_skip\_empty\_files](/ru/reference/settings/session-settings#s3_skip_empty_files) - позволяет пропускать пустые файлы при чтении. По умолчанию включено.

<div id="nested-avro-schemas">
  ## Вложенные схемы Avro
</div>

При чтении файлов Avro, содержащих **вложенные записи**, которые различаются от файла к файлу (например, в некоторых файлах внутри вложенного объекта есть дополнительное поле), ClickHouse может вернуть ошибку вида:

> Количество листьев в записи не соответствует количеству элементов в кортеже...

Это происходит потому, что ClickHouse ожидает, что структуры всех вложенных записей будут соответствовать одной и той же схеме.
Чтобы обработать такой сценарий, можно:

* Использовать `schema_inference_mode='union'` для объединения разных схем вложенных записей, или
* Вручную привести вложенные структуры к одному виду и включить
  `use_structure_from_insertion_table_in_table_functions=1`.

<Info>
  **Примечание о производительности**

  `schema_inference_mode='union'` может работать медленнее на очень больших наборах данных в S3, поскольку для определения схемы нужно просканировать каждый файл.
</Info>

**Пример**

```sql theme={null}
INSERT INTO data_stage
SELECT
    id,
    data
FROM s3('https://bucket-name/*.avro', 'Avro')
SETTINGS schema_inference_mode='union';

## Связанные материалы           

- [Движок S3](/reference/engines/table-engines/integrations/s3)
- [Интеграция S3 с ClickHouse](/integrations/connectors/data-ingestion/AWS/integrating-s3-with-clickhouse)
```
