AzureBlobStorage 表引擎 - ClickHouse Documentation

此引擎可与 Azure Blob 存储生态系统集成。

创建表

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 — 带有 container 和 prefix 的 AzureBlobStorage 端点 URL。也可选择包含 account_name (如果所使用的身份验证方法需要) 。 (http://azurite1:{port}/[account_name]{container_name}/{data_prefix}) 这些参数也可以通过 storage_account_url、account_name 和 container 分别提供。若要指定 prefix，应使用 endpoint。
endpoint_contains_account_name - 此标志用于指定 endpoint 是否包含 account_name，因为只有某些身份验证方法才需要它。 (默认值：true)
connection_string|storage_account_url — connection_string 包含 account name 和 key (Create connection string) ；你也可以在此提供 storage account url，并将 account name 和 account key 作为单独参数提供 (参见参数 account_name 和 account_key)
container_name - Container 名称
blobpath - 文件路径。在 readonly 模式下支持以下通配符：*、**、?、{abc,def} 和 {N..M}，其中 N、M 表示数字，'abc'、'def' 表示字符串。
account_name - 如果使用了 storage_account_url，则可在此指定 account name
account_key - 如果使用了 storage_account_url，则可在此指定 account key
format — 文件的 format。
compression — 支持的值：none、gzip/gz、brotli/br、xz/LZMA、zstd/zst。默认会根据文件扩展名自动检测压缩方式。 (等同于设置为 auto) 。
partition_strategy – 可选值：WILDCARD 或 HIVE。WILDCARD 要求路径中包含 {_partition_id}，其会被替换为分区键。HIVE 不允许使用通配符，假定该路径为表根目录，并生成 Hive 风格的分区目录，以 Snowflake ID 作为文件名、文件格式作为扩展名。默认为 WILDCARD
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://azurite1:10000 替换为 http://localhost: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。

身份验证

目前有 3 种身份验证方式：

Managed Identity - 可通过提供 endpoint、connection_string 或 storage_account_url 使用。
SAS Token - 可通过提供 endpoint、connection_string 或 storage_account_url 使用。可通过 URL 中是否包含 ? 来识别。示例请参见 azureBlobStorage。
Workload Identity - 可通过提供 endpoint 或 storage_account_url 使用。如果在 config 中设置了 use_workload_identity 参数，则会使用 workload identity 进行身份验证。

数据缓存

Azure 表引擎支持将数据缓存到本地磁盘。有关文件系统缓存的配置选项和用法，请参见此章节。缓存依据存储对象的 path 和 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>

复用 ClickHouse storage_configuration 部分中的缓存配置 (以及相应的缓存存储) ，此处有详细说明

PARTITION BY

PARTITION BY —— 可选。在大多数情况下，你不需要分区键；即使需要，通常也不需要比按月分区更细的粒度。分区不会加快查询速度 (这与 ORDER BY 表达式不同) 。绝不要使用粒度过细的分区方式。不要按客户端标识符或名称对数据进行分区 (而应将客户端标识符或名称作为 ORDER BY 表达式中的第一列) 。按月分区时，请使用 toYYYYMM(date_column) 表达式，其中 date_column 是一个类型为 Date 的日期列。这里的分区名称采用 "YYYYMM" 格式。

分区策略

WILDCARD (默认) ：将文件路径中的 {_partition_id} 通配符替换为实际的分区键。不支持读取。 HIVE 对读写采用 hive style partitioning。读取通过递归 glob pattern 实现。写入会按以下格式生成文件：<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 存储表函数

​创建表

​引擎参数

​虚拟列

​身份验证

​数据缓存

​PARTITION BY

​分区策略

​另请参见

创建表