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 c4fcf7511d02 [docs](iceberg) Document REST catalog labels since 5.0.0
(#4532)
c4fcf7511d02 is described below
commit c4fcf7511d021e12d4132092cdbae7fbe3d6abd5
Author: Mingyu Chen (Rayner) <[email protected]>
AuthorDate: Tue Oct 27 14:13:55 2026 +0000
[docs](iceberg) Document REST catalog labels since 5.0.0 (#4532)
Document the Iceberg REST Catalog `$labels` system table introduced by
https://github.com/apache/doris/pull/69135, available since Doris 5.0.0.
Update the English and Chinese current-version Iceberg Catalog guides
with the field definitions, query examples and expected results, cache
refresh instructions, and restrictions. Cover REST-only availability,
nested fields, schema changes, empty results, snapshot-independent
labels, and the server-side scan planning restriction. Add
support-matrix and system-table version notes.
## Validation
- Docusaurus MDX compilation, front matter, and section-link targets
passed for both pages.
- Internal-link checks passed for both pages; existing external links
are report-only.
- All five SQL and expected-output blocks match between English and
Chinese.
- `git diff --check` passed.
- SEO checking reported existing duplicate-title warnings across
versions and locales; front matter is unchanged.
- AI self-review found no additional issues. Page paths, navigation, and
site code are unchanged. Older versions are not updated because this
feature starts in 5.0.0.
## Versions
- [x] dev
- [ ] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [x] Checked by AI
- [ ] Test Cases Built (documentation only; no runtime test cases added
or run)
- [x] Updated required version and language counterparts, or explained
why not
- [x] If only one language changed, confirmed whether source/translation
counterparts need sync (not applicable: both languages updated)
Co-authored-by: morningman <[email protected]>
---
docs/lakehouse/catalogs/iceberg-catalog.mdx | 84 ++++++++++++++++++++++
.../current/lakehouse/catalogs/iceberg-catalog.mdx | 84 ++++++++++++++++++++++
2 files changed, 168 insertions(+)
diff --git a/docs/lakehouse/catalogs/iceberg-catalog.mdx
b/docs/lakehouse/catalogs/iceberg-catalog.mdx
index dbf717bcbf66..b073cf162021 100644
--- a/docs/lakehouse/catalogs/iceberg-catalog.mdx
+++ b/docs/lakehouse/catalogs/iceberg-catalog.mdx
@@ -222,6 +222,8 @@ See the documentation for this system table:
[catalog_meta_cache_statistics](../
| Iceberg Rest Catalog | ✅ | ✅ | Depends on the service
provider | Depends on the service provider | Depends on the service provider
|
| FileSystem | ✅ | ✅ | ✅
| ✅ | ✅ |
+The `labels` system table is supported since version 5.0.0 and is available
only for Iceberg REST Catalogs. See [labels](#labels) below.
+
## Supported Storage Systems
* [HDFS](../storages/hdfs.md)
@@ -1725,6 +1727,8 @@ SELECT * FROM iceberg_table$history;
> The `all_manifests` system table is supported starting from version 4.0.4.
>
> The `position_deletes` system table is supported starting from version 4.1.4.
+>
+> The `labels` system table is supported starting from version 5.0.0 and is
available only for Iceberg REST Catalogs.
:::caution Behavior Change (4.1.4)
@@ -1819,6 +1823,86 @@ Result:
+----------------------------+---------------------+---------------------+---------------------+
```
+### labels
+
+> This feature is supported starting from version 5.0.0
+
+Shows the table-level (`object`) and field-level (`field`) labels that a REST
Catalog provides for an Iceberg table, with one row per label key-value pair.
Use it to inspect information such as table ownership and field data
classifications.
+
+This system table is available only when `iceberg.catalog.type` is `rest`. No
additional Doris configuration is required. The REST Catalog service returns
labels when loading the table; create and modify labels through the service
provider. These labels describe tables or fields and are distinct from the
snapshot Tags shown in [refs](#refs).
+
+**Fields:**
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `scope` | `TEXT` | Label scope: `object` for a table-level label or `field`
for a field-level label. |
+| `field_id` | `INT` | Iceberg field ID. `NULL` for table-level labels. |
+| `field_name` | `TEXT` | Field name resolved against the current table
schema. Nested fields use the full path, such as `address.city`. `NULL` for
table-level labels or when the field ID does not exist in the current schema. |
+| `key` | `TEXT` | Label key. Since `key` is a reserved word in Doris, enclose
it in backticks when explicitly referencing this column in SQL. |
+| `value` | `TEXT` | Label value. |
+
+**Query examples:**
+
+The following examples assume that you have configured the `iceberg_ctl`
catalog as described in [Iceberg REST Catalog](#iceberg-rest-catalog), that the
table `iceberg_db.iceberg_tbl` exists, and that the current user has permission
to query it. The REST Catalog service has configured and returns these labels:
+
+- Table-level label: `owner=team-a`.
+- Label on the `email` field (field ID `2`): `classification=pii`.
+- Label on the nested field `address.city` (field ID `5`):
`classification=location`.
+
+Query all labels, ordered by scope, field ID, and label key:
+
+```sql
+SELECT * FROM iceberg_ctl.iceberg_db.iceberg_tbl$labels
+ORDER BY scope, field_id, `key`;
+```
+
+Result:
+
+```text
++--------+----------+--------------+----------------+----------+
+| scope | field_id | field_name | key | value |
++--------+----------+--------------+----------------+----------+
+| field | 2 | email | classification | pii |
+| field | 5 | address.city | classification | location |
+| object | NULL | NULL | owner | team-a |
++--------+----------+--------------+----------------+----------+
+```
+
+Find fields classified as `pii`:
+
+```sql
+SELECT field_name, `key`, value
+FROM iceberg_ctl.iceberg_db.iceberg_tbl$labels
+WHERE scope = 'field' AND `key` = 'classification' AND value = 'pii';
+```
+
+Result:
+
+```text
++------------+----------------+-------+
+| field_name | key | value |
++------------+----------------+-------+
+| email | classification | pii |
++------------+----------------+-------+
+```
+
+**Caching and refresh:**
+
+Labels are cached with the table metadata and follow the
`meta.cache.iceberg.table.ttl-second` setting. After changing labels on the
service, refresh the base table before querying `$labels` to retrieve the
updated labels:
+
+```sql
+REFRESH TABLE iceberg_ctl.iceberg_db.iceberg_tbl;
+```
+
+After the refresh, the next `$labels` query reloads the table and reads the
labels returned by the service. Set `meta.cache.iceberg.table.ttl-second` to
`0` to disable the table metadata cache and reload labels for each query. See
[Metadata Cache](#meta-cache) for cache settings.
+
+**Notes:**
+
+- If the REST Catalog service returns no labels, the query result is empty. A
table without any snapshots can still return labels if the service provides
them. `COUNT(*)` counts label key-value pairs, rather than data rows in the
base table.
+- Labels are not versioned with snapshots. Using `FOR VERSION AS OF` on
`$labels` does not retrieve historical labels: the query still returns labels
from the current table load, and field names are resolved against the current
schema.
+- Field labels are associated with field IDs. After a field is renamed,
`field_name` shows its new name. If a field is dropped and the service still
returns its labels, `field_id` is retained and `field_name` is `NULL`.
+- Non-REST Catalogs do not support `$labels`; querying it returns an `Unknown
sys table` error. REST Catalogs that require server-side scan planning also do
not support this system table.
+
### manifests
Shows manifest file info of the table:
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/catalogs/iceberg-catalog.mdx
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/catalogs/iceberg-catalog.mdx
index ce4457472aa4..e371033e5386 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/catalogs/iceberg-catalog.mdx
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/catalogs/iceberg-catalog.mdx
@@ -229,6 +229,8 @@ ORDER BY engine_name, entry_name;
| Iceberg Rest Catalog | ✅ | ✅ | 取决于服务提供方 | 取决于服务提供方 | 取决于服务提供方 |
| FileSystem | ✅ | ✅ | ✅ | ✅ | ✅
|
+`labels` 系统表自 5.0.0 版本起支持，且仅适用于 Iceberg REST Catalog，详见下文 [labels](#labels)。
+
## 支持的存储系统
* [HDFS](../storages/hdfs.md)
@@ -1739,6 +1741,8 @@ SELECT * FROM iceberg_table$history;
> `all_manifests` 系统表从 4.0.4 版本开始支持。
>
> `position_deletes` 系统表从 4.1.4 版本开始支持。
+>
+> `labels` 系统表从 5.0.0 版本开始支持，仅适用于 Iceberg REST Catalog。
:::caution 版本行为变更（4.1.4）
@@ -1832,6 +1836,86 @@ SELECT * FROM iceberg_table$history;
+----------------------------+---------------------+---------------------+---------------------+
```
+### labels
+
+> 该功能自 5.0.0 版本支持
+
+显示 REST Catalog 为 Iceberg
表提供的表级（`object`）和字段级（`field`）标签，每个标签键值对占一行。可用于查看表的负责人、字段的数据分类等信息。
+
+仅当 Catalog 的 `iceberg.catalog.type` 为 `rest` 时支持该系统表，无需额外开启 Doris 配置。标签由 REST
Catalog 服务在加载表时返回，标签的创建和修改需通过服务提供方完成。这里的标签是描述表或字段的键值对，与 [refs](#refs) 中引用快照的
Tag 不同。
+
+**字段说明：**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `scope` | `TEXT` | 标签作用范围：`object` 表示表级标签，`field` 表示字段级标签。 |
+| `field_id` | `INT` | Iceberg 字段 ID。表级标签为 `NULL`。 |
+| `field_name` | `TEXT` | 根据当前表结构解析的字段名，嵌套字段使用完整路径，例如 `address.city`。表级标签为
`NULL`；字段 ID 在当前表结构中不存在时也为 `NULL`。 |
+| `key` | `TEXT` | 标签键。`key` 是 Doris 保留字，在 SQL 中显式引用该列时需使用反引号。 |
+| `value` | `TEXT` | 标签值。 |
+
+**查询示例：**
+
+以下示例假设已按照 [Iceberg REST Catalog](#iceberg-rest-catalog) 章节配置 Catalog
`iceberg_ctl`，其中存在表 `iceberg_db.iceberg_tbl`，且当前用户具有该表的查询权限。REST Catalog
服务已为该表设置并返回以下标签：
+
+- 表级标签：`owner=team-a`。
+- 字段 `email`（字段 ID 为 `2`）的标签：`classification=pii`。
+- 嵌套字段 `address.city`（字段 ID 为 `5`）的标签：`classification=location`。
+
+查询全部标签，并按作用范围、字段 ID 和标签键排序：
+
+```sql
+SELECT * FROM iceberg_ctl.iceberg_db.iceberg_tbl$labels
+ORDER BY scope, field_id, `key`;
+```
+
+结果：
+
+```text
++--------+----------+--------------+----------------+----------+
+| scope | field_id | field_name | key | value |
++--------+----------+--------------+----------------+----------+
+| field | 2 | email | classification | pii |
+| field | 5 | address.city | classification | location |
+| object | NULL | NULL | owner | team-a |
++--------+----------+--------------+----------------+----------+
+```
+
+筛选标记为 `pii` 的字段：
+
+```sql
+SELECT field_name, `key`, value
+FROM iceberg_ctl.iceberg_db.iceberg_tbl$labels
+WHERE scope = 'field' AND `key` = 'classification' AND value = 'pii';
+```
+
+结果：
+
+```text
++------------+----------------+-------+
+| field_name | key | value |
++------------+----------------+-------+
+| email | classification | pii |
++------------+----------------+-------+
+```
+
+**缓存与刷新：**
+
+标签随表元数据一起缓存，遵循 `meta.cache.iceberg.table.ttl-second` 的设置。服务端修改标签后，建议刷新原始表，再查询
`$labels` 以获取更新后的标签：
+
+```sql
+REFRESH TABLE iceberg_ctl.iceberg_db.iceberg_tbl;
+```
+
+刷新后，下一次 `$labels` 查询会重新加载表并读取服务端返回的标签。将 `meta.cache.iceberg.table.ttl-second`
设为 `0` 可关闭表元数据缓存，使每次查询重新加载标签；缓存配置详见[元数据缓存](#meta-cache)。
+
+**注意事项：**
+
+- REST Catalog 服务未返回标签时，查询结果为空。即使表尚未产生任何快照，只要服务端返回标签，仍可查询到这些标签。`COUNT(*)`
统计的是标签键值对数量，而不是原始表的数据行数。
+- 标签不随快照进行版本管理。对 `$labels` 使用 `FOR VERSION AS OF`
不会读取历史标签，仍返回本次加载的标签，字段名也按当前表结构解析。
+- 字段标签按字段 ID 关联。字段重命名后，`field_name` 显示新名称；字段删除后，如果服务端仍返回该字段的标签，则保留
`field_id`，`field_name` 为 `NULL`。
+- 非 REST Catalog 不支持 `$labels`，查询会报 `Unknown sys table`
错误。要求服务端扫描规划（server-side scan planning）的 REST Catalog 也不支持查询该系统表。
+
### manifests
显示表的当前 manifest 文件信息：
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
