# Cache Policies Once data is in the cache, four mechanisms let you control how it behaves: | Mechanism | Question it answers | Evicts data? | | ---------------------------- | ------------------------------------------------------- | ------------------------------ | | **Cache Priority (Pinning)** | Which data should survive LRU eviction the longest? | No — influences eviction order | | **TTL** | How long can data stay in cache, regardless of access? | Yes — time-based expiry | | **Cache Filter** | What should be cached at all, and how fresh must it be? | No — controls admission | | **Quota** | How much space can a directory tree consume? | Yes — enforces limits | {% hint style="info" %} TTL and Cache Priority are complementary: TTL controls how long data may stay; Priority controls what gets removed first when space is needed. You can use both together for more comprehensive cache management. {% endhint %} ### Preventing Eviction: Cache Pinning **Cache Priority** is Alluxio's pinning mechanism. Marking a path as `HIGH` priority ensures it is always evicted *after* lower-priority data — in practice, a high-priority dataset stays in cache as long as there is any lower-priority data to evict first. There are three priority levels: `HIGH`, `MEDIUM`, and `LOW`. When cache space is needed, Alluxio evicts `LOW` first, then `MEDIUM`, then `HIGH`. Within the same tier, the base eviction policy (LRU by default) determines order. **Typical use cases:** * Fine-tuned models that must not be cold-started during inference * Dimension tables shared across many concurrent queries * Any dataset where a cache miss has a disproportionate cost For the standard pattern of loading data into cache before pinning, see [Cache Loading](https://documentation.alluxio.io/ee-ai-en/cache/loading-data-into-the-cache). #### Configuration To enable cache priority, you must set the following property in `alluxio-site.properties` on all client and worker nodes: ```properties alluxio.worker.page.store.evictor.priority.enabled=true ``` Since priority rules are persisted in etcd, you must also ensure that etcd connection details are properly configured. #### Basic Operations Priority rules are managed using the `alluxio priority` CLI. For a complete list of commands and flags, please refer to the [CLI guide](https://documentation.alluxio.io/ee-ai-en/reference/user-cli). **Add a priority rule:** ```shell bin/alluxio priority add --path s3://bucket/critical_data --priority high ``` **List priority rules:** ```shell bin/alluxio priority list ``` **Update a priority rule:** ```shell bin/alluxio priority update --path s3://bucket/data --priority medium ``` **Remove a priority rule:** ```shell bin/alluxio priority remove --path s3://bucket/data ``` For files with the same priority level, the standard eviction policy (LRU by default) determines eviction order. For a complete list of flags, see the [CLI guide](https://documentation.alluxio.io/ee-ai-en/reference/user-cli). ### Controlling How Long to Cache: Time-to-Live (TTL) The **Time-to-Live (TTL)** feature allows you to define a maximum lifespan for cached data in specific directories. Once a file's cache duration exceeds its TTL, Alluxio automatically evicts it during its next periodic check. The TTL timer starts when the data is first loaded into the Alluxio cache. This is useful for: * Automatically cleaning up temporary or time-sensitive data. * Ensuring that stale data does not remain in the cache indefinitely. * Satisfying compliance requirements by limiting the lifespan of sensitive data. #### Configuration To use TTL-based eviction, you must enable the feature in `alluxio-site.properties`: ```properties alluxio.ttl.policy.enabled=true ``` It is also critical to configure the scan interval, which determines how frequently workers check for expired data. ```properties # Default is 1h. Set a larger interval for production environments. alluxio.ttl.eviction.check.interval=1h ``` A very short interval can create unnecessary system overhead. We recommend setting this to a value that balances cleanup timeliness with performance, such as `24h` in many production scenarios. If the configured TTL is shorter than the check interval, expired data will only be evicted at the next scan — not immediately. #### Basic Operations TTL rules are managed using the `alluxio ttl` CLI. For a complete list of commands and flags, please refer to the [CLI guide](https://documentation.alluxio.io/ee-ai-en/reference/user-cli). **Add a TTL rule** (24 hours on `/s3/daily_reports/`): ```shell bin/alluxio ttl add --path /s3/daily_reports/ --time 24h ``` **List TTL rules:** ```shell bin/alluxio ttl list ``` ```console Listing all TTL policies /s3/daily_reports/ TTL: 24 hours ``` **Update a TTL rule:** ```shell bin/alluxio ttl update --path /s3/test_folder/ --time 30min ``` {% hint style="warning" %} Avoid very short TTLs (e.g. `5s`). Expired entries are scanned on the configured `alluxio.ttl.eviction.check.interval` (default `1h`), so a TTL shorter than the scan interval has no practical effect. {% endhint %} **Remove a TTL rule:** ```shell bin/alluxio ttl remove --path /s3/test_folder ``` {% hint style="info" %} TTL eviction is **lazy**: the rule is not removed when data expires. After eviction, the rule remains active and will re-apply the next time the same path is loaded. Remove the rule explicitly with `ttl remove` when it is no longer needed. {% endhint %} Like quotas, TTL rules are hierarchical. If multiple TTL rules apply to a file, the most specific path match takes precedence. ### Controlling What to Cache: Cache Filter Policies The **Cache Filter Policy** feature is enabled by default and allows you to create rules that determine which files should or should not be cached based on their path. This is useful for excluding frequently changing files, temporary files, or data that provides little performance benefit from being cached. By default, Alluxio uses an **Immutable** policy, meaning it will cache data upon first read and will not check the UFS for updates afterward. You can override this behavior by defining rules for specific paths. Alluxio defines three filter modes for a file: * **Immutable**: The file's data and metadata will never change. Alluxio will cache it once and never check the UFS for updates. This is the default behavior and the most performant option. * **Skip Cache**: The file's data and metadata should not be cached in Alluxio. All requests for this file will be forwarded directly to the UFS. This is ideal for highly volatile files where cache consistency would be difficult to maintain. * **Max Age**: The file's data and metadata may change. You can specify a duration (e.g., `10m`) after which the cached copy is considered stale. Alluxio will then re-check the UFS for a newer version on the next access. #### Examples of Filter Modes The following examples show the logic behind different filter rules. You would typically apply these rules using the Alluxio CLI or REST API when using ETCD. For detailed command usage, please refer to the [CLI guide](https://documentation.alluxio.io/ee-ai-en/reference/user-cli). **Immutable: For Data That Never Changes** This is the most performant option and should be the default for most of your data. If a file is marked as `immutable`, Alluxio caches it once and never checks the UFS for updates. **Consistency**: This policy provides strong consistency **only if the source file in the UFS truly never changes**. If the source file is modified after being cached, Alluxio will continue to serve the old, stale version, leading to permanent inconsistency. ```json { "apiVersion": "1", "metadata": { "defaultType": "immutable" }, "data": { "defaultType": "immutable" } } ``` **Skip Cache: For Volatile or Rarely Used Data** If you have data that changes frequently (e.g., temporary scripts) or is not worth caching, you can exclude it using a `skipCache` rule. All requests for these files will be served directly from the UFS. **Consistency**: This policy provides **strong consistency**, as it bypasses the cache and reads directly from the source of truth (the UFS). The consistency guarantee is the same as that of the underlying storage system. ```json { "apiVersion": "1", "metadata": { "skipCache": ["file://dev/scripts/.*"], "defaultType": "immutable" }, "data": { "skipCache": ["file://dev/scripts/.*"], "defaultType": "immutable" } } ``` **Max Age: For Data with Bounded Staleness** For data that is updated periodically, you can set a `maxAge`. This tells Alluxio to consider the cached data fresh for the specified duration. After the duration expires, Alluxio will check the UFS for a newer version on the next access. **Consistency**: This policy provides **bounded staleness**. Clients may read a version of the data that is stale, but no older than the specified `maxAge` duration. It offers a balance between performance and freshness but does not guarantee strong consistency. ```json { "apiVersion": "1", "metadata": { "maxAge": {"s3://datalake/tables/pipeline/sales/.*": "1h"}, "defaultType": "immutable" }, "data": { "defaultType": "immutable" } } ``` This configuration is useful for mutable datasets where you can tolerate a certain level of staleness in exchange for higher performance. To specify the duration when setting `defaultType` to be `maxAge`, set `defaultMaxAge`. ```json { "apiVersion": "1", "metadata": { "defaultType": "maxAge", "defaultMaxAge": "10min" }, "data": { "defaultType": "immutable" } } ``` #### Difference Between `maxAge` Cache Filter and TTL Rules The `maxAge` cache filter and TTL rules can appear similar in functionality and thus confusing for a user to choose between when they want to ensure bounded staleness of cached data. The `maxAge` cache filter takes effect at data access time, revalidates the cache with the UFS if the cache has reached the max age. Therefore, an expired cache item won't get automatically revalidated until it is accessed. TTL rules are enforced independently of data access, so cached data will be evicted once its TTL expires, even if it is not accessed. Cache items are not revalidated before they are cleared from the cache by TTL expiration, even if it has not changed in the UFS at all. Therefore, if you want to ensure that cached data is always fresh when accessed, use the `maxAge` cache filter. If you want to ensure that cached data does not linger in the cache beyond a certain time period, use TTL rules. In some cases, you may want to use both features together for more comprehensive cache management. ### Controlling How Much to Cache: Cache Quotas **Cache Quotas** allow administrators to limit the total amount of cache space that can be used by files within a specific directory tree. This is essential for multi-tenant environments or for ensuring that no single dataset or user can monopolize the cluster's cache resources. When a directory's quota is exceeded, Alluxio will take action to enforce the limit. By default, it will stop caching new data for that directory (`NO_CACHE`) and trigger evictions to bring usage back under the limit. #### Configuration To use directory-based quotas, you must enable the feature in `alluxio-site.properties` and specify the coordinator address. ```properties # Enable the directory-based cluster quota feature alluxio.quota.enabled=true # Configure the coordinator address alluxio.coordinator.hostname= alluxio.coordinator.rpc.port= ``` You can also control the behavior when a quota limit is exceeded using the `alluxio.quota.limit.exceeded.action` property. The available actions are: * **`NO_CACHE` (default)**: Stops caching new data under the path but allows read requests to be served from the UFS. * **`REJECT`**: Rejects new write requests that would create cached data under the path, returning an exception to the client. * **`NOOP`**: Continues to allow new data to be cached, relying on eviction to manage the space. This may be insufficient if the write rate is higher than the eviction rate. #### Basic Operations You can manage quotas using the `alluxio quota` CLI. For a complete list of commands and flags, please refer to the [CLI guide](https://documentation.alluxio.io/ee-ai-en/reference/user-cli). **Add a quota** (10 GB on `/s3/data`): ```shell bin/alluxio quota add --directory /s3/data/ --quota-size 10GB ``` ```console Successfully added quota definition for path /s3/data/ with size 10GB. ``` **List quotas:** ```shell bin/alluxio quota list ``` ```console Alluxio path Capacity Used State /s3/data 10.00GB Calculating Available ``` **Update a quota:** ```shell bin/alluxio quota update --directory /local/data/ --quota-size 100GB ``` **Remove a quota:** ```shell bin/alluxio quota remove --directory /s3/data ``` Quotas can also be nested. For example, you can assign a 10GB quota to a team's directory and then subdivide that with smaller quotas for individual projects within that team.