用于存储数据的外部磁盘

在 ClickHouse 中处理的数据通常存储在本地文件系统中——与 ClickHouse 服务器在同一台机器上。这需要大容量磁盘，可能相当昂贵。为了避免这种情况，您可以远程存储数据。支持各种存储：

1. Amazon S3 对象存储。
2. Azure Blob Storage.
3. 不支持：Hadoop 分布式文件系统 (HDFS)

注意

ClickHouse 也支持外部表引擎，这与本页描述的外部存储选项不同，因为它们允许读取存储在某些通用文件格式（如 Parquet）中的数据，而本页我们描述的是 ClickHouse MergeTree 家族或 Log 家族表的存储配置。

1. 要使用存储在 Amazon S3 磁盘上的数据，请使用 S3 表引擎。
2. 要使用存储在 Azure Blob Storage 中的数据，请使用 AzureBlobStorage 表引擎。
3. 不支持：要使用 Hadoop 分布式文件系统中的数据 — HDFS 表引擎。

配置外部存储

MergeTree 和 Log 家族表引擎可以使用类型为 s3、azure_blob_storage、hdfs (不支持)、local_blob_storage、web 的磁盘将数据存储到 S3、AzureBlobStorage、HDFS (不支持)。

磁盘配置需要：

1. type 部分，等于 s3、azure_blob_storage、hdfs (不支持)、local_blob_storage、web 之一。
2. 特定外部存储类型的配置。

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

1. type 等于 object_storage
2. 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 存储部分 中描述，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 版本开始，它也可以如下所示：

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

如果您想仅为特定表配置特定的存储策略，则可以在创建表时在设置中定义它：

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

动态配置

还可以指定存储配置，而无需在配置文件中预定义的磁盘，但可以在 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)
  # highlight-start
  SETTINGS disk = disk(
    type=web,
    endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
  );
  # highlight-end

以下示例向外部存储添加缓存。

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)
  # highlight-start
  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/'
      )
  );
  # highlight-end

在下面突出显示的设置中，请注意 type=web 的磁盘嵌套在 type=cache 的磁盘内。

注意

该示例使用 type=web，但任何磁盘类型都可以配置为动态的，甚至是本地磁盘。 本地磁盘需要路径参数位于服务器配置参数 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)
  # highlight-start
  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/'
      )
  );
  # highlight-end

其中 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。端点 URL 应包含存储数据的存储桶和根路径。
• access_key_id — S3 访问密钥 ID。
• secret_access_key — S3 秘密访问密钥。

可选参数：

• region — S3 区域名称。
• support_batch_delete — 此参数控制是否检查批量删除是否受支持。当使用 Google Cloud Storage (GCS) 时，请将其设置为 false，因为 GCS 不支持批量删除，阻止检查将防止日志中出现错误消息。
• use_environment_credentials — 从环境变量 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 以及 AWS_SESSION_TOKEN（如果存在）读取 AWS 凭证。默认值为 false。
• use_insecure_imds_request — 如果设置为 true，则 S3 客户端将在从 Amazon EC2 元数据获取凭证时使用不安全的 IMDS 请求。默认值为 false。
• expiration_window_seconds — 用于检查基于过期的凭证是否已过期的宽限期。可选，默认值为 120。
• proxy — S3 端点的代理配置。proxy 块内的每个 uri 元素都应包含一个代理 URL。
• connect_timeout_ms — 套接字连接超时时间，以毫秒为单位。默认值为 10 秒。
• request_timeout_ms — 请求超时时间，以毫秒为单位。默认值为 5 秒。
• retry_attempts — 请求失败时的重试次数。默认值为 10。
• single_read_retries — 读取期间连接断开时的重试次数。默认值为 4。
• min_bytes_for_seek — 使用 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 加密 访问 S3 对象所需的标头。如果指定空字符串，则将使用 AWS 管理的 S3 密钥。可选。
• server_side_encryption_kms_encryption_context - 如果与 server_side_encryption_kms_key_id 一起指定，则将为 SSE-KMS 设置给定的加密上下文标头。可选。
• server_side_encryption_kms_bucket_key_enabled - 如果与 server_side_encryption_kms_key_id 一起指定，则将设置启用 SSE-KMS 的 S3 存储桶密钥的标头。可选，可以是 true 或 false，默认为空（匹配存储桶级设置）。
• s3_max_put_rps — 限制为每秒最大 PUT 请求数，超过此限制将进行限流。默认值为 0（无限制）。
• s3_max_put_burst — 在达到每秒请求数限制之前可以同时发出的最大请求数。默认值（0 值）等于 s3_max_put_rps。
• s3_max_get_rps — 限制为每秒最大 GET 请求数，超过此限制将进行限流。默认值为 0（无限制）。
• s3_max_get_burst — 在达到每秒请求数限制之前可以同时发出的最大请求数。默认值（0 值）等于 s3_max_get_rps。
• read_resource — 用于调度对该磁盘的读取请求的资源名称。默认值为空字符串（未为此磁盘启用 IO 调度）。
• write_resource — 用于调度对该磁盘的写入请求的资源名称。默认值为空字符串（未为此磁盘启用 IO 调度）。
• key_template — 定义对象键生成的格式。默认情况下，ClickHouse 从 endpoint 选项中获取 root path 并添加随机生成的后缀。该后缀是一个包含 3 个随机符号的目录和一个包含 29 个随机符号的文件名。使用此选项，您可以完全控制对象键的生成方式。某些使用场景需要对象键的前缀或中间部分包含随机符号。例如： [a-z]{3}-prefix-random/constant-part/random-middle-[a-z]{3}/random-suffix-[a-z]{29}。该值使用 re2 解析。仅支持语法的子集。在使用该选项之前，请检查您首选的格式是否受支持。如果 ClickHouse 无法通过 key_template 的值生成密钥，则磁盘不会初始化。这需要启用特性标志 storage_metadata_write_full_object_key。它禁止在 endpoint 选项中声明 root path。它需要定义选项 key_compatibility_prefix。
• key_compatibility_prefix — 当使用选项 key_template 时，此选项是必需的。为了能够读取元数据版本低于 VERSION_FULL_OBJECT_KEY 的元数据文件中存储的对象键，应在此处设置之前来自 endpoint 选项的 root path。

注意

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

使用 Plain 存储

在 22.10 中引入了一种新的磁盘类型 s3_plain，它提供了一种一次写入存储。配置参数与 s3 磁盘类型相同。与 s3 磁盘类型不同，它按原样存储数据，例如，它使用普通文件名（与 ClickHouse 在本地磁盘上存储文件的方式相同），而不是随机生成的 blob 名称，并且不本地存储任何元数据，例如，它是从 s3 上的数据派生的。

此磁盘类型允许保留表的静态版本，因为它不允许对现有数据执行合并，也不允许插入新数据。此磁盘类型的一个用例是在其上创建备份，这可以通过 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 操作。不支持 Mutations 和表复制。

此磁盘类型的一个用例是非复制的 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 Storage

MergeTree 家族表引擎可以使用类型为 azure_blob_storage 的磁盘将数据存储到 Azure Blob Storage。

截至 2022 年 2 月，此功能仍然是新增加的功能，因此请预期某些 Azure Blob Storage 功能可能尚未实现。

配置标记

<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 Storage 帐户 URL，例如 http://account.blob.core.windows.net 或 http://azurite1:10000/devstoreaccount1。
• container_name - 目标容器名称，默认为 default-container。
• container_already_exists - 如果设置为 false，则在存储帐户中创建一个新的容器 container_name；如果设置为 true，则磁盘直接连接到容器；如果未设置，则磁盘连接到帐户，检查容器 container_name 是否存在，如果尚不存在则创建它。

身份验证参数（磁盘将尝试所有可用的方法和托管身份凭证）：

• connection_string - 用于使用连接字符串进行身份验证。
• account_name 和 account_key - 用于使用共享密钥进行身份验证。

限制参数（主要用于内部使用）：

• 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 请求数。

其他参数：

• metadata_path - 本地文件系统上用于存储 Blob Storage 元数据文件的路径。默认值为 /var/lib/clickhouse/disks/<disk_name>/。
• skip_access_check - 如果为 true，则在磁盘启动时不会执行磁盘访问检查。默认值为 false。
• read_resource — 用于调度对该磁盘的读取请求的资源名称。默认值为空字符串（未为此磁盘启用 IO 调度）。
• write_resource — 用于调度对该磁盘的写入请求的资源名称。默认值为空字符串（未为此磁盘启用 IO 调度）。
• 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 的物理磁盘。

必需参数：

• type — encrypted。否则，不会创建加密磁盘。
• disk — 用于数据存储的磁盘类型。
• key — 用于加密和解密的密钥。类型：Uint64。您可以使用 key_hex 参数以十六进制形式编码密钥。您可以使用 id 属性指定多个密钥（请参阅下面的示例）。

可选参数：

• path — 数据将保存到的磁盘上的位置路径。如果未指定，则数据将保存在根目录中。
• current_key_id — 用于加密的密钥。所有指定的密钥都可以用于解密，并且您始终可以切换到另一个密钥，同时保持对先前加密数据的访问。
• algorithm — 用于加密的算法。可能的值：AES_128_CTR、AES_192_CTR 或 AES_256_CTR。默认值：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>

文件缓存 磁盘配置设置

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

• path - 缓存目录的路径。默认值：None，此设置是必需的。

• max_size - 缓存的最大大小，以字节或可读格式表示，例如 ki, Mi, Gi, etc，示例 10Gi（从 22.10 版本开始支持这种格式）。当达到限制时，将根据缓存驱逐策略驱逐缓存文件。默认值：None，此设置是必需的。

• cache_on_write_operations - 允许启用 write-through 缓存（在任何写入操作时缓存数据：INSERT 查询、后台合并）。默认值：false。可以使用设置 enable_filesystem_cache_on_write_operations 禁用每个查询的 write-through 缓存（仅当缓存配置设置和相应的查询设置都启用时，才会缓存数据）。

• enable_filesystem_query_cache_limit - 允许限制在每个查询中下载的缓存大小（取决于用户设置 max_query_cache_size）。默认值：false。

• enable_cache_hits_threshold - 定义某些数据需要被读取多少次才能被缓存的次数。默认值：false。此阈值可以由 cache_hits_threshold 定义。默认值：0，例如，数据在第一次尝试读取时被缓存。

• enable_bypass_cache_with_threshold - 允许在请求的读取范围超过阈值时完全跳过缓存。默认值：false。此阈值可以由 bypass_cache_threashold 定义。默认值：268435456 (256Mi)。

• max_file_segment_size - 单个缓存文件的最大大小，以字节或可读格式表示 (ki, Mi, Gi, etc，示例 10Gi)。默认值：8388608 (8Mi)。

• max_elements - 缓存文件数量的限制。默认值：10000000。

• load_metadata_threads - 用于在启动时加载缓存元数据的线程数。默认值：16。

文件缓存 查询/配置文件设置

其中一些设置将禁用每个查询/配置文件启用的缓存特性，这些特性默认启用或在磁盘配置设置中启用。例如，您可以在磁盘配置中启用缓存，并通过将每个查询/配置文件的设置 enable_filesystem_cache 设置为 false 来禁用它。 此外，在磁盘配置中将 cache_on_write_operations 设置为 true 意味着“write-though”缓存已启用。但是，如果您需要为特定查询禁用此常规设置，则将 enable_filesystem_cache_on_write_operations 设置为 false 意味着将为特定查询/配置文件禁用写入操作缓存。

• enable_filesystem_cache - 允许为每个查询禁用缓存，即使存储策略配置了 cache 磁盘类型。默认值：true。

• read_from_filesystem_cache_if_exists_otherwise_bypass_cache - 允许仅在缓存已存在时在查询中使用缓存，否则查询数据将不会写入本地缓存存储。默认值：false。

• enable_filesystem_cache_on_write_operations - 启用 write-through 缓存。此设置仅当缓存配置中的 cache_on_write_operations 设置为启用状态时才有效。默认值：false。云默认值：true。

• enable_filesystem_cache_log - 启用向 system.filesystem_cache_log 表记录日志。提供每个查询的缓存使用情况的详细视图。可以为特定查询启用它，也可以在配置文件中启用。默认值：false。

• max_query_cache_size - 可以写入本地缓存存储的缓存大小限制。需要在缓存配置中启用 enable_filesystem_query_cache_limit。默认值：false。

• skip_download_if_exceeds_query_cache - 允许更改设置 max_query_cache_size 的行为。默认值：true。如果启用此设置并且在查询期间达到缓存下载限制，则不会将更多缓存下载到缓存存储。如果禁用此设置并且在查询期间达到缓存下载限制，则仍然会写入缓存，但会驱逐先前下载的（在当前查询中）数据，例如，第二种行为允许在保持查询缓存限制的同时保留 last recently used 行为。

警告 缓存配置设置和缓存查询设置对应于最新的 ClickHouse 版本，对于早期版本，某些功能可能不受支持。

缓存 系统表

• system.filesystem_cache - 系统表，显示缓存的当前状态。

• system.filesystem_cache_log - 系统表，显示每个查询的详细缓存使用情况。需要将 enable_filesystem_cache_log 设置为 true。

缓存 命令

• SYSTEM DROP FILESYSTEM CACHE (<cache_name>) (ON CLUSTER) -- 仅当未提供 <cache_name> 时才支持 ON CLUSTER

• SHOW FILESYSTEM CACHES -- 显示服务器上配置的文件系统缓存列表。（对于 <= 22.8 版本，该命令名为 SHOW CACHES）

SHOW FILESYSTEM CACHES

结果

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

• DESCRIBE FILESYSTEM CACHE '<cache_name>' - 显示特定缓存的缓存配置和一些常规统计信息。缓存名称可以从 SHOW FILESYSTEM CACHES 命令中获取。（对于 22.8 及更早版本，该命令名为 DESCRIBE CACHE）

DESCRIBE FILESYSTEM CACHE 's3_cache'

┌────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 │
└─────────────┴──────────────┴───────────────────────┴────────────────────┴───────────────────────────┴──────────────────────┴──────────────┴──────────────────┴────────────┴─────────────────────────────┴────────────────────────────────────┘

缓存当前指标

• FilesystemCacheSize (文件系统缓存大小)

• FilesystemCacheElements (文件系统缓存元素数量)

缓存异步指标

• FilesystemCacheBytes (文件系统缓存字节数)

• FilesystemCacheFiles (文件系统缓存文件数)

缓存 profile 事件

• CachedReadBufferReadFromSourceBytes, CachedReadBufferReadFromCacheBytes,

• 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 服务器中。

在此示例配置中：

• 磁盘类型为 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。

# highlight-next-line
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)
  # highlight-start
  SETTINGS disk = disk(
      type=web,
      endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
      );
  # highlight-end

一个现成的测试用例。您需要将此配置添加到配置中

<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 — 使用 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>（--metadata-path 可以在查询 SELECT data_paths FROM system.tables WHERE name = 'table_name' 中找到）。

当通过 endpoint 加载文件时，它们必须加载到 <endpoint>/store/ 路径中，但配置必须仅包含 endpoint。

如果在服务器启动表时磁盘加载时 URL 不可访问，则所有错误都会被捕获。如果在这种情况下存在错误，则可以通过 DETACH TABLE table_name -> ATTACH TABLE table_name 重新加载表（使其可见）。如果在服务器启动时成功加载了元数据，则表立即可用。

使用 http_max_single_read_retries 设置来限制单个 HTTP 读取期间的最大重试次数。

零拷贝复制（未准备好用于生产环境）

零拷贝复制是可能的，但不建议用于 S3 和 HDFS（不支持）磁盘。零拷贝复制意味着如果数据远程存储在多台机器上并且需要同步，则仅复制元数据（数据部分的路径），而不复制数据本身。

零拷贝复制尚未准备好用于生产环境

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