This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 25c7e766788 docs: add compaction score API (#3636)
25c7e766788 is described below
commit 25c7e7667882718eaf103ca0f9e3d57d4a347480
Author: Siyang Tang <[email protected]>
AuthorDate: Sat Oct 17 05:40:16 2026 +0800
docs: add compaction score API (#3636)
## Summary
Document the existing BE GET /api/compaction_score endpoint. Complete
the dev and 4.x English/Chinese references with parameter types and
defaults, ADMIN authentication when enabled, deterministic top_n=0
output, response fields, and failure handling.
In storage-compute decoupled mode, the endpoint inspects the BE's cached
running tablets. sync_meta defaults to false; enabling it synchronizes
every cached running tablet before top_n limits the response. The
examples and caveats make this scope and cost explicit.
## Validation
- Verified registration, authentication, parameter parsing,
cached-tablet selection, scoring, sorting, and error responses against
Doris master and branches 4.0, 4.1, and 4.2.
- Rebased on master and resolved the 4.x sidebar conflict while
retaining its current navigation structure.
- Parsed sidebar JSON and ran targeted document governance checks and
git diff --check; no new blocking findings.
- Independently reviewed by a second agent.
The original 3.x and 2.1 additions are also included in this PR; this
review and correction pass covers dev and 4.x.
---------
Co-authored-by: morningman <[email protected]>
---
.../open-api/be-http/compaction-score.md | 88 ++++++++++++++++++++++
.../open-api/be-http/compaction-score.md | 88 ++++++++++++++++++++++
.../open-api/be-http/compaction-score.md | 61 +++++++++++++++
.../open-api/be-http/compaction-score.md | 73 ++++++++++++++++++
.../open-api/be-http/compaction-score.md | 88 ++++++++++++++++++++++
sidebars.ts | 1 +
.../open-api/be-http/compaction-score.md | 61 +++++++++++++++
.../open-api/be-http/compaction-score.md | 73 ++++++++++++++++++
.../open-api/be-http/compaction-score.md | 88 ++++++++++++++++++++++
versioned_sidebars/version-2.1-sidebars.json | 1 +
versioned_sidebars/version-3.x-sidebars.json | 1 +
versioned_sidebars/version-4.x-sidebars.json | 1 +
12 files changed, 624 insertions(+)
diff --git a/docs/admin-manual/open-api/be-http/compaction-score.md
b/docs/admin-manual/open-api/be-http/compaction-score.md
new file mode 100644
index 00000000000..bcefbcf0e2f
--- /dev/null
+++ b/docs/admin-manual/open-api/be-http/compaction-score.md
@@ -0,0 +1,88 @@
+---
+{
+ "title": "View Tablet Compaction Score",
+ "language": "en",
+ "description": "View and rank tablet compaction scores on a BE node, with
optional metadata synchronization in storage-compute decoupled mode."
+}
+---
+
+# View Tablet Compaction Score
+
+## Description
+
+Use this read-only API to find tablets with high compaction scores on one BE
node. A tablet's score is the sum of the scores of its rowsets. Results are
sorted by `compaction_score` in descending order. In storage-compute decoupled
mode, the API inspects running tablets currently cached by this BE, rather than
every tablet in the cluster.
+
+## Prerequisites
+
+Connect directly to the BE HTTP port (8040 by default). If the BE
configuration `enable_all_http_auth` is enabled, use a Doris account with the
global `ADMIN` privilege. Replace the credentials in the examples with that
account.
+
+## Request
+
+```text
+GET /api/compaction_score?top_n=<integer>&sync_meta=<boolean>
+```
+
+The request has no body.
+
+## Query parameters
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `top_n` | Non-negative integer | No | All available tablets | Return at most
the N tablets with the highest scores. `0` returns `[]`. The value must fit in
a signed 64-bit integer. |
+| `sync_meta` | Boolean: `true` or `false` | No | `false` | Storage-compute
decoupled mode only. When `true`, synchronize metadata and rowsets for the BE's
cached running tablets from Meta Service before calculating scores. Omit this
parameter entirely in storage-compute coupled mode, including
`sync_meta=false`. |
+
+## Basic usage
+
+The following request checks connectivity and parameter handling without
returning tablet rows:
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=0'
+```
+
+```json
+[]
+```
+
+## Response
+
+A successful request returns HTTP 200 and a JSON array. Each element has two
string-valued fields:
+
+| Field | Description |
+|---|---|
+| `tablet_id` | Tablet ID. |
+| `compaction_score` | Sum of the compaction scores of the tablet's rowsets. |
+
+For example, return up to 10 tablets:
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=10'
+```
+
+The following output is illustrative; the IDs, scores, and number of returned
tablets depend on the BE:
+
+```json
+[
+ {"compaction_score": "5", "tablet_id": "42595"},
+ {"compaction_score": "4", "tablet_id": "10034"}
+]
+```
+
+In storage-compute decoupled mode, request fresh cached-tablet metadata before
calculating scores:
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=10&sync_meta=true'
+```
+
+The response uses the same JSON format, calculated after synchronization.
+
+## Error handling and caveats
+
+- An unparseable or negative `top_n` returns HTTP 400, for example `invalid
argument: top_n=wrong`.
+- A nonempty `sync_meta` in storage-compute coupled mode returns HTTP 400:
``param `sync_meta` is only available for cloud mode``.
+- In storage-compute decoupled mode, a nonempty `sync_meta` other than `true`
or `false` returns HTTP 400, for example `invalid argument: sync_meta=wrong`.
+- A metadata synchronization failure returns HTTP 500. If authentication is
enabled, missing or invalid credentials can return HTTP 401 or 403.
+- `top_n` limits the response size, not the number of tablets inspected or
synchronized. A score is an observation of this BE's tablet state, rather than
an atomic cluster-wide snapshot.
+
+## Best practices
+
+Start with a small `top_n` and the default `sync_meta=false` to identify
tablets for further investigation. Use `sync_meta=true` when fresh metadata is
necessary; it synchronizes all cached running tablets before applying `top_n`
and can increase latency and Meta Service load.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/open-api/be-http/compaction-score.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/open-api/be-http/compaction-score.md
new file mode 100644
index 00000000000..233dc1fc4c3
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/open-api/be-http/compaction-score.md
@@ -0,0 +1,88 @@
+---
+{
+ "title": "查看 Tablet Compaction Score",
+ "language": "zh-CN",
+ "description": "查看并排序单个 BE 节点的 Tablet Compaction Score，支持在存算分离模式下先同步缓存
Tablet 的元数据。"
+}
+---
+
+# 查看 Tablet Compaction Score
+
+## 描述
+
+通过此只读 API 查找单个 BE 节点上 Compaction Score 较高的 Tablet。一个 Tablet 的分数为其所有 Rowset
分数之和，结果按 `compaction_score` 降序排列。存算分离模式下，API 仅检查当前 BE 缓存中处于运行状态的
Tablet，不会遍历整个集群的全部 Tablet。
+
+## 前提条件
+
+直接访问 BE 的 HTTP 端口（默认为 8040）。如果 BE 配置 `enable_all_http_auth` 已启用，需要使用具有全局
`ADMIN` 权限的 Doris 账号，并将示例中的凭据替换为该账号。
+
+## 请求
+
+```text
+GET /api/compaction_score?top_n=<integer>&sync_meta=<boolean>
+```
+
+请求不包含请求体。
+
+## 请求参数
+
+| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
+|---|---|---|---|---|
+| `top_n` | 非负整数 | 否 | 全部可用 Tablet | 最多返回分数最高的前 N 个 Tablet。`0` 返回
`[]`。数值必须处于有符号 64 位整数范围内。 |
+| `sync_meta` | 布尔值：`true` 或 `false` | 否 | `false` | 仅适用于存算分离模式。为 `true` 时，先从
Meta Service 同步该 BE 缓存中运行状态 Tablet 的元数据和 Rowset，再计算分数。存算一体模式下必须省略整个参数，包括
`sync_meta=false`。 |
+
+## 基本用法
+
+以下请求可检查连通性和参数处理，且不返回 Tablet 行：
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=0'
+```
+
+```json
+[]
+```
+
+## 响应
+
+请求成功时返回 HTTP 200 和 JSON 数组。每个元素包含两个字符串类型的字段：
+
+| 字段 | 描述 |
+|---|---|
+| `tablet_id` | Tablet ID。 |
+| `compaction_score` | 该 Tablet 所有 Rowset 的 Compaction Score 之和。 |
+
+例如，最多返回 10 个 Tablet：
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=10'
+```
+
+以下输出仅作示意，ID、分数和返回数量取决于该 BE 的状态：
+
+```json
+[
+ {"compaction_score": "5", "tablet_id": "42595"},
+ {"compaction_score": "4", "tablet_id": "10034"}
+]
+```
+
+存算分离模式下，可在计算分数前同步缓存 Tablet 的最新元数据：
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=10&sync_meta=true'
+```
+
+响应使用相同的 JSON 格式，分数在同步完成后计算。
+
+## 错误处理与注意事项
+
+- `top_n` 无法解析或为负数时返回 HTTP 400，例如 `invalid argument: top_n=wrong`。
+- 存算一体模式下指定非空 `sync_meta` 时返回 HTTP 400：``param `sync_meta` is only available
for cloud mode``。
+- 存算分离模式下，非空 `sync_meta` 不是 `true` 或 `false` 时返回 HTTP 400，例如 `invalid
argument: sync_meta=wrong`。
+- 元数据同步失败时返回 HTTP 500。启用鉴权后，缺失或无效凭据可能返回 HTTP 401 或 403。
+- `top_n` 只限制响应条数，不限制检查或同步的 Tablet 数量。分数反映该 BE 的 Tablet 状态，不构成整个集群的原子快照。
+
+## 最佳实践
+
+先使用较小的 `top_n` 和默认的 `sync_meta=false` 定位需要进一步排查的 Tablet。需要最新元数据时再使用
`sync_meta=true`；它会在应用 `top_n` 前同步全部缓存中运行状态的 Tablet，可能增加延迟和 Meta Service 负载。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/open-api/be-http/compaction-score.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/open-api/be-http/compaction-score.md
new file mode 100644
index 00000000000..ed0c5c92802
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/open-api/be-http/compaction-score.md
@@ -0,0 +1,61 @@
+---
+{
+ "title": "查看 Tablet Compaction Score",
+ "language": "zh-CN",
+ "description": "用于查看 BE 节点上各 Tablet 的 Compaction Score。"
+}
+---
+
+# 查看 Tablet Compaction Score
+
+## 请求路径
+
+`GET /api/compaction_score?top_n={int}`
+
+## 描述
+
+用于查看某个 BE 节点上各 Tablet 的 Compaction Score。Compaction Score 按每个 Tablet 中所有
Rowset 的 Compaction Score 求和得到。响应结果按 `compaction_score` 降序排列。
+
+## 请求参数
+
+* `top_n`
+
+ 可选。非负整数。指定后仅返回 Compaction Score 最高的前 N 个 Tablet；不指定时返回该 BE 节点上的所有
Tablet。`top_n=0` 返回空数组。
+
+## 请求体
+
+无
+
+## 响应
+
+返回 JSON 数组，每个元素包含以下字段：
+
+* `tablet_id`：Tablet ID。返回值类型为字符串。
+* `compaction_score`：Tablet 的 Compaction Score。返回值类型为字符串。
+
+响应示例：
+
+```json
+[
+ {
+ "compaction_score": "5",
+ "tablet_id": "42595"
+ },
+ {
+ "compaction_score": "4",
+ "tablet_id": "10034"
+ }
+]
+```
+
+## 错误处理
+
+`top_n` 不是合法的非负整数时，API 返回 HTTP 400，错误信息如 `invalid argument: top_n=wrong`。
+
+## 示例
+
+查看 Compaction Score 最高的前 10 个 Tablet：
+
+```shell
+curl "http://127.0.0.1:8040/api/compaction_score?top_n=10";
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/open-api/be-http/compaction-score.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/open-api/be-http/compaction-score.md
new file mode 100644
index 00000000000..63574779bb8
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/open-api/be-http/compaction-score.md
@@ -0,0 +1,73 @@
+---
+{
+ "title": "查看 Tablet Compaction Score",
+ "language": "zh-CN",
+ "description": "用于查看 BE 节点上各 Tablet 的 Compaction Score。"
+}
+---
+
+# 查看 Tablet Compaction Score
+
+## 请求路径
+
+`GET /api/compaction_score?top_n={int}&sync_meta={bool}`
+
+## 描述
+
+用于查看某个 BE 节点上各 Tablet 的 Compaction Score。Compaction Score 按每个 Tablet 中所有
Rowset 的 Compaction Score 求和得到。响应结果按 `compaction_score` 降序排列。
+
+## 请求参数
+
+* `top_n`
+
+ 可选。非负整数。指定后仅返回 Compaction Score 最高的前 N 个 Tablet；不指定时返回该 BE 节点上的所有
Tablet。`top_n=0` 返回空数组。
+
+* `sync_meta`
+
+ 可选。仅适用于存算分离模式。取值为 `true` 或 `false`。设置为 `true` 时，BE 会先从 Meta Service 同步
Tablet 元数据和 Rowset，再计算 Compaction Score。非存算分离模式下不要指定该参数。
+
+## 请求体
+
+无
+
+## 响应
+
+返回 JSON 数组，每个元素包含以下字段：
+
+* `tablet_id`：Tablet ID。返回值类型为字符串。
+* `compaction_score`：Tablet 的 Compaction Score。返回值类型为字符串。
+
+响应示例：
+
+```json
+[
+ {
+ "compaction_score": "5",
+ "tablet_id": "42595"
+ },
+ {
+ "compaction_score": "4",
+ "tablet_id": "10034"
+ }
+]
+```
+
+## 错误处理
+
+* `top_n` 不是合法的非负整数时，API 返回 HTTP 400，错误信息如 `invalid argument: top_n=wrong`。
+* 非存算分离模式下指定 `sync_meta` 时，API 返回 HTTP 400，错误信息为 ``param `sync_meta` is only
available for cloud mode``。
+* `sync_meta` 不是 `true` 或 `false` 时，API 返回 HTTP 400，错误信息如 `invalid argument:
sync_meta=wrong`。
+
+## 示例
+
+查看 Compaction Score 最高的前 10 个 Tablet：
+
+```shell
+curl "http://127.0.0.1:8040/api/compaction_score?top_n=10";
+```
+
+在存算分离模式下同步元数据后查看 Compaction Score：
+
+```shell
+curl "http://127.0.0.1:8040/api/compaction_score?top_n=10&sync_meta=true";
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/open-api/be-http/compaction-score.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/open-api/be-http/compaction-score.md
new file mode 100644
index 00000000000..233dc1fc4c3
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/open-api/be-http/compaction-score.md
@@ -0,0 +1,88 @@
+---
+{
+ "title": "查看 Tablet Compaction Score",
+ "language": "zh-CN",
+ "description": "查看并排序单个 BE 节点的 Tablet Compaction Score，支持在存算分离模式下先同步缓存
Tablet 的元数据。"
+}
+---
+
+# 查看 Tablet Compaction Score
+
+## 描述
+
+通过此只读 API 查找单个 BE 节点上 Compaction Score 较高的 Tablet。一个 Tablet 的分数为其所有 Rowset
分数之和，结果按 `compaction_score` 降序排列。存算分离模式下，API 仅检查当前 BE 缓存中处于运行状态的
Tablet，不会遍历整个集群的全部 Tablet。
+
+## 前提条件
+
+直接访问 BE 的 HTTP 端口（默认为 8040）。如果 BE 配置 `enable_all_http_auth` 已启用，需要使用具有全局
`ADMIN` 权限的 Doris 账号，并将示例中的凭据替换为该账号。
+
+## 请求
+
+```text
+GET /api/compaction_score?top_n=<integer>&sync_meta=<boolean>
+```
+
+请求不包含请求体。
+
+## 请求参数
+
+| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
+|---|---|---|---|---|
+| `top_n` | 非负整数 | 否 | 全部可用 Tablet | 最多返回分数最高的前 N 个 Tablet。`0` 返回
`[]`。数值必须处于有符号 64 位整数范围内。 |
+| `sync_meta` | 布尔值：`true` 或 `false` | 否 | `false` | 仅适用于存算分离模式。为 `true` 时，先从
Meta Service 同步该 BE 缓存中运行状态 Tablet 的元数据和 Rowset，再计算分数。存算一体模式下必须省略整个参数，包括
`sync_meta=false`。 |
+
+## 基本用法
+
+以下请求可检查连通性和参数处理，且不返回 Tablet 行：
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=0'
+```
+
+```json
+[]
+```
+
+## 响应
+
+请求成功时返回 HTTP 200 和 JSON 数组。每个元素包含两个字符串类型的字段：
+
+| 字段 | 描述 |
+|---|---|
+| `tablet_id` | Tablet ID。 |
+| `compaction_score` | 该 Tablet 所有 Rowset 的 Compaction Score 之和。 |
+
+例如，最多返回 10 个 Tablet：
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=10'
+```
+
+以下输出仅作示意，ID、分数和返回数量取决于该 BE 的状态：
+
+```json
+[
+ {"compaction_score": "5", "tablet_id": "42595"},
+ {"compaction_score": "4", "tablet_id": "10034"}
+]
+```
+
+存算分离模式下，可在计算分数前同步缓存 Tablet 的最新元数据：
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=10&sync_meta=true'
+```
+
+响应使用相同的 JSON 格式，分数在同步完成后计算。
+
+## 错误处理与注意事项
+
+- `top_n` 无法解析或为负数时返回 HTTP 400，例如 `invalid argument: top_n=wrong`。
+- 存算一体模式下指定非空 `sync_meta` 时返回 HTTP 400：``param `sync_meta` is only available
for cloud mode``。
+- 存算分离模式下，非空 `sync_meta` 不是 `true` 或 `false` 时返回 HTTP 400，例如 `invalid
argument: sync_meta=wrong`。
+- 元数据同步失败时返回 HTTP 500。启用鉴权后，缺失或无效凭据可能返回 HTTP 401 或 403。
+- `top_n` 只限制响应条数，不限制检查或同步的 Tablet 数量。分数反映该 BE 的 Tablet 状态，不构成整个集群的原子快照。
+
+## 最佳实践
+
+先使用较小的 `top_n` 和默认的 `sync_meta=false` 定位需要进一步排查的 Tablet。需要最新元数据时再使用
`sync_meta=true`；它会在应用 `top_n` 前同步全部缓存中运行状态的 Tablet，可能增加延迟和 Meta Service 负载。
diff --git a/sidebars.ts b/sidebars.ts
index 55b56855b60..c04c166a0a9 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -1169,6 +1169,7 @@ const sidebars: SidebarsConfig = {
'admin-manual/open-api/be-http/reset-rpc-channel',
'admin-manual/open-api/be-http/compaction-status',
'admin-manual/open-api/be-http/compaction-run',
+
'admin-manual/open-api/be-http/compaction-score',
'admin-manual/open-api/be-http/meta',
'admin-manual/open-api/be-http/snapshot',
'admin-manual/open-api/be-http/check-tablet-segment',
diff --git
a/versioned_docs/version-2.1/admin-manual/open-api/be-http/compaction-score.md
b/versioned_docs/version-2.1/admin-manual/open-api/be-http/compaction-score.md
new file mode 100644
index 00000000000..6bb9840d9b0
--- /dev/null
+++
b/versioned_docs/version-2.1/admin-manual/open-api/be-http/compaction-score.md
@@ -0,0 +1,61 @@
+---
+{
+ "title": "View Tablet Compaction Score",
+ "language": "en",
+ "description": "It is used to view tablet compaction scores on a BE node."
+}
+---
+
+# View Tablet Compaction Score
+
+## Request
+
+`GET /api/compaction_score?top_n={int}`
+
+## Description
+
+It is used to view tablet compaction scores on a BE node. The compaction score
is calculated as the sum of the compaction scores of all rowsets in each
tablet. The response is sorted by `compaction_score` in descending order.
+
+## Query parameters
+
+* `top_n`
+
+ Optional. A non-negative integer. If specified, only the top N tablets
with the highest compaction scores are returned. If not specified, all tablets
on the BE node are returned. `top_n=0` returns an empty array.
+
+## Request body
+
+None
+
+## Response
+
+Returns a JSON array. Each element contains the following fields:
+
+* `tablet_id`: Tablet ID. The value is returned as a string.
+* `compaction_score`: Tablet compaction score. The value is returned as a
string.
+
+Example response:
+
+```json
+[
+ {
+ "compaction_score": "5",
+ "tablet_id": "42595"
+ },
+ {
+ "compaction_score": "4",
+ "tablet_id": "10034"
+ }
+]
+```
+
+## Error handling
+
+If `top_n` is not a valid non-negative integer, the API returns HTTP 400 with
an error such as `invalid argument: top_n=wrong`.
+
+## Examples
+
+View the top 10 tablets with the highest compaction scores:
+
+```shell
+curl "http://127.0.0.1:8040/api/compaction_score?top_n=10";
+```
diff --git
a/versioned_docs/version-3.x/admin-manual/open-api/be-http/compaction-score.md
b/versioned_docs/version-3.x/admin-manual/open-api/be-http/compaction-score.md
new file mode 100644
index 00000000000..1e48a284fa1
--- /dev/null
+++
b/versioned_docs/version-3.x/admin-manual/open-api/be-http/compaction-score.md
@@ -0,0 +1,73 @@
+---
+{
+ "title": "View Tablet Compaction Score",
+ "language": "en",
+ "description": "It is used to view tablet compaction scores on a BE node."
+}
+---
+
+# View Tablet Compaction Score
+
+## Request
+
+`GET /api/compaction_score?top_n={int}&sync_meta={bool}`
+
+## Description
+
+It is used to view tablet compaction scores on a BE node. The compaction score
is calculated as the sum of the compaction scores of all rowsets in each
tablet. The response is sorted by `compaction_score` in descending order.
+
+## Query parameters
+
+* `top_n`
+
+ Optional. A non-negative integer. If specified, only the top N tablets
with the highest compaction scores are returned. If not specified, all tablets
on the BE node are returned. `top_n=0` returns an empty array.
+
+* `sync_meta`
+
+ Optional. Cloud mode only. Valid values are `true` and `false`. If set to
`true`, BE synchronizes tablet metadata and rowsets from the meta service
before calculating the compaction scores. Do not specify this parameter in
non-cloud mode.
+
+## Request body
+
+None
+
+## Response
+
+Returns a JSON array. Each element contains the following fields:
+
+* `tablet_id`: Tablet ID. The value is returned as a string.
+* `compaction_score`: Tablet compaction score. The value is returned as a
string.
+
+Example response:
+
+```json
+[
+ {
+ "compaction_score": "5",
+ "tablet_id": "42595"
+ },
+ {
+ "compaction_score": "4",
+ "tablet_id": "10034"
+ }
+]
+```
+
+## Error handling
+
+* If `top_n` is not a valid non-negative integer, the API returns HTTP 400
with an error such as `invalid argument: top_n=wrong`.
+* If `sync_meta` is specified in non-cloud mode, the API returns HTTP 400 with
an error message: ``param `sync_meta` is only available for cloud mode``.
+* If `sync_meta` is not `true` or `false`, the API returns HTTP 400 with an
error such as `invalid argument: sync_meta=wrong`.
+
+## Examples
+
+View the top 10 tablets with the highest compaction scores:
+
+```shell
+curl "http://127.0.0.1:8040/api/compaction_score?top_n=10";
+```
+
+View compaction scores after synchronizing metadata in cloud mode:
+
+```shell
+curl "http://127.0.0.1:8040/api/compaction_score?top_n=10&sync_meta=true";
+```
diff --git
a/versioned_docs/version-4.x/admin-manual/open-api/be-http/compaction-score.md
b/versioned_docs/version-4.x/admin-manual/open-api/be-http/compaction-score.md
new file mode 100644
index 00000000000..bcefbcf0e2f
--- /dev/null
+++
b/versioned_docs/version-4.x/admin-manual/open-api/be-http/compaction-score.md
@@ -0,0 +1,88 @@
+---
+{
+ "title": "View Tablet Compaction Score",
+ "language": "en",
+ "description": "View and rank tablet compaction scores on a BE node, with
optional metadata synchronization in storage-compute decoupled mode."
+}
+---
+
+# View Tablet Compaction Score
+
+## Description
+
+Use this read-only API to find tablets with high compaction scores on one BE
node. A tablet's score is the sum of the scores of its rowsets. Results are
sorted by `compaction_score` in descending order. In storage-compute decoupled
mode, the API inspects running tablets currently cached by this BE, rather than
every tablet in the cluster.
+
+## Prerequisites
+
+Connect directly to the BE HTTP port (8040 by default). If the BE
configuration `enable_all_http_auth` is enabled, use a Doris account with the
global `ADMIN` privilege. Replace the credentials in the examples with that
account.
+
+## Request
+
+```text
+GET /api/compaction_score?top_n=<integer>&sync_meta=<boolean>
+```
+
+The request has no body.
+
+## Query parameters
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `top_n` | Non-negative integer | No | All available tablets | Return at most
the N tablets with the highest scores. `0` returns `[]`. The value must fit in
a signed 64-bit integer. |
+| `sync_meta` | Boolean: `true` or `false` | No | `false` | Storage-compute
decoupled mode only. When `true`, synchronize metadata and rowsets for the BE's
cached running tablets from Meta Service before calculating scores. Omit this
parameter entirely in storage-compute coupled mode, including
`sync_meta=false`. |
+
+## Basic usage
+
+The following request checks connectivity and parameter handling without
returning tablet rows:
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=0'
+```
+
+```json
+[]
+```
+
+## Response
+
+A successful request returns HTTP 200 and a JSON array. Each element has two
string-valued fields:
+
+| Field | Description |
+|---|---|
+| `tablet_id` | Tablet ID. |
+| `compaction_score` | Sum of the compaction scores of the tablet's rowsets. |
+
+For example, return up to 10 tablets:
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=10'
+```
+
+The following output is illustrative; the IDs, scores, and number of returned
tablets depend on the BE:
+
+```json
+[
+ {"compaction_score": "5", "tablet_id": "42595"},
+ {"compaction_score": "4", "tablet_id": "10034"}
+]
+```
+
+In storage-compute decoupled mode, request fresh cached-tablet metadata before
calculating scores:
+
+```shell
+curl -u '<user>:<password>'
'http://127.0.0.1:8040/api/compaction_score?top_n=10&sync_meta=true'
+```
+
+The response uses the same JSON format, calculated after synchronization.
+
+## Error handling and caveats
+
+- An unparseable or negative `top_n` returns HTTP 400, for example `invalid
argument: top_n=wrong`.
+- A nonempty `sync_meta` in storage-compute coupled mode returns HTTP 400:
``param `sync_meta` is only available for cloud mode``.
+- In storage-compute decoupled mode, a nonempty `sync_meta` other than `true`
or `false` returns HTTP 400, for example `invalid argument: sync_meta=wrong`.
+- A metadata synchronization failure returns HTTP 500. If authentication is
enabled, missing or invalid credentials can return HTTP 401 or 403.
+- `top_n` limits the response size, not the number of tablets inspected or
synchronized. A score is an observation of this BE's tablet state, rather than
an atomic cluster-wide snapshot.
+
+## Best practices
+
+Start with a small `top_n` and the default `sync_meta=false` to identify
tablets for further investigation. Use `sync_meta=true` when fresh metadata is
necessary; it synchronizes all cached running tablets before applying `top_n`
and can increase latency and Meta Service load.
diff --git a/versioned_sidebars/version-2.1-sidebars.json
b/versioned_sidebars/version-2.1-sidebars.json
index 27d5d68906c..bb2bd55d3ee 100644
--- a/versioned_sidebars/version-2.1-sidebars.json
+++ b/versioned_sidebars/version-2.1-sidebars.json
@@ -804,6 +804,7 @@
"admin-manual/open-api/be-http/reset-rpc-channel",
"admin-manual/open-api/be-http/compaction-status",
"admin-manual/open-api/be-http/compaction-run",
+
"admin-manual/open-api/be-http/compaction-score",
"admin-manual/open-api/be-http/meta",
"admin-manual/open-api/be-http/snapshot",
"admin-manual/open-api/be-http/check-tablet-segment",
diff --git a/versioned_sidebars/version-3.x-sidebars.json
b/versioned_sidebars/version-3.x-sidebars.json
index f3c5feed1f4..a20d7b8e6a3 100644
--- a/versioned_sidebars/version-3.x-sidebars.json
+++ b/versioned_sidebars/version-3.x-sidebars.json
@@ -945,6 +945,7 @@
"admin-manual/open-api/be-http/reset-rpc-channel",
"admin-manual/open-api/be-http/compaction-status",
"admin-manual/open-api/be-http/compaction-run",
+
"admin-manual/open-api/be-http/compaction-score",
"admin-manual/open-api/be-http/meta",
"admin-manual/open-api/be-http/snapshot",
"admin-manual/open-api/be-http/check-tablet-segment",
diff --git a/versioned_sidebars/version-4.x-sidebars.json
b/versioned_sidebars/version-4.x-sidebars.json
index 84bbcc55048..ec833bdf53f 100644
--- a/versioned_sidebars/version-4.x-sidebars.json
+++ b/versioned_sidebars/version-4.x-sidebars.json
@@ -1310,6 +1310,7 @@
"admin-manual/open-api/be-http/reset-rpc-channel",
"admin-manual/open-api/be-http/compaction-status",
"admin-manual/open-api/be-http/compaction-run",
+ "admin-manual/open-api/be-http/compaction-score",
"admin-manual/open-api/be-http/meta",
"admin-manual/open-api/be-http/snapshot",
"admin-manual/open-api/be-http/check-tablet-segment",
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
