docs: add metric engine sparse primary key encoding configuration (#2211)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: WenyXu <[email protected]>

Author: Copilot

docs/contributor-guide/datanode/metric-engine.md

@@ -37,7 +37,7 @@ Regarding partitioning, logical tables have identical partition rules and Region
 
 Concerning routing metadata, the routing address of a logical table is a logical address - what its corresponding physical table is - then through this physical table for secondary routing to obtain the real physical address. This indirect routing method can significantly reduce the number of metadata modifications required when Region migration scheduling occurs in Metric engines.
 
-Operationally speaking, The `Metric` engine only supports limited operations on physical tables to prevent misoperations such as prohibiting writing into or deleting from a physical table which could affect user's logic-table data. Generally speaking, users can consider that they have read-only access to these physical tables.
+Operationally speaking, The `Metric` engine supports standard DML operations (INSERT, DELETE, SELECT) on logical tables. However, it only supports limited operations on physical tables to prevent misoperations - for example, writing directly to a physical table is prohibited as it could affect user's logical table data. Generally speaking, users can consider that they have read-only access to these physical tables.
 
 To improve performance during simultaneous DDL (Data Definition Language) operations on many tables, the 'Metric' engine has introduced some batch DDL operations. These batch DDL operations can merge lots of DDL actions into one request thereby reducing queries and modifications times for metadata thus enhancing performance. This feature is particularly beneficial in scenarios such as the automatic creation requests brought about by large amounts of metrics during Prometheus Remote Write cold start-up, as well as the modification requests for numerous route-tables mentioned earlier during migration of many physical regions.
 

docs/user-guide/deployments-administration/configuration.md

@@ -394,7 +394,7 @@ How to use distributed tracing, please reference [Tracing](/user-guide/deploymen
 
 ### Region engine options
 
-The parameters corresponding to different storage engines can be configured for `datanode` and `standalone` in the `[region_engine]` section. Currently, only options for `mito` region engine is available.
+The parameters corresponding to different storage engines can be configured for `datanode` and `standalone` in the `[region_engine]` section. Currently, options for `mito` and `metric` region engines are available.
 
 Frequently used options:
 
@@ -474,6 +474,20 @@ Available options:
 | `memtable.data_freeze_threshold`         | Integer | `32768`       | The max rows of data inside the actively writing buffer in one shard.<br/>Only available for `partition_tree` memtable.                                                                                                                                                                                                                                                                                                                                                                            |
 | `memtable.fork_dictionary_bytes`         | String  | `1GiB`        | Max dictionary bytes.<br/>Only available for `partition_tree` memtable.                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
+The `metric` engine is optimized for handling metrics data with a large number of small tables:
+
+```toml
+[[region_engine]]
+[region_engine.metric]
+sparse_primary_key_encoding = true
+```
+
+Available options:
+
+| Key                            | Type    | Default | Descriptions                                                                                                                                                 |
+| ------------------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `sparse_primary_key_encoding`  | Boolean | `true`  | Whether to use sparse primary key encoding. This optimization improves write and query performance by encoding only non-null primary key columns.            |
+
 ### Specify meta client
 
 The `meta_client` options are valid in `datanode` and `frontend` mode, which specify the Metasrv client information.

i18n/zh/docusaurus-plugin-content-docs/current/contributor-guide/datanode/metric-engine.md

@@ -35,7 +35,7 @@ description: 介绍了 Metric 引擎的概念、架构及设计，重点描述
 
 在路由元数据方面，逻辑表的路由地址为逻辑地址，即该逻辑表所对应的物理表是什么，而后通过该物理表进行二次路由取得真正的物理地址。这一间接路由方式能够显著减少 `Metric` 引擎的 Region 发生迁移调度时所需要修改的元数据数量。
 
-在操作方面，`Metric` 引擎仅对物理表的操作进行了有限的支持以防止误操作，例如通过禁止写入物理表、删除物理表等操作防止影响用户逻辑表的数据。总体上可以认为物理表是对用户只读的。
+在操作方面，`Metric` 引擎支持对逻辑表进行标准的 DML 操作（INSERT、DELETE、SELECT）。然而，对物理表的操作进行了有限的支持以防止误操作，例如禁止直接写入物理表等操作防止影响用户逻辑表的数据。总体上可以认为物理表是对用户只读的。
 
 为了提升对大量表同时进行 DDL（Data Definition Language，数据操作语言）操作时性能，如 Prometheus Remote Write 冷启动时大量 metrics 带来的自动建表请求，以及前面提到的迁移物理 Region 时大量路由表的修改请求等，`Metric` 引擎引入了一些批量 DDL 操作。这些批量 DDL 操作能够将大量的 DDL 操作合并成一个请求，从而减少了元数据的查询及修改次数，提升了性能。
 

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/configuration.md

@@ -386,7 +386,7 @@ default_ratio = 1.0
 
 ### Region 引擎选项
 
-datanode 和 standalone 在 `[region_engine]` 部分可以配置不同存储引擎的对应参数。目前只可以配置存储引擎 `mito` 的选项。
+datanode 和 standalone 在 `[region_engine]` 部分可以配置不同存储引擎的对应参数。目前可以配置 `mito` 和 `metric` 存储引擎的选项。
 
 部分常用的选项如下
 
@@ -465,6 +465,20 @@ fork_dictionary_bytes = "1GiB"
 | `memtable.data_freeze_threshold`         | 整数   | `32768`       | 一个 shard 内写缓存可容纳的最大行数<br/>只对 `partition_tree` memtable 生效                                            |
 | `memtable.fork_dictionary_bytes`         | 字符串 | `1GiB`        | 主键字典的大小<br/>只对 `partition_tree` memtable 生效                                                                 |
 
+`metric` 引擎针对包含大量小表的 metrics 数据进行了优化：
+
+```toml
+[[region_engine]]
+[region_engine.metric]
+sparse_primary_key_encoding = true
+```
+
+可用选项：
+
+| 键                                | 类型   | 默认值  | 描述                                                                                                              |
+| --------------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `sparse_primary_key_encoding`     | 布尔值 | `true`  | 是否使用稀疏主键编码。此优化通过仅编码非空主键列来提高写入和查询性能。                                            |
+
 ### 设定 meta client
 
 `meta_client` 选项适用于 `datanode` 和 `frontend` 模块，用于指定 Metasrv 的相关信息。

i18n/zh/docusaurus-plugin-content-docs/version-1.0/contributor-guide/datanode/metric-engine.md

@@ -35,7 +35,7 @@ description: 介绍了 Metric 引擎的概念、架构及设计，重点描述
 
 在路由元数据方面，逻辑表的路由地址为逻辑地址，即该逻辑表所对应的物理表是什么，而后通过该物理表进行二次路由取得真正的物理地址。这一间接路由方式能够显著减少 `Metric` 引擎的 Region 发生迁移调度时所需要修改的元数据数量。
 
-在操作方面，`Metric` 引擎仅对物理表的操作进行了有限的支持以防止误操作，例如通过禁止写入物理表、删除物理表等操作防止影响用户逻辑表的数据。总体上可以认为物理表是对用户只读的。
+在操作方面，`Metric` 引擎支持对逻辑表进行标准的 DML 操作（INSERT、DELETE、SELECT）。然而，对物理表的操作进行了有限的支持以防止误操作，例如禁止直接写入物理表等操作防止影响用户逻辑表的数据。总体上可以认为物理表是对用户只读的。
 
 为了提升对大量表同时进行 DDL（Data Definition Language，数据操作语言）操作时性能，如 Prometheus Remote Write 冷启动时大量 metrics 带来的自动建表请求，以及前面提到的迁移物理 Region 时大量路由表的修改请求等，`Metric` 引擎引入了一些批量 DDL 操作。这些批量 DDL 操作能够将大量的 DDL 操作合并成一个请求，从而减少了元数据的查询及修改次数，提升了性能。
 

i18n/zh/docusaurus-plugin-content-docs/version-1.0/user-guide/deployments-administration/configuration.md

@@ -386,7 +386,7 @@ default_ratio = 1.0
 
 ### Region 引擎选项
 
-datanode 和 standalone 在 `[region_engine]` 部分可以配置不同存储引擎的对应参数。目前只可以配置存储引擎 `mito` 的选项。
+datanode 和 standalone 在 `[region_engine]` 部分可以配置不同存储引擎的对应参数。目前可以配置 `mito` 和 `metric` 存储引擎的选项。
 
 部分常用的选项如下
 
@@ -465,6 +465,20 @@ fork_dictionary_bytes = "1GiB"
 | `memtable.data_freeze_threshold`         | 整数   | `32768`       | 一个 shard 内写缓存可容纳的最大行数<br/>只对 `partition_tree` memtable 生效                                            |
 | `memtable.fork_dictionary_bytes`         | 字符串 | `1GiB`        | 主键字典的大小<br/>只对 `partition_tree` memtable 生效                                                                 |
 
+`metric` 引擎针对包含大量小表的 metrics 数据进行了优化：
+
+```toml
+[[region_engine]]
+[region_engine.metric]
+sparse_primary_key_encoding = true
+```
+
+可用选项：
+
+| 键                                | 类型   | 默认值  | 描述                                                                                                              |
+| --------------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `sparse_primary_key_encoding`     | 布尔值 | `true`  | 是否使用稀疏主键编码。此优化通过仅编码非空主键列来提高写入和查询性能。                                            |
+
 ### 设定 meta client
 
 `meta_client` 选项适用于 `datanode` 和 `frontend` 模块，用于指定 Metasrv 的相关信息。

versioned_docs/version-1.0/contributor-guide/datanode/metric-engine.md

@@ -37,7 +37,7 @@ Regarding partitioning, logical tables have identical partition rules and Region
 
 Concerning routing metadata, the routing address of a logical table is a logical address - what its corresponding physical table is - then through this physical table for secondary routing to obtain the real physical address. This indirect routing method can significantly reduce the number of metadata modifications required when Region migration scheduling occurs in Metric engines.
 
-Operationally speaking, The `Metric` engine only supports limited operations on physical tables to prevent misoperations such as prohibiting writing into or deleting from a physical table which could affect user's logic-table data. Generally speaking, users can consider that they have read-only access to these physical tables.
+Operationally speaking, The `Metric` engine supports standard DML operations (INSERT, DELETE, SELECT) on logical tables. However, it only supports limited operations on physical tables to prevent misoperations - for example, writing directly to a physical table is prohibited as it could affect user's logical table data. Generally speaking, users can consider that they have read-only access to these physical tables.
 
 To improve performance during simultaneous DDL (Data Definition Language) operations on many tables, the 'Metric' engine has introduced some batch DDL operations. These batch DDL operations can merge lots of DDL actions into one request thereby reducing queries and modifications times for metadata thus enhancing performance. This feature is particularly beneficial in scenarios such as the automatic creation requests brought about by large amounts of metrics during Prometheus Remote Write cold start-up, as well as the modification requests for numerous route-tables mentioned earlier during migration of many physical regions.
 

versioned_docs/version-1.0/user-guide/deployments-administration/configuration.md

@@ -394,7 +394,7 @@ How to use distributed tracing, please reference [Tracing](/user-guide/deploymen
 
 ### Region engine options
 
-The parameters corresponding to different storage engines can be configured for `datanode` and `standalone` in the `[region_engine]` section. Currently, only options for `mito` region engine is available.
+The parameters corresponding to different storage engines can be configured for `datanode` and `standalone` in the `[region_engine]` section. Currently, options for `mito` and `metric` region engines are available.
 
 Frequently used options:
 
@@ -474,6 +474,20 @@ Available options:
 | `memtable.data_freeze_threshold`         | Integer | `32768`       | The max rows of data inside the actively writing buffer in one shard.<br/>Only available for `partition_tree` memtable.                                                                                                                                                                                                                                                                                                                                                                            |
 | `memtable.fork_dictionary_bytes`         | String  | `1GiB`        | Max dictionary bytes.<br/>Only available for `partition_tree` memtable.                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
+The `metric` engine is optimized for handling metrics data with a large number of small tables:
+
+```toml
+[[region_engine]]
+[region_engine.metric]
+sparse_primary_key_encoding = true
+```
+
+Available options:
+
+| Key                            | Type    | Default | Descriptions                                                                                                                                                 |
+| ------------------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `sparse_primary_key_encoding`  | Boolean | `true`  | Whether to use sparse primary key encoding. This optimization improves write and query performance by encoding only non-null primary key columns.            |
+
 ### Specify meta client
 
 The `meta_client` options are valid in `datanode` and `frontend` mode, which specify the Metasrv client information.