Add detailed docs for external meta cache engines

Author: suxiaogang223

fe/fe-core/src/main/java/org/apache/doris/datasource/ExternalMetaCacheMgr.java

@@ -514,7 +514,16 @@ public static Map<String, String> getCacheStats(CacheStats cacheStats, long esti
     }
 
     /**
-     * Default fallback cache: only provides schema entry loading for unknown engines.
+     * Fallback implementation of {@link AbstractExternalMetaCache} for engines that do not
+     * provide dedicated cache entries.
+     *
+     * <p>Registered entries:
+     * <ul>
+     *   <li>{@code schema}: schema-only cache keyed by {@link SchemaCacheKey}</li>
+     * </ul>
+     *
+     * <p>This class keeps compatibility for generic external engines and routes only schema
+     * loading/invalidation. No engine-specific metadata (partitions/files/snapshots) is cached.
      */
     private static class DefaultExternalMetaCache extends AbstractExternalMetaCache {
         private static final CacheSpec SCHEMA_CACHE_SPEC = CacheSpec.fromTtlValue(

fe/fe-core/src/main/java/org/apache/doris/datasource/doris/DorisExternalMetaCache.java

@@ -42,7 +42,18 @@
 import java.util.stream.Collectors;
 
 /**
- * Doris engine implementation of external meta cache.
+ * Remote Doris engine implementation of {@link AbstractExternalMetaCache}.
+ *
+ * <p>Registered entries:
+ * <ul>
+ *   <li>{@code backends}: remote backend topology keyed by catalog id</li>
+ *   <li>{@code schema}: schema cache keyed by {@link SchemaCacheKey}</li>
+ * </ul>
+ *
+ * <p>The backend cache is intentionally independent from table/db invalidation and can be
+ * refreshed explicitly via {@link #invalidateBackendCache(long)}.
+ *
+ * <p>db/table/partition invalidation only targets schema entries.
  */
 public class DorisExternalMetaCache extends AbstractExternalMetaCache {
     private static final Logger LOG = LogManager.getLogger(DorisExternalMetaCache.class);

fe/fe-core/src/main/java/org/apache/doris/datasource/hive/HiveExternalMetaCache.java

@@ -83,8 +83,27 @@
 import java.util.stream.Collectors;
 
 /**
- * Hive engine external meta cache implementation.
- * It serves both schema cache and hive metastore cache under one engine entry set.
+ * Hive engine implementation of {@link AbstractExternalMetaCache}.
+ *
+ * <p>This cache consolidates schema metadata and Hive Metastore-derived runtime metadata
+ * under one engine so callers can use a unified invalidation path.
+ *
+ * <p>Registered entries:
+ * <ul>
+ *   <li>{@code schema}: table schema cache keyed by {@link SchemaCacheKey}</li>
+ *   <li>{@code partition_values}: partition value/index structures per table</li>
+ *   <li>{@code partition}: single partition metadata keyed by partition values</li>
+ *   <li>{@code file}: file listing cache for partition/table locations</li>
+ * </ul>
+ *
+ * <p>Invalidation behavior:
+ * <ul>
+ *   <li>{@link #invalidateDb(long, String)} and {@link #invalidateTable(long, String, String)}
+ *   clear all related entries with table/db granularity.</li>
+ *   <li>{@link #invalidatePartitions(long, String, String, List)} supports partition-level
+ *   invalidation when specific partition names are provided, and falls back to table-level
+ *   invalidation for empty input or unresolved table metadata.</li>
+ * </ul>
  */
 public class HiveExternalMetaCache extends AbstractExternalMetaCache {
     private static final Logger LOG = LogManager.getLogger(HiveExternalMetaCache.class);

fe/fe-core/src/main/java/org/apache/doris/datasource/hudi/HudiExternalMetaCache.java

@@ -58,7 +58,25 @@
 import java.util.stream.Collectors;
 
 /**
- * Hudi engine implementation of external meta cache.
+ * Hudi engine implementation of {@link AbstractExternalMetaCache}.
+ *
+ * <p>Registered entries:
+ * <ul>
+ *   <li>{@code partition}: mutable {@link TablePartitionValues} holder keyed by table and
+ *   partition column types</li>
+ *   <li>{@code fs_view}: {@link HoodieTableFileSystemView} for timeline-aware file listing</li>
+ *   <li>{@code meta_client}: {@link HoodieTableMetaClient} for table metadata access</li>
+ *   <li>{@code schema}: Hudi schema cache keyed by table identity + timestamp</li>
+ * </ul>
+ *
+ * <p>Partition cache values are updated in place with read/write locks to avoid rebuilding
+ * large partition maps on every request.
+ *
+ * <p>Invalidation behavior:
+ * <ul>
+ *   <li>db/table invalidation clears all four entries for matching keys</li>
+ *   <li>partition-level invalidation currently falls back to table-level invalidation</li>
+ * </ul>
  */
 public class HudiExternalMetaCache extends AbstractExternalMetaCache {
     private static final Logger LOG = LogManager.getLogger(HudiExternalMetaCache.class);

fe/fe-core/src/main/java/org/apache/doris/datasource/iceberg/IcebergExternalMetaCache.java

@@ -52,7 +52,26 @@
 import java.util.function.Consumer;
 
 /**
- * Iceberg engine implementation of external meta cache.
+ * Iceberg engine implementation of {@link AbstractExternalMetaCache}.
+ *
+ * <p>Registered entries:
+ * <ul>
+ *   <li>{@code table}: loaded Iceberg {@link Table} instances per Doris table mapping</li>
+ *   <li>{@code view}: loaded Iceberg {@link View} instances</li>
+ *   <li>{@code manifest}: parsed manifest payload ({@link ManifestCacheValue}) keyed by
+ *   manifest path and content type</li>
+ *   <li>{@code schema}: schema cache keyed by table identity + schema id</li>
+ * </ul>
+ *
+ * <p>Manifest entry keys are path-based and intentionally not table-scoped. This allows
+ * shared manifests to reuse one cache entry across tables in the same catalog.
+ *
+ * <p>Invalidation behavior:
+ * <ul>
+ *   <li>catalog invalidation clears all entries and drops Iceberg {@link ManifestFiles} IO cache</li>
+ *   <li>db/table invalidation clears table/view/schema entries, while keeping manifest entries</li>
+ *   <li>partition-level invalidation falls back to table-level invalidation</li>
+ * </ul>
  */
 public class IcebergExternalMetaCache extends AbstractExternalMetaCache {
     private static final Logger LOG = LogManager.getLogger(IcebergExternalMetaCache.class);

fe/fe-core/src/main/java/org/apache/doris/datasource/maxcompute/MaxComputeExternalMetaCache.java

@@ -38,7 +38,19 @@
 import java.util.function.Function;
 
 /**
- * MaxCompute engine implementation of external meta cache.
+ * MaxCompute engine implementation of {@link AbstractExternalMetaCache}.
+ *
+ * <p>Registered entries:
+ * <ul>
+ *   <li>{@code metadata}: per-catalog {@link MaxComputeMetadataCache} stored under a fixed key</li>
+ *   <li>{@code schema}: schema cache keyed by {@link SchemaCacheKey}</li>
+ * </ul>
+ *
+ * <p>The metadata cache entry is a container for multiple inner caches (partition values,
+ * table info and related objects). Database/table invalidation first delegates to that
+ * container, then invalidates schema entries.
+ *
+ * <p>Partition-level invalidation currently follows table-level invalidation semantics.
  */
 public class MaxComputeExternalMetaCache extends AbstractExternalMetaCache {
     public static final String ENGINE = "maxcompute";

fe/fe-core/src/main/java/org/apache/doris/datasource/paimon/PaimonExternalMetaCache.java

@@ -48,7 +48,22 @@
 import java.util.concurrent.ExecutorService;
 
 /**
- * Paimon engine implementation of external meta cache.
+ * Paimon engine implementation of {@link AbstractExternalMetaCache}.
+ *
+ * <p>Registered entries:
+ * <ul>
+ *   <li>{@code table}: loaded Paimon table handle per table mapping</li>
+ *   <li>{@code schema}: schema cache keyed by table identity + schema id</li>
+ * </ul>
+ *
+ * <p>Snapshot-related helpers reuse the table/schema entries to derive partition metadata
+ * and latest snapshot state without introducing extra cache entries.
+ *
+ * <p>Invalidation behavior:
+ * <ul>
+ *   <li>db/table invalidation clears both table and schema entries by matching local names</li>
+ *   <li>partition-level invalidation falls back to table-level invalidation</li>
+ * </ul>
  */
 public class PaimonExternalMetaCache extends AbstractExternalMetaCache {
     public static final String ENGINE = "paimon";