Перейти к основному содержимому
Перейти к основному содержимому

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

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

Синтаксис​

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

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

Аргументы​

АргументОписание
connection_stringСтрока подключения, включающая встроенные учетные данные (имя учетной записи + ключ учетной записи или токен SAS). При использовании этого варианта параметры account_name и account_key не должны передаваться отдельно. См. Настройка строки подключения.
storage_account_urlURL конечной точки учетной записи хранилища, например 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 в качестве имен файлов и форматом файла в качестве расширения. По умолчанию — WILDCARD.
partition_columns_in_data_fileНеобязательный параметр. Используется только со стратегией партиционирования HIVE. Указывает ClickHouse, следует ли ожидать, что столбцы партиции будут записаны в файл данных. По умолчанию — false.
extra_credentialsИспользуйте client_id и tenant_id для аутентификации. Если заданы extra_credentials, они имеют приоритет над account_name и account_key.

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

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

КлючОбязательныйОписание
containerYesИмя контейнера. Соответствует позиционному аргументу container_name.
blob_pathYesПуть к файлу (с необязательными подстановочными знаками). Соответствует позиционному аргументу blobpath.
connection_stringNo*Строка подключения со встроенными учетными данными. *Необходимо указать либо connection_string, либо storage_account_url.
storage_account_urlNo*URL конечной точки учетной записи хранилища. *Необходимо указать либо connection_string, либо storage_account_url.
account_nameNoТребуется при использовании storage_account_url.
account_keyNoТребуется при использовании storage_account_url.
formatNoФормат файла.
compressionNoТип сжатия.
structureNoСтруктура таблицы.
client_idNoИдентификатор клиента для аутентификации.
tenant_idNoИдентификатор арендатора для аутентификации.
Примечание

Имена ключей в именованной коллекции отличаются от имен позиционных аргументов функции: 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 для чтения и записи. Файлы создаются в следующем формате: <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.

В качестве альтернативы пользователи могут использовать сгенерированный URL-адрес SAS для BLOB-объекта:

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.