Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

azureBlobStorage

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

Синтаксис

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

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

Аргументы

Аргумент Описание
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, а в качестве расширения — формат файла. Без явного указания стратегии для пути с {_partition_id} используется WILDCARD. Для пути с другим glob не используется стратегия партиционирования и игнорируется PARTITION BY. Для пути без glob используется HIVE, если значение file_like_engine_default_partition_strategy равно 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 Нет Идентификатор тенанта для аутентификации.

Пример:

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;

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

Путь, содержащий {_partition_id}, предполагает стратегию партиционирования WILDCARD. Путь с другим glob-шаблоном не использует стратегию партиционирования и игнорирует PARTITION BY. Путь без glob-шаблона использует HIVE, если file_like_engine_default_partition_strategy имеет значение HIVE; в противном случае стратегия партиционирования не используется.

INSERT INTO TABLE FUNCTION azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_{_partition_id}.csv',
    'CSV',
    'auto',
    'wildcard',
    '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} в пути к файлу на фактический ключ партиционирования. По умолчанию выбирается, когда путь содержит {_partition_id}.

Если partition_strategy не задана, путь с другим glob не использует стратегию партиционирования и игнорирует PARTITION BY. Путь без glob использует HIVE, если file_like_engine_default_partition_strategy имеет значение HIVE; в противном случае стратегия партиционирования не используется.

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

┌

Либо пользователи могут использовать сгенерированный 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')

┌
Navigation