用于存储数据的外部磁盘 - ClickHouse Documentation

ClickHouse 处理的数据通常存储在运行 ClickHouse server 的机器的本地文件系统中。这需要大容量磁盘，成本可能较高。为了避免将数据存储在本地，支持以下几种存储选项：

Amazon S3 对象存储。
Azure Blob 存储。
不支持：Hadoop Distributed File System (HDFS)

ClickHouse 还支持外部表引擎，它们与本页介绍的外部存储选项不同，因为前者允许读取以通用文件格式 (如 Parquet) 存储的数据。本页介绍的是 ClickHouse MergeTree 家族或 Log 家族表的存储配置。

如需处理存储在 Amazon S3 磁盘上的数据，请使用 S3 表引擎。
如需处理存储在 Azure Blob 存储中的数据，请使用 AzureBlobStorage 表引擎。
如需处理 Hadoop Distributed File System (不支持) 中的数据，请使用 HDFS 表引擎。

配置外部存储

MergeTree 和 Log 家族的表引擎可分别通过类型为 s3、azure_blob_storage、hdfs (不支持) 的磁盘，将数据存储到 S3、AzureBlobStorage、HDFS (不支持) 中。磁盘配置需要：

一个 type 配置项，其值必须是 s3、azure_blob_storage、hdfs (不支持) 、local_blob_storage、web 之一。
针对具体外部存储类型的配置。

从 ClickHouse 24.1 版本开始，可以使用新的配置选项。这需要指定：

值为 object_storage 的 type
object_storage_type，其值必须是 s3、azure_blob_storage (或从 24.3 起简写为 azure) 、hdfs (不支持) 、local_blob_storage (或从 24.3 起简写为 local) 、web 之一。

此外，还可以指定 metadata_type (默认值为 local) ，也可将其设置为 plain、web，以及从 24.4 开始支持的 plain_rewritable。 plain 元数据类型的用法见plain storage 部分；web 元数据类型只能与 web 对象存储类型一起使用；local 元数据类型会将元数据文件存储在本地 (每个元数据文件都包含对象存储中文件的映射，以及与这些文件相关的一些附加元信息) 。例如：

<s3>
    <type>s3</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3>

等同于以下配置 (从版本 24.1 开始) ：

<s3>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>local</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3>

如下配置：

<s3_plain>
    <type>s3_plain</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

等于：

<s3_plain>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>plain</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

完整的存储配置示例如下：

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
                <use_environment_credentials>1</use_environment_credentials>
            </s3>
        </disks>
        <policies>
            <s3>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3>
        </policies>
    </storage_configuration>
</clickhouse>

从 24.1 版本开始，其形式也可以如下：

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>object_storage</type>
                <object_storage_type>s3</object_storage_type>
                <metadata_type>local</metadata_type>
                <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
                <use_environment_credentials>1</use_environment_credentials>
            </s3>
        </disks>
        <policies>
            <s3>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3>
        </policies>
    </storage_configuration>
</clickhouse>

要将某种特定的存储设为所有 MergeTree 表的默认选项，请在配置文件中添加以下部分：

<clickhouse>
    <merge_tree>
        <storage_policy>s3</storage_policy>
    </merge_tree>
</clickhouse>

如果你想为特定表配置特定的存储策略，可以在创建该表时在 settings 中进行定义：

CREATE TABLE test (a Int32, b String)
ENGINE = MergeTree() ORDER BY a
SETTINGS storage_policy = 's3';

你也可以用 disk 替代 storage_policy。在这种情况下，配置文件中无需包含 storage_policy 部分，只需有一个 disk 部分即可。

CREATE TABLE test (a Int32, b String)
ENGINE = MergeTree() ORDER BY a
SETTINGS disk = 's3';

refresh_parts_interval 和 table_disk

此设置适用于非 Replicated 的 MergeTree 表。在这类表中，parts 可能由外部写入，因此需要从存储中刷新元数据以重新发现这些 parts。 MergeTree 设置 refresh_parts_interval 可定期从底层存储刷新数据分区片段列表 (例如发现外部写入的 parts) 。这里的关键区别在于跨副本共享元数据与副本本地元数据 (例如每个副本各自维护本地元数据的 S3) ：只有在元数据共享时，新的 parts 才会对所有副本可见。仅使用对象存储本身并不意味着元数据是共享的。

对象存储 (例如 disk = 's3') 并不意味着元数据是共享的。 当元数据默认按副本存储在本地时，每个副本都会独立管理自己指向对象存储中 blob 的指针。在一个副本上所做的更改，对其他副本不可见。在这种情况下，refresh_parts_interval 不会让新的 parts 在副本之间变得可见，因为每个副本读取的都是各自的本地元数据。
自动刷新 parts 要求 filesystem 元数据是共享的 (或者表使用表自有的只读元数据，从而能够进行刷新) 。将 table_disk = true 与表本地磁盘一起使用 (例如 SETTINGS disk = disk(type=object_storage, ...), table_disk = true) 是获得正确语义的一种方式：表负责元数据的生命周期管理，存储会被视为只读，因此会执行 refresh_parts_interval，并且能够发现外部新增的 parts。
使用全局定义的磁盘时 (例如在 storage_configuration 中设置 disk = 's3') ，如果采用默认的本地元数据，则每个副本都有自己的元数据状态。即使 blob 可能位于 S3 中，就 refresh_parts_interval 而言，该存储也不被视为共享存储，因此在 ClickHouse 外部或在另一个副本上创建的新的 parts 都不会被检测到。

若要自动刷新 parts，请确保元数据是共享的，或按上述方式使用带有 table_disk = true 的表级磁盘。如果在元数据为副本本地的情况下仅依赖 refresh_parts_interval，则 parts 不会按预期刷新。

refresh_parts_interval 不用于 ReplicatedMergeTree 表。复制表已经通过复制机制同步 parts。此设置仅适用于 parts 由外部写入且需要刷新元数据的非复制表 MergeTree 表。

动态配置

也可以在配置文件中不预先定义磁盘，直接指定存储配置，而是在 CREATE/ATTACH 查询设置中进行配置。以下示例查询基于上述动态磁盘配置，展示了如何使用本地磁盘缓存存储在 URL 上的表数据。

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
    type=web,
    endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
  );

下面的示例将为外部存储添加缓存。

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
    type=cache,
    max_size='1Gi',
    path='/var/lib/clickhouse/custom_disk_cache/',
    disk=disk(
      type=web,
      endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
      )
  );

在下方高亮显示的设置中，请注意，type=web 的磁盘嵌套在 type=cache 的磁盘内。

此示例使用了 type=web，但任何磁盘类型都可以配置为动态磁盘，包括本地磁盘。本地磁盘要求其 path 参数位于 server 配置参数 custom_local_disks_base_directory 中。该参数没有默认值，因此使用本地磁盘时也需要设置它。

也可以将基于配置文件的配置与通过 SQL 定义的配置结合使用：

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
    type=cache,
    max_size='1Gi',
    path='/var/lib/clickhouse/custom_disk_cache/',
    disk=disk(
      type=web,
      endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
      )
  );

其中，web 来自服务端配置文件：

<storage_configuration>
    <disks>
        <web>
            <type>web</type>
            <endpoint>'https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'</endpoint>
        </web>
    </disks>
</storage_configuration>

使用 S3 存储

必需参数

参数	说明
`endpoint`	采用 `path` 或 `virtual hosted` 样式的 S3 端点 URL。应包含存储数据所用的存储桶和根路径。
`access_key_id`	用于身份验证的 S3 访问密钥 ID。
`secret_access_key`	用于身份验证的 S3 私密访问密钥。

可选参数

Parameter	Description	Default Value
`region`	S3 区域名称。	-
`support_batch_delete`	控制是否检查对批量删除的支持。使用 Google Cloud Storage (GCS) 时，请将其设为 `false`，因为 GCS 不支持批量删除。	`true`
`use_environment_credentials`	如果存在，则从环境变量 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 中读取 AWS 凭证。注意：环境凭证会在所有 S3 磁盘之间共享。若要为不同磁盘使用不同的凭证，请改为为每个磁盘显式指定 `access_key_id` 和 `secret_access_key`。	`false`
`use_insecure_imds_request`	如果为 `true`，则在从 Amazon EC2 元数据获取凭证时使用不安全的 IMDS 请求。	`false`
`expiration_window_seconds`	检查基于过期时间的凭证是否已过期时使用的宽限期 (秒) 。	`120`
`proxy`	S3 端点的代理配置。`proxy` 块中的每个 `uri` 元素都应包含一个代理 URL。	-
`connect_timeout_ms`	套接字连接超时时间 (毫秒) 。	`10000` (10 秒)
`request_timeout_ms`	请求超时时间 (毫秒) 。	`5000` (5 秒)
`retry_attempts`	失败请求的重试次数。	`10`
`single_read_retries`	读取过程中连接中断时的重试次数。	`4`
`min_bytes_for_seek`	使用寻道操作而不是顺序读取时的最小字节数。	`1 MB`
`metadata_path`	用于存储 S3 元数据文件的本地文件系统路径。	`/var/lib/clickhouse/disks/<disk_name>/`
`skip_access_check`	如果为 `true`，则在启动期间跳过磁盘访问检查。	`false`
`header`	向请求中添加指定的 HTTP 请求头。可多次指定。	-
`server_side_encryption_customer_key_base64`	访问使用 SSE-C 加密的 S3 对象所需的请求头。	-
`server_side_encryption_kms_key_id`	访问使用 SSE-KMS encryption 的 S3 对象所需的请求头。空字符串表示使用 AWS 托管的 S3 密钥。	-
`server_side_encryption_kms_encryption_context`	SSE-KMS 的加密上下文请求头 (与 `server_side_encryption_kms_key_id` 一起使用) 。	-
`server_side_encryption_kms_bucket_key_enabled`	为 SSE-KMS 启用 S3 bucket key (与 `server_side_encryption_kms_key_id` 一起使用) 。	与 bucket 级设置一致
`s3_max_put_rps`	开始限流前每秒允许的最大 PUT 请求数。	`0` (无限制)
`s3_max_put_burst`	达到 RPS 限制前允许的最大并发 PUT 请求数。	与 `s3_max_put_rps` 相同
`s3_max_get_rps`	开始限流前每秒允许的最大 GET 请求数。	`0` (无限制)
`s3_max_get_burst`	达到 RPS 限制前允许的最大并发 GET 请求数。	与 `s3_max_get_rps` 相同
`read_resource`	调度读取请求使用的资源名称。	空字符串 (已禁用)
`write_resource`	调度写入请求使用的资源名称。	空字符串 (已禁用)
`key_template`	使用 re2 语法定义对象键的生成格式。要求启用 `storage_metadata_write_full_object_key` 标志。与 `endpoint` 中的 `root path` 不兼容。需要指定 `key_compatibility_prefix`。	-
`key_compatibility_prefix`	与 `key_template` 配合使用时必需。用于指定 `endpoint` 中先前的 `root path`，以便读取旧版本元数据。	-
`read_only`	仅允许从该磁盘读取。	-

也支持通过 s3 类型使用 Google Cloud Storage (GCS)。请参阅基于 GCS 的 MergeTree。

使用 Plain Storage

在 22.10 版本中，引入了一种新的磁盘类型 s3_plain，可提供一次写入型存储。它的配置参数与 s3 磁盘类型相同。与 s3 磁盘类型不同，它会原样存储数据。换句话说，它不会使用随机生成的 blob 名称，而是使用普通文件名 (与 ClickHouse 在本地磁盘上存储文件的方式相同) ，并且不会在本地存储任何元数据。例如，这些元数据可根据 s3 上的数据推导出来。这种磁盘类型可用于保留表的静态版本，因为它不允许对现有数据执行 merge，也不允许插入新数据。该磁盘类型的一个典型用法是基于它创建 backups，这可以通过 BACKUP TABLE data TO Disk('plain_disk_name', 'backup_name') 来完成。之后，你可以执行 RESTORE TABLE data AS data_restored FROM Disk('plain_disk_name', 'backup_name') 或使用 ATTACH TABLE data (...) ENGINE = MergeTree() SETTINGS disk = 'plain_disk_name'。配置：

<s3_plain>
    <type>s3_plain</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

从 24.1 起，可以使用 plain 元数据类型配置任何对象存储磁盘 (s3、azure、hdfs (不支持) 、local) 。配置：

<s3_plain>
    <type>object_storage</type>
    <object_storage_type>azure</object_storage_type>
    <metadata_type>plain</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

使用 S3 Plain Rewritable 存储

24.4 中引入了一种新的磁盘类型 s3_plain_rewritable。与 s3_plain 磁盘类型类似，它不需要额外的存储空间来保存元数据文件，而是将元数据存储在 S3 中。不同于 s3_plain 磁盘类型，s3_plain_rewritable 允许执行合并，并支持 INSERT 操作。不支持变更和表的复制。这种磁盘类型的一个适用场景是非复制的 MergeTree 表。虽然 s3 磁盘类型也适用于非复制的 MergeTree 表，但如果你不需要该表的本地元数据，并且可以接受受限的操作集，则可以选择 s3_plain_rewritable 磁盘类型。例如，它对系统表就可能很有用。配置：

<s3_plain_rewritable>
    <type>s3_plain_rewritable</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain_rewritable>

等于

<s3_plain_rewritable>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>plain_rewritable</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain_rewritable>

自 24.5 起，可以使用 plain_rewritable 元数据类型来配置任何对象存储磁盘 (s3、azure、local) 。

使用 Azure Blob 存储

MergeTree 家族表引擎可使用类型为 azure_blob_storage 的磁盘将数据存储到 Azure Blob 存储中。配置示例：

<storage_configuration>
    ...
    <disks>
        <blob_storage_disk>
            <type>azure_blob_storage</type>
            <storage_account_url>http://account.blob.core.windows.net</storage_account_url>
            <container_name>container</container_name>
            <account_name>account</account_name>
            <account_key>pass123</account_key>
            <metadata_path>/var/lib/clickhouse/disks/blob_storage_disk/</metadata_path>
            <cache_path>/var/lib/clickhouse/disks/blob_storage_disk/cache/</cache_path>
            <skip_access_check>false</skip_access_check>
        </blob_storage_disk>
    </disks>
    ...
</storage_configuration>

连接参数

参数	描述	默认值
`storage_account_url` (必填)	Azure Blob 存储账户 URL。示例：`http://account.blob.core.windows.net` 或 `http://azurite1:10000/devstoreaccount1`。	-
`container_name`	目标容器名称。	`default-container`
`container_already_exists`	控制容器创建行为： - `false`：创建新容器 - `true`：直接连接到现有容器 - 未设置：检查容器是否存在，并在需要时创建	-

身份验证参数 (磁盘会尝试所有可用方法以及 Managed Identity Credential) ：

参数	描述
`connection_string`	用于通过连接字符串进行身份验证。
`account_name`	用于通过 Shared Key 进行身份验证 (与 `account_key` 配合使用) 。
`account_key`	用于通过 Shared Key 进行身份验证 (与 `account_name` 配合使用) 。

限制参数

参数	描述
`s3_max_single_part_upload_size`	上传到 Blob Storage 的单个块的最大大小。
`min_bytes_for_seek`	可寻道区域的最小大小。
`max_single_read_retries`	从 Blob Storage 读取一个数据块的最大重试次数。
`max_single_download_retries`	从 Blob Storage 下载可读缓冲区的最大重试次数。
`thread_pool_size`	用于实例化 `IDiskRemote` 的最大线程数。
`s3_max_inflight_parts_for_one_file`	单个对象的并发 PUT 请求最大数量。

其他参数

Parameter	Description	Default Value
`metadata_path`	用于存储 Blob Storage 元数据文件的本地文件系统路径。	`/var/lib/clickhouse/disks/<disk_name>/`
`skip_access_check`	如果为 `true`，则在启动时跳过磁盘访问检查。	`false`
`read_resource`	用于调度读取请求的资源名称。	空字符串 (已禁用)
`write_resource`	用于调度写入请求的资源名称。	空字符串 (已禁用)
`metadata_keep_free_space_bytes`	为元数据磁盘预留的可用空间大小。	-

可在集成测试目录中找到可用的配置示例 (例如，test_merge_tree_azure_blob_storage 或 test_azure_blob_storage_zero_copy_replication) 。

零拷贝复制尚不能用于生产环境在 ClickHouse 22.8 及更高版本中，零拷贝复制默认处于禁用状态。不建议在生产环境中使用此功能。

使用 HDFS 存储 (不支持)

在此示例配置中：

磁盘类型为 hdfs (不支持)
数据存储在 hdfs://hdfs1:9000/clickhouse/

顺便说明一下，HDFS 目前不受支持，因此使用时可能会遇到一些问题。如果出现任何问题，欢迎提交修复的拉取请求。

<clickhouse>
    <storage_configuration>
        <disks>
            <hdfs>
                <type>hdfs</type>
                <endpoint>hdfs://hdfs1:9000/clickhouse/</endpoint>
                <skip_access_check>true</skip_access_check>
            </hdfs>
            <hdd>
                <type>local</type>
                <path>/</path>
            </hdd>
        </disks>
        <policies>
            <hdfs>
                <volumes>
                    <main>
                        <disk>hdfs</disk>
                    </main>
                    <external>
                        <disk>hdd</disk>
                    </external>
                </volumes>
            </hdfs>
        </policies>
    </storage_configuration>
</clickhouse>

请注意，HDFS 在某些特殊情况下可能无法正常工作。

使用数据加密

你可以对存储在 S3、HDFS (不受支持) 的外部磁盘或本地磁盘上的数据进行加密。要启用加密模式，必须在配置文件中定义一个类型为 encrypted 的磁盘，并选择一个用于保存数据的底层磁盘。encrypted 磁盘会在写入时即时加密所有文件，而从 encrypted 磁盘读取文件时则会自动解密。因此，你可以像使用普通磁盘一样使用 encrypted 磁盘。磁盘配置示例：

<disks>
  <disk1>
    <type>local</type>
    <path>/path1/</path>
  </disk1>
  <disk2>
    <type>encrypted</type>
    <disk>disk1</disk>
    <path>path2/</path>
    <key>_16_ascii_chars_</key>
  </disk2>
</disks>

例如，当 ClickHouse 将某个表中的数据写入 disk1 上的文件 store/all_1_1_0/data.bin 时，实际上该文件会写入物理磁盘上的 /path1/store/all_1_1_0/data.bin 路径。将同一文件写入 disk2 时，实际上它会以加密方式写入物理磁盘上的 /path1/path2/store/all_1_1_0/data.bin 路径。

必需参数

Parameter	Type	Description
`type`	String	必须设置为 `encrypted`，以创建加密磁盘。
`disk`	String	用于底层存储的磁盘类型。
`key`	Uint64	用于加密和解密的密钥。可通过 `key_hex` 以十六进制形式指定。也可使用 `id` 属性指定多个密钥。

可选参数

参数	类型	默认值	描述
`path`	String	根目录	数据在磁盘上的保存位置。
`current_key_id`	String	-	用于加密的密钥 ID。所有指定的密钥均可用于解密。
`algorithm`	枚举	`AES_128_CTR`	加密算法。可选值： - `AES_128_CTR` (16 字节密钥) - `AES_192_CTR` (24 字节密钥) - `AES_256_CTR` (32 字节密钥)

磁盘配置示例：

<clickhouse>
    <storage_configuration>
        <disks>
            <disk_s3>
                <type>s3</type>
                <endpoint>...
            </disk_s3>
            <disk_s3_encrypted>
                <type>encrypted</type>
                <disk>disk_s3</disk>
                <algorithm>AES_128_CTR</algorithm>
                <key_hex id="0">00112233445566778899aabbccddeeff</key_hex>
                <key_hex id="1">ffeeddccbbaa99887766554433221100</key_hex>
                <current_key_id>1</current_key_id>
            </disk_s3_encrypted>
        </disks>
    </storage_configuration>
</clickhouse>

使用本地缓存

从 22.3 版本开始，可以在存储配置中为磁盘配置本地缓存。对于 22.3 - 22.7 版本，仅 s3 磁盘类型支持缓存。对于 >= 22.8 版本，所有磁盘类型都支持缓存：S3、Azure、Local、Encrypted 等。对于 >= 23.5 版本，仅远程磁盘类型支持缓存：S3、Azure、HDFS (不支持) 。缓存使用 LRU 缓存策略。 22.8 及以上版本的配置示例：

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>...</endpoint>
                ... s3 configuration ...
            </s3>
            <cache>
                <type>cache</type>
                <disk>s3</disk>
                <path>/s3_cache/</path>
                <max_size>10Gi</max_size>
            </cache>
        </disks>
        <policies>
            <s3_cache>
                <volumes>
                    <main>
                        <disk>cache</disk>
                    </main>
                </volumes>
            </s3_cache>
        <policies>
    </storage_configuration>

22.8 之前版本的配置示例：

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>...</endpoint>
                ... s3 configuration ...
                <data_cache_enabled>1</data_cache_enabled>
                <data_cache_max_size>10737418240</data_cache_max_size>
            </s3>
        </disks>
        <policies>
            <s3_cache>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3_cache>
        <policies>
    </storage_configuration>

File Cache 磁盘配置设置：这些设置应在磁盘配置部分中定义。

Parameter	Type	Default	Description
`path`	String	-	必填。用于存储缓存的目录路径。
`max_size`	Size	-	必填。缓存的最大大小，单位可以是字节或可读格式 (例如 `10Gi`) 。达到限制时，文件会按 LRU 策略被逐出。支持 `ki`、`Mi`、`Gi` 格式 (自 v22.10 起) 。
`cache_on_write_operations`	Boolean	`false`	为 `INSERT` 查询和后台合并启用直写缓存。可通过 `enable_filesystem_cache_on_write_operations` 按查询覆盖。
`enable_filesystem_query_cache_limit`	Boolean	`false`	基于 `max_query_cache_size` 启用按查询的缓存大小限制。
`enable_cache_hits_threshold`	Boolean	`false`	启用后，数据仅在被读取多次后才会被缓存。
`cache_hits_threshold`	Integer	`0`	数据被缓存前所需的读取次数 (需要 `enable_cache_hits_threshold`) 。
`enable_bypass_cache_with_threshold`	Boolean	`false`	对较大的读取范围跳过缓存。
`bypass_cache_threshold`	Size	`256Mi`	触发绕过缓存的读取范围大小 (需要 `enable_bypass_cache_with_threshold`) 。
`max_file_segment_size`	Size	`8Mi`	单个缓存文件段的最大大小，单位可以是字节或可读格式。
`max_elements`	Integer	`10000000`	缓存文件的最大数量。
`load_metadata_threads`	Integer	`16`	启动时用于加载缓存元数据的线程数。
`use_split_cache`	Boolean	`false`	将文件拆分为 system/data 两类。
`split_cache_ratio`	Double	`0.1`	`split_cache` 中 system 部分占缓存总大小的比例。

注意：Size 值支持 ki、Mi、Gi 等单位 (例如 10Gi) 。

File Cache 查询/profile 设置

Setting	Type	Default	Description
`enable_filesystem_cache`	Boolean	`true`	按查询启用/禁用缓存，即使使用的是 `cache` 磁盘类型也是如此。
`read_from_filesystem_cache_if_exists_otherwise_bypass_cache`	Boolean	`false`	启用后，仅当数据已存在于缓存中时才使用缓存；新数据不会被缓存。
`enable_filesystem_cache_on_write_operations`	Boolean	`false` (Cloud: `true`)	启用写穿缓存。要求在缓存配置中启用 `cache_on_write_operations`。
`enable_filesystem_cache_log`	Boolean	`false`	启用详细的缓存使用日志，并将其写入 `system.filesystem_cache_log`。
`filesystem_cache_allow_background_download`	Boolean	`true`	允许在后台完成部分已下载分段的剩余下载。禁用后，当前查询/session 的下载会保持在前台执行。
`max_query_cache_size`	Size	`false`	每个查询的最大缓存大小。要求在缓存配置中启用 `enable_filesystem_query_cache_limit`。
`filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit`	Boolean	`true`	控制达到 `max_query_cache_size` 时的行为： - `true`：停止下载新数据 - `false`：淘汰旧数据，为新数据腾出空间

缓存配置设置和缓存查询设置对应的是最新版本的 ClickHouse，较早版本可能不支持其中某些功能。

缓存相关系统表

Table Name	Description	Requirements
`system.filesystem_cache`	显示文件系统缓存的当前状态。	无
`system.filesystem_cache_log`	提供每个查询的详细缓存使用统计信息。	需要 `enable_filesystem_cache_log = true`

缓存命令

`SYSTEM CLEAR|DROP FILESYSTEM CACHE (<cache_name>) (ON CLUSTER)` — `ON CLUSTER`

仅当未提供 <cache_name> 时，才支持此命令

`SHOW FILESYSTEM CACHES`

显示 server 上已配置的文件系统缓存列表。 (对于小于或等于 22.8 的版本，该命令名为 SHOW CACHES)

Query

SHOW FILESYSTEM CACHES

Response

┌─Caches────┐
│ s3_cache  │
└───────────┘

`DESCRIBE FILESYSTEM CACHE '<cache_name>'`

显示指定缓存的配置及一些常规统计信息。缓存名称可通过 SHOW FILESYSTEM CACHES 命令获取。 (在小于或等于 22.8 的版本中，该命令名为 DESCRIBE CACHE)

Query

DESCRIBE FILESYSTEM CACHE 's3_cache'

Response

┌────max_size─┬─max_elements─┬─max_file_segment_size─┬─boundary_alignment─┬─cache_on_write_operations─┬─cache_hits_threshold─┬─current_size─┬─current_elements─┬─path───────┬─background_download_threads─┬─enable_bypass_cache_with_threshold─┐
│ 10000000000 │      1048576 │             104857600 │            4194304 │                         1 │                    0 │         3276 │               54 │ /s3_cache/ │                           2 │                                  0 │
└─────────────┴──────────────┴───────────────────────┴────────────────────┴───────────────────────────┴──────────────────────┴──────────────┴──────────────────┴────────────┴─────────────────────────────┴────────────────────────────────────┘

缓存当前状态指标	缓存异步指标	缓存 profile events
`FilesystemCacheSize`	`FilesystemCacheBytes`	`CachedReadBufferReadFromSourceBytes`, `CachedReadBufferReadFromCacheBytes`
`FilesystemCacheElements`	`FilesystemCacheFiles`	`CachedReadBufferReadFromSourceMicroseconds`, `CachedReadBufferReadFromCacheMicroseconds`
		`CachedReadBufferCacheWriteBytes`, `CachedReadBufferCacheWriteMicroseconds`
		`CachedWriteBufferCacheWriteBytes`, `CachedWriteBufferCacheWriteMicroseconds`

使用静态 Web 存储 (只读)

这是一个只读磁盘。其数据只能读取，不能修改。新表通过 ATTACH TABLE 查询加载到该磁盘 (见下方示例) 。本地磁盘实际上不会被使用，每个 SELECT 查询都会触发一次 http 请求，以拉取所需数据。对表数据进行任何修改都会导致异常，也就是说，不允许执行以下类型的查询：CREATE TABLE、 ALTER TABLE、RENAME TABLE、 DETACH TABLE 和 TRUNCATE TABLE。 Web 存储可用于只读场景。一个示例用途是托管示例数据，或用于迁移数据。有一个工具 clickhouse-static-files-uploader，它会为指定表准备一个数据目录 (SELECT data_paths FROM system.tables WHERE name = 'table_name') 。对于所需的每个表，都会生成一个文件目录。这些文件可以上传到例如提供静态文件的 Web 服务器。完成这些准备后，你可以通过 DiskWeb 将该表加载到任何 ClickHouse server 中。在此示例配置中：

磁盘类型为 web
数据托管在 http://nginx:80/test1/
使用了本地存储上的缓存

<clickhouse>
    <storage_configuration>
        <disks>
            <web>
                <type>web</type>
                <endpoint>http://nginx:80/test1/</endpoint>
            </web>
            <cached_web>
                <type>cache</type>
                <disk>web</disk>
                <path>cached_web_cache/</path>
                <max_size>100000000</max_size>
            </cached_web>
        </disks>
        <policies>
            <web>
                <volumes>
                    <main>
                        <disk>web</disk>
                    </main>
                </volumes>
            </web>
            <cached_web>
                <volumes>
                    <main>
                        <disk>cached_web</disk>
                    </main>
                </volumes>
            </cached_web>
        </policies>
    </storage_configuration>
</clickhouse>

如果某个 Web 数据集预计不会经常使用，也可以在查询中临时配置存储；请参见动态配置，这样就无需编辑配置文件。GitHub 上托管了一个演示数据集。如需为 Web 存储准备自己的表，请参阅工具 clickhouse-static-files-uploader

在这个 ATTACH TABLE 查询中，提供的 UUID 与数据目录名称一致，而端点是 GitHub 原始内容的 URL。

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
      type=web,
      endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
      );

这里有一个现成的测试用例。你需要将此配置添加到 config 中：

<clickhouse>
    <storage_configuration>
        <disks>
            <web>
                <type>web</type>
                <endpoint>https://clickhouse-datasets.s3.yandex.net/disk-with-static-files-tests/test-hits/</endpoint>
            </web>
        </disks>
        <policies>
            <web>
                <volumes>
                    <main>
                        <disk>web</disk>
                    </main>
                </volumes>
            </web>
        </policies>
    </storage_configuration>
</clickhouse>

然后执行以下查询：

ATTACH TABLE test_hits UUID '1ae36516-d62d-4218-9ae3-6516d62da218'
(
    WatchID UInt64,
    JavaEnable UInt8,
    Title String,
    GoodEvent Int16,
    EventTime DateTime,
    EventDate Date,
    CounterID UInt32,
    ClientIP UInt32,
    ClientIP6 FixedString(16),
    RegionID UInt32,
    UserID UInt64,
    CounterClass Int8,
    OS UInt8,
    UserAgent UInt8,
    URL String,
    Referer String,
    URLDomain String,
    RefererDomain String,
    Refresh UInt8,
    IsRobot UInt8,
    RefererCategories Array(UInt16),
    URLCategories Array(UInt16),
    URLRegions Array(UInt32),
    RefererRegions Array(UInt32),
    ResolutionWidth UInt16,
    ResolutionHeight UInt16,
    ResolutionDepth UInt8,
    FlashMajor UInt8,
    FlashMinor UInt8,
    FlashMinor2 String,
    NetMajor UInt8,
    NetMinor UInt8,
    UserAgentMajor UInt16,
    UserAgentMinor FixedString(2),
    CookieEnable UInt8,
    JavascriptEnable UInt8,
    IsMobile UInt8,
    MobilePhone UInt8,
    MobilePhoneModel String,
    Params String,
    IPNetworkID UInt32,
    TraficSourceID Int8,
    SearchEngineID UInt16,
    SearchPhrase String,
    AdvEngineID UInt8,
    IsArtifical UInt8,
    WindowClientWidth UInt16,
    WindowClientHeight UInt16,
    ClientTimeZone Int16,
    ClientEventTime DateTime,
    SilverlightVersion1 UInt8,
    SilverlightVersion2 UInt8,
    SilverlightVersion3 UInt32,
    SilverlightVersion4 UInt16,
    PageCharset String,
    CodeVersion UInt32,
    IsLink UInt8,
    IsDownload UInt8,
    IsNotBounce UInt8,
    FUniqID UInt64,
    HID UInt32,
    IsOldCounter UInt8,
    IsEvent UInt8,
    IsParameter UInt8,
    DontCountHits UInt8,
    WithHash UInt8,
    HitColor FixedString(1),
    UTCEventTime DateTime,
    Age UInt8,
    Sex UInt8,
    Income UInt8,
    Interests UInt16,
    Robotness UInt8,
    GeneralInterests Array(UInt16),
    RemoteIP UInt32,
    RemoteIP6 FixedString(16),
    WindowName Int32,
    OpenerName Int32,
    HistoryLength Int16,
    BrowserLanguage FixedString(2),
    BrowserCountry FixedString(2),
    SocialNetwork String,
    SocialAction String,
    HTTPError UInt16,
    SendTiming Int32,
    DNSTiming Int32,
    ConnectTiming Int32,
    ResponseStartTiming Int32,
    ResponseEndTiming Int32,
    FetchTiming Int32,
    RedirectTiming Int32,
    DOMInteractiveTiming Int32,
    DOMContentLoadedTiming Int32,
    DOMCompleteTiming Int32,
    LoadEventStartTiming Int32,
    LoadEventEndTiming Int32,
    NSToDOMContentLoadedTiming Int32,
    FirstPaintTiming Int32,
    RedirectCount Int8,
    SocialSourceNetworkID UInt8,
    SocialSourcePage String,
    ParamPrice Int64,
    ParamOrderID String,
    ParamCurrency FixedString(3),
    ParamCurrencyID UInt16,
    GoalsReached Array(UInt32),
    OpenstatServiceName String,
    OpenstatCampaignID String,
    OpenstatAdID String,
    OpenstatSourceID String,
    UTMSource String,
    UTMMedium String,
    UTMCampaign String,
    UTMContent String,
    UTMTerm String,
    FromTag String,
    HasGCLID UInt8,
    RefererHash UInt64,
    URLHash UInt64,
    CLID UInt32,
    YCLID UInt64,
    ShareService String,
    ShareURL String,
    ShareTitle String,
    ParsedParams Nested(
        Key1 String,
        Key2 String,
        Key3 String,
        Key4 String,
        Key5 String,
        ValueDouble Float64),
    IslandID FixedString(16),
    RequestNum UInt32,
    RequestTry UInt8
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(EventDate)
ORDER BY (CounterID, EventDate, intHash32(UserID))
SAMPLE BY intHash32(UserID)
SETTINGS storage_policy='web';

必需参数

参数	描述
`type`	`web`。否则不会创建该磁盘。
`endpoint`	`path` 格式的端点 URL。端点 URL 必须包含一个用于存储数据的根路径，也就是数据上传后的存储位置。

可选参数

参数	描述	默认值
`min_bytes_for_seek`	使用寻道操作而不是顺序读取的最小字节数	`1` MB
`remote_fs_read_backoff_threashold`	读取远程磁盘数据时的最大等待时间	`10000` 秒
`remote_fs_read_backoff_max_tries`	使用退避机制读取时的最大重试次数	`5`

如果查询因异常 DB:Exception Unreachable URL 失败，你可以尝试调整以下设置：http_connection_timeout、http_receive_timeout、keep_alive_timeout。要获取用于上传的文件，请运行： clickhouse static-files-disk-uploader --metadata-path <path> --output-dir <dir> (可通过查询 SELECT data_paths FROM system.tables WHERE name = 'table_name' 找到 --metadata-path) 。通过 endpoint 加载文件时，文件必须加载到 <endpoint>/store/ 路径下，但配置中只能填写 endpoint。如果服务器在启动表时，磁盘加载过程中 URL 无法访问，系统会捕获所有错误。在这种情况下如果出现错误，可以通过 DETACH TABLE table_name -> ATTACH TABLE table_name 重新加载表 (使其重新可见) 。如果元数据在服务器启动时已成功加载，则表会立即可用。使用 http_max_single_read_retries 设置来限制单次 HTTP 读取期间的最大重试次数。

零拷贝复制 (尚不适用于生产环境)

可以在 S3 和 HDFS (不受支持) 磁盘上使用零拷贝复制，但不建议这样做。零拷贝复制是指：如果数据远程存储在多台机器上并且需要同步，则只复制元数据 (数据分区片段的路径) ，而不复制数据本身。

零拷贝复制尚不适用于生产环境在 ClickHouse 22.8 及更高版本中，零拷贝复制默认被禁用。不建议在生产环境中使用此功能。

​配置外部存储

​refresh_parts_interval 和 table_disk

​动态配置

​使用 S3 存储

​必需参数

​可选参数

​使用 Plain Storage

​使用 S3 Plain Rewritable 存储

​使用 Azure Blob 存储

​连接参数

​限制参数

​其他参数

​使用 HDFS 存储 (不支持)

​使用数据加密

​必需参数

​可选参数

​使用本地缓存

​File Cache 查询/profile 设置

​缓存相关系统表

​缓存命令

SYSTEM CLEAR|DROP FILESYSTEM CACHE (<cache_name>) (ON CLUSTER) — ON CLUSTER

SHOW FILESYSTEM CACHES

DESCRIBE FILESYSTEM CACHE '<cache_name>'

​使用静态 Web 存储 (只读)

​必需参数

​可选参数

​零拷贝复制 (尚不适用于生产环境)

配置外部存储

refresh_parts_interval 和 table_disk

动态配置

使用 S3 存储

必需参数

可选参数

使用 Plain Storage

使用 S3 Plain Rewritable 存储

使用 Azure Blob 存储

连接参数

限制参数

其他参数

使用 HDFS 存储 (不支持)

使用数据加密

必需参数

可选参数

使用本地缓存

File Cache 查询/profile 设置

缓存相关系统表

缓存命令

`SYSTEM CLEAR|DROP FILESYSTEM CACHE (<cache_name>) (ON CLUSTER)` — `ON CLUSTER`

`SHOW FILESYSTEM CACHES`

`DESCRIBE FILESYSTEM CACHE '<cache_name>'`

使用静态 Web 存储 (只读)

必需参数

可选参数

零拷贝复制 (尚不适用于生产环境)