This is an automated email from the ASF dual-hosted git repository.
jshao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new 5c68e49fb0 [#7180] improvement(doc): Add docs support (#7460)
5c68e49fb0 is described below
commit 5c68e49fb061eea1450a35d517952f36f3935370
Author: Lord of Abyss <103809695+abyss-l...@users.noreply.github.com>
AuthorDate: Thu Jun 26 11:30:40 2025 +0800
[#7180] improvement(doc): Add docs support (#7460)
### What changes were proposed in this pull request?
Add docs support for cache.
### Why are the changes needed?
Fix: #7180
### Does this PR introduce _any_ user-facing change?
no
### How was this patch tested?
local test.
---
docs/gravitino-server-config.md | 50 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 50 insertions(+)
diff --git a/docs/gravitino-server-config.md b/docs/gravitino-server-config.md
index eb25843246..e5599f6685 100644
--- a/docs/gravitino-server-config.md
+++ b/docs/gravitino-server-config.md
@@ -75,6 +75,56 @@ We strongly recommend that you change the default value of
`gravitino.entity.sto
For H2 database, All tables needed by Gravitino are created automatically when
the Gravitino server starts up. For MySQL, you should firstly initialize the
database tables yourself by executing the ddl scripts in the
`${GRAVITINO_HOME}/scripts/mysql/` directory.
+### Storage cache configuration
+
+To enable storage caching, please modify the following settings in the
`${GRAVITINO_HOME}/conf/gravitino.conf` file:
+
+```
+# Whether to enable the cache
+gravitino.cache.enabled=true
+
+# Specify the cache implementation (no need to use the fully qualified class
name)
+gravitino.cache.implementation=caffeine
+```
+
+| Configuration Key | Description
| Default Value | Required | Since Version |
+|----------------------------------|--------------------------------------------|------------------------|----------|---------------|
+| `gravitino.cache.enabled` | Whether to enable caching
| `true` | Yes | 1.0.0 |
+| `gravitino.cache.implementation` | Specifies the cache implementation
| `caffeine` | Yes | 1.0.0 |
+| `gravitino.cache.maxEntries` | Maximum number of entries allowed in
cache | `10000` | No | 1.0.0 |
+| `gravitino.cache.expireTimeInMs` | Cache expiration time (in milliseconds)
| `3600000` (about 1 hr) | No | 1.0.0 |
+| `gravitino.cache.enableStats` | Whether to enable cache statistics
logging | `false` | No | 1.0.0 |
+| `gravitino.cache.enableWeigher` | Whether to enable weight-based eviction
| `true` | No | 1.0.0 |
+
+- `gravitino.cache.enableWeigher`: When enabled, eviction is based on weight
and `maxEntries` will be ignored.
+- `gravitino.cache.expireTimeInMs`: Controls the cache TTL in milliseconds.
+- If `gravitino.cache.enableStats` is enabled, Gravitino will log cache
statistics (hit count, miss count, load failures, etc.) every 5 minutes at the
Info level.
+
+#### Eviction strategies
+
+Gravitino supports multiple eviction strategies including capacity-based,
weight-based, and time-based (TTL) eviction. The following describes how they
work with Caffeine:
+
+##### Capacity-based eviction
+
+When `gravitino.cache.enableWeigher` is **disabled**, Gravitino limits the
number of cached entries using `gravitino.cache.maxEntries` and employs
Caffeine’s W-TinyLFU eviction policy to remove the least-used entries when the
cache is full.
+
+##### Weight-based eviction
+
+When `gravitino.cache.enableWeigher` is **enabled**, Gravitino uses a
combination of `maximumWeight` and a custom weigher to control the total weight
of the cache:
+
+- Each entity type has a default weight (e.g., Metalake > Catalog > Schema);
+- Entries are evicted based on the combined weight limit (`maximumWeight`);
+- If a single cache item exceeds the total weight limit, it will not be cached;
+- When this strategy is active, `maxEntries` will be ignored.
+
+##### Time-based eviction
+
+All cache entries are subject to a TTL (Time-To-Live) expiration policy. By
default, the TTL is `3600000ms` (1 hour) and can be adjusted via the
`gravitino.cache.expireTimeInMs` setting:
+
+- TTL starts at the time of entry creation; once it exceeds the configured
duration, the entry expires automatically;
+- TTL can work in conjunction with both capacity and weight-based eviction;
+- Expired entries will also trigger asynchronous cleanup mechanisms for
resource release and logging.
+
### Tree lock configuration
Gravitino server uses tree lock to ensure the consistency of the data. The
tree lock is a memory lock (Currently, Gravitino only supports in memory lock)
that can be used to ensure the consistency of the data in Gravitino server. The
configuration items are as follows:
