事件数据模型

greptime_private.events 有以下公共列。

列	含义
type	事件类型，例如 create_table 或 region_migration。
timestamp	记录该行的时间。
payload	与事件类型相关的 JSON 数据。
actor	记录为操作发起人的数据库用户；事件没有关联用户请求时为 SQL NULL。
event_context	有上下文时，用于描述事件触发原因的 JSON。

事件发起人（actor）

actor 表示 GreptimeDB 记录的操作发起用户，可用于查找谁执行了 ADMIN 语句， 或谁提交了 Procedure。

当一次操作触发 Procedure 时，GreptimeDB 会将数据库用户记录为 actor。该 Procedure 及其启动的子 Procedure 会在整个生命周期内沿用这个值。没有关联用户 请求的事件，其 actor 为 SQL NULL。

启用鉴权后， actor 是通过身份验证的数据库用户。未启用鉴权时，actor 不能用于确认实际 调用者：MySQL 和 PostgreSQL 记录客户端提供的用户名，HTTP 和 gRPC 则记录 默认用户 greptime。

Procedure 事件列

Procedure 事件还有以下列：

列	含义
procedure_id	Procedure 的唯一 ID。
procedure_state	记录事件时的 Procedure 状态。取值为 Running、Done、Retrying、PrepareRollback、RollingBack、Failed 和 Poisoned。
procedure_trigger	Procedure 事件触发信息，采用 JSON 格式。type 可为 Submitted、Recovered、ChildSubmitted、Retrying、RollingBack、Succeeded、Failed 或 Poisoned。
procedure_error	Procedure 出错时的 Debug 格式错误信息；其他情况为空字符串。

触发类型为 Submitted 的事件状态通常为 Running。Procedure 成功完成后，完成记录的状态为 Done，触发类型为 Succeeded。完成记录根据 Procedure 完成时的状态生成，因此字段可能 与提交时的记录不同。事件会异步写入，写入失败不会影响 Procedure 的执行结果。

event_context 只写入 Submitted 记录。存在该字段时，其中稳定的 reason 值可以是 manual、auto_create、auto_alter、auto_repartition、auto_rebalance、 region_failover、scheduled_gc 或 unknown。例如，通过 MySQL 提交的事件可能包含 {"protocol":"mysql","reason":"manual"}。

除 Submitted 和 Succeeded 外，Procedure 还可能在适用时产生以下触发类型。 并非每个 Procedure 都会产生所有触发类型，记录顺序也不保证与下表一致：

type	含义和字段
Recovered	根 Procedure 从持久化状态恢复。
ChildSubmitted	尝试提交子 Procedure。procedure_trigger 包含子 Procedure 的 procedure_id 和提交 outcome（Accepted、AlreadyAccepted、ManagerStopped 或 SpawnFailed）。
Retrying	正在重试 Procedure 的执行或回滚。procedure_trigger 包含重试 phase（Execute 或 Rollback）和 attempt。
RollingBack	开始回滚 Procedure。
Failed	Procedure 到达失败终态。请检查 procedure_error 中的失败详情。
Poisoned	Procedure 无法继续。请检查 procedure_error 中的失败详情。

管理函数事件列

admin_function 事件记录 ADMIN 语句返回的结果。

列	含义
admin_function_name	执行的管理函数名称。
admin_function_status	执行状态：Succeeded 或 Failed。
admin_function_output	JSON 数据。函数成功时包含 result，函数失败时包含 error。

事件的 payload 包含函数参数。如果返回结果是 Procedure ID，可使用该 ID 查询 Procedure 事件以查看执行进度。

查询 JSON 字段

详细信息请参阅 JSON 函数。在事件查询中， json_to_string 将 JSON 值转换为可读文本，json_get_string 按路径提取值， json_path_match 计算 JSON 谓词，json_is_null 检查值是否为 JSON null。如需检查 SQL NULL，应单独使用 IS NULL。

例如，以下查询从包含 event_context 的 create_table 行中提取相关字段：

SELECT procedure_state,
       json_get_string(procedure_trigger, 'type') AS trigger_type,
       json_path_match(procedure_trigger, '$.type == "Submitted"') AS is_submitted,
       json_get_string(event_context, 'reason') AS reason
FROM greptime_private.events
WHERE type = 'create_table'
  AND timestamp >= now() - INTERVAL '1' hour
  AND schema_name = '<database_name>'
  AND table_name = '<table_name>'
  AND event_context IS NOT NULL
ORDER BY timestamp;

+-----------------+--------------+--------------+--------+
| procedure_state | trigger_type | is_submitted | reason |
+-----------------+--------------+--------------+--------+
| Running         | Submitted    |            1 | manual |
+-----------------+--------------+--------------+--------+

JSON null 和 SQL NULL

在 create_table 示例以及 DDL/repartition Procedure 完成后产生的事件中，终态 payload 可能是 JSON null，而不是 SQL NULL：

SELECT procedure_state, json_to_string(payload) AS payload,
       payload IS NULL AS payload_is_sql_null,
       json_is_null(payload) AS payload_is_json_null,
       json_get_string(procedure_trigger, 'type') AS trigger_type
FROM greptime_private.events
WHERE type = 'create_table'
  AND timestamp >= now() - INTERVAL '1' hour
  AND schema_name = '<database_name>'
  AND table_name = '<table_name>'
ORDER BY timestamp;

+-----------------+------------------------------------------------------------+---------------------+----------------------+--------------+
| procedure_state | payload                                                    | payload_is_sql_null | payload_is_json_null | trigger_type |
+-----------------+------------------------------------------------------------+---------------------+----------------------+--------------+
| Running         | {"create_if_not_exists":false,"engine":"mito","version":1} | 0                   | 0                    | Submitted    |
| Done            | null                                                       | 0                   | 1                    | Succeeded    |
+-----------------+------------------------------------------------------------+---------------------+----------------------+--------------+

Procedure 事件的专用列

以下列只会在对应事件类型中填充；不适用时为 SQL NULL。

• 数据库、表和视图事件： catalog_name、schema_name 以及适用的表或视图名称和 ID 列用于标识对象。Flow 事件使用 catalog_name 和 flow_name；其 schema_name 为 SQL NULL。physical_table_id 仅适用于 create_logical_tables 和 alter_logical_tables。详见 DDL 事件。
• Region 迁移： region_id、region_number 标识 Region； region_migration_trigger_reason、region_migration_src_node_id、 region_migration_src_peer_addr、region_migration_dst_node_id 和 region_migration_dst_peer_addr 记录迁移原因、源端和目标端。
• Repartition： catalog_name、schema_name、table_name 和 table_id 标识受影响的表。 parent_procedure_id 关联父 Procedure，repartition_group_id 标识分组操作。 source_region_id、source_region_number、source_partition_expr、 target_region_id、target_region_number 和 target_partition_expr 描述源和目标 Region 及其分区表达式。
• 批量 GC： region_id、region_number 和 gc_report 记录处理的 Region 及 GC 结果。
• WAL 清理： topic_name、prunable_entry_id 和 latest_offset 分别表示 topic、 请求的清理边界和排他的最新 offset。