修改配置参数--ByteHouse 企业版-火山引擎

文档中心

导航

修改配置参数

最近更新时间：2025.08.05 10:07:50首次发布时间：2025.04.22 20:36:57

本文介绍如何在 ByteHouse 企业版中配置集群参数和用户参数、如何为指定用户授予/解除用户参数的使用权限以及如何创建自定义用户参数。

功能概述

ByteHouse 企业版集群支持通过 config.xml 和 user.xml 配置文件，分别配置集群参数和用户参数，以满足您对于集群性能优化和业务适配的需求。

	集群参数（config.xml）	用户参数（user.xml）
定义	针对集群级别的全局配置项，影响整个集群的运行规则，如资源分配上限、服务超时时间等。	针对指定用户的参数，用于个性化配置指定用户在操作过程中的系统行为，如查询优化、导入优化等。
作用范围	覆盖集群内所有节点、用户及查询任务。	仅限于指定用户，不影响其他用户或整个系统。
使用场景	集群参数可用于集群架构调整、全局性能优化、通用规则管控等场景。	您可以按需调整用户参数，满足您特定业务场景的需求。ByteHouse 也内置了适用于不同场景的用户参数模板，可满足特定数据模型查询（如星型模型、雪花模型、宽表数据）和高并发场景的需求。
配置方式	支持通过视觉化设置或 XML 配置文件调整参数，操作详情请参见配置集群参数。	修改用户参数：ByteHouse 支持您通过视觉化设置或 XML 配置文件调整用户参数，操作详情请参见修改用户参数。管理用户参数模板：启用用户参数模板：默认情况下，所有用户均使用 ByteHouse 默认配置（Default Profile），您可通过为指定用户授予权限的方式使用其他用户参数模板，操作详情请参见为用户授予/解除用户参数权限。自定义用户参数模板：ByteHouse 也支持您按需创建用户参数，操作详情请参见创建用户参数模板。
生效机制	集群参数变更后通常需要重启集群才能生效，因此需在业务低峰期操作，避免影响在线服务。	修改用户参数或为用户授予/移除用户参数权限后，参数将对指定用户即时生效。

ByteHouse 内置的用户参数模板说明如下：

默认配置：即 Default Profile，系统默认用户参数，ByteHouse 默认为所有用户授予此权限。
内置模板：ByteHouse 提供了适用于特定场景的用户参数模板，您可为指定用户授权以启用模板，包括：
- 复杂查询模板（星型模型）：适用于星型模型的数据集。
- 复杂查询模板（雪花模型）：适用于雪花模型的数据集。
- 宽表查询模板：适用于宽表查询。
- 高并发模板：适用于并发 100-1000 的模式。

使用限制

仅 Cluster Admin 和 System Admin 角色的用户支持修改配置参数操作。

注意事项

集群参数完成修改后需要手动重启集群才能生效。重启前，请先确认重启目标集群不会对业务产生影响。
用户参数完成修改后无需重启集群，参数实时生效。

配置集群参数

操作步骤

登录 ByteHouse 企业版管理控制台，在页面左上角，选择目标集群所在的地域，单击集群管理页签，进入集群列表页面，单击目标集群所在行操作列的集群参数，单击修改集群参数。
进入参数编辑状态，填写变更说明，通过视觉化设置或 XML 设置修改参数值。
- 视觉化设置：以可视化方式展示常用参数的名称、参考值、运行参数值等信息。但视觉化设置仅展示常用参数，如果您在参数列表中未找到所需修改的参数或您需要自定义参数，可通过 XML 设置修改。
- XML 设置：以 XML 方式展示参数，包括常用参数和自定义参数。
修改完成后单击保存并下发。
配置下发任务提交后，部分参数需重启集群后生效，单击页面上的重启集群。重启前，请确认重启目标集群不会对业务产生影响。

集群参数说明

参数名称	默认值	参数描述
builtin_dictionaries_reload_interval	3600 s	内置字典的自动重新加载间隔。
compiled_expression_cache_size	134,217,728 bytes	编译后表达式的缓存大小。
default_session_timeout	3600 s	默认会话超时时间。
keep_alive_timeout	10 s	在关闭连接之前等待传入请求的秒数。
max_session_timeout	3600 s	会话超时时间的最大值。
mark_cache_size	4,294,967,296 bytes	标记（Mark）缓存的大小。
max_concurrent_queries	200	最大并发查询数。
max_connections	4096	集群的最大并发连接数。
max_open_files	0	最大打开文件数。 0：不限制大小。其他≥0的值：限制指定大小。
max_partition_size_to_drop	0 bytes	删除 part 的大小限制。 0：不限制大小。其他≥0的值：限制指定大小。
max_server_memory_usage_to_ram_ratio	0.9	服务器内存使用与物理内存的最大比例。
max_table_size_to_drop	0 bytes	删除表的大小限制。 0：不限制。其他≥0的值：限制指定大小。
uncompressed_cache_size	4,294,967,296 bytes	使用的未压缩数据的缓存大小，默认 4GB。
timezone	UTC	集群使用的时区。

配置用户参数

ByteHouse 企业版用户参数支持以下功能：

修改用户参数：ByteHouse 支持通过可视化方式或 XML 配置文件调整参数。
管理用户参数模板：
- 为指定用户授予/解除用户参数的使用权限。
- 创建自定义用户参数模板。

修改用户参数

登录 ByteHouse 企业版管理控制台，在页面左上角选择目标集群所在的地域，单击集群管理页签，进入集群列表页面。单击目标集群所在行操作列的集群参数，单击查看用户参数。
单击您想修改的用户参数名称，例如 Default Profile，进入详情页面。
单击修改配置，您可以通过视觉化设置或 XML 设置修改参数值。

编辑界面示例如下：
- 视觉化设置：以可视化方式展示常用参数的名称、运行参数值、类型等信息。但视觉化设置仅展示常用参数，如果您在参数列表中未找到所需修改的参数或您需要自定义参数，可通过 XML 设置修改。
- XML 设置：以 XML 方式展示参数，包括常用参数和自定义参数。
修改完成后单击保存并下发，系统将对应修改集群参数。用户参数无需重启，修改完成后秒级即可生效。

创建用户参数模板

ByteHouse 支持您按需创建用户参数模板。

登录 ByteHouse 企业版管理控制台，在页面左上角选择目标集群所在的地域，单击集群管理页签，进入集群列表页面。单击目标集群所在行操作列的集群参数，单击查看用户参数。
单击创建用户参数，进入创建页面。
根据界面要求，填写用户参数信息。
- 用户参数名称：定义您的用户参数名称。
- 已授予用户：为指定用户授予用户参数的查看、使用和管理权限。
- 描述：自定义描述，便于后续管理。
- 用户参数：根据您的业务需求通过视觉化设置或 XML 设置定义您的用户参数。
填写完成后，单击创建并下发。

为用户授予/解除用户参数权限

ByteHouse 内置的用户参数模板和您创建的用户参数需先授予用户权限才能使用。
每位用户仅支持被授予一份用户参数模板的使用权限，授予权限后，系统将使用新用户参数覆盖已有的用户参数配置。解除用户与指定用户参数的绑定后，系统将使用默认用户参数（Default Profile）配置覆盖已有的用户参数配置。
操作步骤：

登录 ByteHouse 企业版管理控制台，在页面左上角选择目标集群所在的地域，单击集群管理页签，进入集群列表页面，单击目标集群所在行操作列的集群参数，单击查看用户参数。
在用户参数页面，单击用户参数名称所在行的授予用户按钮，进入用户参数授权页面。
- 授予权限：从已授予用户下拉列表中选择用户。
- 解除已授予的权限：单击用户名称后的叉号（×）。
配置完成后，单击确定。提交后，您可在已授予用户列查看用户名称，确认权限调整已生效。您也可根据调整的参数类型，使用授权用户执行查询操作，验证查询行为是否符合预期。

用户参数说明

参数名称	默认值	参数描述
`dialect_type`	CLICKHOUSE	SQL 方言。可选 CLICKHOUSE / ANSI / MYSQL。
`enable_sharding_optimize`	0	查询是否在节点内先计算出结果再联合多节点结果，如果您能确保查询的 JOIN KEY = GROUP BY KEY = SHARDING KEY 时，该参数设置为 1，查询性能将大幅提升。其余情况需要设置为 0，否则查询结果会错误。
`input_format_skip_unknown_fields`	1（True）	在 JSONEachRow/TSKV 等格式导入时，是否忽略未知列。设置为 1 表示忽略，设置为 0 表示报错。
`max_execution_time`	300 s	单条 SQL 查询的最大超时时间（单位：秒）。
`max_insert_block_size`	1,048,576 行	单个 INSERT 操作中生成一个数据块（Part）的最大行数。
`max_insert_block_size_bytes`	0 bytes（不限制）	单个 INSERT 操作中生成一个数据块（Part）的最大字节数（预估值）。
`max_memory_usage`	9,771,050,598 bytes（约 9.1 GB）	单次查询允许使用的最大内存。说明 `max_memory_usage` 和 `max_memory_usage_for_user` 是两个独立生效的内存参数，没有参数值大小关系约束。
`max_memory_usage_for_user`	9,771,050,598 bytes（约 9.1 GB）	同一时刻所有用户查询允许使用的最大内存总和。
`max_partitions_per_insert_block`	1,000	单个 INSERT 操作中数据最多分布的分区数，用于避免生成过多小文件。
`max_query_size`	1,048,576 bytes（约 1 MB）	SQL 语句的最大长度限制。
`max_threads`	8	查询处理线程的最大数量（不包括从远程服务器检索数据的线程）。