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

Этот движок обеспечивает интеграцию с экосистемой Azure Blob Storage.

Создание таблицы

CREATE TABLE azure_blob_storage_table (name String, value UInt32)
    ENGINE = AzureBlobStorage(connection_string|storage_account_url, container_name, blobpath, [account_name, account_key, format, compression, partition_strategy, partition_columns_in_data_file, extra_credentials(client_id=, tenant_id=)])
    [PARTITION BY expr]
    [SETTINGS ...]

Параметры движка

endpoint — URL конечной точки AzureBlobStorage с контейнером и префиксом. Дополнительно может содержать account_name, если это требуется используемому методу аутентификации. (http://azurite1:{port}/[account_name]{container_name}/{data_prefix}), либо эти параметры могут быть переданы отдельно с помощью storage_account_url, account_name и container. Для указания префикса должен использоваться endpoint.
endpoint_contains_account_name - флаг, указывающий, содержит ли endpoint account_name, так как это требуется только для некоторых методов аутентификации. (По умолчанию: true)
connection_string|storage_account_url — connection_string включает имя учетной записи и ключ (Create connection string), либо здесь также можно указать URL учетной записи хранилища, а имя учетной записи и ключ учетной записи передать отдельными параметрами (см. параметры account_name и account_key)
container_name - имя контейнера
blobpath - путь к файлу. Поддерживает следующие шаблоны (wildcards) в режиме только для чтения: *, **, ?, {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).
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.

Пример

Пользователи могут использовать эмулятор Azurite для локальной разработки с Azure Storage. Дополнительные сведения — здесь. При использовании локального экземпляра Azurite пользователям может потребоваться заменить http://localhost:10000 на http://azurite1:10000 в командах ниже, если предполагается, что Azurite доступен по хосту azurite1.

CREATE TABLE test_table (key UInt64, data String)
    ENGINE = AzureBlobStorage('DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite1:10000/devstoreaccount1/;', 'testcontainer', 'test_table', 'CSV');

INSERT INTO test_table VALUES (1, 'a'), (2, 'b'), (3, 'c');

SELECT * FROM test_table;

┌─key──┬─data──┐
│  1   │   a   │
│  2   │   b   │
│  3   │   c   │
└──────┴───────┘

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

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

Аутентификация

В настоящее время есть три способа аутентификации:

Managed Identity — может использоваться при указании endpoint, connection_string или storage_account_url.
SAS Token — может использоваться при указании endpoint, connection_string или storage_account_url. Определяется по наличию символа '?' в URL. См. раздел azureBlobStorage с примерами.
Workload Identity — может использоваться при указании endpoint или storage_account_url. Если параметр use_workload_identity установлен в конфигурации, для аутентификации используется механизм workload identity.

Кэш данных

Движок таблицы Azure поддерживает кэширование данных на локальном диске. Параметры конфигурации и использование кэша файловой системы описаны в этом разделе. Кэширование выполняется в зависимости от пути и ETag объекта хранилища, поэтому ClickHouse не будет читать устаревшую версию кэша.

Чтобы включить кэширование, используйте настройки filesystem_cache_name = '<name>' и enable_filesystem_cache = 1.

SELECT *
FROM azureBlobStorage('DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite1:10000/devstoreaccount1/;', 'testcontainer', 'test_table', 'CSV')
SETTINGS filesystem_cache_name = 'cache_for_azure', enable_filesystem_cache = 1;

добавьте следующий раздел в конфигурационный файл ClickHouse:

<clickhouse>
    <filesystem_caches>
        <cache_for_azure>
            <path>path to cache directory</path>
            <max_size>10Gi</max_size>
        </cache_for_azure>
    </filesystem_caches>
</clickhouse>

повторно используйте конфигурацию кеша (и, соответственно, хранилище кеша) из секции storage_configuration ClickHouse, описанной здесь

PARTITION BY

PARTITION BY — необязательный параметр. В большинстве случаев ключ партиционирования не нужен, а когда он все же требуется, обычно нет необходимости делать его более детализированным, чем по месяцам. Партиционирование не ускоряет выполнение запросов (в отличие от выражения ORDER BY). Не следует использовать слишком детализированное партиционирование. Не партиционируйте данные по идентификаторам или именам клиентов (вместо этого сделайте идентификатор или имя клиента первым столбцом в выражении ORDER BY).

Для партиционирования по месяцам используйте выражение toYYYYMM(date_column), где date_column — это столбец с датой типа Date. Имена партиций в этом случае имеют формат "YYYYMM".

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

wildcard: заменяет подстановочный шаблон {_partition_id} в пути к файлу фактическим ключом партиционирования. Чтение не поддерживается. Выбирается по умолчанию только при значении настройки compatibility ниже 26.6; в противном случае по умолчанию используется hive (см. настройку file_like_engine_default_partition_strategy).

hive реализует партиционирование в стиле Hive для операций чтения и записи. Чтение реализовано с использованием рекурсивного glob-шаблона. Запись генерирует файлы в следующем формате: <prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>.

Примечание: при использовании стратегии партиционирования hive настройка use_hive_partitioning не влияет на поведение.

Пример стратегии партиционирования hive:

arthur :) create table azure_table (year UInt16, country String, counter UInt8) ENGINE=AzureBlobStorage(account_name='devstoreaccount1', account_key='Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==', storage_account_url = 'http://localhost:30000/devstoreaccount1', container='cont', blob_path='hive_partitioned', format='Parquet', compression='auto', partition_strategy='hive') PARTITION BY (year, country);

arthur :) insert into azure_table values (2020, 'Russia', 1), (2021, 'Brazil', 2);

arthur :) select _path, * from azure_table;

   ┌─_path──────────────────────────────────────────────────────────────────────┬─year─┬─country─┬─counter─┐
1. │ cont/hive_partitioned/year=2020/country=Russia/7351305360873664512.parquet │ 2020 │ Russia  │       1 │
2. │ cont/hive_partitioned/year=2021/country=Brazil/7351305360894636032.parquet │ 2021 │ Brazil  │       2 │
   └────────────────────────────────────────────────────────────────────────────┴──────┴─────────┴─────────┘

См. также

Табличная функция Azure Blob Storage

Создание таблицы​

Параметры движка​

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

Аутентификация​

Кэш данных​

PARTITION BY​

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

См. также​