Manipulating the cache key

Redefining the cache key

Explicitly setting the cache key

You can set the cache key explicitly (including attaching conditions) by adding a request setting via the Settings pane of your configuration control panel and including a comma-separated list of cache keys. The values of the cache keys listed are combined to make a single hash, and each unique hash is considered a unique object.

For example, if you don't want the query string to be part of the cache key, but you don't want to change req.url so that the query string still ends up in your logs, you could use the following text for the hash keys:

regsub(req.url, "\?.*$", ""), req.http.host

In the UI, the text would appear in the Hash Keys field of a new request setting:

the Hash Keys field of Request Settings

As a general rule, you should always have req.url as one of your cache keys or as part of one. The example above includes req.url inside the regsub() therefore passing this requirement.

Purging adjustments when making additions to cache keys

Because purging works on individual hashes, additions to cache keys can complicate purging URLs. However, it can also be simplified.

For example, if you were to change your cache key to just req.url and not the default req.url, req.http.host, then purging http://foo.example.com/file.html would also purge http://bar.example.com/file.html. Keep in mind this is because they're actually the same object in the cache!

On the other hand, if you were to change your cache key req.url, req.http.host, req.http.Fastly-SSL, you would have to purge http://example.com/ and https://example.com/ individually.

In the latter case, if you were to use the Vary header instead of changing the cache key, you could still have different content on the two URLs, yet purge them with a single purge. In this case you would add a new Cache Header, use http.Vary as the Destination, and use the following as the Source:

if(beresp.http.Vary, beresp.http.Vary ",", "") "Fastly-SSL"

Using a POST request body as a cache key

As long as the body of a POST request is less than 2K in size and the content type is application/x-www-form-urlencoded, then we allow you to use it as part of the cache key. Your VCL should look something like:

sub vcl_hash {
  set req.hash += req.url;
  set req.hash += req.http.host;
  if (req.request == "POST" && req.postbody) {
    set req.hash += req.postbody;

You'll also need to force a cache lookup, but only for requests that can be cached, by doing something like this in vcl_recv:

  if (req.request == "POST" && req.postbody ~ "(^|&)action=list(&|$)") {

You can use a cookie as a cache key or just check for the presence of a cookie set to a specific value by controlling its request conditions. Both methods are simple and shown in the steps below.

Using a cookie as a cache key looks complicated but it's actually quite simple. Let's say your cookie is called "MyCookie" and it looks like mycookie=

  1. Go to the configuration tab, select your service, and select the Content pane.

    content pane.png

  2. Click the New button next to the Headers section and create a new header called Set MyCookie Header Default.

    • Set the Type to Request
    • Set the Action to Set
    • Set the Destination to http.X-MyCookie
    • Set the Source to "0" (with quotes)
  3. Create another new header called Set MyCookie Header from Cookie.

    • Set the Type to Request
    • Set the Action to Set
    • Set the Destination to http.X-MyCookie
    • Set the Source to regsub(req.http.cookie, ".*mycookie =([^;]+);.*", "\1")
    • Set the Priority to be larger than the default header you just created
  4. Click the gear icon to the right of the newly created Set MyCookie Header from Cookie header and select Request Conditions.


  5. Choose the request conditions.

    • Set the Name to Has MyCookie cookie
    • Set the Apply If to req.http.cookie ~ "mycookie="
  6. Now select the Settings pane.


  7. Click the New button next to the Request Settings section and create a new request setting.

    • Set the Name to Set Hash from Cookie
    • Set the Hash Keys to req.url, req.http.host, req.http.X-MyCookie
  8. Click the gear icon to the right of the newly created request setting and select Conditions.


  9. On the Choose Conditions window, click New to add a new condition.

An alternative way if you're just checking for the presence of the cookie set to some specific value (e.g., 1):

  1. Add a new Request Setting where the Hash Key is req.url, req.http.host, "Has mycookie"
  2. Add a condition to that setting where the "Apply if ..." is req.http.cookie ~ ".*mycookie =1;.*"
Back to Top