A Cache Key is an identifier that Cloudflare uses for a file in our cache, and the Cache Key Template defines the identifier for a given HTTP request. For example, consider the following HTTP request on a TLS connection:
GET /logo.jpg HTTP/1.1Host: www.cloudflare.comUser-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36Accept: image/jpg
As we can see from the example, the default cache key includes:
- Full URL:
- scheme - not shown above, but could be HTTP or HTTPS.
- host - which in this example is
- URI with query string - in this example is
- Origin header sent by client (for CORS support).
To create a Cache Key, see Create a Custom Cache Key.
Cache Key Template
There are a couple of common reasons to change the Cache Key Template. You might change the Cache Key Template to:
- Fragment the cache so one URL is stored in multiple files. For example, to store different files based on a specific query string in the URL.
- Consolidate the cache so different HTTP requests are stored in the same file. For example, to remove the Origin header added to Cloudflare Cache Keys by default.
A Cache Level of Ignore Query String creates a Cache Key that includes all the elements in the default cache key, except for the query string in the URI that is no longer included. For instance, a request for
http://example.com/file.jpg?something=123 and a request for
http://example.com/file.jpg?something=789 will have the same cache key, in this case.
Cache Key Settings
The following fields control the Cache Key Template.
The query string controls which URL query string parameters go into the Cache Key. You can
include specific query string parameters or
exclude them using the respective fields. When you include a query string parameter, the
value of the query string parameter is used in the Cache Key.
If you include the query string foo in a URL like
https://www.example.com/?foo=bar, then bar appears in the Cache Key. Exactly one of
exclude is expected.
- To include all query string parameters (the default behavior), use include: “*”
- To ignore query strings, use exclude: “*”
- To include most query string parameters but exclude a few, use the exclude field which assumes the other query string parameters are included.
Headers control which headers go into the Cache Key. Similar to Query String, you can include specific headers or exclude default headers.
When you include a header, the header value is included in the Cache Key. For example, if an HTTP request contains an HTTP header like
X-Auth-API-key: 12345, and you include the
X-Auth-API-Key header in your Cache Key Template, then
12345 appears in the Cache Key.
To check for the presence of a header without including its actual value, use the
Currently, you can only exclude the
Origin header. The
Origin header is always included unless explicitly excluded. Including the Origin header in the Cache Key is important to enforce CORS. Additionally, you cannot include the following headers:
- Headers that have high cardinality and risk sharding the cache
- Headers that re-implement cache or proxy features
- Headers that are covered by other Cache Key features
- Headers that are specific to Cloudflare and prefixed with
- Headers that are already included in the custom Cache Key template, e.g.
Host determines which host header to include in the Cache Key.
resolved: false, Cloudflare includes the
Hostheader in the HTTP request sent to the origin.
resolved: true, Cloudflare includes the
Hostheader that was resolved to get the
origin IPfor the request. In this scenario, the
Hostheader may be different from the header actually sent if the Cloudflare Resolve Override feature is used.
cookie controls which cookies appear in the Cache Key. You can either include the cookie value or check for the presence of a particular cookie.
You cannot include cookies specific to Cloudflare. Cloudflare cookies are prefixed with
User feature fields add features about the end-user (client) into the Cache Key.
device_typeclassifies a request as
tabletbased on the User Agent
geoincludes the client’s country, derived from the IP address
langincludes the first language code contained in the
Accept-Languageheader sent by the client
The Prefetch feature is not compatible with the custom cache keys. With custom cache key Page Rules or Cache Rules, the custom cache key is used to cache all assets. However, Prefetch always uses the default cache key. This results in a key mismatch.