databendlabs · BohuTANG · Jun 3, 2025 · Jun 3, 2025
diff --git a/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/_category_.json b/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/_category_.json
@@ -0,0 +1,3 @@
+{
+    "label": "系统历史表"
+}
diff --git a/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/index.md b/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/index.md
@@ -0,0 +1,55 @@
+---
+title: 系统历史表
+---
+
+# 系统历史表
+
+系统历史表在 `system_history` schema 中持久化存储数据，用于审计、故障排查和合规目的。这些表跟踪查询执行、用户登录和系统日志信息，可通过标准 SQL 进行查询。
+
+## 可用的系统历史表
+
+| 表                                               | 描述                                                     |
+|--------------------------------------------------|---------------------------------------------------------|
+| [system_history.log_history](log-history.md)     | 存储来自各系统组件的原始日志条目                        |
+| [system_history.query_history](query-history.md)  | 存储查询执行的结构化详情                                |
+| [system_history.profile_history](profile-history.md) | 存储详细的查询执行详情和统计信息                      |
+| [system_history.login_history](login-history.md)  | 记录用户登录事件                                        |
+
+## 启用系统历史表
+
+> **注意**：在 **Databend Cloud** 中，系统历史表会自动启用且无需配置。以下内容仅适用于**自托管 Databend**。
+
+在自托管 Databend 中，系统历史表默认禁用。需在 `databend-query.toml` 文件中配置 `[log.history]` 部分来启用。
+
+<details>
+<summary>配置示例</summary>
+
+```toml
+[log.history]
+# 开启历史表功能
+on = true
+level = "INFO"
+
+# 配置各表的保留策略
+[[log.history.tables]]
+table_name = "log_history"
+retention = 168  # 7 天（单位：小时）
+
+[[log.history.tables]]
+table_name = "query_history"
+retention = 168
+
+[[log.history.tables]]
+table_name = "profile_history"
+retention = 168
+
+[[log.history.tables]]
+table_name = "login_history"
+retention = 168
+```
+
+> **注意**：开启历史日志功能时，`log_history` 表默认启用。
+
+</details>
+
+完整配置选项详见[查询配置：[log.history] 部分](/guides/deploy/references/node-config/query-config#loghistory-section)。
diff --git a/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/log-history.md b/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/log-history.md
@@ -0,0 +1,45 @@
+---
+title: system_history.log_history
+---
+
+存储从各种节点采集的原始日志条目。此表作为后续日志转换的主要数据源。
+
+所有其他日志表均派生自此表，区别在于其他日志表会对数据进行转换，使其结构更加清晰。
+
+```sql
+DESCRIBE system_history.log_history;
+
+╭──────────────────────────────────────────────────────╮
+│     Field    │    Type   │  Null  │ Default │  Extra │
+│    String    │   String  │ String │  String │ String │
+├──────────────┼───────────┼────────┼─────────┼────────┤
+│ timestamp    │ TIMESTAMP │ YES    │ NULL    │        │
+│ path         │ VARCHAR   │ YES    │ NULL    │        │
+│ target       │ VARCHAR   │ YES    │ NULL    │        │
+│ log_level    │ VARCHAR   │ YES    │ NULL    │        │
+│ cluster_id   │ VARCHAR   │ YES    │ NULL    │        │
+│ node_id      │ VARCHAR   │ YES    │ NULL    │        │
+│ warehouse_id │ VARCHAR   │ YES    │ NULL    │        │
+│ query_id     │ VARCHAR   │ YES    │ NULL    │        │
+│ message      │ VARCHAR   │ YES    │ NULL    │        │
+│ fields       │ VARIANT   │ YES    │ NULL    │        │
+│ batch_number │ BIGINT    │ YES    │ NULL    │        │
+╰──────────────────────────────────────────────────────╯
+```
+
+```sql
+SELECT * FROM system_history.log_history LIMIT 1;
+
+*************************** 1. row ***************************
+   timestamp: 2025-06-03 01:29:49.335455
+        path: databend_common_meta_client::channel_manager: channel_manager.rs:86
+      target: databend_common_meta_client::channel_manager
+   log_level: INFO
+  cluster_id: test_cluster
+     node_id: CkdmtwYXLRMhJIvVzl6i11
+warehouse_id: NULL
+    query_id: NULL
+     message: MetaChannelManager done building RealClient to 127.0.0.1:9191, start handshake
+      fields: {}
+batch_number: 41
+```
diff --git a/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/login-history.md b/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/login-history.md
@@ -0,0 +1,41 @@
+---
+title: system_history.login_history
+---
+
+记录系统所有登录尝试，包括成功和失败的登录事件。此表适用于用户访问审计和身份验证问题诊断。
+
+登录成功示例：
+```sql
+SELECT * FROM system_history.login_history LIMIT 1;
+
+*************************** 1. row ***************************
+    event_time: 2025-06-03 06:04:57.353108
+       handler: HTTP
+    event_type: LoginSuccess
+connection_uri: /query
+     auth_type: Password
+     user_name: root
+     client_ip: 127.0.0.1
+    user_agent: bendsql/0.26.2-unknown
+    session_id: 9a3ba9d8-44d9-49ca-9446-501deaca15c9
+       node_id: 765ChL6Ra949Ioeb5LrTs
+ error_message: 
+```
+
+登录失败示例：
+```sql
+SELECT * FROM system_history.login_history LIMIT 1;
+
+*************************** 1. row ***************************
+    event_time: 2025-06-03 06:07:32.512021
+       handler: MySQL
+    event_type: LoginFailed
+connection_uri: 
+     auth_type: Password
+     user_name: root1
+     client_ip: 127.0.0.1:62050
+    user_agent: 
+    session_id: 4fb87258-865a-402c-8680-e3be1e01b4e6
+       node_id: 765ChL6Ra949Ioeb5LrTs
+ error_message: UnknownUser. Code: 2201, Text = User 'root1'@'%' does not exist..
+```
diff --git a/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/profile-history.md b/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/profile-history.md
@@ -0,0 +1,28 @@
+---
+title: system_history.profile_history
+---
+用于存储 Databend 中 SQL 查询的详细执行配置文件。每个条目提供性能指标和执行统计信息，便于用户分析并优化查询性能。
+
+`profiles` 字段包含详细信息的 JSON 对象。
+
+```sql
+DESCRIBE system_history.profile_history;
+
+╭─────────────────────────────────────────────────────────╮
+│      Field      │    Type   │  Null  │ Default │  Extra │
+│      String     │   String  │ String │  String │ String │
+├─────────────────┼───────────┼────────┼─────────┼────────┤
+│ timestamp       │ TIMESTAMP │ YES    │ NULL    │        │
+│ query_id        │ VARCHAR   │ YES    │ NULL    │        │
+│ profiles        │ VARIANT   │ YES    │ NULL    │        │
+│ statistics_desc │ VARIANT   │ YES    │ NULL    │        │
+╰─────────────────────────────────────────────────────────╯
+```
+
+`profiles` 字段可用于提取特定信息。例如，要获取每个物理计划的 `OutputRows` 值，可执行以下查询：
+```sql
+SELECT jq('[.[] | {id, output_rows: .statistics[4]}]', profiles ) AS result FROM system_history.profile_history LIMIT 1;
+
+*************************** 1. row ***************************
+result: [{"id":0,"output_rows":1},{"id":3,"output_rows":8},{"id":1,"output_rows":1},{"id":2,"output_rows":1}]
+```
diff --git a/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/query-history.md b/docs/cn/sql-reference/00-sql-reference/32-system-history-tables/query-history.md
@@ -0,0 +1,110 @@
+---
+title: system_history.query_history
+---
+
+详细记录 Databend 中所有 SQL 查询的执行日志。每个查询会生成两条记录：起始记录和完成记录。该表对监控查询活动、审计用户行为及分析性能指标具有重要价值。
+
+```sql
+SELECT * FROM system_history.query_history LIMIT 2;
+
+*************************** 1. row ***************************
+                log_type: 1
+           log_type_name: Start
+            handler_type: HTTPQuery
+               tenant_id: test_tenant
+              cluster_id: test_cluster
+                 node_id: CkdmtwYXLRMhJIvVzl6i11
+                sql_user: root
+          sql_user_quota: NULL
+     sql_user_privileges: NULL
+                query_id: 55758078-e85d-4fac-95fc-0203ba0d68b2
+              query_kind: Query
+              query_text: SELECT * FROM system_history.log_history LIMIT 1
+              query_hash: e67623933f7ca8c66be47f5645f02367
+query_parameterized_hash: 100446ab318d76cf2bfd2aaecff07305
+              event_date: 2025-06-03
+              event_time: 2025-06-03 01:32:49.864759
+        query_start_time: 2025-06-03 01:32:49.843950
+       query_duration_ms: 0
+query_queued_duration_ms: 0
+        current_database: default
+            written_rows: 0
+           written_bytes: 0
+       join_spilled_rows: 0
+      join_spilled_bytes: 0
+        agg_spilled_rows: 0
+       agg_spilled_bytes: 0
+   group_by_spilled_rows: 0
+  group_by_spilled_bytes: 0
+        written_io_bytes: 0
+written_io_bytes_cost_ms: 0
+               scan_rows: 0
+              scan_bytes: 0
+           scan_io_bytes: 0
+   scan_io_bytes_cost_ms: 0
+         scan_partitions: 0
+        total_partitions: 0
+             result_rows: 0
+            result_bytes: 0
+  bytes_from_remote_disk: 0
+   bytes_from_local_disk: 0
+       bytes_from_memory: 0
+          client_address: 127.0.0.1
+              user_agent: bendsql/0.26.2-unknown
+          exception_code: 0
+          exception_text: 
+          server_version: v1.2.747-nightly-1ed0ae8571(rust-1.88.0-nightly-2025-06-03T01:16:19.413296000Z)
+               query_tag: 
+             has_profile: NULL
+       peek_memory_usage: {}
+*************************** 2. row ***************************
+                log_type: 2
+           log_type_name: Finish
+            handler_type: HTTPQuery
+               tenant_id: test_tenant
+              cluster_id: test_cluster
+                 node_id: CkdmtwYXLRMhJIvVzl6i11
+                sql_user: root
+          sql_user_quota: NULL
+     sql_user_privileges: NULL
+                query_id: 55758078-e85d-4fac-95fc-0203ba0d68b2
+              query_kind: Query
+              query_text: SELECT * FROM system_history.log_history LIMIT 1
+              query_hash: e67623933f7ca8c66be47f5645f02367
+query_parameterized_hash: 100446ab318d76cf2bfd2aaecff07305
+              event_date: 2025-06-03
+              event_time: 2025-06-03 01:32:49.878900
+        query_start_time: 2025-06-03 01:32:49.843950
+       query_duration_ms: 34
+query_queued_duration_ms: 0
+        current_database: default
+            written_rows: 0
+           written_bytes: 0
+       join_spilled_rows: 0
+      join_spilled_bytes: 0
+        agg_spilled_rows: 0
+       agg_spilled_bytes: 0
+   group_by_spilled_rows: 0
+  group_by_spilled_bytes: 0
+        written_io_bytes: 0
+written_io_bytes_cost_ms: 0
+               scan_rows: 38
+              scan_bytes: 30922
+           scan_io_bytes: 0
+   scan_io_bytes_cost_ms: 0
+         scan_partitions: 0
+        total_partitions: 0
+             result_rows: 1
+            result_bytes: 1156
+  bytes_from_remote_disk: 7580
+   bytes_from_local_disk: 0
+       bytes_from_memory: 0
+          client_address: 127.0.0.1
+              user_agent: bendsql/0.26.2-unknown
+          exception_code: 0
+          exception_text: 
+          server_version: v1.2.747-nightly-1ed0ae8571(rust-1.88.0-nightly-2025-06-03T01:16:19.413296000Z)
+               query_tag: 
+             has_profile: NULL
+       peek_memory_usage: {"CkdmtwYXLRMhJIvVzl6i11":571809}
+```