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

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

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

Синтаксис​

azureBlobStorage(- connection_string|storage_account_url, container_name, blobpath, [account_name, account_key, format, compression, structure, partition_strategy, partition_columns_in_data_file, extra_credentials(client_id=, tenant_id=)])

Аргументы​

АргументОписание
connection_string| storage_account_urlconnection_string включает имя и ключ учетной записи (Create connection string), либо вы можете указать здесь URL учетной записи хранилища, а имя учетной записи и ключ учетной записи — как отдельные параметры (см. параметры account_name и account_key)
container_nameИмя контейнера
blobpathПуть к файлу. Поддерживает следующие подстановочные шаблоны в режиме только для чтения: *, **, ?, {abc,def} и {N..M}, где N, M — числа, 'abc', 'def' — строки.
account_nameЕсли используется storage_account_url, то здесь может быть указано имя учетной записи
account_keyЕсли используется storage_account_url, то здесь может быть указан ключ учетной записи
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.

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

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

Примеры​

Аналогично движку таблиц AzureBlobStorage, пользователи могут использовать эмулятор Azurite для локальной разработки с использованием Azure Storage. Дополнительные сведения см. здесь. Ниже предполагается, что Azurite доступен по имени хоста azurite1.

Запишите данные в хранилище Azure Blob, используя следующее:

INSERT INTO TABLE FUNCTION azureBlobStorage('http://azurite1:10000/devstoreaccount1',
    'testcontainer', 'test_{_partition_id}.csv', 'devstoreaccount1', 'Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==',
    'CSV', 'auto', 'column1 UInt32, column2 UInt32, column3 UInt32') PARTITION BY column3 VALUES (1, 2, 3), (3, 2, 1), (78, 43, 3);

Затем его можно прочитать с помощью

SELECT * FROM azureBlobStorage('http://azurite1:10000/devstoreaccount1',
    'testcontainer', 'test_1.csv', 'devstoreaccount1', 'Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==',
    'CSV', 'auto', 'column1 UInt32, column2 UInt32, column3 UInt32');

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

или с использованием строки подключения

SELECT count(*) FROM azureBlobStorage('DefaultEndpointsProtocol=https;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;EndPointSuffix=core.windows.net',
    'testcontainer', 'test_3.csv', 'CSV', 'auto' , 'column1 UInt32, column2 UInt32, column3 UInt32');

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

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

  • _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 = 'http://localhost:30000/devstoreaccount1', 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, 'Россия', 1), (2021, 'Бразилия', 2);

select _path, * from azureBlobStorage(azure_conf2, storage_account_url = 'http://localhost:30000/devstoreaccount1', 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 строка. Затрачено: 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 строка. Прошло: 0,153 сек.