> ## 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.

> Предоставляет табличный интерфейс для выборки/вставки файлов в Azure Blob Storage. Аналогична функции s3.

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

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>;
};

Предоставляет табличный интерфейс для выборки/вставки файлов в [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs). Эта табличная функция аналогична [функции s3](/ru/reference/functions/table-functions/s3).

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

<Tabs>
  <Tab title="Строка подключения">
    Учетные данные встроены в строку подключения, поэтому отдельно указывать `account_name`/`account_key` не требуется:

    ```sql theme={null}
    azureBlobStorage(connection_string, container_name, blobpath [, format, compression, structure])
    ```
  </Tab>

  <Tab title="URL учетной записи хранилища">
    Требует указания `account_name` и `account_key` в качестве отдельных аргументов:

    ```sql theme={null}
    azureBlobStorage(storage_account_url, container_name, blobpath, account_name, account_key [, format, compression, structure])
    ```
  </Tab>

  <Tab title="Именованная коллекция">
    Полный список поддерживаемых ключей см. ниже в разделе [Именованные коллекции](#named-collections):

    ```sql theme={null}
    azureBlobStorage(named_collection[, option=value [,..]])
    ```
  </Tab>
</Tabs>

<div id="arguments">
  ## Аргументы
</div>

| Аргумент                         | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_string`              | Строка подключения, включающая встроенные учетные данные (имя учетной записи + ключ учетной записи или SAS-токен). При использовании этой формы `account_name` и `account_key` **не** следует передавать отдельно. См. [Настройка строки подключения](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json\&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json#configure-a-connection-string-for-an-azure-storage-account). |
| `storage_account_url`            | URL конечной точки учетной записи хранилища, например `https://myaccount.blob.core.windows.net/`. При использовании этой формы **необходимо** также передать `account_name` и `account_key`.                                                                                                                                                                                                                                                                                                                   |
| `container_name`                 | Имя контейнера.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `blobpath`                       | Путь к файлу. Поддерживает следующие подстановочные шаблоны в режиме только для чтения: `*`, `**`, `?`, `{abc,def}` и `{N..M}`, где `N`, `M` — числа, `'abc'`, `'def'` — строки.                                                                                                                                                                                                                                                                                                                               |
| `account_name`                   | Имя учетной записи хранилища. **Обязательно** при использовании `storage_account_url` без SAS; **не** должно передаваться при использовании `connection_string`.                                                                                                                                                                                                                                                                                                                                               |
| `account_key`                    | Ключ учетной записи хранилища. **Обязательно** при использовании `storage_account_url` без SAS; **не** должно передаваться при использовании `connection_string`.                                                                                                                                                                                                                                                                                                                                              |
| `format`                         | [Формат](/ru/reference/formats) файла.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `compression`                    | Поддерживаемые значения: `none`, `gzip/gz`, `brotli/br`, `xz/LZMA`, `zstd/zst`. По умолчанию сжатие определяется автоматически по расширению файла (то же, что и при значении `auto`).                                                                                                                                                                                                                                                                                                                         |
| `structure`                      | Структура таблицы. Формат: `'column1_name column1_type, column2_name column2_type, ...'`.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `partition_strategy`             | Необязательно. Поддерживаемые значения: `WILDCARD` или `HIVE`. Для `WILDCARD` требуется `{_partition_id}` в пути, который заменяется ключом партиционирования. `HIVE` не допускает подстановочных шаблонов, предполагает, что путь является корнем таблицы, и создает директории с партициями в стиле Hive, где в качестве имен файлов используются Snowflake ID, а в качестве расширения — формат файла. По умолчанию используется `WILDCARD`.                                                                |
| `partition_columns_in_data_file` | Необязательно. Используется только со стратегией партиционирования `HIVE`. Указывает ClickHouse, следует ли ожидать, что столбцы партиций будут записаны в файл данных. По умолчанию `false`.                                                                                                                                                                                                                                                                                                                  |
| `extra_credentials`              | Используйте `client_id` и `tenant_id` для аутентификации. Если указаны `extra_credentials`, они имеют приоритет над `account_name` и `account_key`.                                                                                                                                                                                                                                                                                                                                                            |

<div id="named-collections">
  ## Именованные коллекции
</div>

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

| Ключ                  | Обязательно | Описание                                                                                                                       |
| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `container`           | Да          | Имя контейнера. Соответствует позиционному аргументу `container_name`.                                                         |
| `blob_path`           | Да          | Путь к файлу (с необязательными подстановочными шаблонами). Соответствует позиционному аргументу `blobpath`.                   |
| `connection_string`   | Нет\*       | Строка подключения со встроенными учетными данными. \*Должен быть указан либо `connection_string`, либо `storage_account_url`. |
| `storage_account_url` | Нет\*       | URL конечной точки учетной записи хранилища. \*Должен быть указан либо `connection_string`, либо `storage_account_url`.        |
| `account_name`        | Нет         | Обязателен при использовании `storage_account_url`                                                                             |
| `account_key`         | Нет         | Обязателен при использовании `storage_account_url`                                                                             |
| `format`              | Нет         | Формат файла.                                                                                                                  |
| `compression`         | Нет         | Тип сжатия.                                                                                                                    |
| `structure`           | Нет         | Структура таблицы.                                                                                                             |
| `client_id`           | Нет         | Идентификатор клиента для аутентификации.                                                                                      |
| `tenant_id`           | Нет         | Идентификатор тенанта для аутентификации.                                                                                      |

<Note>
  Имена ключей именованной коллекции отличаются от имён позиционных аргументов функции: `container` (не `container_name`) и `blob_path` (не `blobpath`).
</Note>

**Пример:**

```sql theme={null}
CREATE NAMED COLLECTION azure_my_data AS
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'mycontainer',
    blob_path = 'data/*.parquet',
    account_name = 'myaccount',
    account_key = 'mykey...==',
    format = 'Parquet';

SELECT *
FROM azureBlobStorage(azure_my_data)
LIMIT 5;
```

Вы также можете переопределить значения именованной коллекции при выполнении запроса:

```sql theme={null}
SELECT *
FROM azureBlobStorage(azure_my_data, blob_path = 'other_data/*.csv', format = 'CSVWithNames')
LIMIT 5;
```

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

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

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

<div id="reading-with-storage-account-url">
  ### Чтение с использованием `storage_account_url`
</div>

```sql theme={null}
SELECT *
FROM azureBlobStorage(
    'https://myaccount.blob.core.windows.net/',
    'mycontainer',
    'data/*.parquet',
    'myaccount',
    'mykey...==',
    'Parquet'
)
LIMIT 5;
```

<div id="reading-with-connection-string">
  ### Чтение с использованием варианта `connection_string`
</div>

```sql theme={null}
SELECT *
FROM azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'data/*.csv',
    'CSVWithNames'
)
LIMIT 5;
```

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

```sql theme={null}
INSERT INTO TABLE FUNCTION azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_{_partition_id}.csv',
    'CSV',
    'auto',
    'column1 UInt32, column2 UInt32, column3 UInt32'
) PARTITION BY column3
VALUES (1, 2, 3), (3, 2, 1), (78, 43, 3);
```

Затем прочитайте данные из определённой партиции:

```sql theme={null}
SELECT *
FROM azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_1.csv',
    'CSV',
    'auto',
    'column1 UInt32, column2 UInt32, column3 UInt32'
);
```

```response theme={null}
┌─column1─┬─column2─┬─column3─┐
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘
```

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

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

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

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

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

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

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

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

```sql theme={null}
INSERT INTO TABLE FUNCTION azureBlobStorage(
    azure_conf2,
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'cont',
    blob_path = 'azure_table_root',
    format = 'CSVWithNames',
    compression = 'auto',
    structure = 'year UInt16, country String, id Int32',
    partition_strategy = 'hive'
) PARTITION BY (year, country)
VALUES (2020, 'Russia', 1), (2021, 'Brazil', 2);
```

```result theme={null}
SELECT _path, * FROM azureBlobStorage(
    azure_conf2,
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'cont',
    blob_path = 'azure_table_root/**.csvwithnames'
)

   ┌─_path───────────────────────────────────────────────────────────────────────────┬─id─┬─year─┬─country─┐
1. │ cont/azure_table_root/year=2021/country=Brazil/7351307847391293440.csvwithnames │  2 │ 2021 │ Brazil  │
2. │ cont/azure_table_root/year=2020/country=Russia/7351307847378710528.csvwithnames │  1 │ 2020 │ Russia  │
   └─────────────────────────────────────────────────────────────────────────────────┴────┴──────┴─────────┘
```

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

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

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

**Пример**

Использование виртуального столбца, созданного при секционировании в стиле Hive

```sql theme={null}
SELECT * FROM azureBlobStorage(config, storage_account_url='...', container='...', blob_path='http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;
```

<div id="using-shared-access-signatures-sas-sas-tokens">
  ## Использование Shared Access Signatures (SAS)
</div>

Shared Access Signature (SAS) — это URI, который предоставляет ограниченный доступ к контейнеру или файлу в Azure Storage. Используйте его, чтобы предоставить ограниченный по времени доступ к ресурсам учётной записи хранилища, не передавая ключ этой учётной записи хранилища. Подробнее [здесь](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature).

Функция `azureBlobStorage` поддерживает Shared Access Signatures (SAS).

[Токен Blob SAS](https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/how-to-guides/create-sas-tokens?tabs=Containers) содержит всю информацию, необходимую для аутентификации запроса, включая целевой blob, разрешения и срок действия. Чтобы сформировать URL-адрес blob, добавьте токен SAS к конечной точке сервиса blob. Например, если конечная точка — `https://clickhousedocstest.blob.core.windows.net/`, запрос будет выглядеть так:

```sql theme={null}
SELECT count()
FROM azureBlobStorage('BlobEndpoint=https://clickhousedocstest.blob.core.windows.net/;SharedAccessSignature=sp=r&st=2025-01-29T14:58:11Z&se=2025-01-29T22:58:11Z&spr=https&sv=2022-11-02&sr=c&sig=Ac2U0xl4tm%2Fp7m55IilWl1yHwk%2FJG0Uk6rMVuOiD0eE%3D', 'exampledatasets', 'example.csv')

┌─count()─┐
│      10 │
└─────────┘

1 row in set. Elapsed: 0.425 sec.
```

Либо пользователи могут использовать сгенерированный [Blob SAS URL](https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/how-to-guides/create-sas-tokens?tabs=Containers):

```sql theme={null}
SELECT count()
FROM azureBlobStorage('https://clickhousedocstest.blob.core.windows.net/?sp=r&st=2025-01-29T14:58:11Z&se=2025-01-29T22:58:11Z&spr=https&sv=2022-11-02&sr=c&sig=Ac2U0xl4tm%2Fp7m55IilWl1yHwk%2FJG0Uk6rMVuOiD0eE%3D', 'exampledatasets', 'example.csv')

┌─count()─┐
│      10 │
└─────────┘

1 row in set. Elapsed: 0.153 sec.
```

<div id="related">
  ## См. также
</div>

* [Движок таблицы AzureBlobStorage](/ru/reference/engines/table-engines/integrations/azureBlobStorage)