版本：1.0.x

集群配置参数

Server 配置参数

ByConity Server 端的配置保存在 cnch-server.xml 中，进程启动时通过 --config-file 指定， server 会自动从 cnch-server.xml 中加载配置。

cnch_type

配置 ByConity 进程类型，可配置为 server 或者 worker。其中 server 主要负责接收查询请求并负责将查询调度到 worker；worker 节点主要负责执行来自 server 的查询任务。举例如下：

Example:

<cnch_type>server</cnch_type>

tcp_port

server 和客户端进行连接的 TCP 端口

Example：

<tcp_port>9000</tcp_port>

http_port

server 与客户端进行连接的 HTTP 端口

Example:

<https_port>9999</https_port>

rpc_port

server 与其他组件进行交互的 RPC 端口

Example:

<rpc_port>8124</rpc_port>

exchange_port

复杂查询的数据传输端口（将来考虑与 rpc_port 合并）

exchange_status_port

复杂查询的控制指令端口（将来考虑与 rpc_port 合并）

path

本地数据路径目录

Example:

<path>/var/lib/clickhouse/</path>

tmp_path

本地临时目录路径,用来存放查询过程中的临时数据

Example：

<tmp_path>/var/lib/clickhouse/tmp/</tmp_path>

users_config

用户相关配置文件的路径。

Example:

<users_config>/path/to/userconf/users.xml</users_config>

Service discovery

配置与 server 进程通信的其他组件(包括其他 server)。与 server 交互的其他组件有 server, tso, daemon manager, virtual warehouse 以及 resource manager

keys:

mode : 服务发现模式, 可选择的配置参数为 local , dns, consul
cluster: 集群名称
disable_cache：如果配置为 false, 将启用缓存以减少调用服务发现的次数
cache_timeout : 缓存过期时间

Example

<service_discovery>
    <mode>dns</mode>
    <cluster>default</cluster>
        <disable_cache>false</disable_cache>
        <cache_timeout>5</cache_timeout>
    <server>
        <psm>data.cnch.server</psm>
        <service>cnch-server-pp</service>
        <headless_service>cnch-server-pp-headless</headless_service>
    </server>
    <tso>
        <psm>data.cnch.tso</psm>
        <service>cnch-tso</service>
        <headless_service>cnch-tso-headless</headless_service>
    </tso>
    <vw>
        <psm>data.cnch.vw</psm>
    </vw>
    <daemon_manager>
        <psm>data.cnch.daemon_manager</psm>
        <service>cnch-daemon-manager</service>
        <headless_service>cnch-daemon-manager-headless</headless_service>
    </daemon_manager>
    <resource_manager>
        <psm>data.cnch.resource_manager</psm>
        <service>cnch-resource-manager</service>
        <headless_service>cnch-resource-manager-headless</headless_service>
    </resource_manager>
</service_discovery>

Catalog service

集群元数据相关配置

Keys:

type : 元数据存储引擎类型，支持 bytekv, fdb

Example:

<!-- For foundationDB metastore-->
<catalog_service>
    <!--TODO: move name_space into catalog_service tag -->
    <!--Metastore storage type, support `bytekv` and `fdb`-->
    <type>fdb</type>
    <fdb>
        <cluster_file>/path/to/fdb/cluster_config</cluster_file>
    </fdb>
</catalog_service>

HDFS 配置参数

启动服务时，会按照 cfs_addr>hdfs_addr>hdfs_ha_nameservice>hdfs_nnproxy 的顺序来检测配置项，一但命中某个配置项配置则使用对应的配置项来访问 HDFS

hdfs_user

访问 HDFS 时默认使用的用户的名称，默认 clickhouse

Example:

<hdfs_user>clickhouse</hdfs_user>

cfs_addr

cfs 服务的地址，格式为 cfs://service_url

Example:

<cfs_addr>cfs://service_url</cfs_addr>

hdfs_addr

hdfs 服务的地址，格式为 hdfs://nnip:nnport/path

Example:

<hdfs_addr>hdfs://nnip:nnport/path</hdfs_addr>

hdfs_ha_nameservice

hdfs 服务的名称，需要在 libhdfs3 的配置文件中提前配置好

Example:

<hdfs_ha_nameservice>hdfs_service</hdfs_ha_nameservice>

hdfs_nnproxy

访问HDFS时默认使用的 nnproxy 名称，默认 nnproxy

Example:

<hdfs_nnproxy>nnproxy</hdfs_nnproxy>

storage_configuration

配置说明

接下来的配置层级与配置文件中 storage_configuration 配置层级一一对应

storage_configuration
- cnch_default_policy，指定 CNCH 存储实际数据所使用的 StoragePolicy，可选配置项，默认是 cnch_default_hdfs，这个 StoragePolicy 中应当仅包含单个 HDFSDisk 或 S3Disk
  - 当建表的时候，对于 CNCH 表，如果没有指定 storage_policy 这个 MergeTreeSettings，则会被默认修改为 ${cnch_default_policy}
- cnch_auxility_policy，指定 CNCH 在本地磁盘上存储临时数据所使用的 StoragePolicy，可选配置项，默认是 default
- disks
  - ${DISK_NAME}
    - type，这个磁盘的类型，可选配置项，默认是 local
      - CNCH 支持选用 hdfs/bytehdfs/s3/bytes3 这四种磁盘作为远端存储
      - 为了与内部的配置兼容，hdfs/bytehdfs 均解析为内部的 bytehdfs 这种 Disk，社区版本的 HDFSDisk 的 type 被重命名为 communityhdfs； s3/bytes3 会解析成内部的 bytes3 这种 Disk，社区版本的 S3Disk被重命名成 communitys3
      - CNCH 所使用的 StoragePolicy 所指定的 HDFSDisk/S3Disk，其配置项在所有的 Server/Worker 的配置文件中都应当相同
    - path
      - 数据将被存储在这个 Disk 的哪个路径中，必需的配置项
    - hdfs_params
      - 针对 bytehdfs 类型的磁盘所新增的可选配置项，包含如下参数
      - hdfs_user，连接 hdfs 所使用的 user，可选配置项，默认是 clickhouse
      - cfs_addr，cfs 的地址，可选配置项，仅在使用 cfs 时需要配置此配置项
      - hdfs_addr，hdfs 的 namenode 的地址，可选配置项，如 hdfs://nnip:nnport/path
      - hdfs_ha_nameservice，可选配置项，如果需要使用 hdfs 的 HA，可以使用该配置项指定对应的 service，对应的 hdfs 配置需要通过 hdfs3_config 配置文件来配置
      - hdfs_nnproxy，hdfs 的 nnproxy 的地址，可选配置项，默认是 nnproxy
      - 如果 DiskByteHDFS 没有配置 hdfs_params 配置项，则会去配置文件中找到全局的配置项，例如配置文件中 hdfs_user 这个配置项的值
    - region
      - bytes3 disk的配置项，标识s3服务的region
    - endpoint
      - bytes3 disk的配置项，标识s3服务的endpoint
    - bucket
      - bytes3 disk的配置项，标识s3服务的bucket
    - akid
      - bytes3 disk的配置项，标示访问s3所使用的access key id，如果没有配置会检查 AWS_ACCESS_KEY_ID 这个环境变量
    - aksecret
      - bytes3 disk的配置项，标示访问s3所使用的access key secret，如果没有配置会检查 AWS_SECRET_ACCESS_KEY 这个环境变量
- policies
  - ${STORAGE_POLICY_NAME}，byconity 使用的远端存储的 StoragePolicy 目前仅支持单个 Volume 同时 Volume 中仅包含单个 Disk
    - volumes
      - ${VOLUME_NAME}
        default，这个 Volume 中的默认磁盘，必需的配置项，默认的磁盘会被用来存放部分不支持多盘存储的数据，例如 metastore 等
        disk，这个 Volume 所包含的所有磁盘名称，必需的配置项，对应 Disk 需要在 storage_configuration.disks 中配置好

配置示例

<storage_configuration>
    <disks>
        <default></default>
        <server_local_disk1>
            <path>/home/ch_test_service/service_test_env/server_data1/</path>
        </server_local_disk1>
        <server_local_disk2>
            <path>/home/ch_test_service/service_test_env/server_data2/</path>
        </server_local_disk2>
        <server_hdfs_disk0>
            <path>/user/cnch/</path>
            <type>bytehdfs</type>
        </server_hdfs_disk0>
        <server_s3_disk0>
            <type>bytes3</type>
            <region>cn-beijing</region>
            <endpoint>https://tos-s3-cn-beijing.volces.com</endpoint>
            <bucket>byconity</bucket>
            <path>test-service/</path>
            <ak_id>some_access_key_id</ak_id>
            <ak_secret>some_access_key_secret</ak_secret>
        </server_s3_disk0>
    </disks>
    <policies>
        <default>
            <volumes>
                <local>
                    <default>default</default>
                    <disk>default</disk>
                    <disk>server_local_disk1</disk>
                    <disk>server_local_disk2</disk>
                </local>
            </volumes>
        </default>
        <cnch_default_hdfs>
            <volumes>
                <hdfs>
                    <default>server_hdfs_disk0</default>
                    <disk>server_hdfs_disk0</disk>
                </hdfs>
            </volumes>
        </cnch_default_hdfs>
        <cnch_default_s3>
            <volumes>
                <s3>
                    <default>server_s3_disk0</default>
                    <disk>server_s3_disk0</disk>
                </s3>
            </volumes>
        </cnch_default_s3>
    </policies>
</storage_configuration>

为了兼容内部旧版本的配置项，如果用户仅指定了 default 这一个 StoragePolicy，同时包含 hdfs 和 local 这两个 volume，那么这个配置项会被解析成两个 StoragePolicy，一个是 default，但是仅包含 local 这个 volume，另一个是 ${cnch_default_policy}，仅包含 hdfs 这个 volume
可以通过在 storage_configuration 中配置多个 storage policy，我们可以指定表的数据需要存储到什么地方。比方说，可以将 cnch_default_policy 设置为 cnch_default_hdfs 来让数据默认存储到 hdfs 上，同时通过在建表的时候通过指定 storage policy 来让某张表的数据存储到 s3 上

create table test_store (key Int) engine = CnchMergeTree order by key settings storage_policy = 'cnch_default_s3';

hdfs3_config

libhdfs3 配置文件路径

Example:

<hdfs3_config>/path/to/conf/hdfs3.xml</hdfs3_config>

disk_cache_strategies

该配置项用于管理 ByConity 中的 DiskCache 行为，包含三种不同的策略，如文件级别、MergeTree表、Hive外表。有不同的缓存路径和管理策略。该配置项定义了定义了多个参数用于管理缓存行为，以优化 I/O 性能和提高数据处理速度。具体示例和参数项说明如下：

配置DiskCache的相关参数：

参数名称	描述	默认值
hits_to_cache	同一份数据被访问多少次才会被缓存	2
segment_size	缓存DiskCache的最小单位所包含的行数	8192
lru_max_size	LRU cache的最大容量（bytes）	2
lru_max_object_num	LRU cache的最大数量（std::numeric_limits<size_t>::max()）	4294967295（32位系统）
random_drop_threshold	随机丢弃缓存任务的阈值	50
stats_bucket_size	存储并缓存Key次数的bucket数目	10000
lru_update_interval	LRU cache更新间隔（秒）	60
cache_dispatcher_per_disk	是否为每个盘启动加载线程	true
cache_loader_per_disk	为每个盘分配的多线程数	2
cache_shard_num	LRU cache的分片数目	12
cache_set_rate_limit	缓存写入速率限制器	0 (不限速)
disk_cache_dir	缓存写入的相对路径	disk_cache_v1

举例:

<disk_cache_strategies>
    <File> // 通用的文件粒度的DiskCache
        <disk_cache_dir>file_disk_cache</disk_cache_dir>
    </File>
    <MergeTree>// 适用于MergeTree表的DiskCache
        <disk_cache_dir>mergetree_disk_cache</disk_cache_dir>
    </MergeTree>
    <Hive> // 适用于Hive外表的DiskCache
        <disk_cache_dir>hive_disk_cache</disk_cache_dir>
    </Hive>
</disk_cache_strategies>

配置SplitDiskCache的相关参数

ByConity本地缓存策略支持Meta&Data数据缓存分离，在一些特定场景下优先缓存Meta数据，有效降低一些小I/O带来的远程读长尾现象。

参数名称	描述	默认值
meta_cache_nums_ratio	meta缓存的文件占用比例	默认0表示混合混存；大于0表示分离缓存
meta_cache_size_ratio	meta缓存的空间占用比例	50

举例：

<disk_cache_strategies>
    <simple>
          ...
          <meta_cache_nums_ratio>50</meta_cache_nums_ratio>
          <meta_cache_size_ratio>10</meta_cache_size_ratio>
    </simple>
 <disk_cache_strategies>

配置StealingDiskCache的相关参数

Server在分发Part给Worker时会根据负载均衡调整算法，可能导致同一Part在不同查询中分发到不同节点，增加Cache失效率。另外，当启用Preload功能时，这种不一致性可能导致预热的Part无法被后续查询利用。而DiskCacheStealing通过一致性HASH算法确保Part在固定节点缓存，并在非缓存节点查询时从远端节点读取数据，以提升本地磁盘缓存性能。

参数名称	描述	默认值
stealing_max_request_rate	读远端缓存的最大速率	0（不限制）
stealing_connection_timeout_ms	读远端缓存的连接超时阈值	5000（5秒）
stealing_read_timeout_ms	读远端缓存的读取超时阈值	10000（10秒）
stealing_max_retry_times	读远端缓存失败时的最大重试次数	3
stealing_retry_sleep_ms	读远端缓存失败时的重试间隔	100（100毫秒）
stealing_max_queue_count	读远端缓存的最大队列长度	10000

举例：

<disk_cache_strategies>
    <MergeTree>
        <stealing_max_request_rate>0</stealing_max_request_rate>
        <stealing_connection_timeout_ms>5</stealing_connection_timeout_ms>
        <stealing_read_timeout_ms>10</stealing_read_timeout_ms>
        <stealing_max_retry_times>3</stealing_max_retry_times>
        <stealing_retry_sleep_ms>100</stealing_retry_sleep_ms>
        <stealing_max_queue_count>10000</stealing_max_queue_count>
    </MergeTree>
</disk_cache_strategies>

如何在表级别启动StealingDiskCache

对于现有表，可以使用 ALTER TABLE 语句来更改表的配置：

ALTER TABLE [database].[table] ON CLUSTER cluster  
SETTINGS disk_cache_stealing_mode = 3;

对于新表，可以在创建表时 CREATE TABLE 指定参数：

CREATE TABLE [database].[table]  
(  
    ... -- 列定义  
) ENGINE = MergeTree()  
SETTINGS disk_cache_stealing_mode = 3;

参数说明

`disk_cache_stealing_mode`	描述
0	默认值，关闭DiskCacheStealing
1	仅在缓存读取时向远端节点发起RPC请求，以读取远端缓存副本
2	仅在缓存写入时向远端节点发起RPC请求，以写入远端缓存副本
3	写入缓存时尝试向远端节点写入副本，读取缓存时若本地没有，尝试向远端节点读取

cnch_kafka_log

配置后，CNCH 将开启 kafka_log, 可通过系统表查看消费日志

Example:

<cnch_kafka_log>
    <database>cnch_system</database>
    <table>cnch_kafka_log</table>
    <flush_max_row_count>10000</flush_max_row_count>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
</cnch_kafka_log>

brpc配置参数

cnch_transaction_cleaner_max_threads

CNCH 后台清理 transaction record 的线程池大小，默认 128

Example:

<cnch_transaction_cleaner_max_threads>128</cnch_transaction_cleaner_max_threads>

cnch_transaction_cleaner_queue_size

CNCH 后台清理 transaction record 的线程池队列大小，默认 10000

Example:

<cnch_transaction_cleaner_queue_size>10000</cnch_transaction_cleaner_queue_size>

dance_merge_selector

配置自研 merge 选择策略参数

Example:

<dance_merge_selector>
    <max_total_rows_to_merge>10000000</max_total_rows_to_merge>
</dance_merge_selector>

exchange_timeout_ms

复杂查询数据传输 rpc 超时，默认 100000

Example:

<exchange_timeout_ms>100000</exchange_timeout_ms>

TSO 配置参数

tso_service

配置 tso 服务，包括服务端口，元数据存储等

Keys:

port: TSO 服务 TCP 端口
type: TSO 元数据存储引擎

Example:

<tso_service>
    <port>8080</port>
    <!-- Support for CNCH-CE Merge. Metastore store type, support `bytekv` and `fdb` -->
    <type>fdb</type>
    <fdb>
        <cluster_file>/path/to/fdb/conf/fdb.cluster</cluster_file>>
    </fdb>
 </tso_service>

service_discovery

服务发现相关配置，高可用 TSO 进程通过服务发现获取其他 TSO server 地址及端口进行通信

Keys:

mode : 与其他模块 service discovery 一样，支持 dns, consul, local 等模式

Example:

<service_discovery>
    <mode>dns</mode>
    <tso>
        <psm>data.cnch.tso</psm>
        <service>cnch-tso</service>
        <headless_service>cnch-tso-headless</headless_service>
    </tso>
</service_discovery>

Daemon Manager 配置参数

daemon_manager

配置 daemon manager 进程端口以及调度后台任务的信息

Keys:

port: DM 进程 TCP 端口
http: DM 进程 http 端口等配置
workload_thread_interval_ms: 后台任务调度的时间间隔
daemon_jobs: DM 负责调度的后台任务类型及配置。可调度的任务类型包括：PART_GC, PART_MERGE, CONSUMER, GLOBAL_GC, TXN_GC 等

Example:

<daemon_manager>
    <port>8090</port>
    <http>
        <port>8091</port>
        <receive_timeout>1800</receive_timeout>
        <send_timeout>1800</send_timeout>
    </http>
    <workload_thread_interval_ms>1000</workload_thread_interval_ms>
    <daemon_jobs>
        <job>
            <name>PART_GC</name>
            <!-- Interval in millisecond -->
            <interval>10000</interval>
        </job>
        <job>
            <name>PART_MERGE</name>
            <!-- Interval in millisecond -->
            <interval>10000</interval>
        </job>
        <job>
            <name>CONSUMER</name>
            <!-- Interval in millisecond -->
            <interval>10000</interval>
        </job>
        <job>
            <name>GLOBAL_GC</name>
            <!-- Interval in millisecond -->
            <interval>50000</interval>
        </job>
        <job>
            <name>TXN_GC</name>
            <!-- Interval in millisecond -->
            <interval>600000</interval>
        </job>
        <job>
            <name>DEDUP_WORKER</name>
            <!-- Interval in millisecond -->
            <interval>10000</interval>
        </job>
        <job>
            <name>PART_CLUSTERING</name>
            <!-- Interval in millisecond -->
            <interval>10000</interval>
        </job>
    </daemon_jobs>
</daemon_manager>

cnch_data_retention_time_in_sec

被删除的表及数据库在被彻底清理之前的保留时间，默认 3 天。期间内，用户可以恢复已经删除的数据。

Example:

<cnch_data_retention_time_in_sec>86400</cnch_data_retention_time_in_sec>

Resource Manager 配置参数

resource_manager

配置 resource manager 进程端口、初始 VW 配置等信息。

Keys：

port: 服务启动的端口号
vws: 初始配置的 VW 相关信息

Example：

<resource_manager>
    <port>18989</port>
    <vws>
        <vw>
            <name>vw_default</name>
            <type>Default</type>
            <num_workers>1</num_workers>
            <worker_groups>
                <worker_group>
                    <name>wg_default</name>
                    <type>Physical</type>
                </worker_group>
            </worker_groups>
        </vw>
    </vws>
</resource_manager>

catalog

Catalog 相关配置

Keys:

name_space

Example:

<name_space>default</name_space>

catalog_service

catalog_service 相关配置。

Keys:

type - catalog 服务的类型

Example:

<!-- For foundationDB metastore-->
<catalog_service>
    <!--TODO: move name_space into catalog_service tag -->
    <!--Metastore storage type, support `bytekv` and `fdb`-->
    <type>fdb</type>
    <fdb>
        <cluster_file>/path/to/fdb/cluster_config</cluster_file>
    </fdb>
</catalog_service>

集群配置参数

Server 配置参数​

cnch_type​

tcp_port​

http_port​

rpc_port​

exchange_port​

exchange_status_port​

path​

tmp_path​

users_config​

Service discovery​

Catalog service​

HDFS 配置参数​

hdfs_user​

cfs_addr​

hdfs_addr​

hdfs_ha_nameservice​

hdfs_nnproxy​

storage_configuration​

配置说明​

配置示例​

hdfs3_config​

disk_cache_strategies​

配置DiskCache的相关参数：​

配置SplitDiskCache的相关参数​

配置StealingDiskCache的相关参数​

如何在表级别启动StealingDiskCache​

cnch_kafka_log​

brpc配置参数​

cnch_transaction_cleaner_max_threads​

cnch_transaction_cleaner_queue_size​

dance_merge_selector​

exchange_timeout_ms​

TSO 配置参数​

tso_service​

service_discovery​

Daemon Manager 配置参数​

daemon_manager​

cnch_data_retention_time_in_sec​

Resource Manager 配置参数​

resource_manager​

catalog​

catalog_service​

Server 配置参数

cnch_type

tcp_port

http_port

rpc_port

exchange_port

exchange_status_port

path

tmp_path

users_config

Service discovery

Catalog service

HDFS 配置参数

hdfs_user

cfs_addr

hdfs_addr

hdfs_ha_nameservice

hdfs_nnproxy

storage_configuration

配置说明

配置示例

hdfs3_config

disk_cache_strategies

配置DiskCache的相关参数：

配置SplitDiskCache的相关参数

配置StealingDiskCache的相关参数

如何在表级别启动StealingDiskCache

cnch_kafka_log

brpc配置参数

cnch_transaction_cleaner_max_threads

cnch_transaction_cleaner_queue_size

dance_merge_selector

exchange_timeout_ms

TSO 配置参数

tso_service

service_discovery

Daemon Manager 配置参数

daemon_manager

cnch_data_retention_time_in_sec

Resource Manager 配置参数

resource_manager

catalog

catalog_service