azureBlobStorage

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

​

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

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

​

Синтаксис

Строка подключения

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

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

URL учетной записи хранилища

Требует указания 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, а в качестве расширения — формат файла. По умолчанию используется настройка file_like_engine_default_partition_strategy (WILDCARD при настройках compatibility старше 26.6, иначе HIVE).
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} в пути к файлу на фактический ключ партиционирования. Выбирается по умолчанию только при значениях compatibility ниже 26.6; в противном случае по умолчанию используется HIVE (см. настройку file_like_engine_default_partition_strategy).

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