Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

query_* 服务器设置

View as MarkdownEdit this pageReport an issueSet up docs MCP

这些设置用于配置 ClickHouse 服务器，且由 ClickHouse 源代码自动生成。

query_cache

查询缓存的配置。

可用设置如下：

Setting Description Default Value
max_entries 缓存中可存储的 SELECT 查询结果的最大数量。 1024
max_entry_size_in_bytes 可保存到缓存中的 SELECT 查询结果的最大大小 (以字节为单位) 。 1048576
max_entry_size_in_rows 可保存到缓存中的 SELECT 查询结果的最大行数。 30000000
max_size_in_bytes 缓存的最大大小 (以字节为单位) 。0 表示禁用查询缓存。 1073741824

示例

<query_cache>
    <max_size_in_bytes>1073741824</max_size_in_bytes>
    <max_entries>1024</max_entries>
    <max_entry_size_in_bytes>1048576</max_entry_size_in_bytes>
    <max_entry_size_in_rows>30000000</max_entry_size_in_rows>
</query_cache>

query_log

用于记录在启用 log_queries=1 设置时收到的查询。

查询会记录到 system.query_log 表中，而不是单独的文件中。你可以通过 table 参数更改该表的名称 (见下文) 。

以下设置可通过子标签配置：

Setting Description Default Note
database 数据库名称。
table 系统表名称。
engine 系统表的 MergeTree 引擎定义。 如果已定义 partition_by 或 order_by，则不能使用。如果未指定，默认使用 MergeTree
partition_by 系统表的 自定义分区键。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 partition_by 参数
ttl 指定表的 生存时间 (TTL)。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 ttl 参数
order_by 系统表的 自定义排序键。如果定义了 engine，则不能使用。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 order_by 参数
storage_policy 该表使用的存储策略名称 (可选) 。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 storage_policy 参数
settings 控制 MergeTree 行为的附加参数 (可选) 。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 settings 参数
flush_interval_milliseconds 将数据从内存缓冲区刷写到表的时间间隔。 7500
max_size_rows 日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。 1048576
reserved_size_rows 为日志预分配的内存行数。 8192
buffer_size_rows_flush_threshold 行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。 max_size_rows / 2
flush_on_crash 设置在发生崩溃时是否将日志转储到磁盘。 false

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>
设置 描述 默认值
skip_alias_columns 为 true 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。 false

enable_user_query_log 参数 (默认启用) 会创建 system.user_query_log，使每个用户无需访问该表即可查看配置的查询日志表中属于自己的记录。这仅在查询日志存储于本地时有效：如果 engine 委托给另一台服务器 (例如 Distributed)，请禁用 enable_user_query_log，因为 system.user_query_log 无法跨 ClickHouse 协议服务器边界执行按用户的访问检查，并且会拒绝从此类后端读取数据。

如果该表不存在，ClickHouse 会创建它。如果在升级 ClickHouse 服务器后查询日志的结构发生变化，旧结构的表会被重命名，并自动创建一个新表。

示例

<query_log>
    <database>system</database>
    <table>query_log</table>
    <engine>Engine = MergeTree PARTITION BY event_date ORDER BY event_time TTL event_date + INTERVAL 30 day</engine>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
    <enable_user_query_log>true</enable_user_query_log>
</query_log>

query_masking_rules

基于 Regexp 的规则会在查询及所有日志消息写入服务器日志、system.query_log、system.text_log、system.processes 表，以及发送给客户端的日志之前，对其进行处理。 这样可以防止 SQL 查询中的敏感数据 (如姓名、电子邮件、个人标识符或信用卡号) 泄露到日志中。

示例

<query_masking_rules>
    <rule>
        <name>hide SSN</name>
        <regexp>(^|\D)\d{3}-\d{2}-\d{4}($|\D)</regexp>
        <replace>000-00-0000</replace>
    </rule>
</query_masking_rules>

配置字段：

Setting Description
name 规则名称 (可选)
regexp 与 RE2 兼容的正则表达式 (必填)
replace 用于替换敏感数据的字符串 (可选，默认为六个星号)

查询脱敏规则会应用于整个查询 (以防格式错误 / 无法解析的查询泄露敏感数据) 。

system.events 表中有一个计数器 QueryMaskingRulesMatch，用于统计查询脱敏规则的总匹配次数。

对于分布式查询，每台服务器都必须单独配置，否则传递到其他 节点的子查询将以未脱敏状态存储。

query_metric_log

默认处于禁用状态。

启用

如需手动启用 system.query_metric_log 的指标历史记录收集功能，请创建 /etc/clickhouse-server/config.d/query_metric_log.xml，内容如下：

<clickhouse>
    <query_metric_log>
        <database>system</database>
        <table>query_metric_log</table>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <collect_interval_milliseconds>1000</collect_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
    </query_metric_log>
</clickhouse>

禁用

要禁用 query_metric_log 设置，需要创建以下文件 /etc/clickhouse-server/config.d/disable_query_metric_log.xml，内容如下：

<clickhouse>
    <query_metric_log remove="1" />
</clickhouse>

以下设置可通过子标签配置：

Setting Description Default Note
database 数据库名称。
table 系统表名称。
engine 系统表的 MergeTree 引擎定义。 如果已定义 partition_by 或 order_by，则不能使用。如果未指定，默认使用 MergeTree
partition_by 系统表的 自定义分区键。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 partition_by 参数
ttl 指定表的 生存时间 (TTL)。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 ttl 参数
order_by 系统表的 自定义排序键。如果定义了 engine，则不能使用。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 order_by 参数
storage_policy 该表使用的存储策略名称 (可选) 。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 storage_policy 参数
settings 控制 MergeTree 行为的附加参数 (可选) 。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 settings 参数
flush_interval_milliseconds 将数据从内存缓冲区刷写到表的时间间隔。 7500
max_size_rows 日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。 1048576
reserved_size_rows 为日志预分配的内存行数。 8192
buffer_size_rows_flush_threshold 行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。 max_size_rows / 2
flush_on_crash 设置在发生崩溃时是否将日志转储到磁盘。 false

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>
设置 描述 默认值
skip_alias_columns 为 true 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。 false

query_thread_log

用于记录在启用 log_query_threads=1 设置时接收到的查询线程的设置。

查询会记录到 system.query_thread_log 表中，而不是单独的文件中。您可以通过 table 参数更改该表的名称 (见下文) 。

以下设置可通过子标签配置：

Setting Description Default Note
database 数据库名称。
table 系统表名称。
engine 系统表的 MergeTree 引擎定义。 如果已定义 partition_by 或 order_by，则不能使用。如果未指定，默认使用 MergeTree
partition_by 系统表的 自定义分区键。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 partition_by 参数
ttl 指定表的 生存时间 (TTL)。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 ttl 参数
order_by 系统表的 自定义排序键。如果定义了 engine，则不能使用。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 order_by 参数
storage_policy 该表使用的存储策略名称 (可选) 。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 storage_policy 参数
settings 控制 MergeTree 行为的附加参数 (可选) 。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 settings 参数
flush_interval_milliseconds 将数据从内存缓冲区刷写到表的时间间隔。 7500
max_size_rows 日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。 1048576
reserved_size_rows 为日志预分配的内存行数。 8192
buffer_size_rows_flush_threshold 行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。 max_size_rows / 2
flush_on_crash 设置在发生崩溃时是否将日志转储到磁盘。 false

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>
设置 描述 默认值
skip_alias_columns 为 true 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。 false

如果该表不存在，ClickHouse 会创建它。如果在升级 ClickHouse 服务器时查询线程日志的结构发生了变化，则旧结构的表会被重命名，并自动创建一个新表。

示例

<query_thread_log>
    <database>system</database>
    <table>query_thread_log</table>
    <partition_by>toMonday(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</query_thread_log>

query_views_log

用于记录视图 (如 live、materialized 等) 的设置，具体取决于接收到的查询是否启用了 log_query_views=1 设置。

查询会记录到 system.query_views_log 表中，而不是单独的文件中。你可以通过 table 参数更改该表的名称 (见下文) 。

以下设置可通过子标签配置：

Setting Description Default Note
database 数据库名称。
table 系统表名称。
engine 系统表的 MergeTree 引擎定义。 如果已定义 partition_by 或 order_by，则不能使用。如果未指定，默认使用 MergeTree
partition_by 系统表的 自定义分区键。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 partition_by 参数
ttl 指定表的 生存时间 (TTL)。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 ttl 参数
order_by 系统表的 自定义排序键。如果定义了 engine，则不能使用。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 order_by 参数
storage_policy 该表使用的存储策略名称 (可选) 。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 storage_policy 参数
settings 控制 MergeTree 行为的附加参数 (可选) 。 如果为系统表指定了 engine，则应直接在 'engine' 内指定 settings 参数
flush_interval_milliseconds 将数据从内存缓冲区刷写到表的时间间隔。 7500
max_size_rows 日志的最大行数。当未刷写的日志数量达到 max_size 时，日志会被转储到磁盘。 1048576
reserved_size_rows 为日志预分配的内存行数。 8192
buffer_size_rows_flush_threshold 行数阈值。达到该阈值后，会在后台启动将日志刷写到磁盘的操作。 max_size_rows / 2
flush_on_crash 设置在发生崩溃时是否将日志转储到磁盘。 false

此外，以下服务器级设置控制所有系统日志表的默认刷写策略：

<default_system_log_flush_policy>
    <skip_alias_columns>true</skip_alias_columns>
</default_system_log_flush_policy>
设置 描述 默认值
skip_alias_columns 为 true 时，系统日志表的 schema 中会省略 ALIAS 列。S3 支持的系统日志需要启用此项。 false

如果该表不存在，ClickHouse 会创建它。如果在 ClickHouse 服务器 更新后，查询视图日志的结构发生了变化，则会将旧结构的表重命名，并自动创建一个新表。

示例

<query_views_log>
    <database>system</database>
    <table>query_views_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <max_size_rows>1048576</max_size_rows>
    <reserved_size_rows>8192</reserved_size_rows>
    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
    <flush_on_crash>false</flush_on_crash>
</query_views_log>
Navigation