Set up docs MCP描述
存储已执行查询的元数据和统计信息，例如开始时间、耗时、错误消息、资源使用情况以及其他执行细节。它不存储查询结果。
您可以在服务器配置的 query_log 部分修改查询日志设置。
您可以通过设置 log_queries = 0 来禁用查询日志。我们不建议关闭日志，因为此表中的信息对于排查问题非常重要。
数据的刷写周期在 query_log 服务器设置部分的 flush_interval_milliseconds 参数中设置。要强制刷写，请使用 SYSTEM FLUSH LOGS 查询。
ClickHouse 不会自动从该表中删除数据。更多详细信息，请参见 Introduction。
system.query_log 表会记录两类查询：
- 初始 (顶级) 查询。
- 由其他查询发起的子查询，包括用于分布式执行的查询以及诸如视图评估等内部子查询。对于这些查询，原始初始查询的信息会显示在
initial_*列中。
根据查询的状态 (参见 type 列) ，每个查询会在 query_log 表中创建一行或两行：
- 如果查询执行成功，则会创建两行，类型分别为
QueryStart和QueryFinish。 - 如果在查询处理期间发生错误，则会创建两个事件，类型分别为
QueryStart和ExceptionWhileProcessing。 - 如果在启动查询之前发生错误，则会创建一个类型为
ExceptionBeforeStart的事件。
您可以使用 log_queries_probability 设置来减少记录到 query_log 表中的查询数量。
您可以使用 log_formatted_queries 设置将格式化后的查询记录到 formatted_query 列。
列
hostname(LowCardinality(String)) — 执行查询的服务器主机名。type(Enum8('QueryStart' = 1, 'QueryFinish' = 2, 'ExceptionBeforeStart' = 3, 'ExceptionWhileProcessing' = 4)) — 执行查询时发生的事件类型。取值：QueryStart— 查询执行成功开始，QueryFinish— 查询执行成功结束，ExceptionBeforeStart— 查询执行开始前发生异常，ExceptionWhileProcessing— 查询执行过程中发生异常。event_date(Date) — 查询起始日期。event_time(DateTime) — 查询开始时间。event_time_microseconds(DateTime64(6)) — 查询开始时间，精确到微秒。query_start_time(DateTime) — 查询开始执行的时间。query_start_time_microseconds(DateTime64(6)) — 查询开始执行的时间，精确到微秒。query_duration_ms(UInt64) — 查询执行耗时 (毫秒) 。read_rows(UInt64) — 从参与该查询的所有表和表函数中读取的总行数。它包括常规子查询，以及用于 IN 和 JOIN 的子查询。对于分布式查询，read_rows 包括在所有副本上读取的总行数。每个副本都会发送其 read_rows 值，而发起查询的服务器会汇总所有接收到的值以及本地值。缓存中的数据量不会影响该值。read_bytes(UInt64) — 查询中涉及的所有表和表函数读取的总字节数。它包括常规子查询，以及用于 IN 和 JOIN 的子查询。对于分布式查询，read_bytes 包含从所有副本读取的总行数。每个副本都会发送其 read_bytes 值，而查询的发起服务器会汇总所有接收到的值以及本地值。缓存容量不会影响此值。written_rows(UInt64) — 该查询写入的行数，包括由管道触发的下游 insert 所写入的任何行，例如处于 attached 状态的 materialized view。对于同步 insert，这些下游行记录在query_kind=Insert条目上；对于异步 insert，这些行记录在query_kind=AsyncInsertFlush条目上，而面向客户端的Insert条目仅记录从客户端接收的行。对于不写入行的查询，该值为 0。written_bytes(UInt64) — 该查询写入的字节数 (未压缩) ，包括由管道触发的下游 insert 所写入的任何字节，例如处于 attached 状态的 materialized view。对于同步 insert，这些下游字节记录在query_kind=Insert条目上；对于异步 insert，这些字节记录在query_kind=AsyncInsertFlush条目上，而面向客户端的Insert条目仅记录从客户端接收的字节。对于不写入数据的查询，该值为 0。result_rows(UInt64) — SELECT 查询结果中的行数，或 insert 写入的行数。对于同步 insert，这包括在query_kind=Insert条目上记录的、由管道触发的下游 insert 所写入的行 (例如处于 attached 状态的 materialized view) ；对于异步 insert，这些下游行记录在query_kind=AsyncInsertFlush条目上，而面向客户端的Insert条目仅记录从客户端接收的行。result_bytes(UInt64) — 用于存储查询结果所占用的 RAM 字节数。memory_usage(UInt64) — 查询的内存占用。current_database(LowCardinality(String)) — 当前 database 的名称。query(String) — 查询字符串。formatted_query(String) — 格式化后的查询字符串。normalized_query_hash(UInt64) — 数值型哈希值；对于仅字面量值不同的查询，该值相同。query_kind(LowCardinality(String)) — 查询类型。databases(Array(LowCardinality(String))) — 查询中涉及的数据库名称。tables(Array(LowCardinality(String))) — 查询中涉及的表名称。columns(Array(LowCardinality(String))) — 查询中包含的列名。partitions(Array(LowCardinality(String))) — 查询中包含的分区名称。projections(Array(LowCardinality(String))) — 查询执行期间使用的投影名称。views(Array(LowCardinality(String))) — 查询中包含的 (物化或实时) 视图名称。exception_code(Int32) — 异常代码。exception(String) — 异常信息。stack_trace(String) — 堆栈跟踪。如果查询成功完成，则为空字符串。is_initial_query(UInt8) — 查询是否为初始查询。可能的值：1 — 初始 (顶层) 查询，0 — 由另一条查询发起的子查询，包括用于分布式执行的查询和内部子查询。connection_address(IPv6) — 发起连接的客户端 IP 地址。通过代理连接时，此地址为代理的地址。connection_port(UInt16) — 建立连接的客户端端口。通过代理连接时，该端口为代理端口。user(LowCardinality(String)) — 发起当前查询的用户名。query_id(String) — 查询 ID。address(IPv6) — 用于执行查询的 IP 地址。若通过代理连接且设置了auth_use_forwarded_address，这里显示的将是客户端地址，而非代理地址。port(UInt16) — 用于发起查询的客户端端口。若通过代理连接且设置了auth_use_forwarded_address，则此处显示的是客户端端口，而非代理端口。initial_user(LowCardinality(String)) — 同一查询链中执行初始查询的用户名。initial_query_id(String) — 同一查询链中初始查询的 ID。initial_address(IPv6) — 同一查询链中发起初始查询的 IP 地址。initial_port(UInt16) — 同一查询链中发起初始查询的客户端端口。initial_query_start_time(DateTime) — 同一查询链中初始查询的开始时间。initial_query_start_time_microseconds(DateTime64(6)) — 同一查询链中初始查询的开始时间，精确到微秒。authenticated_user(LowCardinality(String)) — 该会话中已通过身份验证的用户名。interface(UInt8) — 发起查询所使用的接口。可能的值：1 — TCP，2 — HTTP。is_secure(UInt8) — 表示查询是否通过安全接口执行的标志os_user(LowCardinality(String)) — 运行 clickhouse-client 的操作系统用户名。client_hostname(LowCardinality(String)) — 运行 clickhouse-client 或其他 TCP 客户端的客户端主机的主机名。client_name(LowCardinality(String)) — clickhouse-client 或其他 TCP 客户端的名称。client_agent(LowCardinality(String)) — 调用该客户端的 AI 编码 agent (例如claude-code或cursor) ，通过环境变量检测得出。如果未检测到 agent，则为空。client_revision(UInt32) — clickhouse-client 或其他 TCP 客户端的修订号。client_version_major(UInt32) —clickhouse-client或其他 TCP 客户端的主版本号。client_version_minor(UInt32) — clickhouse-client 或其他 TCP 客户端的次要版本号。client_version_patch(UInt32) — clickhouse-client 或其他 TCP 客户端版本的补丁版本号部分。script_query_number(UInt32) — 在 clickhouse-client 中，多查询脚本中的查询编号。script_line_number(UInt32) — 在包含多个查询的脚本中，clickhouse-client 使用的查询起始行号。http_method(UInt8) — 发起该查询的 HTTP 方法。可能的值：0 - 查询通过 TCP 接口发起，1 - 使用了 GET 方法，2 - 使用了 POST 方法，4 - 使用了 PUT 方法，5 - 使用了 DELETE 方法，6 - 使用了 HEAD 方法。http_user_agent(LowCardinality(String)) — HTTP 查询中传递的 HTTP 请求头 UserAgent。http_referer(String) — 在 HTTP 查询中传递的 HTTP 请求头 Referer (包含发出该查询的页面的完整或部分地址) 。forwarded_for(String) — 在 HTTP 查询里传递的 HTTP 请求头 X-Forwarded-For。quota_key(String) — 在 quotas 设置中指定的配额键 (请参见 keyed) 。distributed_depth(UInt64) — 查询在各服务器之间被转发的次数。revision(UInt32) — ClickHouse 修订号。http_handler_name(String) — 调用该查询的 SQL 定义 HTTP handler (CREATE HANDLER) 的名称。若该查询并非通过此类 handler 调用，则为空。http_request_url(String) — 调用该查询的 HTTP 请求路径 (不含查询字符串) 。为避免持久化敏感请求参数，省略了查询字符串。对于非 HTTP 查询，该值为空。log_comment(String) — 日志注释。可设置为任意字符串，长度不超过 max_query_size。若未定义，则为空字符串。thread_ids(Array(UInt64)) — 参与执行查询的线程 ID。这些线程不一定是同时运行的。peak_threads_usage(UInt64) — 同时执行该查询的线程数上限。ProfileEvents(Map(LowCardinality(String), UInt64)) — 用于记录不同指标的 ProfileEvents。其说明可在 system.events 表中找到Settings(Map(LowCardinality(String), LowCardinality(String))) — 客户端执行查询时发生变更的设置。要启用设置变更的日志记录，请将 log_query_settings 参数设为 1。used_aggregate_functions(Array(LowCardinality(String))) — 查询执行过程中使用的聚合函数的规范名称。used_aggregate_function_combinators(Array(LowCardinality(String))) — 查询执行期间使用的聚合函数组合器的规范名称。used_database_engines(Array(LowCardinality(String))) — 查询执行过程中使用的数据库引擎的规范名称。used_data_type_families(Array(LowCardinality(String))) — 查询执行期间使用的数据类型族的规范名称。used_dictionaries(Array(LowCardinality(String))) — 查询执行期间所使用字典的规范名称。used_formats(Array(LowCardinality(String))) — 查询执行期间所用格式的规范名称。used_functions(Array(LowCardinality(String))) — 查询执行过程中使用的函数的规范名称。used_storages(Array(LowCardinality(String))) — 查询执行期间使用的存储的规范名称。used_table_functions(Array(LowCardinality(String))) — 查询执行过程中使用的表函数的规范名称。used_executable_user_defined_functions(Array(LowCardinality(String))) — 查询执行期间所使用的可执行用户自定义函数的标准名称。used_sql_user_defined_functions(Array(LowCardinality(String))) — 查询执行期间使用的 SQL 用户自定义函数的规范名称。used_row_policies(Array(LowCardinality(String))) — 查询执行期间所使用的行策略名称列表。used_privileges(Array(LowCardinality(String))) — 查询执行期间成功通过校验的权限。missing_privileges(Array(LowCardinality(String))) — 查询执行期间缺少的权限。transaction_id(Tuple(UInt64, UInt64, UUID)) — 执行该查询时所属事务的标识符。query_cache_usage(Enum8('Unknown' = 0, 'None' = 1, 'Write' = 2, 'Read' = 3)) — 查询执行过程中对查询缓存的使用情况。值：'Unknown' = 状态未知，'None' = 查询结果既未写入查询结果缓存，也未从查询结果缓存中读取，'Write' = 查询结果已写入查询结果缓存，'Read' = 查询结果已从查询结果缓存中读取。asynchronous_read_counters(Map(LowCardinality(String), UInt64)) — 异步读取的指标。is_internal(UInt8) — 表示该查询是否为内部执行的辅助查询。
别名：
ProfileEvents.Names—mapKeys(ProfileEvents)的别名。ProfileEvents.Values—mapValues(ProfileEvents)的别名。Settings.Names—mapKeys(Settings)的别名。Settings.Values—mapValues(Settings)的别名。
示例
基本示例
SELECT *
FROM system.query_log
WHERE type = 'QueryFinish'
AND is_initial_query = 1
ORDER BY query_start_time DESC
LIMIT 1
FORMAT Vertical;Row 1:
──────
hostname: clickhouse.eu-central1.internal
type: QueryFinish
event_date: 2021-11-03
event_time: 2021-11-03 16:13:54
event_time_microseconds: 2021-11-03 16:13:54.953024
query_start_time: 2021-11-03 16:13:54
query_start_time_microseconds: 2021-11-03 16:13:54.952325
query_duration_ms: 0
read_rows: 69
read_bytes: 6187
written_rows: 0
written_bytes: 0
result_rows: 69
result_bytes: 48256
memory_usage: 0
current_database: default
query: DESCRIBE TABLE system.query_log
formatted_query:
normalized_query_hash: 8274064835331539124
query_kind:
databases: []
tables: []
columns: []
projections: []
views: []
exception_code: 0
exception:
stack_trace:
is_initial_query: 1
user: default
query_id: 7c28bbbb-753b-4eba-98b1-efcbe2b9bdf6
address: ::ffff:127.0.0.1
port: 40452
initial_user: default
initial_query_id: 7c28bbbb-753b-4eba-98b1-efcbe2b9bdf6
initial_address: ::ffff:127.0.0.1
initial_port: 40452
initial_query_start_time: 2021-11-03 16:13:54
initial_query_start_time_microseconds: 2021-11-03 16:13:54.952325
interface: 1
os_user: sevirov
client_hostname: clickhouse.eu-central1.internal
client_name: ClickHouse
client_revision: 54449
client_version_major: 21
client_version_minor: 10
client_version_patch: 1
http_method: 0
http_user_agent:
http_referer:
forwarded_for:
quota_key:
revision: 54456
log_comment:
thread_ids: [30776,31174]
ProfileEvents: {'Query':1,'NetworkSendElapsedMicroseconds':59,'NetworkSendBytes':2643,'SelectedRows':69,'SelectedBytes':6187,'ContextLock':9,'RWLockAcquiredReadLocks':1,'RealTimeMicroseconds':817,'UserTimeMicroseconds':427,'SystemTimeMicroseconds':212,'OSCPUVirtualTimeMicroseconds':639,'OSReadChars':894,'OSWriteChars':319}
Settings: {'load_balancing':'random','max_memory_usage':'10000000000'}
used_aggregate_functions: []
used_aggregate_function_combinators: []
used_database_engines: []
used_data_type_families: []
used_dictionaries: []
used_formats: []
used_functions: []
used_storages: []
used_table_functions: []
used_executable_user_defined_functions:[]
used_sql_user_defined_functions: []
used_privileges: []
missing_privileges: []
query_cache_usage: NoneCloud 示例
在 ClickHouse Cloud 中，system.query_log 仅存在于各个节点本地；要查看所有记录，必须通过 clusterAllReplicas 发起查询。
例如，要汇总 “default” 集群中每个副本上的 query_log 行，可以这样写：
SELECT *
FROM clusterAllReplicas('default', system.query_log)
WHERE event_time >= now() - toIntervalHour(1)
LIMIT 10
SETTINGS skip_unavailable_shards = 1;另请参见
- system.query_thread_log — 此表包含每个查询执行线程的信息。