[doc](lakehouse) Add external metadata cache memory management for 4.1.4

i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/system-tables/information_schema/catalog_meta_cache_statistics.md

@@ -2,63 +2,80 @@
 {
     "title": "catalog_meta_cache_statistics",
     "language": "zh-CN",
-    "description": "查看当前连接的 FE 中，External Catalog 的元数据缓存信息。"
+    "description": "查看 FE 节点上的 External Catalog 元数据缓存配置、运行状态和内存治理统计信息。"
 }
 ---
 
 ## 概述
 
-查看当前连接的 FE 中，External Catalog 的元数据缓存信息。
+`catalog_meta_cache_statistics` 为当前用户可见的每个 FE、External Catalog、元数据缓存引擎和缓存模块显示一行数据。除缓存配置和 Caffeine 运行指标外，该表还显示 Doris 4.1.4 引入的保留内存上限、估算使用量、淘汰内存和准入拒绝信息。
 
 ## 所属数据库
 
-
 `information_schema`
 
-
 ## 表信息
 
-该表中一行表示“某个 FE 上、某个 external catalog 的一个 cache entry”的统计快照。
-
 | 列名 | 类型 | 说明 |
-| :----------- | :--- | :----------- |
-| FE_HOST | text | 上报该统计的 FE 主机 |
-| CATALOG_NAME | text | Catalog 名字 |
-| ENGINE_NAME | text | Meta cache 引擎名，如 `hive`、`iceberg`、`paimon` |
-| ENTRY_NAME | text | 引擎内部的 cache entry 名，如 `schema`、`file`、`manifest` |
-| EFFECTIVE_ENABLED | boolean | 综合 `enable` / `ttl-second` / `capacity` 后，该缓存是否真正生效 |
-| CONFIG_ENABLED | boolean | 配置中的原始 `enable` 值 |
-| AUTO_REFRESH | boolean | 该 entry 是否启用异步 refresh-after-write |
-| TTL_SECOND | bigint | TTL 秒数。`0` 表示关闭，`-1` 表示永不过期 |
-| CAPACITY | bigint | 最大条目数 |
-| ESTIMATED_SIZE | bigint | 当前缓存条目估计数 |
-| REQUEST_COUNT | bigint | 总请求数 |
-| HIT_COUNT | bigint | 命中次数 |
-| MISS_COUNT | bigint | 未命中次数 |
-| HIT_RATE | double | 命中率 |
-| LOAD_SUCCESS_COUNT | bigint | 成功加载次数 |
-| LOAD_FAILURE_COUNT | bigint | 失败加载次数 |
-| TOTAL_LOAD_TIME_MS | bigint | 总加载耗时，单位毫秒 |
-| AVG_LOAD_PENALTY_MS | double | 平均加载耗时，单位毫秒 |
-| EVICTION_COUNT | bigint | 被驱逐条目数 |
-| INVALIDATE_COUNT | bigint | 显式失效次数 |
-| LAST_LOAD_SUCCESS_TIME | text | 最近一次成功加载时间 |
-| LAST_LOAD_FAILURE_TIME | text | 最近一次失败加载时间 |
-| LAST_ERROR | text | 最近一次加载失败错误信息 |
+|---|---|---|
+| `FE_HOST` | STRING | 上报该行数据的 FE 节点。 |
+| `CATALOG_NAME` | STRING | External Catalog 名称。 |
+| `ENGINE_NAME` | STRING | 元数据缓存引擎，例如 `hive`、`iceberg` 或 `paimon`。 |
+| `ENTRY_NAME` | STRING | 引擎中的缓存模块名称。 |
+| `EFFECTIVE_ENABLED` | BOOLEAN | 综合 enable、TTL、capacity 和 weight 配置后，该模块当前是否实际生效。 |
+| `CONFIG_ENABLED` | BOOLEAN | 配置的 `enable` 值。 |
+| `AUTO_REFRESH` | BOOLEAN | 是否启用受管理的自动刷新。 |
+| `TTL_SECOND` | BIGINT | 过期时间，单位为秒。`-1` 表示永不过期，`0` 表示关闭模块。 |
+| `CAPACITY` | BIGINT | 配置的条目数容量。启用 `max-weight` 后不再同时作为条目数上限，但 `0` 仍会关闭模块。 |
+| `ESTIMATED_SIZE` | BIGINT | 缓存映射数量的近似值。 |
+| `REQUEST_COUNT` | BIGINT | 缓存查询总次数。 |
+| `HIT_COUNT` | BIGINT | 缓存命中次数。 |
+| `MISS_COUNT` | BIGINT | 缓存未命中次数。 |
+| `HIT_RATE` | DOUBLE | 缓存命中率，范围为 `0.0` 到 `1.0`。 |
+| `LOAD_SUCCESS_COUNT` | BIGINT | 缓存加载成功次数。 |
+| `LOAD_FAILURE_COUNT` | BIGINT | 缓存加载失败次数。 |
+| `TOTAL_LOAD_TIME_MS` | BIGINT | 缓存加载总耗时，单位为毫秒。 |
+| `AVG_LOAD_PENALTY_MS` | DOUBLE | 平均加载耗时，单位为毫秒。 |
+| `EVICTION_COUNT` | BIGINT | Caffeine 和本地预算主动淘汰的次数。 |
+| `INVALIDATE_COUNT` | BIGINT | 显式失效缓存的次数。 |
+| `LAST_LOAD_SUCCESS_TIME` | STRING | 最近一次加载成功时间。 |
+| `LAST_LOAD_FAILURE_TIME` | STRING | 最近一次加载失败时间。 |
+| `LAST_ERROR` | STRING | 最近一次加载错误；没有记录时为空。 |
+| `WEIGHT_BOUNDED` | BOOLEAN | 当前模块是否受到 FE、Catalog 或模块级内存上限约束。 |
+| `MAX_WEIGHT` | BIGINT | 模块的有效内存上限，单位为字节。 |
+| `ESTIMATED_WEIGHT` | BIGINT | 当前模块已预留的估算内存，单位为字节。 |
+| `EVICTION_WEIGHT` | BIGINT | 自动淘汰和本地预算淘汰累计释放的估算字节数。 |
+| `WEIGHT_REJECT_COUNT` | BIGINT | 因估算不完整或权重预算不足而拒绝缓存准入的次数。 |
+| `CATALOG_MAX_WEIGHT` | BIGINT | Catalog 内存上限，单位为字节。 |
+| `CATALOG_ESTIMATED_WEIGHT` | BIGINT | 当前 Catalog 中受管理模块已预留的估算内存。 |
+| `GLOBAL_MAX_WEIGHT` | BIGINT | FE 外部元数据缓存总内存上限，单位为字节。 |
+| `GLOBAL_ESTIMATED_WEIGHT` | BIGINT | 当前 FE 上受管理外部元数据缓存已预留的估算内存。 |
+| `LAST_WEIGHT_REJECT_REASON` | STRING | 最近一次权重准入拒绝原因。 |
 
+对于仍按条目数管理的模块，或者未配置的父级上限，不适用的 weight 数值列使用 `-1`。
 
 ## 使用示例
 
+查看按内存管理的模块及其最近一次准入结果：
+
 ```sql
-SELECT catalog_name, engine_name, entry_name,
-       effective_enabled, ttl_second, capacity,
-       estimated_size, hit_rate, last_error
+SELECT fe_host, catalog_name, engine_name, entry_name,
+       max_weight, estimated_weight, eviction_weight,
+       weight_reject_count, last_weight_reject_reason,
+       catalog_max_weight, catalog_estimated_weight,
+       global_max_weight, global_estimated_weight
 FROM information_schema.catalog_meta_cache_statistics
-ORDER BY catalog_name, engine_name, entry_name;
+WHERE weight_bounded = true
+ORDER BY fe_host, catalog_name, engine_name, entry_name;
 ```
 
-常见用法：
+查看指定 Catalog 的缓存效果和加载失败信息：
 
-- 用 `ENGINE_NAME` + `ENTRY_NAME` 定位具体的逻辑缓存。
-- 用 `EFFECTIVE_ENABLED`、`TTL_SECOND`、`CAPACITY` 确认实际生效的缓存策略。
-- 用 `HIT_RATE`、`ESTIMATED_SIZE`、`LOAD_FAILURE_COUNT`、`LAST_ERROR` 排查缓存行为。
+```sql
+SELECT engine_name, entry_name, effective_enabled,
+       estimated_size, request_count, hit_rate,
+       load_failure_count, last_error
+FROM information_schema.catalog_meta_cache_statistics
+WHERE catalog_name = 'iceberg_ctl'
+ORDER BY engine_name, entry_name;
+```

i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/catalogs/hive-catalog.mdx

@@ -89,15 +89,16 @@
 
 ### 缓存属性配置（4.1.x+） {#meta-cache-unified-model}
 
-各引擎 cache entry 使用统一的配置键格式：`meta.cache.<engine>.<entry>.{enable,ttl-second,capacity}`。
+各引擎 cache entry 使用统一的配置键格式：`meta.cache.<engine>.<entry>.{enable,ttl-second,capacity,max-weight}`。`max-weight` 当前只适用于部分已接入估算器的模块，详见[外表元数据缓存内存管理](../external-meta-cache-memory-management.md)。
 
 | 属性 | 示例 | 含义 |
 |---|---|---|
 | `enable` | `true/false` | 是否启用该缓存模块。 |
 | `ttl-second` | `600`、`0`、`-1` | `0` 表示关闭缓存（即刻生效，可用于查看最新数据）；`-1` 表示永不过期；其他正整数表示按访问时间计算 TTL（秒）。 |
-| `capacity` | `10000` | 最大缓存条目数（按条目数量计）。`0` 表示关闭。 |
+| `capacity` | `10000` | 按条目数计算的最大容量。启用 `max-weight` 后不再同时作为条目数上限，但 `0` 仍会关闭缓存。 |
+| `max-weight` | `1GB` | 可选的估算保留内存上限。Hive 当前仅 `partition_values` 支持；`0` 会关闭该模块。 |
 
-**生效逻辑说明：** 只有当 `enable=true` 且 `ttl-second != 0` 且 `capacity > 0` 时，该模块缓存才会生效。
+**生效逻辑说明：** 只有当 `enable=true`、`ttl-second != 0`、`capacity > 0`，并且 `max-weight` 未配置或不为 `0` 时，该模块缓存才会生效。
 
 ### 缓存模块 {#meta-cache-unified-modules}
 
@@ -136,7 +137,7 @@
 * **性能优化**：对于元数据变动不频繁的场景，建议适当增大 `capacity` 和 `ttl-second` 以减少对 Hive Metastore 和文件系统的访问压力。
 
 :::caution
-**Hive Catalog 注意事项**：Hive 的 `meta.cache.hive.*` 属性修改**不支持热生效**。修改配置后，必须重建 Catalog 或重启 FE 节点才能应用新的缓存配置。
+**Hive Catalog 注意事项**：从 Doris 4.1.4 开始，Catalog 属性修改成功后会重置 Catalog 执行上下文，并清理该 Catalog 路由到的所有元数据缓存引擎中已初始化的条目；下一次访问使用新的上下文和配置重建。已经开始的查询不受影响。
 :::
 
 ### 可观测性 {#meta-cache-unified-observability}
@@ -638,7 +639,7 @@
     <summary>2.1 & 3.0 版本</summary>
     <Tabs>
         <TabItem value='S3' label='S3' default>
             非 EC2 环境下，需要使用 [aws configure ](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) 配置 Credentials 信息，同时在~/.aws 目录下生成 credentials 文件。
 
             或者显示的在创建 catalog 参数中新增凭据提供方式 <b>"aws.catalog.credentials.provider.factory.class"="com.amazonaws.glue.catalog.credentials.ConfigurationAWSCredentialsProviderFactory"</b>
             ```sql
@@ -758,7 +759,7 @@
 
 ### 查询 Hive 事务表
 
 Hive Transactional 表是 Hive 中支持 ACID 语义的表。详情可见 [Hive Transactions](https://cwiki.apache.org/confluence/display/Hive/Hive+Transactions)。
 
 * Hive Transactional 表支持情况
 
@@ -989,7 +990,7 @@
   );
   ```
 
   创建后，可以通过 `SHOW CREATE TABLE` 命令查看 Hive 的建表语句。
 
   注意，不同于 Hive 中的建表语句。在 Doris 中创建 Hive 分区表时，分区列也必须写到 Table 的 Schema 中。同时，分区列必须在所有 Schema 的最后，且顺序保持一致。
 

i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/catalogs/hudi-catalog.md

@@ -62,7 +62,7 @@
 
 ### 缓存属性配置（4.1.x+） {#meta-cache-unified-model}
 
-各引擎 cache entry 使用统一的配置键格式：`meta.cache.<engine>.<entry>.{enable,ttl-second,capacity}`。
+Hudi cache entry 使用配置键格式 `meta.cache.hudi.<entry>.{enable,ttl-second,capacity}`。Hudi 模块当前仍按条目数管理，不接受模块级 `max-weight`，详见[外表元数据缓存内存管理](../external-meta-cache-memory-management.md)。
 
 | 属性 | 示例 | 含义 |
 |---|---|---|
@@ -102,7 +102,7 @@
   -- 关闭分区元数据缓存，以感知 Hudi 表的最新分区变动
   ALTER CATALOG hudi_ctl SET PROPERTIES ("meta.cache.hudi.partition.ttl-second" = "0");
   ```
-* **性能优化**：`ALTER CATALOG ... SET PROPERTIES` 的修改在 Hudi 中支持热生效（通过 HMS catalog 属性更新路径）。
+* **性能优化**：自 Doris 4.1.4 起，Catalog 属性修改成功后会重置 Catalog 执行上下文，并清理该 Catalog 路由到的所有元数据缓存引擎中已初始化的条目；下一次访问使用新的上下文和配置重建，正在执行的查询不受影响。
 
 ### 可观测性 {#meta-cache-unified-observability}
 
@@ -242,7 +242,7 @@
 +-------------------+--------+--------------------------+-----------+-----------------------+
 ```
 
 可以使用 `FOR TIME AS OF` 语句，根据快照的时间 ([时间格式](https://hudi.apache.org/docs/0.14.0/quick-start-guide/#timetravel)和 Hudi 官网保持一致) 读取历史版本的数据。示例如下：
 
 ```sql
 SELECT * FROM hudi_tbl FOR TIME AS OF "2022-10-07 17:20:37";
@@ -264,13 +264,13 @@
 
 * `beginTime`
 
   必填项。时间格式和 Hudi 官网 [hudi\_table\_changes](https://hudi.apache.org/docs/0.14.0/quick-start-guide/#incremental-query) 保持一致，支持 "earliest"。
 
 * `endTime`
 
   选填，默认最新 commitTime。
 
 可以在 `@incr`函数中添加更多选项，兼容 [Spark Read Options](https://hudi.apache.org/docs/0.14.0/configurations#Read-Options)。
 
 通过 `desc` 查看执行计划，可以发现 Doris 将 `@incr` 转化为 `predicates` 下推给 `VHUDI_SCAN_NODE`:
 

i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/catalogs/iceberg-catalog.mdx

@@ -55,7 +55,7 @@
 
   * `dlf`：使用阿里云 DLF 作为元数据服务。
 
   * `s3tables`：使用 AWS S3 Tables Catalog 访问 [S3 Table Bucket](https://aws.amazon.com/s3/features/tables/)。
 
 * `<warehouse>`
 
@@ -99,7 +99,7 @@
 
 ## 元数据缓存 {#meta-cache}
 
-为了提升访问外部数据源的性能，Apache Doris 会对 Iceberg 的元数据进行缓存。元数据包括表结构（Schema）、表对象、View 对象和 Manifest 详情等。
+为了提升访问外部数据源的性能，Apache Doris 会对 Iceberg 的元数据进行缓存。元数据包括表结构（Schema）、表对象、Snapshot、View 对象和 Manifest 详情等。
 
 :::tip
 对于 Doris 4.1.x 之前的版本，元数据缓存主要由 FE 配置项全局控制，详情请参阅[元数据缓存](../meta-cache.md)。
@@ -108,15 +108,16 @@
 
 ### 缓存属性配置（4.1.x+） {#meta-cache-unified-model}
 
-各引擎 cache entry 使用统一的配置键格式：`meta.cache.<engine>.<entry>.{enable,ttl-second,capacity}`。
+各引擎 cache entry 使用统一的配置键格式：`meta.cache.<engine>.<entry>.{enable,ttl-second,capacity,max-weight}`。内存上限只适用于已接入估算器的模块，详见[外表元数据缓存内存管理](../external-meta-cache-memory-management.md)。
 
 | 属性 | 示例 | 含义 |
 |---|---|---|
 | `enable` | `true/false` | 是否启用该缓存模块。 |
 | `ttl-second` | `600`、`0`、`-1` | `0` 表示关闭缓存（即刻生效，可用于查看最新数据）；`-1` 表示永不过期；其他正整数表示按访问时间计算 TTL（秒）。 |
-| `capacity` | `10000` | 最大缓存条目数（按条目数量计）。`0` 表示关闭。 |
+| `capacity` | `10000` | 按条目数计算的最大容量。启用 `max-weight` 后不再同时作为条目数上限，但 `0` 仍会关闭缓存。 |
+| `max-weight` | `1GB` | 可选的估算保留内存上限。Iceberg 的 `table`、`snapshot`、`manifest` 支持；`0` 会关闭对应模块。 |
 
-**生效逻辑说明：** 只有当 `enable=true` 且 `ttl-second != 0` 且 `capacity > 0` 时，该模块缓存才会生效。
+**生效逻辑说明：** 只有当 `enable=true`、`ttl-second != 0`、`capacity > 0`，并且 `max-weight` 未配置或不为 `0` 时，该模块缓存才会生效。
 
 ### 缓存模块 {#meta-cache-unified-modules}
 
@@ -126,6 +127,7 @@
 |---|---|---|
 | `schema` | `meta.cache.iceberg.schema.` | 缓存表结构。影响：列新增、删除、类型变更在 Doris 中的可见性。若关闭，每次查询都会拉取最新 Schema。 |
 | `table` | `meta.cache.iceberg.table.` | 缓存 Iceberg 表元数据对象。影响：最新 Snapshot、Partition Spec、Sort Order、表属性等表级元数据在 Doris 中的可见性；若关闭，每次规划都会重新加载表元数据。 |
+| `snapshot` | `meta.cache.iceberg.snapshot.` | 缓存 Snapshot 元数据及其保留的表元数据代际，减少重复加载 Snapshot 和分区投影的开销；支持 `max-weight`。 |
 | `view` | `meta.cache.iceberg.view.` | 缓存 Iceberg View 元数据对象。影响：View 定义、Schema、属性变更在 Doris 中的可见性。 |
 | `manifest` | `meta.cache.iceberg.manifest.` | 缓存 Manifest 详情。主要影响查询规划时重复读取 Manifest 文件的开销，通常不直接决定表或 Snapshot 是否可见。注意：该模块默认关闭，需手动启用。 |
 
@@ -156,7 +158,7 @@
         "meta.cache.iceberg.manifest.ttl-second" = "600"
       );
       ```
-    * `ALTER CATALOG ... SET PROPERTIES` 的修改在 Iceberg Catalog 中支持热生效。
+    * 自 Doris 4.1.4 起，Catalog 属性修改成功后会重置 Catalog 执行上下文，并清理该 Catalog 路由到的所有元数据缓存引擎中已初始化的条目；下一次访问使用新的上下文和配置重建，正在执行的查询不受影响。
 
 ### 可观测性 {#meta-cache-unified-observability}
 
@@ -181,7 +183,7 @@
 | 3.0 | 1.6.1 |
 | 3.1 | 1.9.1 |
 | 4.0 | 1.9.1 |
-| 4.1 | 1.10.1 |
+| 4.1（4.1.4+） | 1.10.1 |
 
 ## 支持的 Iceberg 格式
 
@@ -283,7 +285,7 @@
 :::info 版本说明
 
 4.0.8 之前的版本在读取时按精确匹配定位列，含大小写混合列名的 Iceberg / Paimon 表可能读到错误的列或查询失败。该问题已在 4.0.8 中修复。
 
 :::
 
 ## Namespace 映射
@@ -692,7 +694,7 @@
         <TabItem value='S3' label='S3' default>
             AWS Glue 和 S3 存储服务共用一套认证信息。
 
             非 EC2 环境下，需要使用 [aws configure](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) 配置 Credentials 信息，同时在 ~/.aws 目录下生成 credentials 文件。
             ```sql
             CREATE CATALOG glue PROPERTIES (
                 'type' = 'iceberg',
@@ -2210,7 +2212,7 @@
 
     * 支持创建单列或多列分区表。
 
     * 支持分区转换函数来支持 Iceberg 隐式分区以及分区演进的功能。具体 Iceberg 分区转换函数可以查看 [Iceberg partition transforms](https://iceberg.apache.org/spec/#partition-transforms)。
 
         * `year(ts)` 或者 `years(ts)`
 
@@ -2790,7 +2792,7 @@
 1. `rewrite_data_files` 操作会读取数据文件并重新写入，会产生额外的 I/O 和计算开销，请合理分配集群资源。
 2. 执行前可以通过[查看数据文件分布](#查看数据文件分布)章节中的 SQL 来评估是否需要执行重写操作。
 3. WHERE 条件可用于限制重写的分区或数据范围，这个条件会过滤掉那些不包含符合 WHERE 条件的数据的文件，从而减少重写的文件数量和数据量。
 4. 执行前可以通过[重写文件选择逻辑](#重写文件选择逻辑)章节中的 SQL 来计算哪些文件会被重写。
 
 ### rewrite_manifests
 
@@ -3027,7 +3029,7 @@
 
 ### Dangling Delete
 
 某些情况下，在执行完 `rewrite_data_files` 方法后，某些 Position Delete 的引用可能没有从 Snapshot 元数据中删除（Dangling Delete）。此时如果直接使用元数据中的行数信息，结果可能是[错误](https://iceberg.apache.org/docs/nightly/spark-procedures/#rewrite_position_delete_files)的。
 
 因此，在默认情况下，对于 `COUNT(*)` 查询，如果发现存在 Position Delete 文件，则不启用 COUNT 下推优化，而是直接读取文件获取真实的 `COUNT(*)` 结果。但这种方式耗时较长。
 
@@ -3087,7 +3089,7 @@
             WHEN file_size_in_bytes > @max_file_size_bytes THEN 'Too large'
         END AS size_issue
     FROM iceberg_table$data_files
     WHERE file_size_in_bytes < @min_file_size_bytes
     OR file_size_in_bytes > @max_file_size_bytes
     ORDER BY `partition`, file_size_in_bytes DESC;
     ```
@@ -3148,7 +3150,7 @@
     FROM file_analysis
     UNION ALL
     SELECT
         'Percentage meeting file-level conditions (%)',
         ROUND(SUM(CASE WHEN meets_file_level_conditions THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2)
     FROM file_analysis;
     ```

i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/catalogs/maxcompute-catalog.md

@@ -6,7 +6,7 @@
 }
 ---
 
 [MaxCompute](https://help.aliyun.com/zh/maxcompute/) 是阿里云上的企业级 SaaS（Software as a Service）模式云数据仓库。通过 MaxCompute 提供的开放存储 SDK，Doris 可以获取 MaxCompute 的表信息，并进行查询和写入操作。
 
 ## 适用场景
 
@@ -122,7 +122,7 @@
 
 ### 缓存属性配置（4.1.x+） {#meta-cache-unified-model}
 
-各引擎 cache entry 使用统一的配置键格式：`meta.cache.<engine>.<entry>.{enable,ttl-second,capacity}`。
+MaxCompute cache entry 使用配置键格式 `meta.cache.maxcompute.<entry>.{enable,ttl-second,capacity}`。MaxCompute 模块当前仍按条目数管理，不接受模块级 `max-weight`，详见[外表元数据缓存内存管理](../external-meta-cache-memory-management.md)。
 
 | 属性 | 示例 | 含义 |
 |---|---|---|
@@ -159,7 +159,7 @@
   -- 关闭分区值缓存，以感知 MaxCompute 表的最新分区
   ALTER CATALOG mc_ctl SET PROPERTIES ("meta.cache.maxcompute.partition_values.ttl-second" = "0");
   ```
-* **注意**：`meta.cache.maxcompute.*` 目前没有专门的热生效 hook。修改配置后，建议重建 Catalog 或重启 FE 以确保生效。
+* **注意**：自 Doris 4.1.4 起，Catalog 属性修改成功后会重置 Catalog 执行上下文，并清理该 Catalog 路由到的所有元数据缓存引擎中已初始化的条目；下一次访问使用新的上下文和配置重建，正在执行的查询不受影响。
 
 ### 可观测性 {#meta-cache-unified-observability}
 

i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/catalogs/paimon-catalog.mdx

@@ -64,7 +64,7 @@
 * `{StorageProperties}`
 
     StorageProperties 部分用于填写存储系统相关的连接和认证信息。具体可参阅【支持的存储系统】部分。
 
 * `{PaimonProperties}`
 
     PaimonProperties 部分用于填写 Paimon 相关的属性。
@@ -222,7 +222,7 @@
 
 ## 元数据缓存 {#meta-cache}
 
-为了提升访问外部数据源的性能，Apache Doris 会对 Paimon 的元数据进行缓存。元数据包括表结构（Schema）和表对象等。
+为了提升访问外部数据源的性能，Apache Doris 会对 Paimon 的元数据进行缓存。元数据包括表结构（Schema）、表对象、Snapshot 和分区投影等。
 
 :::tip
 对于 Doris 4.1.x 之前的版本，元数据缓存主要由 FE 配置项全局控制，详情请参阅[元数据缓存](../meta-cache.md)。
@@ -231,15 +231,16 @@
 
 ### 缓存属性配置（4.1.x+） {#meta-cache-unified-model}
 
-各引擎 cache entry 使用统一的配置键格式：`meta.cache.<engine>.<entry>.{enable,ttl-second,capacity}`。
+各引擎 cache entry 使用统一的配置键格式：`meta.cache.<engine>.<entry>.{enable,ttl-second,capacity,max-weight}`。内存上限适用于已接入估算器的 `table` 和 `snapshot` 模块，详见[外表元数据缓存内存管理](../external-meta-cache-memory-management.md)。
 
 | 属性 | 示例 | 含义 |
 |---|---|---|
 | `enable` | `true/false` | 是否启用该缓存模块。 |
 | `ttl-second` | `600`、`0`、`-1` | `0` 表示关闭缓存（即刻生效，可用于查看最新数据）；`-1` 表示永不过期；其他正整数表示按访问时间计算 TTL（秒）。 |
-| `capacity` | `10000` | 最大缓存条目数（按条目数量计）。`0` 表示关闭。 |
+| `capacity` | `10000` | 按条目数计算的最大容量。启用 `max-weight` 后不再同时作为条目数上限，但 `0` 仍会关闭缓存。 |
+| `max-weight` | `1GB` | 可选的估算保留内存上限。Paimon 的 `table` 和 `snapshot` 支持；`0` 会关闭对应模块。 |
 
-**生效逻辑说明：** 只有当 `enable=true` 且 `ttl-second != 0` 且 `capacity > 0` 时，该模块缓存才会生效。
+**生效逻辑说明：** 只有当 `enable=true`、`ttl-second != 0`、`capacity > 0`，并且 `max-weight` 未配置或不为 `0` 时，该模块缓存才会生效。
 
 ### 缓存模块 {#meta-cache-unified-modules}
 
@@ -249,6 +250,7 @@
 |---|---|---|
 | `schema` | `meta.cache.paimon.schema.` | 缓存表结构。影响：列新增、删除、类型变更在 Doris 中的可见性。若关闭，每次查询都会拉取最新 Schema。 |
 | `table` | `meta.cache.paimon.table.` | 缓存 Paimon 表元数据对象。影响：最新 Snapshot、Schema 演进、分支/标签引用等表级元数据在 Doris 中的可见性，同时减少查询规划时的元数据加载开销。 |
+| `snapshot` | `meta.cache.paimon.snapshot.` | 缓存 Snapshot 元数据、Schema 代际和分区投影；支持 `max-weight`。 |
 
 ### 旧参数映射与转换 {#meta-cache-mapping}
 
@@ -268,7 +270,7 @@
   -- 关闭表对象缓存，以感知 Paimon 表的最新快照
   ALTER CATALOG paimon_ctl SET PROPERTIES ("meta.cache.paimon.table.ttl-second" = "0");
   ```
-* **性能优化**：`ALTER CATALOG ... SET PROPERTIES` 的修改在 Paimon Catalog 中支持热生效。
+* **性能优化**：自 Doris 4.1.4 起，Catalog 属性修改成功后会重置 Catalog 执行上下文，并清理该 Catalog 路由到的所有元数据缓存引擎中已初始化的条目；下一次访问使用新的上下文和配置重建，正在执行的查询不受影响。启用 Doris 内存治理后，默认关闭 Paimon SDK 自带的 `CachingCatalog`；显式配置 `paimon.cache-enabled` 时以用户配置为准。
 
 ### 可观测性 {#meta-cache-unified-observability}
 
@@ -287,7 +289,7 @@
 
 ### 支持的 Paimon 版本
 
-当前依赖的 Paimon 版本为 1.0.0。
+Doris 4.1.4 当前依赖的 Paimon 版本为 1.4.2。
 
 ### 支持的 Paimon 格式
 
@@ -1452,7 +1454,7 @@
 ```
 
 ## 附录
 
 ### FAQ
 
 1. `Could not find a file io implementation for scheme 's3a' in the classpath`