Skip to content

[feature](fe) Add byte-weighted external metadata caches - #66579

Draft
CalvinKirs wants to merge 4 commits into
apache:masterfrom
CalvinKirs:cache_memory
Draft

[feature](fe) Add byte-weighted external metadata caches#66579
CalvinKirs wants to merge 4 commits into
apache:masterfrom
CalvinKirs:cache_memory

Conversation

@CalvinKirs

@CalvinKirs CalvinKirs commented Aug 7, 2026

Copy link
Copy Markdown
Member

What problem does this PR solve?

Issue Number: None

Related PR: #66533

Problem Summary:

External connector metadata caches are bounded only by entry count. A small number of large file listings, partition maps, table metadata objects, or manifest values can therefore consume excessive FE heap while remaining below the configured entry capacity.

This change adds an optional byte-weighted cache path. When max-weight is configured, the cache requires a typed estimator and uses Caffeine maximumWeight; otherwise it preserves the existing maximumSize(capacity) behavior.

The production integrations cover:

  • Hive file-listing values.
  • Iceberg table, partition, and manifest values.
  • Paimon derived partition-view values.

Large values precompute their estimated retained bytes when they are constructed, so the Caffeine weighing callback is O(1). Paimon's legacy count-bounded path does not build or traverse the weighted wrapper, so its default behavior and estimation cost remain unchanged.

Opt-in JMH/JOL benchmarks compare cached weight lookup, construction-time estimation, and JOL retained-graph traversal. The Paimon benchmark covers 10,000 and 100,000 partitions.

Release note

External metadata caches can opt into byte-based limits with meta.cache.<engine>.<entry>.max-weight properties. Paimon partition views use meta.cache.paimon.partition_view.max-weight.

Check List (For Author)

  • Test

    • Regression test
    • Unit Test
    • Manual test (add detailed scripts or steps below)
    • No need to test or manual test. Explain why:
      • This is a refactor/code format and no logic has been changed.
      • Previous test can cover this change.
      • No code files have been changed.
      • Other reason

    Unit tests:

    • ./run-fe-ut.sh --run org.apache.doris.common.util.ParseUtilTest,org.apache.doris.common.CacheFactoryTest,org.apache.doris.datasource.metacache.CacheSpecTest,org.apache.doris.datasource.metacache.MetaCacheEntryTest,org.apache.doris.datasource.metacache.AbstractExternalMetaCacheTest
    • ./run-fe-ut.sh --run org.apache.doris.connector.cache.ConnectorMetadataCacheTest,org.apache.doris.connector.paimon.PaimonPartitionViewSizeEstimatorTest,org.apache.doris.connector.paimon.PaimonConnectorValidatePropertiesTest

    Build and benchmark compilation:

    • DISABLE_BUILD_UI=ON ./build.sh --fe
    • mvn -Pbenchmark -pl fe-benchmark -am test-compile -DskipTests

    The JMH benchmarks were compiled but not executed in this PR update.

  • Behavior changed:

    • No.
    • Yes. Configured caches can use byte-weighted eviction; count-based capacity remains the default.
  • Does this need documentation?

    • No.
    • Yes.

Check List (For Reviewer who merge this PR)

  • Confirm the release note
  • Confirm test cases
  • Confirm document
  • Add branch pick label

### What problem does this PR solve?

Issue Number: None

Related PR: None

Problem Summary: External metadata caches are currently bounded only by entry count. Add framework support for an optional catalog-level max-weight, an entry-specific size estimator contract, mutually exclusive Caffeine size/weight construction, saturated integer weight conversion, and weighted cache statistics. Complete the framework by supporting weighted caches with synchronous removal listeners, accepting convenient binary size suffixes such as MB while retaining bare-byte compatibility, strictly rejecting malformed, negative, and overflowing max-weight values, and keeping statistics reads lightweight and side-effect free. Existing entries continue to use maximumSize unless they explicitly register an estimator and configure max-weight. Catalog-specific estimators and information_schema exposure are intentionally not included.

### Release note

None

### Check List (For Author)

- Test: Unit Test
    - ./run-fe-ut.sh --run org.apache.doris.common.util.ParseUtilTest,org.apache.doris.common.CacheFactoryTest,org.apache.doris.datasource.metacache.CacheSpecTest,org.apache.doris.datasource.metacache.MetaCacheEntryTest,org.apache.doris.datasource.metacache.AbstractExternalMetaCacheTest (80 tests passed)
    - DISABLE_BUILD_UI=ON ./build.sh --fe (passed, including Checkstyle)
- Behavior changed: Yes. Entries that register an estimator and configure max-weight use weighted eviction, invalid max-weight values are rejected, and statistics reads no longer trigger Caffeine maintenance.
- Does this need documentation: No
### What problem does this PR solve?

Issue Number: None

Related PR: None

Problem Summary: External connector metadata caches are bounded only by entry count, so a small number of large file, partition, table, or manifest values can consume excessive FE heap. Add optional byte-weighted cache construction and typed, precomputed estimators for Hive file listings and Iceberg table, partition, and manifest entries while preserving count-based defaults.

### Release note

External metadata caches can opt into byte-based limits with per-entry meta.cache.<engine>.<entry>.max-weight properties.

### Check List (For Author)

- Test: Unit Test

  - Connector cache CacheSpecTest and MetaCacheEntryTest (28 tests passed)

  - Hive and Iceberg production sources compiled in the FE unit-test reactor

- Behavior changed: Yes, configured connector caches can use maximumWeight; existing maximumSize behavior remains the default.

- Does this need documentation: No
@hello-stephen

Copy link
Copy Markdown
Contributor

Thank you for your contribution to Apache Doris.
Don't know what should be done next? See How to process your PR.

Please clearly describe your PR:

  1. What problem was fixed (it's best to include specific error reporting information). How it was fixed.
  2. Which behaviors were modified. What was the previous behavior, what is it now, why was it modified, and what possible impacts might there be.
  3. What features were added. Why was this function added?
  4. Which code was refactored and why was this part of the code refactored?
  5. Which functions were optimized and what is the difference before and after the optimization?

### What problem does this PR solve?

Issue Number: None

Related PR: apache#66533

Problem Summary: Add opt-in JMH benchmarks for the production Hive file-listing and Iceberg partition and manifest cache estimators. The benchmarks compare the constant-time cached weight lookup, the one-time value construction and estimation cost, and JOL retained-graph traversal without adding benchmark dependencies to the default FE reactor.

### Release note

None

### Check List (For Author)

- Test: Manual test
    - `mvn -Pbenchmark -pl fe-benchmark -am test-compile -DskipTests`
- Behavior changed: No
- Does this need documentation: No
### What problem does this PR solve?

Issue Number: None

Related PR: apache#66533

Problem Summary: Paimon's derived partition-view cache was limited only by entry count, so a catalog containing large partition views could retain substantially more FE heap than its configured entry capacity implied. Extend the generic connector metadata cache to accept a type-specific estimator, add a Paimon partition-view estimator that computes the complete immutable entry weight once when max-weight is enabled, and use the stored value for O(1) Caffeine weighing. Keep the legacy count-bounded path unchanged. Add JMH/JOL benchmarks for 10,000 and 100,000 Paimon partitions.

### Release note

Paimon partition-view caches support the catalog property `meta.cache.paimon.partition_view.max-weight`.

### Check List (For Author)

- Test: Unit Test
    - `./run-fe-ut.sh --run org.apache.doris.connector.cache.ConnectorMetadataCacheTest,org.apache.doris.connector.paimon.PaimonPartitionViewSizeEstimatorTest,org.apache.doris.connector.paimon.PaimonConnectorValidatePropertiesTest`
    - `mvn -Pbenchmark -pl fe-benchmark -am test-compile -DskipTests`
- Behavior changed: Yes. Paimon partition-view caches can opt into byte-weighted eviction; existing capacity behavior remains the default.
- Does this need documentation: No
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants