[Doc] update enable_iceberg_metadata_cache in Iceberg catalog doc and…

… add heading levels to all catalog docs (backport #44582) (#44601) Co-authored-by: amber-create <48005258@qq.com>
StarRocks · Apr 23, 2024 · 6f9bfa6 · 6f9bfa6
1 parent e148644
commit 6f9bfa6
Show file tree

Hide file tree

Showing 16 changed files with 43 additions and 20 deletions.
diff --git a/docs/en/data_source/catalog/deltalake_catalog.md b/docs/en/data_source/catalog/deltalake_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "English"
+toc_max_heading_level: 5
 ---
 
 # Delta Lake catalog

diff --git a/docs/en/data_source/catalog/elasticsearch_catalog.md b/docs/en/data_source/catalog/elasticsearch_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "English"
+toc_max_heading_level: 4
 ---
 
 # Elasticsearch catalog

diff --git a/docs/en/data_source/catalog/hive_catalog.md b/docs/en/data_source/catalog/hive_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "English"
+toc_max_heading_level: 5
 ---
 
 # Hive catalog

diff --git a/docs/en/data_source/catalog/hudi_catalog.md b/docs/en/data_source/catalog/hudi_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "English"
+toc_max_heading_level: 5
 ---
 
 # Hudi catalog

diff --git a/docs/en/data_source/catalog/iceberg_catalog.md b/docs/en/data_source/catalog/iceberg_catalog.md
@@ -1,6 +1,6 @@
 ---
 displayed_sidebar: "English"
-toc_max_heading_level: 3
+toc_max_heading_level: 5
 ---
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -104,7 +104,8 @@ PROPERTIES
 (
     "type" = "iceberg",
     MetastoreParams,
-    StorageCredentialParams
+    StorageCredentialParams,
+    MetadataUpdateParams
 )
 ```
 
@@ -205,17 +206,17 @@ Description: The type of metastore that you use for your Iceberg cluster. Set th
 ###### aws.glue.use_instance_profile
 
 Required: Yes
-Description: Specifies whether to enable the instance profile-based authentication method and the assumed role-based authentication method. Valid values: `true` and `false`. Default value: `false`. 
+Description: Specifies whether to enable the instance profile-based authentication method and the assumed role-based authentication method. Valid values: `true` and `false`. Default value: `false`.
 
 ###### aws.glue.iam_role_arn
 
 Required: No
-Description: The ARN of the IAM role that has privileges on your AWS Glue Data Catalog. If you use the assumed role-based authentication method to access AWS Glue, you must specify this parameter. 
+Description: The ARN of the IAM role that has privileges on your AWS Glue Data Catalog. If you use the assumed role-based authentication method to access AWS Glue, you must specify this parameter.
 
 ###### aws.glue.region
 
 Required: Yes
-Description: The region in which your AWS Glue Data Catalog resides. Example: `us-west-1`. 
+Description: The region in which your AWS Glue Data Catalog resides. Example: `us-west-1`.
 
 ###### aws.glue.access_key
 
@@ -337,12 +338,12 @@ Description:  Specifies whether to enable the instance profile-based authenticat
 ###### aws.s3.iam_role_arn
 
 Required: No
-Description: The ARN of the IAM role that has privileges on your AWS S3 bucket. If you use the assumed role-based authentication method to access AWS S3, you must specify this parameter. 
+Description: The ARN of the IAM role that has privileges on your AWS S3 bucket. If you use the assumed role-based authentication method to access AWS S3, you must specify this parameter.
 
 ###### aws.s3.region
 
 Required: Yes
-Description:  The region in which your AWS S3 bucket resides. Example: `us-west-1`. 
+Description:  The region in which your AWS S3 bucket resides. Example: `us-west-1`.
 
 ###### aws.s3.access_key
 
@@ -586,6 +587,15 @@ Description: The service account that you want to impersonate.
 
 ---
 
+#### MetadataUpdateParams
+
+A set of parameters about how StarRocks caches the metadata of Hive. This parameter set is optional.
+
+Currently, this parameter set contains only one parameter, `enable_iceberg_metadata_cache`, which specifies whether to cache pointers and partition names for Iceberg tables. This parameter is supported from v3.2.1 onwards:
+
+- From v3.2.1 to v3.2.3, this parameter is set to `true` by default, regardless of what metastore service is used.
+- In v3.2.4 and later, if the Iceberg cluster uses AWS Glue as metastore, this parameter still defaults to `true`. However, if the Iceberg cluster uses other metastore service such as Hive metastore, this parameter defaults to `false`.
+
 ### Examples
 
 The following examples create an Iceberg catalog named `iceberg_catalog_hms` or `iceberg_catalog_glue`, depending on the type of metastore you use, to query data from your Iceberg cluster. Chose the tab that matches your storage type:
@@ -1355,9 +1365,3 @@ Description: The amount of time after which a cache entry on disk expires counti
 Unit: Bytes
 Default value: `8388608`, equivalent to 8 MB
 Description: The maximum size of a file that can be cached. Files whose size exceeds the value of this parameter cannot be cached. If a query requests these files, StarRocks retrieves them from the remote storage.
-
-### Configure Iceberg table pointer and partition name caching
-
-You can use the session variable [`enable_iceberg_metadata_cache`](../../reference/System_variable.md) to specify whether to cache pointers and partition names for Iceberg tables. This variable is supported from v3.2.1 onwards.
-
-From v3.2.1 to v3.2.3, this parameter is set to `true` by default, regardless of what metastore service is used. In v3.2.4 and later, if the Iceberg cluster uses AWS Glue as metastore, this parameter still defaults to `true`. However, if the Iceberg cluster uses other metastore service such as Hive metastore, this parameter defaults to `false`.
diff --git a/docs/en/data_source/catalog/jdbc_catalog.md b/docs/en/data_source/catalog/jdbc_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "English"
+toc_max_heading_level: 4
 ---
 
 # JDBC catalog

diff --git a/docs/en/data_source/catalog/paimon_catalog.md b/docs/en/data_source/catalog/paimon_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "English"
+toc_max_heading_level: 5
 ---
 
 # Paimon catalog

diff --git a/docs/en/data_source/catalog/unified_catalog.md b/docs/en/data_source/catalog/unified_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "English"
+toc_max_heading_level: 5
 ---
 
 # Unified catalog

diff --git a/docs/zh/data_source/catalog/deltalake_catalog.md b/docs/zh/data_source/catalog/deltalake_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "Chinese"
+toc_max_heading_level: 5
 ---
 
 # Delta Lake catalog

diff --git a/docs/zh/data_source/catalog/elasticsearch_catalog.md b/docs/zh/data_source/catalog/elasticsearch_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "Chinese"
+toc_max_heading_level: 4
 ---
 
 # Elasticsearch catalog

diff --git a/docs/zh/data_source/catalog/hive_catalog.md b/docs/zh/data_source/catalog/hive_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "Chinese"
+toc_max_heading_level: 5
 ---
 
 # Hive catalog

diff --git a/docs/zh/data_source/catalog/hudi_catalog.md b/docs/zh/data_source/catalog/hudi_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "Chinese"
+toc_max_heading_level: 5
 ---
 
 # Hudi catalog

diff --git a/docs/zh/data_source/catalog/iceberg_catalog.md b/docs/zh/data_source/catalog/iceberg_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "Chinese"
+toc_max_heading_level: 5
 ---
 
 # Iceberg catalog
@@ -77,7 +78,8 @@ PROPERTIES
 (
     "type" = "iceberg",
     MetastoreParams,
-    StorageCredentialParams
+    StorageCredentialParams,
+    MetadataUpdateParams
 )
 ```
 
@@ -479,6 +481,15 @@ Iceberg Catalog 从 3.0 版本起支持 Google GCS。
     | gcp.gcs.service_account_private_key    | ""         | "-----BEGIN PRIVATE KEY----xxxx-----END PRIVATE KEY-----\n"  | 创建 Meta Service Account 时生成的 JSON 文件中的 Private Key。 |
     | gcp.gcs.impersonation_service_account  | ""         | "hello"                                                      | 需要模拟的目标 Data Service Account。 |
 
+#### MetadataUpdateParams
+
+指定元数据缓存策略的一组参数。此组参数为可选。
+
+当前仅包含 `enable_iceberg_metadata_cache` 一个参数，用于指定是否缓存 Iceberg 表指针和分区名相关的数据。该参数自 3.2.1 版本起支持：
+
+- 在 3.2.1 到 3.2.3 版本，该参数默认值统一为 `true`。
+- 自 3.2.4 版本起，如果 Iceberg 集群的元数据服务为 AWS Glue，该参数默认值仍为 `true`，如果 Iceberg 集群的元数据服务为 Hive Metastore（简称 HMS）或其他，则该参数默认值变更为 `false`。
+
 ### 示例
 
 以下示例创建了一个名为 `iceberg_catalog_hms` 或 `iceberg_catalog_glue` 的 Iceberg Catalog，用于查询 Iceberg 集群里的数据。
@@ -1141,9 +1152,3 @@ StarRocks 采用 Least Recently Used (LRU) 策略来缓存和淘汰数据，基
 | iceberg_metadata_memory_cache_expiration_seconds | 秒       | `86500`                                              | 内存中的缓存自最后一次访问后的过期时间。                     |
 | iceberg_metadata_disk_cache_expiration_seconds   | 秒       | `604800`，即一周                                     | 磁盘中的缓存自最后一次访问后的过期时间。                     |
 | iceberg_metadata_cache_max_entry_size            | 字节     | `8388608`，即 8 MB                                   | 缓存的单个文件最大大小，以防止单个文件过大挤占其他文件空间。超过此大小的文件不会缓存，如果查询命中则会直接访问远端元数据文件。 |
-
-## 配置 Iceberg 表指针和分区名缓存
-
-您可以通过系统变量 [`enable_iceberg_metadata_cache`](../../reference/System_variable.md) 指定是否缓存 Iceberg 表指针和分区名相关的数据。该变量自 3.2.1 版本起支持。
-
-在 3.2.1 到 3.2.3 版本，该参数默认值统一为 `true`。自 3.2.4 版本起，如果 Iceberg 集群的元数据服务为 AWS Glue，该参数默认值仍为 `true`，如果 Iceberg 集群的元数据服务为 Hive Metastore（简称 HMS）或其他，则该参数默认值变更为 `false`。
diff --git a/docs/zh/data_source/catalog/jdbc_catalog.md b/docs/zh/data_source/catalog/jdbc_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "Chinese"
+toc_max_heading_level: 4
 ---
 
 # JDBC catalog

diff --git a/docs/zh/data_source/catalog/paimon_catalog.md b/docs/zh/data_source/catalog/paimon_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "Chinese"
+toc_max_heading_level: 5
 ---
 
 # Paimon catalog

diff --git a/docs/zh/data_source/catalog/unified_catalog.md b/docs/zh/data_source/catalog/unified_catalog.md
@@ -1,5 +1,6 @@
 ---
 displayed_sidebar: "Chinese"
+toc_max_heading_level: 5
 ---
 
 # Unified catalog