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

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

Синтаксис

Строка подключения
URL учетной записи хранилища
Именованная коллекция

Учетные данные встроены в строку подключения, поэтому отдельно указывать account_name/account_key не требуется:

azureBlobStorage(connection_string, container_name, blobpath [, format, compression, structure])

Требует указания account_name и account_key в качестве отдельных аргументов:

azureBlobStorage(storage_account_url, container_name, blobpath, account_name, account_key [, format, compression, structure])

Полный список поддерживаемых ключей см. ниже в разделе Именованные коллекции:

azureBlobStorage(named_collection[, option=value [,..]])

Аргументы

Аргумент	Описание
`connection_string`	Строка подключения, включающая встроенные учетные данные (имя учетной записи + ключ учетной записи или SAS-токен). При использовании этой формы `account_name` и `account_key` не следует передавать отдельно. См. Настройка строки подключения.
`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`	Формат файла.
`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`.

Именованные коллекции

Аргументы также можно передавать с помощью именованных коллекций. В этом случае поддерживаются следующие ключи:

Ключ	Обязательно	Описание
`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`	Нет	Идентификатор тенанта для аутентификации.

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

Пример:

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;

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

SELECT *
FROM azureBlobStorage(azure_my_data, blob_path = 'other_data/*.csv', format = 'CSVWithNames')
LIMIT 5;

Возвращаемое значение

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

Примеры

Чтение с использованием `storage_account_url`

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

Чтение с использованием варианта `connection_string`

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

Запись с партиционированием

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

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

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'
);

┌─column1─┬─column2─┬─column3─┐
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

Виртуальные столбцы

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

Запись с разбиением на партиции

Стратегия партиционирования

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

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

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  │
   └─────────────────────────────────────────────────────────────────────────────────┴────┴──────┴─────────┘

настройка use_hive_partitioning

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

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;

Использование Shared Access Signatures (SAS)

Shared Access Signature (SAS) — это URI, который предоставляет ограниченный доступ к контейнеру или файлу в Azure Storage. Используйте его, чтобы предоставить ограниченный по времени доступ к ресурсам учётной записи хранилища, не передавая ключ этой учётной записи хранилища. Подробнее здесь. Функция azureBlobStorage поддерживает Shared Access Signatures (SAS). Токен Blob SAS содержит всю информацию, необходимую для аутентификации запроса, включая целевой blob, разрешения и срок действия. Чтобы сформировать URL-адрес blob, добавьте токен SAS к конечной точке сервиса blob. Например, если конечная точка — https://clickhousedocstest.blob.core.windows.net/, запрос будет выглядеть так:

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:

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.

Движок таблицы AzureBlobStorage

​Синтаксис

​Аргументы

​Именованные коллекции

​Возвращаемое значение

​Примеры

​Чтение с использованием storage_account_url

​Чтение с использованием варианта connection_string

​Запись с партиционированием

​Виртуальные столбцы

​Запись с разбиением на партиции

​Стратегия партиционирования

​настройка use_hive_partitioning

​Использование Shared Access Signatures (SAS)

​См. также

Синтаксис

Аргументы

Именованные коллекции

Возвращаемое значение

Примеры

Чтение с использованием `storage_account_url`

Чтение с использованием варианта `connection_string`

Запись с партиционированием

Виртуальные столбцы

Запись с разбиением на партиции

Стратегия партиционирования

настройка use_hive_partitioning

Использование Shared Access Signatures (SAS)

См. также