跳至主要内容

用于存储数据的外部磁盘

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

  1. Amazon S3 对象存储。
  2. Azure Blob 存储.
  3. 不支持：Hadoop 分布式文件系统 (HDFS)
ClickHouse 还支持外部表引擎，它与本页面上描述的外部存储选项不同，因为它们允许读取存储在某些通用文件格式（如 Parquet）中的数据，而本页面上描述的是 ClickHouse MergeTree 系列或 Log 系列表的存储配置。
  1. 要使用存储在 Amazon S3 磁盘上的数据，请使用 S3 表引擎。
  2. 要使用存储在 Azure Blob 存储中的数据，请使用 AzureBlobStorage 表引擎。
  3. 不支持：要使用 Hadoop 分布式文件系统中的数据 - HDFS 表引擎。

配置外部存储​

MergeTree 和 Log 系列表引擎可以将数据存储到 S3、AzureBlobStorage、HDFS（不支持）中，分别使用类型为 s3、azure_blob_storage、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 元数据类型的用法在 普通存储部分 中进行了描述，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)
  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，但任何磁盘类型都可以配置为动态，即使是本地磁盘。本地磁盘需要路径参数位于服务器配置参数 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 - S3 端点 URL，采用 path 或 virtual hosted 样式。端点 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 - 本地 FS 上存储 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 选项中获取“根路径”，并添加随机生成的后缀。该后缀是一个包含 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 选项中声明“根路径”。它需要定义选项 key_compatibility_prefix。
  • key_compatibility_prefix — 当使用选项 key_template 时，需要此选项。为了能够读取存储在元数据文件中的对象密钥（元数据版本低于 VERSION_FULL_OBJECT_KEY），应在此处设置 endpoint 选项中的先前“根路径”。
注意

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

使用普通存储​

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

在 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 存储。

截至 2022 年 2 月，此功能仍然是新添加的功能，因此预计某些 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，则在存储帐户中创建一个新的容器 container_name；如果设置为 true，则磁盘直接连接到容器；如果未设置，则磁盘连接到帐户，检查容器 container_name 是否存在，如果不存在则创建它。

身份验证参数（磁盘将尝试所有可用方法**和**托管标识凭据）

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

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

  • s3_max_single_part_upload_size - 限制单个块上传到 Blob 存储的大小。
  • min_bytes_for_seek - 限制可搜索区域的大小。
  • max_single_read_retries - 限制从 Blob 存储读取数据块的尝试次数。
  • max_single_download_retries - 限制从 Blob 存储下载可读缓冲区的尝试次数。
  • thread_pool_size - 限制实例化 IDiskRemote 的线程数。
  • s3_max_inflight_parts_for_one_file - 限制可以为一个对象同时运行的 put 请求数。

其他参数

  • metadata_path - 在本地文件系统上存储 Blob 存储元数据文件的路径。默认值为 /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 将某些表中的数据从文件 store/all_1_1_0/data.bin 写入到 disk1 时，实际上该文件将沿着路径 /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、本地、加密等。对于 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 - 缓存目录的路径。默认：无，此设置是必须的。

  • max_size - 缓存的最大大小，单位为字节或可读格式，例如 ki, Mi, Gi, 等，例如 10Gi（此格式从 22.10 版本开始生效）。当达到限制时，缓存文件将根据缓存驱逐策略被驱逐。默认：无，此设置是必须的。

  • 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, 等，例如 10Gi）。默认：8388608（8Mi）。

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

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

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

其中一些设置将禁用每个查询/配置文件中默认或在磁盘配置设置中启用的缓存功能。例如，您可以在磁盘配置中启用缓存，并在每个查询/配置文件设置 enable_filesystem_cache 为 false 来禁用它。同样，在磁盘配置中将 cache_on_write_operations 设置为 true 表示启用了“write-through”缓存。但是，如果您需要为特定查询禁用此全局设置，则将 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。如果此设置开启并且查询期间达到缓存下载限制，则不再下载缓存到缓存存储。如果此设置关闭并且查询期间达到缓存下载限制，则缓存仍将写入，代价是驱逐先前下载（在当前查询中）的数据，例如，第二种行为允许在保持查询缓存限制的同时保留 最近最少使用 行为。

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

缓存**系统表**

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

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

缓存**命令**

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

  • 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

缓存配置文件事件

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

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 — 使用 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 及更高版本中，默认情况下禁用零拷贝复制。此功能不建议用于生产环境。