kwbase: add four MySQL-compatible metadata views · Pull Request !1887 · KWDB/kwdb

# PR Summary

## Summary

关联需求：[支持 MySQL 核心系统视图](https://gitee.com/kwdb/kwdb/issues/IKGBWY)

本分支新增或扩展四个只读元数据视图：`information_schema.user_attributes`、`information_schema.column_statistics`、`kwdb_internal.partitions` 和 `information_schema.processlist`。实现只消费既有用户、统计、分区描述符、zone 配置和集群会话数据，不修改这些数据的生成、写入、持久化格式或生命周期。

### `information_schema.user_attributes`

- 新增 MySQL 兼容的 `USER`、`HOST`、`ATTRIBUTE` 三列；`USER` 和 `ATTRIBUTE` 作为 KWDB 保留字以带引号的大写标识符定义。
- 通过既有 `forEachRole` 只读枚举 `system.users`，过滤 `isRole=true` 的 SQL 角色，仅返回登录用户账户。
- `root`、`node` 或具有 admin 角色的用户可以查看全部普通用户；非管理员只能查看当前会话用户自身，避免账户枚举。
- `USER` 取 `system.users.username`。KWDB 没有 MySQL `user@host` 账户维度，也没有账户级 JSON attribute 数据源，因此 `HOST` 和 `ATTRIBUTE` 固定返回 SQL `NULL`，不使用 `role_options` 等非等价数据代替。

### `information_schema.column_statistics`

- 新增 `SCHEMA_NAME`、`TABLE_NAME`、`COLUMN_NAME`、`HISTOGRAM JSONB` 四列。已有统计数据持久化在 `system.table_statistics`：`tableID` 和 `columnIDs` 标识统计对象，`createdAt`、`rowCount`、`nullCount` 提供统计时间和行数，`histogram BYTES` 保存序列化的 `stats.HistogramData`。视图通过 `TableStatisticsCache.GetTableStats(table.ID)` 读取这些记录；缓存未命中时由缓存层查询系统表，按 `createdAt DESC` 排序，并完成 protobuf 反序列化及 bucket 上界解码，视图不直接解析或暴露原始 `BYTES`。
- 先通过 `forEachTableDesc(..., hideVirtual, ...)` 遍历当前 catalog 下对用户可见的物理表，再读取表统计；隐藏列、虚拟表、无 histogram 统计和多列统计不输出。
- `GetTableStats` 按创建时间从新到旧返回记录。实现按 `ColumnID` 去重，每列最多输出第一份可用单列直方图；列 ID 无法解析时返回错误，避免把历史统计归属到错误列。

统计数据到 JSON 的转换链路如下：

| 已有统计数据 | 缓存层解码结果 | `HISTOGRAM` JSON 输出 |
| --- | --- | --- |
| `system.table_statistics.createdAt` | `TableStatistic.CreatedAt` | 转为 UTC，格式化为 `yyyy-MM-dd HH:mm:ss.ffffff`，写入 `last-updated`。 |
| `rowCount`、`nullCount` | `TableStatistic.RowCount`、`NullCount` | `null-values = NullCount / RowCount`；`RowCount=0` 时为 `0`，超过 `1` 时钳制为 `1`。非 NULL 行数为 `max(RowCount-NullCount, 0)`，作为累计频率分母。 |
| `histogram` 中的 `column_type` | `HistogramData.ColumnType` | 布尔/整数映射为 `int`，浮点映射为 `double`，十进制映射为 `decimal`，日期及时间映射为 `datetime`，其余映射为 `string`，写入 `data-type`。 |
| bucket `upper_bound` 的升序键编码 | `HistogramBucket.UpperBound`（SQL Datum） | 先按列类型执行 `DecodeTableKey`，再通过 `tree.AsJSON(..., UTC)` 转为对应 JSON 标量，作为 bucket 上界。 |
| bucket `num_eq`、`num_range` | `NumEq`、`NumRange` | 逐 bucket 累加 `NumRange + NumEq`，再除以非 NULL 行数，生成 `cumulative_frequency`；结果超过 `1` 时钳制为 `1`。 |
| bucket `distinct_range`、`num_eq` | `DistinctRange`、`NumEq` | `distinct_values = DistinctRange + 1`（仅当 `NumEq > 0` 时加 `1`），用于 `equi-height` bucket。 |
| histogram bucket 数量 | `len(TableStatistic.Histogram)` | 写入 `number-of-buckets-specified`。KWDB 未保存创建统计时请求的 bucket 上限，因此这里表示实际 bucket 数量。 |

生成的 JSON 对象固定包含以下 6 个键；JSON 对象的键顺序不作为兼容契约：

```json
{
  "buckets": [],
  "data-type": "int|double|decimal|datetime|string",
  "histogram-type": "singleton|equi-height",
  "last-updated": "yyyy-MM-dd HH:mm:ss.ffffff",
  "null-values": 0.0,
  "number-of-buckets-specified": 0
}
```

当全部 bucket 的 `NumRange == 0` 且 `DistinctRange == 0` 时，输出 `singleton`。每个 bucket 是二元数组：

```json
{
  "buckets": [
    [10, 0.5],
    [20, 0.75],
    [30, 1.0]
  ],
  "data-type": "int",
  "histogram-type": "singleton",
  "last-updated": "2026-10-02 08:30:00.000000",
  "null-values": 0.2,
  "number-of-buckets-specified": 3
}
```

数组元素依次为 `[upper_bound, cumulative_frequency]`。示例仅说明格式；实际值来自对应列最新一份可用单列统计。

只要任一 bucket 的 `NumRange != 0` 或 `DistinctRange != 0`，整份 histogram 输出为 `equi-height`。每个 bucket 是四元数组：

```json
{
  "buckets": [
    [10, 10, 0.25, 1.0],
    [10, 20, 0.75, 6.0],
    [20, 30, 1.0, 4.0]
  ],
  "data-type": "int",
  "histogram-type": "equi-height",
  "last-updated": "2026-10-02 08:30:00.000000",
  "null-values": 0.0,
  "number-of-buckets-specified": 3
}
```

数组元素依次为 `[display_lower_bound, upper_bound, cumulative_frequency, distinct_values]`。KWDB histogram 只保存 bucket 上界，没有 MySQL 所需的独立下界；因此首个 bucket 使用自身上界作为展示下界，后续 bucket 使用前一个 bucket 的上界作为展示下界。该下界仅用于兼容展示，不表示底层额外保存了完整区间边界。

- KWDB 没有可靠的 MySQL `sampling-rate` 和 `collation-id` 数据源，JSON 中明确省略这两个键，不伪造默认值。

### `kwdb_internal.partitions`

- 保留原有 11 列及其位置，继续满足 `SHOW PARTITIONS` 对 `table_id`、`index_id`、`parent_name`、`name`、分区值和 zone 字段的依赖；在末尾追加 25 个 MySQL 兼容列，总列数扩展为 36。
- 数据链路为：

```text
  forEachTableDescAll
    -> 当前用户可见的数据库/schema/表
    -> TableDescriptor.ForeachNonDropIndex
    -> IndexDescriptor.Partitioning
    -> LIST/RANGE/HASH 节点转换
    -> DecodePartitionTuple + GetZoneConfigInTxn
    -> 旧 11 列 + 新 25 列
  ```

- `TABLE_CATALOG`、`TABLE_SCHEMA`、`TABLE_NAME` 分别取真实数据库名、schema 名和表名；未分区表不生成合成空行。
- 分区方法根据描述符映射为 `LIST`、`RANGE` 或 `HASH`。表达式由索引分区列按定义顺序拼接，多列分区保留 `region, id` 形式。
- LIST/RANGE 使用 `DecodePartitionTuple` 解析边界；HASH 输出离散点或 `from TO to` 范围。`PARTITION_DESCRIPTION` 直接复用当前行已经解码的 `list_value`、`range_value` 或 `hash_value`，避免重复解码和两套展示逻辑不一致。
- 顶层分区序号按当前索引内定义顺序从 `1` 开始。递归处理 LIST 子分区时：
  - 原有 `parent_name/name` 继续表达直接父子边；
  - 新增 `PARTITION_*` 始终锚定递归链顶层分区；
  - `SUBPARTITION_*` 表达当前节点及其在直接父节点内的序号、方法和列表达式；
  - 列偏移随递归层级累加，使子分区表达式使用正确的后续索引列。
- 每个分区继续调用既有 `GetZoneConfigInTxn` 解析 `zone_id/subzone_id`；新增兼容列没有增加新的外部数据源。
- KWDB 没有可靠的分区粒度行数、空间、时间、校验和、注释、nodegroup 和 tablespace 数据，因此以下 13 列固定为 SQL `NULL`：`TABLE_ROWS`、`AVG_ROW_LENGTH`、`DATA_LENGTH`、`MAX_DATA_LENGTH`、`INDEX_LENGTH`、`DATA_FREE`、`CREATE_TIME`、`UPDATE_TIME`、`CHECK_TIME`、`CHECKSUM`、`PARTITION_COMMENT`、`NODEGROUP`、`TABLESPACE_NAME`。其中不使用整表统计冒充分区级 `TABLE_ROWS`。

### `information_schema.processlist`

- 新增 MySQL 顺序的 `ID`、`USER`、`HOST`、`DB`、`COMMAND`、`TIME`、`STATE`、`INFO` 八列；`USER` 使用带引号的大写标识符，保持 MySQL 列名并避开 KWDB 保留字。
- 每次视图查询只调用一次 `StatusServer.ListSessions`，随后基于同一份响应生成全部行。该响应是语句级稳定快照，但集群各节点采集时刻不同，不承诺跨节点原子快照。
- 复用 `makeSessionsRequest` 的权限语义：管理员请求全体会话，普通用户只请求与当前用户名相同的会话，避免泄露其他用户的 SQL 文本。
- 一个 MySQL 连接对应一行，而 KWDB `Session.ActiveQueries` 是数组。实现选择开始时间最早的活动查询作为当前会话的代表，不依赖数组顺序。
- 字段转换：
  - `ID`：输出完整 128 位 `Session.ID` 字符串，避免截断或哈希；与 MySQL `BIGINT` 类型不同，是明确的 KWDB 兼容扩展。
  - `USER`、`HOST`：分别取 `Session.Username` 和 `Session.ClientAddress`。
  - `DB`：当前会话结构没有可靠默认数据库字段，固定为 SQL `NULL`。
  - 活动会话：`COMMAND='Query'`；`TIME` 为一次性快照时间减活动查询开始时间的完整秒数，节点时钟偏差导致负值时钳制为 `0`；`STATE` 取原始 query phase；`INFO` 取当前 SQL。
  - 空闲会话：`COMMAND='Sleep'`，`TIME/STATE/INFO` 均为 `NULL`，不使用会话存续时间或历史 SQL 冒充空闲持续时间和当前语句。
- 节点级扇出错误不是会话行。实现保留健康节点返回的会话并记录 warning，不合成伪行；整体 `ListSessions` 调用失败时直接返回错误。

### 注册、兼容与联动更新

- 为新增 `information_schema` 视图追加固定虚拟表 ID，并更新 `MinVirtualID`，保持已有虚拟对象 ID 不变。
- 新增视图自动获得 `public SELECT`，同步更新 `SHOW TABLES`、`SHOW GRANTS`、`table_privileges`、`pg_catalog.pg_description` 等固定期望及其排序。
- `column_statistics` 和 `processlist` 的注册会改变系统目录中的虚拟表数量；同步更新 `ts_create_bug` 的 1n、5c、5cr master。
- 新增 `qa/Integration/basic_v3/information_schema_views_04.sql`，并提供 1n、5c、5cr 三套 master，覆盖四视图的稳定输出。

### 测试资产

下表仅描述本分支写入的覆盖内容；实际执行状态以 `Verification` 为准。

| 测试资产 | 覆盖内容 |
| --- | --- |
| `logic_test/column_statistics` | 四列 DDL、单列/多列过滤、singleton/equi-height JSON、NULL 比例、最新统计去重、权限隔离。 |
| `logic_test/user_attributes` | 三列 DDL、角色过滤、普通用户自见、root/admin 全见、`HOST/ATTRIBUTE` 固定 `NULL`。 |
| `logic_test/kwdb_internal` | 36 列结构、未分区表空集、LIST/RANGE/HASH、多列分区表达式、旧列兼容、固定 `NULL` 字段。 |
| `logic_test/information_schema` | `processlist` 八列、活动/空闲状态、root/普通用户可见性，以及系统视图枚举和权限联动。 |
| `logic_test/grant_table`、`logic_test/pg_catalog` | 新视图默认授权、系统目录注释和排序联动。 |
| `qa/Integration/basic_v3/information_schema_views_04.sql` | root 场景下四视图 smoke、三种分区方法、histogram 关键字段、动态 processlist 稳定断言。 |
| `qa/Integration/basic_v3/master/*` | 1n、5c、5cr 基准输出及系统目录数量变化。 |

## Verification

已执行：

```bash
git diff --check origin/master..HEAD
```

结果：通过。

用户提供的外部测试日志表明，开发过程中已运行 `information_schema`、`pg_catalog`、`grant_table` logic 测试和 `information_schema_views_04.sql` QA 用例，并据失败结果修正了保留字引用、列名大小写、系统视图排序和 QA master；

结果：通过。

- `make testlogic `。
- `go test` / `make test`。
- `qa/run_test_local_v2.sh TEST_v2_integration_basic_v2.sh information_schema_views_04.sql` 的最终 1n、5c、5cr 回归。

## Risks

- `column_statistics` 是受限 MySQL 兼容：`sampling-rate`、`collation-id` 无可靠来源而被省略；equi-height 下界由相邻上界推导，属于展示转换，不是底层完整边界数据。
- 统计描述符和 `TableStatisticsCache` 可能来自不同时点；历史统计引用已删除列时查询会返回错误。
- `kwdb_internal.partitions` 的 25 个兼容列追加在旧列之后，依赖 `SELECT *` 固定列数的客户端会看到结构变化；13 个无分区粒度来源的字段始终为 `NULL`。
- 子分区递归沿用现有 LIST `Subpartitioning` 模型；
- `partitions` 保留每个分区一次 zone 查询的既有成本，大量分区时查询成本随分区数增长。
- `processlist` 会触发集群会话 RPC，结果不是跨节点原子快照；部分节点失败时只返回健康节点数据。`ID` 使用 STRING 而非 MySQL BIGINT，`DB` 和空闲 `TIME` 因无可靠来源返回 `NULL`。
- 新增虚拟表会影响系统目录对象数量、授权输出和固定排序；

类型	指派人员	状态
审查	zhaochunze e3ric zhaoqinhu MikeFeng David Zhang liangbo01 William Shi ZhiTong Dou ZhangZirui Albert ZhaoK renyanzheng zhangyg amateur1978 Jerry Z Epoch	进行中 (0/2人)
测试	liuhuanpak 张帅 Yang Xing ZhanYuying	进行中 (0/1人)

GVPKWDB / kwdb

搜索帮助

GVP KWDB / kwdb