Overview
Menu

Cache Key Introduction

What is Cache Key

Cache Key is used to determine whether the file resources accessed by users hit the edge caching content of EdgeOne, and it is the unique identifier of cached resources within the node. Cache hits can help your site:
Reduce origin-pull requests and lower the bandwidth consumption of the origin.
Improve the access request speed of users.
The working principle of Cache Key is as follows:
When a file is cached in the EdgeOne edge node, the node will generate a corresponding Cache Key identifier for the file according to the Cache Key rules. By default, the Cache Key is calculated based on the client request URL and query string. When other clients initiate an HTTP request to the edge node, the node will compare the HTTP request with the Cache Key of all cached resources in the node according to the Cache Key calculation rule. If they are consistent, the corresponding cached resources will be directly responded to the client, which is a cache hit.




Cache Key's application scenarios

Cache Key is used for EdgeOne nodes to establish multi-version caching content for different versions of files. Even if the client requests through the same path, the correct user file can be responded through the calculation rules of Cache Key.

You can understand how to correctly configure Cache Key to help you correctly match the requested cache files and reduce the origin-pull rate through the following scenario examples.
For example, User A and User B have the following requests:
Request A: https://www.example.com/Image/test.jpg?version=1&time=1651752743
Request B: https://www.example.com/Image/test.jpg?version=2&time=1651758319
Scenario 1: The file paths accessed by users are completely identical, but there are version differentiations according to version parameter carried in the query string. The above requests are two different images. In this case, version parameter that affects the file version should be retained in the Cache Key to ensure that the node can correctly cache and respond to the corresponding file content.
Scenario 2: The content of the query string in the user's access URL does not affect the file content. The files corresponding to the above requests are the same and do not affect the file version. In this case, all query strings should be ignored in the Cache Key calculation to improve the hit rate of files in the node and reduce the origin-pull requests.

Customizable Cache Key content and effective rules

EdgeOne allows users to customize Cache Key rules, supports configuring query strings, HTTP request headers, or cookies to distinguish caches. You can learn how to configure custom Cache Key rules through Custom Cache Key.
Note:
1. The calculation of Cache Key is based on the HTTP request content initiated by the client to the node. The origin URL rewriting, origin follow redirect, origin HTTP request header, and Rewrite access URL do not affect the calculation of Cache Key.
2. When Token authentication is configured in EdgeOne, the authentication content will not participate in the Cache Key calculation.
3. When image processing parameters are enabled in EdgeOne, the image processing parameters carried in the request will participate in the Cache Key calculation by default.

Query string

The query string refers to the string parameters after the "?" in the request URL (including one or multiple parameters, separated by "&"), for example, color=blue&size=large in https://www.example.com/images/example.jpg?color=blue&size=large.

EdgeOne supports customizing the retention of specified query string content to distinguish caches.
Note:
When retaining the query string as the Cache Key, if the position order of the parameters changes, the Cache Key will also change.
For example, when clients initiate the following requests separately:
Request A: https://www.example.com/Image/test.jpg?version=1&type=a
Request B: https://www.example.com/Image/test.jpg?version=2&type=a
Request C: https://www.example.com/Image/test.jpg?type=a&version=1
Configuration
Cache behavior
Query string configuration is to retain all
The parameter content carried by Request A and Request B is different, corresponding to different cache versions. The parameter content of Request A and Request C is consistent, but the order is different, corresponding to different cache versions.
Query string configuration is to ignore all
Requests A, B, and C all correspond to the same cache version.
Query string configuration is to retain the specified parameter Type
The parameter order and content of Request A and Request B are completely identical, corresponding to the same cache version; the parameter content of Request B and Request C is the same, but the order is different, corresponding to different cache versions.
Query string configuration is to ignore the specified parameter Type
The remaining parameter content of Request A and Request B is not consistent, corresponding to different cache versions; the remaining parameter content of Request A and Request C is consistent, but the order is not consistent, corresponding to different cache versions.

HTTP request header

EdgeOne supports adding specified HTTP request headers to the Cache Key calculation. EdgeOne edge nodes will establish different cache versions based on the request header content. The order change of the request header does not affect the calculation of the Cache Key.
For example, specify the HTTP request header User-Agent to be included in the Cache Key calculation. The URL and parameter content of the following Request A and Request B are consistent, but the User-Agent header content is not consistent, corresponding to different cache versions.
Request A: https://www.example.com/Image/test.jpg?version=1&type=a, with User-Agent: chrome
Request B: https://www.example.com/Image/test.jpg?version=1&type=a, with User-Agent: ios

Cookie

EdgeOne supports adding specified parameters in the Cookie to the Cache Key calculation, distinguishing cache versions based on Cookie parameters and content. When multiple parameters in the Cookie participate in the Cache Key calculation, the order change of the parameters does not affect the Cache Key calculation.
For example, specify the User parameter in the Cookie to be included in the Cache Key calculation. The parameter content of the following Request A and Request B is the same, corresponding to the same cache, and the parameter content of Request A and Request C is different, corresponding to different cache versions.
Request A: https://www.example.com/Image/test.jpg?version=1&type=a, with Cookie: User=A;ID=1.
Request B: https://www.example.com/Image/test.jpg?version=1&type=a, with Cookie: User=A;ID=2.
Request C: https://www.example.com/Image/test.jpg?version=1&type=a, with Cookie: User=B;ID=1.

Learn more