---
title: About dictionaries
summary: null
url: >-
  https://www.fastly.com/documentation/guides/full-site-delivery/dictionaries/about-dictionaries
---

[Dictionaries](https://www.fastly.com/documentation/guides/full-site-delivery/dictionaries/about-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:

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

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

```vcl
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](https://www.fastly.com/documentation/guides/full-site-delivery/dictionaries/working-with-dictionaries#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 control panel 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](https://www.fastly.com/documentation/guides/full-site-delivery/dictionaries/about-dictionaries#how-to-create-and-use-dictionaries) the data a dictionary contains at any time after it is created, without ever incrementing a service's version. Changes immediately impact all service versions, including the active one.

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](https://www.fastly.com/documentation/guides/full-site-delivery/dictionaries/working-with-dictionaries#working-with-dictionaries-via-the-dictionaries-page).
- via [VCL snippets](https://www.fastly.com/documentation/guides/full-site-delivery/dictionaries/working-with-dictionaries#working-with-dictionaries-about-fastly-vcl-snippets).
- via [the Fastly API](https://www.fastly.com/documentation/reference/api/dictionaries/).

> **HINT:** You can create a [private dictionary](https://www.fastly.com/documentation/guides/full-site-delivery/dictionaries/working-with-dictionaries#private-dictionaries) to store dictionary items that can't be listed or read via the control panel or the 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](https://docs.fastly.com/products/network-services-resource-limits#vcl-and-configuration-limits), [contact support](https://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 dictionaries, be sure to take this into account.
- **The contents of dictionaries are stored as VCL.** Dictionaries are exposed as VCL tables and can be accessed using the `table.contains` and `table.lookup` functions. 

  Personal data should not be incorporated into VCL. Our [Compliance and Law FAQ](https://www.fastly.com/trust/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](https://www.fastly.com/documentation/guides/getting-started/services/working-with-cdn-services#comparing-different-service-versions) to view the point at which the dictionary container was associated with the service version in the first place.

> **IMPORTANT:** 
>
> Personal information, secrets, or sensitive data should not be included in dictionaries or incorporated into VCL. In addition, we do not maintain version histories of your dictionaries. Our [Compliance and Law FAQ](https://www.fastly.com/trust/faq) describes in detail how Fastly handles personal data privacy.
>
>

## Related content

- [Dictionaries API documentation](https://www.fastly.com/documentation/reference/api/dictionaries/)
- [Dictionaries CLI documentation](https://www.fastly.com/documentation/reference/cli/service/dictionary/)