AzureBlobStorage 表引擎

此引擎可与 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 作为文件名、文件格式作为扩展名。未显式指定策略时，包含 {_partition_id} 的路径使用 wildcard。包含其他 glob 的路径不使用分区策略，并忽略 PARTITION BY。不含 glob 的路径会在 file_like_engine_default_partition_strategy 为 hive 时使用 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://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;

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>

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

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

按月分区时，请使用 toYYYYMM(date_column) 表达式，其中 date_column 是一个类型为 Date 的日期列。这里的分区名称采用 "YYYYMM" 格式。

wildcard：将文件路径中的 {_partition_id} 通配符替换为实际的分区键。不支持读取。当路径包含 {_partition_id} 时默认选用。

未设置 partition_strategy 时，包含其他 glob 的路径不使用分区策略，并忽略 PARTITION BY。不含 glob 的路径在 file_like_engine_default_partition_strategy 为 hive 时使用 hive；否则不使用分区策略。

hive 对读写采用 hive 风格分区。读取通过递归 glob pattern 实现。写入会按以下格式生成文件：<prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>。

注意：使用 hive 分区策略时，use_hive_partitioning 设置不生效。

hive 分区策略示例：

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

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

select _path, * from azure_table;

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

Azure Blob 存储表函数