About Edge Dictionaries

Fastly offers updatable, global, Edge Dictionaries, a type of container that allow you to store data as key-value pairs and 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
table <ID> {
  "KEY_STRING": "VALUE_STRING",
  "KEY_STRING2": "VALUE_STRING2",
  ...
}

for use with a service.

When Edge 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 our guide on private Edge 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

Edge 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 an Edge 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. Edge Dictionaries would help you do this.

How to create and use dictionaries

To create an Edge 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 Fastly web interface.
• via the Fastly API.

Limitations and considerations

When creating Edge Dictionaries, keep the following things in mind:

• Edge Dictionaries created with custom VCL cannot be manipulated using the API or the web interface. 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 256 characters and their values are limited to 8000 characters. If you find your dictionaries approaching these resource limits, contact us at support@fastly.com. 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 Edge Dictionaries, be sure to take this into account.
• The contents of Edge 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 Edge 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 Edge 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 Edge 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.