> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 包含已执行查询相关信息的系统表，例如开始时间、处理耗时和错误消息。

# system.query_log

<Info>
  **在 ClickHouse Cloud 中查询**

  此系统表中的数据分别保存在 ClickHouse Cloud 各节点的本地。因此，如需查看所有数据的完整情况，需要使用 `clusterAllReplicas` 函数。更多详情请参见[此处](/zh/reference/system-tables/overview#system-tables-in-clickhouse-cloud)。
</Info>

<div id="description">
  ## 描述
</div>

存储已执行查询的元数据和统计信息，例如开始时间、耗时、错误消息、资源使用情况以及其他执行细节。它不存储查询结果。

您可以在服务器配置的 [query\_log](/zh/reference/settings/server-settings/settings#query_log) 部分修改查询日志设置。

您可以通过设置 [log\_queries = 0](/zh/reference/settings/session-settings#log_queries) 来禁用查询日志。我们不建议关闭日志，因为此表中的信息对于排查问题非常重要。

数据的刷写周期在 [query\_log](/zh/reference/settings/server-settings/settings#query_log) 服务器设置部分的 `flush_interval_milliseconds` 参数中设置。要强制刷写，请使用 [SYSTEM FLUSH LOGS](/zh/reference/statements/system#flush-logs) 查询。

ClickHouse 不会自动从该表中删除数据。更多详细信息，请参见 [Introduction](/zh/reference/system-tables/overview#system-tables-introduction)。

`system.query_log` 表会记录两类查询：

1. 由客户端直接运行的初始查询。
2. 由其他查询发起的子查询 (用于分布式查询执行) 。对于这类查询，父查询的信息会显示在 `initial_*` 列中。

根据查询的状态 (参见 `type` 列) ，每个查询会在 `query_log` 表中创建一行或两行：

1. 如果查询执行成功，则会创建两行，类型分别为 `QueryStart` 和 `QueryFinish`。
2. 如果在查询处理期间发生错误，则会创建两个事件，类型分别为 `QueryStart` 和 `ExceptionWhileProcessing`。
3. 如果在启动查询之前发生错误，则会创建一个类型为 `ExceptionBeforeStart` 的事件。

您可以使用 [log\_queries\_probability](/zh/reference/settings/session-settings#log_queries_probability) 设置来减少记录到 `query_log` 表中的查询数量。

您可以使用 [log\_formatted\_queries](/zh/reference/settings/session-settings#log_formatted_queries) 设置将格式化后的查询记录到 `formatted_query` 列。

<div id="columns">
  ## 列
</div>

* `hostname` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 执行查询的服务器主机名。
* `type` ([Enum8('QueryStart' = 1, 'QueryFinish' = 2, 'ExceptionBeforeStart' = 3, 'ExceptionWhileProcessing' = 4)](/zh/reference/data-types/enum)) — 执行查询时发生的事件类型。取值：`QueryStart` — 查询执行成功开始，`QueryFinish` — 查询执行成功结束，`ExceptionBeforeStart` — 查询执行开始前发生异常，`ExceptionWhileProcessing` — 查询执行过程中发生异常。
* `event_date` ([Date](/zh/reference/data-types/date)) — 查询起始日期。
* `event_time` ([DateTime](/zh/reference/data-types/datetime)) — 查询开始时间。
* `event_time_microseconds` ([DateTime64(6)](/zh/reference/data-types/datetime64)) — 查询开始时间，精确到微秒。
* `query_start_time` ([DateTime](/zh/reference/data-types/datetime)) — 查询开始执行的时间。
* `query_start_time_microseconds` ([DateTime64(6)](/zh/reference/data-types/datetime64)) — 查询开始执行的时间，精确到微秒。
* `query_duration_ms` ([UInt64](/zh/reference/data-types/int-uint)) — 查询执行耗时 (毫秒) 。
* `read_rows` ([UInt64](/zh/reference/data-types/int-uint)) — 从参与该查询的所有表和表函数中读取的总行数。它包括常规子查询，以及用于 IN 和 JOIN 的子查询。对于分布式查询，read\_rows 包括在所有副本上读取的总行数。每个副本都会发送其 read\_rows 值，而发起查询的服务器会汇总所有接收到的值以及本地值。缓存中的数据量不会影响该值。
* `read_bytes` ([UInt64](/zh/reference/data-types/int-uint)) — 查询中涉及的所有表和表函数读取的总字节数。它包括常规子查询，以及用于 IN 和 JOIN 的子查询。对于分布式查询，read\_bytes 包含从所有副本读取的总行数。每个副本都会发送其 read\_bytes 值，而查询的发起服务器会汇总所有接收到的值以及本地值。缓存容量不会影响此值。
* `written_rows` ([UInt64](/zh/reference/data-types/int-uint)) — 该查询写入的行数，包括由管道触发的下游 insert 所写入的任何行，例如处于 attached 状态的 materialized view。对于同步 insert，这些下游行记录在 `query_kind` = `Insert` 条目上；对于异步 insert，这些行记录在 `query_kind` = `AsyncInsertFlush` 条目上，而面向客户端的 `Insert` 条目仅记录从客户端接收的行。对于不写入行的查询，该值为 0。
* `written_bytes` ([UInt64](/zh/reference/data-types/int-uint)) — 该查询写入的字节数 (未压缩) ，包括由管道触发的下游 insert 所写入的任何字节，例如处于 attached 状态的 materialized view。对于同步 insert，这些下游字节记录在 `query_kind` = `Insert` 条目上；对于异步 insert，这些字节记录在 `query_kind` = `AsyncInsertFlush` 条目上，而面向客户端的 `Insert` 条目仅记录从客户端接收的字节。对于不写入数据的查询，该值为 0。
* `result_rows` ([UInt64](/zh/reference/data-types/int-uint)) — SELECT 查询结果中的行数，或 insert 写入的行数。对于同步 insert，这包括在 `query_kind` = `Insert` 条目上记录的、由管道触发的下游 insert 所写入的行 (例如处于 attached 状态的 materialized view) ；对于异步 insert，这些下游行记录在 `query_kind` = `AsyncInsertFlush` 条目上，而面向客户端的 `Insert` 条目仅记录从客户端接收的行。
* `result_bytes` ([UInt64](/zh/reference/data-types/int-uint)) — 用于存储查询结果所占用的 RAM 字节数。
* `memory_usage` ([UInt64](/zh/reference/data-types/int-uint)) — 查询的内存占用。
* `current_database` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 当前 database 的名称。
* `query` ([String](/zh/reference/data-types/string)) — 查询字符串。
* `formatted_query` ([String](/zh/reference/data-types/string)) — 格式化后的查询字符串。
* `normalized_query_hash` ([UInt64](/zh/reference/data-types/int-uint)) — 数值型哈希值；对于仅字面量值不同的查询，该值相同。
* `query_kind` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 查询类型。
* `databases` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询中涉及的数据库名称。
* `tables` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询中涉及的表名称。
* `columns` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询中包含的列名。
* `partitions` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询中包含的分区名称。
* `projections` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间使用的投影名称。
* `views` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询中包含的 (物化或实时) 视图名称。
* `exception_code` ([Int32](/zh/reference/data-types/int-uint)) — 异常代码。
* `exception` ([String](/zh/reference/data-types/string)) — 异常信息。
* `stack_trace` ([String](/zh/reference/data-types/string)) — 堆栈跟踪。如果查询成功完成，则为空字符串。
* `is_initial_query` ([UInt8](/zh/reference/data-types/int-uint)) — 查询类型。可能的值：1 — 查询由客户端发起，0 — 查询由另一条查询在分布式查询执行过程中发起。
* `connection_address` ([IPv6](/zh/reference/data-types/ipv6)) — 发起连接的客户端 IP 地址。通过代理连接时，此地址为代理的地址。
* `connection_port` ([UInt16](/zh/reference/data-types/int-uint)) — 建立连接的客户端端口。通过代理连接时，该端口为代理端口。
* `user` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 发起当前查询的用户名。
* `query_id` ([String](/zh/reference/data-types/string)) — 查询 ID。
* `address` ([IPv6](/zh/reference/data-types/ipv6)) — 用于执行查询的 IP 地址。若通过代理连接且设置了 `auth_use_forwarded_address`，这里显示的将是客户端地址，而非代理地址。
* `port` ([UInt16](/zh/reference/data-types/int-uint)) — 用于发起查询的客户端端口。若通过代理连接且设置了 `auth_use_forwarded_address`，则此处显示的是客户端端口，而非代理端口。
* `initial_user` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 执行初始查询的用户名 (用于分布式查询执行) 。
* `initial_query_id` ([String](/zh/reference/data-types/string)) — 初始查询 ID (用于分布式查询执行) 。
* `initial_address` ([IPv6](/zh/reference/data-types/ipv6)) — 发起父查询时所使用的 IP 地址。
* `initial_port` ([UInt16](/zh/reference/data-types/int-uint)) — 发起父查询时使用的客户端端口。
* `initial_query_start_time` ([DateTime](/zh/reference/data-types/datetime)) — 初始查询的开始时间 (用于分布式查询执行) 。
* `initial_query_start_time_microseconds` ([DateTime64(6)](/zh/reference/data-types/datetime64)) — 初始查询开始时间，精确到微秒 (适用于分布式查询执行) 。
* `authenticated_user` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 该会话中已通过身份验证的用户名。
* `interface` ([UInt8](/zh/reference/data-types/int-uint)) — 发起查询所使用的接口。可能的值：1 — TCP，2 — HTTP。
* `is_secure` ([UInt8](/zh/reference/data-types/int-uint)) — 表示查询是否通过安全接口执行的标志
* `os_user` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 运行 clickhouse-client 的操作系统用户名。
* `client_hostname` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 运行 clickhouse-client 或其他 TCP 客户端的客户端主机的主机名。
* `client_name` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — clickhouse-client 或其他 TCP 客户端的名称。
* `client_agent` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — 调用该客户端的 AI 编码 agent (例如 `claude-code` 或 `cursor`) ，通过环境变量检测得出。如果未检测到 agent，则为空。
* `client_revision` ([UInt32](/zh/reference/data-types/int-uint)) — clickhouse-client 或其他 TCP 客户端的修订号。
* `client_version_major` ([UInt32](/zh/reference/data-types/int-uint)) — `clickhouse-client` 或其他 TCP 客户端的主版本号。
* `client_version_minor` ([UInt32](/zh/reference/data-types/int-uint)) — clickhouse-client 或其他 TCP 客户端的次要版本号。
* `client_version_patch` ([UInt32](/zh/reference/data-types/int-uint)) — clickhouse-client 或其他 TCP 客户端版本的补丁版本号部分。
* `script_query_number` ([UInt32](/zh/reference/data-types/int-uint)) — 在 clickhouse-client 中，多查询脚本中的查询编号。
* `script_line_number` ([UInt32](/zh/reference/data-types/int-uint)) — 在包含多个查询的脚本中，clickhouse-client 使用的查询起始行号。
* `http_method` ([UInt8](/zh/reference/data-types/int-uint)) — 发起该查询的 HTTP 方法。可能的值：0 — 查询通过 TCP 接口发起，1 — 使用了 GET 方法，2 — 使用了 POST 方法。
* `http_user_agent` ([LowCardinality(String)](/zh/reference/data-types/lowcardinality)) — HTTP 查询中传递的 HTTP 请求头 UserAgent。
* `http_referer` ([String](/zh/reference/data-types/string)) — 在 HTTP 查询中传递的 HTTP 请求头 Referer (包含发出该查询的页面的完整或部分地址) 。
* `forwarded_for` ([String](/zh/reference/data-types/string)) — 在 HTTP 查询里传递的 HTTP 请求头 X-Forwarded-For。
* `quota_key` ([String](/zh/reference/data-types/string)) — 在 quotas 设置中指定的配额键 (请参见 keyed) 。
* `distributed_depth` ([UInt64](/zh/reference/data-types/int-uint)) — 查询在各服务器之间被转发的次数。
* `revision` ([UInt32](/zh/reference/data-types/int-uint)) — ClickHouse 修订号。
* `log_comment` ([String](/zh/reference/data-types/string)) — 日志注释。可设置为任意字符串，长度不超过 max\_query\_size。若未定义，则为空字符串。
* `thread_ids` ([Array(UInt64)](/zh/reference/data-types/array)) — 参与执行查询的线程 ID。这些线程不一定是同时运行的。
* `peak_threads_usage` ([UInt64](/zh/reference/data-types/int-uint)) — 同时执行该查询的线程数上限。
* `ProfileEvents` ([Map(LowCardinality(String), UInt64)](/zh/reference/data-types/map)) — 用于记录不同指标的 ProfileEvents。其说明可在 system.events 表中找到
* `Settings` ([Map(LowCardinality(String), LowCardinality(String))](/zh/reference/data-types/map)) — 客户端执行查询时发生变更的设置。要启用设置变更的日志记录，请将 log\_query\_settings 参数设为 1。
* `used_aggregate_functions` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行过程中使用的聚合函数的规范名称。
* `used_aggregate_function_combinators` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间使用的聚合函数组合器的规范名称。
* `used_database_engines` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行过程中使用的数据库引擎的规范名称。
* `used_data_type_families` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间使用的数据类型族的规范名称。
* `used_dictionaries` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间所使用字典的规范名称。
* `used_formats` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间所用格式的规范名称。
* `used_functions` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行过程中使用的函数的规范名称。
* `used_storages` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间使用的存储的规范名称。
* `used_table_functions` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行过程中使用的表函数的规范名称。
* `used_executable_user_defined_functions` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间所使用的可执行用户自定义函数的标准名称。
* `used_sql_user_defined_functions` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间使用的 SQL 用户自定义函数的规范名称。
* `used_row_policies` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间所使用的行策略名称列表。
* `used_privileges` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间成功通过校验的权限。
* `missing_privileges` ([Array(LowCardinality(String))](/zh/reference/data-types/array)) — 查询执行期间缺少的权限。
* `transaction_id` ([Tuple(UInt64, UInt64, UUID)](/zh/reference/data-types/tuple)) — 执行该查询时所属事务的标识符。
* `query_cache_usage` ([Enum8('Unknown' = 0, 'None' = 1, 'Write' = 2, 'Read' = 3)](/zh/reference/data-types/enum)) — 查询执行过程中对查询缓存的使用情况。值：'Unknown' = 状态未知，'None' = 查询结果既未写入查询结果缓存，也未从查询结果缓存中读取，'Write' = 查询结果已写入查询结果缓存，'Read' = 查询结果已从查询结果缓存中读取。
* `asynchronous_read_counters` ([Map(LowCardinality(String), UInt64)](/zh/reference/data-types/map)) — 异步读取的指标。
* `is_internal` ([UInt8](/zh/reference/data-types/int-uint)) — 表示该查询是否为内部执行的辅助查询。

**别名：**

* `ProfileEvents.Names` — `mapKeys(ProfileEvents)` 的别名。
* `ProfileEvents.Values` — `mapValues(ProfileEvents)` 的别名。
* `Settings.Names` — `mapKeys(Settings)` 的别名。
* `Settings.Values` — `mapValues(Settings)` 的别名。

<div id="examples">
  ## 示例
</div>

**基本示例**

```sql theme={null}
SELECT * FROM system.query_log WHERE type = 'QueryFinish' ORDER BY query_start_time DESC LIMIT 1 FORMAT Vertical;
```

```text theme={null}
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:                     None
```

**Cloud 示例**

在 ClickHouse Cloud 中，`system.query_log` 仅存在于各个节点本地；要查看所有记录，必须通过 [`clusterAllReplicas`](/zh/reference/functions/table-functions/cluster) 发起查询。

例如，要汇总 “default” 集群中每个副本上的 query\_log 行，可以这样写：

```sql theme={null}
SELECT * 
FROM clusterAllReplicas('default', system.query_log)
WHERE event_time >= now() - toIntervalHour(1)
LIMIT 10
SETTINGS skip_unavailable_shards = 1;
```

<div id="see-also">
  ## 另请参见
</div>

* [system.query\_thread\_log](/zh/reference/system-tables/query_thread_log) — 此表包含每个查询执行线程的信息。