# Tiered Cache **Tiered Cache** is a second cache layer between [Cache](/en/documentation/platform/applications/#cache) and your origin, kept in one region. The first layer is the cache of the data center that answered the request. The second layer is shared by every data center and keeps objects longer than the first. When a request misses the first layer, the data center asks the Tiered Cache layer before it asks the origin. An object fetched once from the origin is then served to every data center from that layer. You turn the layer on per cache setting, and it applies to the objects that setting caches. For the full request path, refer to [Expiration and freshness](/en/documentation/platform/applications/cache/expiration-and-freshness/). A miss in the first layer is answered from Azion's infrastructure instead of your origin. The response arrives with less latency, and fewer requests reach the origin. The origin handles less load at a lower infrastructure cost, and an object stays cached longer. The price is one extra hop on a miss in the first layer and a floor on the TTL of the setting. --- ## Interfaces Tiered Cache is a field of a cache setting, so every interface that writes a cache setting turns it on. The table names where the control sits in each one. | Interface | Where | Value | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | [Azion Console](https://console.azion.com/) | The **Cache** section of the **Create Cache Settings** drawer, under the **Cache Settings** tab of an application in [Applications](/en/documentation/platform/applications/) | The **Tiered Cache** toggle, off on a new setting | | [Azion API v4](/en/documentation/devtools/api/) | `POST /v4/workspace/applications/{application_id}/cache_settings` | `modules.cache.tiered_cache.enabled`, `true` or `false`, and `modules.cache.tiered_cache.topology` | | [Azion CLI](/en/documentation/devtools/cli/) | `azion create cache-setting --file` with the JSON body | The same `tiered_cache` object. The `--tiered-caching-enabled` flag alone is rejected with error `21001`, because no flag sets the cache behavior | | `azion.config.js` | An entry of the `cache` array, of type `AzionCache` | `tieredCache: { enabled, topology }` | Two conditions bind the setting. Its cache behavior must be *Override cache behavior*, because the API rejects Tiered Cache under *Honor cache policies* with error `21001`. Its **Max Age** must be at least 3 seconds, or the API returns error `21020`. Tiered Cache is included on every service plan and is turned on per cache setting. For every field of a cache setting, with the title and the fix of each error, refer to [Cache settings](/en/documentation/platform/applications/cache/cache-settings/). For the Console steps that apply a setting to a path, refer to [Configure cache policies for an application](/en/documentation/guides/application-performance/cache-and-purge/cache-settings/). --- ## Topology The `topology` of a cache setting names the region that hosts the Tiered Cache layer for the objects that setting caches. The API, the CLI JSON body, and `azion.config.js` accept the three values below. Any other value returns error `10039`, `Invalid Choice`. | Value | Meaning | | ---------------- | ------------------- | | `nearest-region` | Nearest region | | `br-east-1` | Brazil, east | | `us-east-1` | United States, east | --- ## TTL The time to live (TTL) of an object in the Tiered Cache layer is the **Max Age** of its cache setting. While the toggle is on, that field carries a floor of 3 seconds. A new setting starts at 60 seconds, the default of **Max Age** in the Console, the API, and the CLI. For example, a **Max Age** of 2 seconds with Tiered Cache on is rejected with error `21020`. The same setting at 3 seconds is accepted. Tiered Cache is designed for objects that stay cached for a long time. Azion also offers the option of hosting the Tiered Cache servers in other regions. To switch between regions in your applications, please contact the [Sales team](https://www.azion.com/en/contact/). --- ## Purge [Real-Time Purge](/en/documentation/platform/applications/cache/real-time-purge/) removes an object from the Tiered Cache layer before its TTL ends. The layer is `tiered_cache` in the API body and in the `--layer` flag of `azion purge`. A cache key purge is the only type that reaches it. A URL or wildcard purge with that layer returns error `30001`, `Invalid Purge Layer For Purge Type`. To remove an object held in both layers, purge Tiered Cache first and then Cache, so the first layer is not refilled from a stale Tiered Cache copy. For the Console, API, and CLI steps, refer to [Purge cached content](/en/documentation/guides/application-performance/cache-and-purge/purge-cached-content/). --- ## Bypass Cache A [Bypass Cache](/en/documentation/platform/applications/rules-engine/#bypass-cache) rule in Rules Engine affects Azion's cache and not the Tiered Cache layer. An application with active Tiered Cache settings continues to cache objects in that layer for the minimum TTL. For the symptom this produces and what to do about it, refer to [Troubleshoot Applications](/en/documentation/platform/applications/troubleshooting/#cache). --- ## Observability [Real-Time Metrics](/en/documentation/platform/real-time-metrics/) carries a **Tiered Cache** dataset beside its Cache dataset. [Real-Time Events](/en/documentation/platform/real-time-events/) carries a **Tiered Cache** dataset as well. The data Tiered Cache has transferred is queried through GraphQL. For the query and its response, refer to [Query usage data from Tiered Cache](/en/documentation/guides/platform/observability/query-tiered-cache-usage-data-with-graphql/). --- ## Related resources - [Cache settings](/en/documentation/platform/applications/cache/cache-settings.md): Every field of a cache setting, with the Tiered Cache rows, the errors, and the request body. - [Expiration and freshness](/en/documentation/platform/applications/cache/expiration-and-freshness.md): The path a request takes through the first layer, the Tiered Cache layer, and the origin. - [Applications limits](/en/documentation/platform/applications/limits.md#cache): The TTL floor and ceiling with Tiered Cache on, and what each plan includes. - [Purge cached content](/en/documentation/guides/application-performance/cache-and-purge/purge-cached-content.md): The Console, API, and CLI steps that purge an object from the Tiered Cache layer by cache key.