DeltaLake 表引擎

该引擎可与亚马逊 S3、GCS 和 Azure Blob 存储中现有的 Delta Lake 表集成，并支持读写。

该引擎可与 S3、GCP 和 Azure 存储中现有的 Delta Lake 表集成，并支持读写 (S3 和 GCS 的写入自 v25.10 起，Azure 的写入自 v26.9 起) 。

​

创建 DeltaLake 表

默认情况下，Delta Lake 表必须已存在于 S3、GCP 或 Azure 存储中，以下命令会在不提供 DDL 列定义的情况下附加到该表。设置 allow_delta_lake_create_table = 1 后，对不含 _delta_log 的位置执行带显式列定义的 CREATE TABLE 会改为通过 delta-kernel-rs 写入初始提交以创建新的 Delta Lake 表 (尚不支持创建分区表) ；而在 Unity DataLakeCatalog 数据库中，该表还会注册到目录中。

S3

语法

CREATE TABLE table_name
ENGINE = DeltaLake(url, [aws_access_key_id, aws_secret_access_key,] [extra_credentials])

引擎参数

• url — 指向现有 Delta Lake 表路径的存储桶 URL。
• aws_access_key_id, aws_secret_access_key - AWS 账户用户的长期凭证。可使用它们对请求进行身份验证。该参数为可选项。如果未指定凭证，则会从配置文件中读取。
• extra_credentials - 可选。用于传递 role_arn，以便在 ClickHouse Cloud 中实现基于角色的访问。配置步骤请参见 Secure S3。

引擎参数也可以通过 Named Collections 指定。

示例

CREATE TABLE deltalake
ENGINE = DeltaLake('http://mars-doc-test.s3.amazonaws.com/clickhouse-bucket-3/test_table/', 'ABC123', 'Abc+123')

使用命名集合：

<clickhouse>
    <named_collections>
        <deltalake_conf>
            <url>http://mars-doc-test.s3.amazonaws.com/clickhouse-bucket-3/</url>
            <access_key_id>ABC123</access_key_id>
            <secret_access_key>Abc+123</secret_access_key>
        </deltalake_conf>
    </named_collections>
</clickhouse>

CREATE TABLE deltalake
ENGINE = DeltaLake(deltalake_conf, filename = 'test_table')

GCP

语法

-- 使用 HTTPS URL（推荐）
CREATE TABLE table_name
ENGINE = DeltaLake('https://storage.googleapis.com/<bucket>/<path>/', '<access_key_id>', '<secret_access_key>')

不支持 gs://clickhouse-docs-example-bucket 这类 gsutil URI，请使用以 https://storage.googleapis.com 开头的 URL

参数

• url — 指向 Delta Lake 表的 GCS 存储桶 URL。必须使用 https://storage.googleapis.com/<bucket>/<path>/ 格式 (GCS XML API 端点) ，或使用会自动转换的 gs://<bucket>/<path>/。
• access_key_id — GCS Access Key。可通过 Google Cloud Console → Cloud Storage → Settings → Interoperability 创建。
• secret_access_key — GCS 密钥。

命名集合

您也可以使用命名集合。 例如：

CREATE NAMED COLLECTION gcs_creds AS
access_key_id = '<access_key>',
secret_access_key = '<secret>';

CREATE TABLE gcpDeltaLake
ENGINE = DeltaLake(gcs_creds, url = 'https://storage.googleapis.com/<bucket>/<path>')

Azure

语法

CREATE TABLE table_name
ENGINE = DeltaLake(connection_string|storage_account_url, container_name, blobpath, [account_name, account_key, format, compression])

参数

• connection_string — Azure 连接字符串
• storage_account_url — Azure 存储账户 URL (例如，https://account.blob.core.windows.net)
• container_name — Azure 容器名称
• blobpath — 容器内 Delta Lake 表的路径
• account_name — Azure 存储账户名称
• account_key — Azure 存储账户密钥

​

使用 DeltaLake 表写入数据

使用 DeltaLake 表引擎创建表后，可以通过以下方式向表中插入数据：

SET allow_delta_lake_writes = 1;

INSERT INTO deltalake(id, firstname, lastname, gender, age)
VALUES (1, 'John', 'Smith', 'M', 32);

Delta Lake 写入目前处于 Beta 阶段，默认禁用，必须使用 SET allow_delta_lake_writes = 1; 启用 (自版本 26.7 起可用；在更早版本中请使用 SET allow_experimental_delta_lake_writes = 1;) 。

仅支持通过 delta kernel 向该表引擎写入数据。 支持向 S3 和 GCS 写入，自版本 26.9 起也支持向 Azure 写入。 delta kernel 不支持 Azure workload identity 身份验证 (extra_credentials(client_id = ..., tenant_id = ...)) 。

​

数据缓存

DeltaLake 表引擎和表函数支持数据缓存，与 S3、AzureBlobStorage 和 HDFS 存储相同。更多详情，请参见”S3 表引擎”。

​

另请参阅

• deltaLake 表函数