About dictionaries

Dictionaries are a type of container that allow you to store data as key-value pairs that can be used in a service without being attached to a single version.

Using dictionaries, you can turn frequently repeated statements like this:

1
2
3
4
5

if (something == "value1") {
  set other = "result1";
} else if (something == "value2") {
  set other = "result2";
}

into a single function that acts as constant, like this:

1
2
3
4
5
6
7

table things {
  "value1": "result1",
  "value2": "result2",
  ...
}

set other = table.lookup(things, something);

This allows you to easily make changes to these statements without it being tied to a specific version.

When dictionaries might be useful

• Content sharing and social media outlets updating large referer block lists
• Mobile advertisers validating a key to prevent cache-bust guessing
• Customers authenticating valid user keys at the edge (see private dictionaries)
• Global publishers redirecting users to a specific country site based on geo-location
• Image providers performing token checks for certain objects
• Advertising technology companies blocking bad actors at edge
• Customers deploying web interface versions with simple value change via API

How dictionaries work

Dictionaries are made up of dictionary containers and the dictionary items within them. Once you attach a dictionary container to a version of your service and that service is activated, the data in it becomes versionless. This means you can add to and update the data a dictionary contains at any time after it is created, without ever incrementing a service's version.

For example, say you have a referer block list that changes frequently and you want to associate it with a service. Any time that service's configuration changes, especially if the configuration rolls back to a previous version, you would want the block-listed referer domains to continue to remain with the service configuration instead of being removed. Dictionaries would help you do this.

How to create and use dictionaries

To create a dictionary and use it within your service, start by creating an empty dictionary container and then add its entries in a working version of a service that's unlocked and not yet activated. You can create dictionaries:

• via the Dictionaries page.
• via VCL snippets.
• via the Fastly API.

Limitations and considerations

When creating dictionaries, keep the following things in mind:

• Dictionaries created with custom VCL cannot be manipulated using the API or the Dictionaries page. If you create a dictionary container using custom VCL, that dictionary must always be manipulated via custom VCL. Dictionaries uploaded via custom VCL aren't versionless.
• Dictionary containers, item keys, and their values have specific limits. Dictionary containers are limited to 1000 items. Dictionary item keys are limited to 255 characters and their values are limited to 8000 characters. If you find your dictionaries approaching these resource limits, contact support. We may be able to help you figure out more efficient ways to do things.
• Dictionary item keys are case sensitive. The names of dictionary items are case sensitive. When designing your dictionaries, be sure to take this into account.
• The contents of dictionaries are stored as VCL. Personal data should not be incorporated into VCL. Our Compliance and Law FAQ describes in detail how Fastly handles personal data privacy.

When making changes to dictionaries, keep the following things in mind:

• When you delete a dictionary container, you'll only delete it from the service version you're editing. Dictionary containers are tied to versions and can be cloned and reverted. When using dictionaries, we want you to be able to do things like delete a dictionary container from a current version of your service in order to roll back your configuration to a previous version using as few steps as possible.
• When you delete a dictionary container, we don't delete the dictionary items inside it. The dictionary items in a dictionary container are versionless. When you change service versions, we want you to still be able to access the data.
• Dictionary item deletions are permanent. Because we don't store data, if you delete a dictionary item, the entry is gone forever from all service versions.
• Event logs don't exist for dictionary changes. If you add, update, or remove a dictionary item, there will be no record of it. The only record of a change will exist when you compare service versions to view the point at which the dictionary container was associated with the service version in the first place.