Ignore Set-Cookie or query string parameters when caching content on CDN servers

The Ignore query string and Ignore Set-Cookie options control how query parameters and Set-Cookie response headers affect CDN caching. Both are available in the Cache section of CDN resource settings.

Query string setting

The Ignore query string option determines how the CDN caches URLs that have query parameters. Query parameters are optional key-value pairs separated by = and joined by &, appearing at the end of a URL after a ?:

http://cdn.example.com/photo.jpeg?id=6&color=blue

When disabled, the full query string is included in the cache key, so URLs with different query parameter values are cached as separate objects.

To enable it in the CDB Technical Web Portal:

1. In the left sidebar, navigate to CDN > CDN resources and click the CNAME of the resource to configure.

2. In the sidebar, under Cache, click Query string.

3. Enable the Ignore query string toggle.

4. Select a mode and set its parameters.

The enabled option has three modes:

Mode	Parameters in the list	Other parameters
Ignore all	—	Ignored
Ignore all except	Included in cache key	Ignored
Ignore only	Ignored	Included in cache key

• Ignore all (default). Files with different query parameters are cached as a single object, regardless of parameter values.

These URLs are cached as a single object because all parameters are ignored:

http://cdn.example.com/photo.jpeg?id=6&color=blue
http://cdn.example.com/photo.jpeg?id=1&color=blue

• Ignore all except. Files with the specified query parameters are cached as separate objects; files with other parameters are cached as a single object.

  Enter each parameter name on a separate line in the text field that appears.

With id in the text field, these URLs are cached as separate objects because the id values differ, and the color parameter is ignored:

http://cdn.example.com/photo.jpeg?id=6&color=blue
http://cdn.example.com/photo.jpeg?id=1&color=blue

With color in the text field, these URLs are cached as a single object because the color values are the same, and the id parameter is ignored:

http://cdn.example.com/photo.jpeg?id=6&color=blue
http://cdn.example.com/photo.jpeg?id=1&color=blue

• Ignore only. Files with the specified query parameters are cached as a single object; files with other parameters are cached as separate objects.

  Enter each parameter name on a separate line in the text field that appears.

With id in the text field, these URLs are cached as a single object because the id values are ignored, and the color values are the same:

http://cdn.example.com/photo.jpeg?id=6&color=blue
http://cdn.example.com/photo.jpeg?id=1&color=blue

With color in the text field, these URLs are cached as separate objects because the color values are ignored, and the id values differ:

http://cdn.example.com/photo.jpeg?id=6&color=blue
http://cdn.example.com/photo.jpeg?id=1&color=blue

⚠️

Enabling or changing this option may invalidate cached content for URLs with query strings. CDN servers will request those files from the origin again, which can increase origin load.

5. Click Save changes.

Set-Cookie setting

When Ignore Set-Cookie is disabled, the CDN takes the Set-Cookie response header into account when storing the response in cache. Files with different Set-Cookie header values are cached as separate objects, so multiple cached copies of the same content can accumulate and the cache hit ratio drops.

The Ignore Set-Cookie option changes this behavior: files are cached as a single object regardless of the Set-Cookie header value. CDB recommends enabling this option for the best cache hit ratio.

To enable it, open Cache > Set-Cookie, enable the Ignore Set-Cookie toggle, and click Save changes.

Update the resource options to control how query parameters and Set-Cookie headers affect the CDN cache key. Find the resource ID in list CDN resources.

ℹ️

An API token is required.

export GCORE_API_KEY="{YOUR_API_KEY}"
export CDN_RESOURCE_ID="{YOUR_RESOURCE_ID}"

Query string

Only one of these three options can be enabled. Enabling a second one returns HTTP 400, so set enabled to false on the active option in the same request and keep its value.

The samples below switch modes in sequence: Ignore all, then Ignore all except, then Ignore only, then the full query string. When a different query-string option is already enabled, set that option to enabled false in the same request.

value is required. For query_params_whitelist and query_params_blacklist, an empty value list returns HTTP 400 while the option is enabled.

Ignore all

Send ignoreQueryString with enabled true and value true. URLs that differ only by query parameters are cached as one object.

import os
from gcore import CDB

client = CDB()

resource = client.cdn.cdn_resources.update(
    int(os.environ["CDN_RESOURCE_ID"]),
    options={
        "ignore_query_string": {"enabled": True, "value": True},
    },
)
print(resource.options.ignore_query_string.enabled, resource.options.ignore_query_string.value)

package main

import (
    "context"
    "fmt"
    "os"
    "strconv"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cdn"
)

func main() {
    client := gcore.NewClient()
    ctx := context.Background()
    resourceID, err := strconv.ParseInt(os.Getenv("CDN_RESOURCE_ID"), 10, 64)
    if err != nil {
        panic(err)
    }

    resource, err := client.CDN.CDNResources.Update(ctx, resourceID, cdn.CDNResourceUpdateParams{
        Options: cdn.CDNResourceUpdateParamsOptions{
            IgnoreQueryString: cdn.CDNResourceUpdateParamsOptionsIgnoreQueryString{
                Enabled: true,
                Value:   true,
            },
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(resource.Options.IgnoreQueryString.Enabled, resource.Options.IgnoreQueryString.Value)
}

curl -X PATCH "https://api.cdb-staging.cdn.orange.com/cdn/resources/$CDN_RESOURCE_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "ignoreQueryString": {
        "enabled": true,
        "value": true
      }
    }
  }'

The API returns HTTP 200:

{
  "id": 12345,
  "options": {
    "ignoreQueryString": {
      "enabled": true,
      "value": true
    }
  }
}

Ignore all except

In this sample, ignore_query_string is the option enabled above, so the request sets it to enabled false and keeps value true. query_params_whitelist names the parameters that stay in the cache key. Other parameters are ignored, so URLs that differ only in an unlisted parameter are cached as one object.

import os
from gcore import CDB

client = CDB()

resource = client.cdn.cdn_resources.update(
    int(os.environ["CDN_RESOURCE_ID"]),
    options={
        "ignore_query_string": {"enabled": False, "value": True},
        "query_params_whitelist": {"enabled": True, "value": ["id"]},
    },
)
print(resource.options.query_params_whitelist.enabled, resource.options.query_params_whitelist.value)

package main

import (
    "context"
    "fmt"
    "os"
    "strconv"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cdn"
)

func main() {
    client := gcore.NewClient()
    ctx := context.Background()
    resourceID, err := strconv.ParseInt(os.Getenv("CDN_RESOURCE_ID"), 10, 64)
    if err != nil {
        panic(err)
    }

    resource, err := client.CDN.CDNResources.Update(ctx, resourceID, cdn.CDNResourceUpdateParams{
        Options: cdn.CDNResourceUpdateParamsOptions{
            IgnoreQueryString: cdn.CDNResourceUpdateParamsOptionsIgnoreQueryString{
                Enabled: false,
                Value:   true,
            },
            QueryParamsWhitelist: cdn.CDNResourceUpdateParamsOptionsQueryParamsWhitelist{
                Enabled: true,
                Value:   []string{"id"},
            },
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(resource.Options.QueryParamsWhitelist.Enabled, resource.Options.QueryParamsWhitelist.Value)
}

curl -X PATCH "https://api.cdb-staging.cdn.orange.com/cdn/resources/$CDN_RESOURCE_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "ignoreQueryString": {
        "enabled": false,
        "value": true
      },
      "query_params_whitelist": {
        "enabled": true,
        "value": ["id"]
      }
    }
  }'

The API returns HTTP 200:

{
  "id": 12345,
  "options": {
    "ignoreQueryString": {
      "enabled": false,
      "value": true
    },
    "query_params_whitelist": {
      "enabled": true,
      "value": ["id"]
    }
  }
}

Ignore only

In this sample, query_params_whitelist is the option enabled above, so the request sets it to enabled false and keeps id. query_params_blacklist names the parameters left out of the cache key. Listed parameters are ignored, and every other parameter stays in the cache key.

import os
from gcore import CDB

client = CDB()

resource = client.cdn.cdn_resources.update(
    int(os.environ["CDN_RESOURCE_ID"]),
    options={
        "query_params_whitelist": {"enabled": False, "value": ["id"]},
        "query_params_blacklist": {"enabled": True, "value": ["color"]},
    },
)
print(resource.options.query_params_blacklist.enabled, resource.options.query_params_blacklist.value)

package main

import (
    "context"
    "fmt"
    "os"
    "strconv"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cdn"
)

func main() {
    client := gcore.NewClient()
    ctx := context.Background()
    resourceID, err := strconv.ParseInt(os.Getenv("CDN_RESOURCE_ID"), 10, 64)
    if err != nil {
        panic(err)
    }

    resource, err := client.CDN.CDNResources.Update(ctx, resourceID, cdn.CDNResourceUpdateParams{
        Options: cdn.CDNResourceUpdateParamsOptions{
            QueryParamsWhitelist: cdn.CDNResourceUpdateParamsOptionsQueryParamsWhitelist{
                Enabled: false,
                Value:   []string{"id"},
            },
            QueryParamsBlacklist: cdn.CDNResourceUpdateParamsOptionsQueryParamsBlacklist{
                Enabled: true,
                Value:   []string{"color"},
            },
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(resource.Options.QueryParamsBlacklist.Enabled, resource.Options.QueryParamsBlacklist.Value)
}

curl -X PATCH "https://api.cdb-staging.cdn.orange.com/cdn/resources/$CDN_RESOURCE_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "query_params_whitelist": {
        "enabled": false,
        "value": ["id"]
      },
      "query_params_blacklist": {
        "enabled": true,
        "value": ["color"]
      }
    }
  }'

The API returns HTTP 200:

{
  "id": 12345,
  "options": {
    "query_params_whitelist": {
      "enabled": false,
      "value": ["id"]
    },
    "query_params_blacklist": {
      "enabled": true,
      "value": ["color"]
    }
  }
}

Include the full query string

Set enabled to false on the active option and keep value, so the full query string is part of the cache key again. The request below turns off Ignore only and keeps color.

import os
from gcore import CDB

client = CDB()

resource = client.cdn.cdn_resources.update(
    int(os.environ["CDN_RESOURCE_ID"]),
    options={
        "query_params_blacklist": {"enabled": False, "value": ["color"]},
    },
)
print(resource.options.query_params_blacklist.enabled, resource.options.query_params_blacklist.value)

package main

import (
    "context"
    "fmt"
    "os"
    "strconv"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cdn"
)

func main() {
    client := gcore.NewClient()
    ctx := context.Background()
    resourceID, err := strconv.ParseInt(os.Getenv("CDN_RESOURCE_ID"), 10, 64)
    if err != nil {
        panic(err)
    }

    resource, err := client.CDN.CDNResources.Update(ctx, resourceID, cdn.CDNResourceUpdateParams{
        Options: cdn.CDNResourceUpdateParamsOptions{
            QueryParamsBlacklist: cdn.CDNResourceUpdateParamsOptionsQueryParamsBlacklist{
                Enabled: false,
                Value:   []string{"color"},
            },
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(resource.Options.QueryParamsBlacklist.Enabled, resource.Options.QueryParamsBlacklist.Value)
}

curl -X PATCH "https://api.cdb-staging.cdn.orange.com/cdn/resources/$CDN_RESOURCE_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "query_params_blacklist": {
        "enabled": false,
        "value": ["color"]
      }
    }
  }'

The API returns HTTP 200:

{
  "id": 12345,
  "options": {
    "query_params_blacklist": {
      "enabled": false,
      "value": ["color"]
    }
  }
}

📝

In the Go SDK, set Value to true when Enabled is false for ignoreQueryString and ignore_cookie. Both fields set to false are omitted, and the stored option stays unchanged.

Set-Cookie

Send ignore_cookie with enabled true and value true so files with different Set-Cookie header values are cached as one object. This option can stay enabled together with one query-string option.

import os
from gcore import CDB

client = CDB()

resource = client.cdn.cdn_resources.update(
    int(os.environ["CDN_RESOURCE_ID"]),
    options={
        "ignore_cookie": {"enabled": True, "value": True},
    },
)
print(resource.options.ignore_cookie.enabled, resource.options.ignore_cookie.value)

package main

import (
    "context"
    "fmt"
    "os"
    "strconv"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cdn"
)

func main() {
    client := gcore.NewClient()
    ctx := context.Background()
    resourceID, err := strconv.ParseInt(os.Getenv("CDN_RESOURCE_ID"), 10, 64)
    if err != nil {
        panic(err)
    }

    resource, err := client.CDN.CDNResources.Update(ctx, resourceID, cdn.CDNResourceUpdateParams{
        Options: cdn.CDNResourceUpdateParamsOptions{
            IgnoreCookie: cdn.CDNResourceUpdateParamsOptionsIgnoreCookie{
                Enabled: true,
                Value:   true,
            },
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(resource.Options.IgnoreCookie.Enabled, resource.Options.IgnoreCookie.Value)
}

curl -X PATCH "https://api.cdb-staging.cdn.orange.com/cdn/resources/$CDN_RESOURCE_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "ignore_cookie": {
        "enabled": true,
        "value": true
      }
    }
  }'

The API returns HTTP 200:

{
  "id": 12345,
  "options": {
    "ignore_cookie": {
      "enabled": true,
      "value": true
    }
  }
}

Turn Ignore Set-Cookie off

Set enabled to false and keep value true. Files with different Set-Cookie header values are cached as separate objects again, and the stored value remains true.

import os
from gcore import CDB

client = CDB()

resource = client.cdn.cdn_resources.update(
    int(os.environ["CDN_RESOURCE_ID"]),
    options={
        "ignore_cookie": {"enabled": False, "value": True},
    },
)
print(resource.options.ignore_cookie.enabled, resource.options.ignore_cookie.value)

package main

import (
    "context"
    "fmt"
    "os"
    "strconv"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cdn"
)

func main() {
    client := gcore.NewClient()
    ctx := context.Background()
    resourceID, err := strconv.ParseInt(os.Getenv("CDN_RESOURCE_ID"), 10, 64)
    if err != nil {
        panic(err)
    }

    resource, err := client.CDN.CDNResources.Update(ctx, resourceID, cdn.CDNResourceUpdateParams{
        Options: cdn.CDNResourceUpdateParamsOptions{
            IgnoreCookie: cdn.CDNResourceUpdateParamsOptionsIgnoreCookie{
                Enabled: false,
                Value:   true,
            },
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(resource.Options.IgnoreCookie.Enabled, resource.Options.IgnoreCookie.Value)
}

curl -X PATCH "https://api.cdb-staging.cdn.orange.com/cdn/resources/$CDN_RESOURCE_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "ignore_cookie": {
        "enabled": false,
        "value": true
      }
    }
  }'

The API returns HTTP 200:

{
  "id": 12345,
  "options": {
    "ignore_cookie": {
      "enabled": false,
      "value": true
    }
  }
}

Control how query parameters and the Set-Cookie response header affect the CDN cache key with the Terraform provider v2. The cache key decides whether two URLs are stored as one object or as separate objects.

Enable only one of ignore_query_string, query_params_whitelist, and query_params_blacklist. A second enabled option returns HTTP 400. For query_params_whitelist and query_params_blacklist, an empty value list returns HTTP 400 while the option is enabled. An option left out of options stays unchanged, so set enabled to false on the active option in the same configuration and keep its value.

Enabling or changing a query-string option can invalidate cached URLs that contain a query string, so CDN servers request those files from the origin again and origin load can increase.

Query string

ignore_cookie can stay enabled beside whichever query-string option is active. The configurations below switch modes in sequence. When a different query-string option is already enabled, set that option to enabled false in the same configuration and keep its value. Run terraform apply after editing options.

Ignore all

Set ignore_query_string so URLs that differ only by query parameters are cached as one object.

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "cdn.example.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"

  options = {
    ignore_query_string = {
      enabled = true
      value   = true
    }
  }
}

Ignore all except

Set query_params_whitelist to the parameter names that stay in the cache key. URLs that differ only by an unlisted parameter are cached as one object, while different values of a listed parameter are cached as separate objects. In this configuration, ignore_query_string is the option enabled above, so it is turned off and its stored value stays true. id stays in the cache key.

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "cdn.example.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"

  options = {
    ignore_query_string = {
      enabled = false
      value   = true
    }
    query_params_whitelist = {
      enabled = true
      value   = ["id"]
    }
  }
}

Ignore only

Set query_params_blacklist to the parameter names left out of the cache key. Listed parameters are ignored, so URLs that differ only by those parameters are cached as one object, while every other parameter stays in the cache key. In this configuration, query_params_whitelist is the option enabled above, so it is turned off and id stays stored. color is ignored.

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "cdn.example.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"

  options = {
    query_params_whitelist = {
      enabled = false
      value   = ["id"]
    }
    query_params_blacklist = {
      enabled = true
      value   = ["color"]
    }
  }
}

Full query string

Set enabled to false on the active option and keep value, so the full query string is part of the cache key again. This configuration turns off Ignore only and keeps color, while a disabled query_params_whitelist left out of options stays disabled and keeps id.

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "cdn.example.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"

  options = {
    query_params_blacklist = {
      enabled = false
      value   = ["color"]
    }
  }
}

Set-Cookie

Set ignore_cookie so files with different Set-Cookie header values are cached as one object. A query-string option left out of options stays unchanged.

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "cdn.example.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"

  options = {
    ignore_cookie = {
      enabled = true
      value   = true
    }
  }
}

Set-Cookie with Ignore only

Keep ignore_cookie enabled beside query_params_blacklist, so different Set-Cookie values are still one object and color stays out of the cache key. This configuration uses the query-string state from Ignore only, where ignore_query_string and query_params_whitelist are already disabled. When either is still enabled, set it to enabled false in the same configuration, because an omitted option stays unchanged.

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "cdn.example.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"

  options = {
    query_params_blacklist = {
      enabled = true
      value   = ["color"]
    }
    ignore_cookie = {
      enabled = true
      value   = true
    }
  }
}

Set-Cookie off

Set enabled to false and keep value true. Files with different Set-Cookie header values are cached as separate objects again, and the stored value remains true.

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "cdn.example.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"

  options = {
    ignore_cookie = {
      enabled = false
      value   = true
    }
  }
}