---
title: Working with dictionaries
summary: null
url: >-
https://www.fastly.com/documentation/guides/full-site-delivery/dictionaries/working-with-dictionaries
---
[Dictionaries](/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. Dictionaries are made up of dictionary containers and dictionary items. You use dictionary items to create and store the key-value pairs, which are then added to a dictionary container. The dictionary container is attached to a service version but can be updated at any time after it is created, without ever incrementing a service's version.
You can work with dictionaries using the [Dictionaries page](#working-with-dictionaries-via-the-dictionaries-page), [custom VCL snippets](#working-with-dictionaries-about-fastly-vcl-snippets), or [Fastly API](/reference/api/dictionaries/). You can also create [private dictionaries](#private-dictionaries).
## Before you begin
Before working with dictionaries, be sure to review our [About dictionaries](/guides/full-site-delivery/dictionaries/about-dictionaries) guide to familiarize yourself with how dictionaries work, common use cases, and limitations to using dictionaries.
## Working with dictionaries via the Dictionaries page
You can create and interact with dictionaries using the Dictionaries page.
### Viewing dictionaries created using the Dictionaries page
To view a dictionary via the Dictionaries page, navigate to the dictionary management area of your service:
1.
1.
1.
1. Click **Dictionaries** under **Data**. Existing dictionaries, if any, associated with the currently selected service version appear.
From the Dictionaries page, you can use the search bar to filter the list of dictionaries. On any dictionary card, use the search bar to filter for keys or values within the dictionary.
> **HINT:** Remember that dictionary containers are versioned. If you don't see an dictionary attached to your service, check the service version to make sure you're looking at the right one.
### Creating a dictionary via the Dictionaries page
Creating a dictionary via the Dictionaries page requires you to create a dictionary container and then create the items that will exist in it.
#### Creating a dictionary container
Start by creating a dictionary container using the following steps:
1.
1.
1.
1. Click **Dictionaries** under **Data**.
1. Click **Create a dictionary**.
1. In the **Name of dictionary** field, enter a descriptive name for the dictionary (e.g., `Example Dictionary`).
1. Click **Add**.
1. From the **Activate** menu, select **Activate on Production** to deploy your configuration changes to the service version you're editing.
#### Creating a dictionary item
Once you've created a dictionary container, add items into it:
1. Click **Add item**.
1. In the **Key** field, enter the unique identifier for some item of data (e.g., `example.com`).
1. In the **Value** field, enter the value associated with the unique identifier (e.g., `yes`).
1. Click **Add**. The key-value pair appears in the dictionary container. This addition will become effective immediately. Changes immediately impact all service versions, including the active one.
### Using a dictionary
Once you've created a dictionary, you can start using it. To use a dictionary, you’ll need to [create and add a header](/guides/full-site-delivery/headers/adding-or-modifying-headers-on-http-requests-and-responses). Follow the steps below:
1.
1.
1.
1.
1. Click **Create header**.
1. Fill out the **Create a header** fields as follows:
* In the **Name** field, enter the name of your header rule (for example, `Redirect lookup`).
* From the **Type** menu, select **Request**, and from the **Action** menu, select **Set**.
* In the **Destination** field, enter the name of the header affected by the selected action (e.g., `url`).
* In the **Source** field, enter where the content for the header comes from (e.g., `table.lookup(redirects, req.url)`).
* From the **Ignore if set** menu, select **No**
* Leave the **Priority** field as is.
1. Click **Create** to create the header. A new header appears on the Content page.
Once you’ve created a header, you can [create a condition](/guides/full-site-delivery/conditions/using-conditions) to specify when to use the dictionary:
1. Click **Attach a condition** next to new header you just created.
1. Click **Create a new request condition**.
1. In the **Name** field, enter a name for your condition (e.g., `My dictionary condition`)
1. In the **Apply if** field, enter a condition (e.g., `table.lookup(redirects, req.url)`)
1. Click **Save and apply to**.
1.
### Editing a dictionary container via the Dictionaries page
You can edit the name of a dictionary container that was created via the Dictionaries page in any unlocked service version:
1. [Find a dictionary](#viewing-dictionaries-created-using-the-dictionaries-page) associated with an unlocked version of your service.
1. Click the pencil 
next to the dictionary container name.
1. Change the name, then click **Save**.
### Editing a dictionary item via the Dictionaries page
You can edit the dictionary items within a container at any time. To edit the key-value pair in a dictionary container that was created via the Dictionaries page:
1. [Find any dictionary](#viewing-dictionaries-created-using-the-dictionaries-page) associated with your service in which the key-value pairs appear. Because dictionary items are versionless, the service version you choose doesn't matter. Choose the one that makes the most sense to you.
1. Hover your cursor over a dictionary item, then click the pencil that appears.
1. Edit the key or value as necessary.
1. Click **Save**. The changes you make will be immediately applied to your configuration. If your dictionary container has already been associated with a deployed service version, those changes will happen live. Changes immediately impact all service versions, including the active one.
### Deleting a dictionary via the Dictionaries page
Keeping in mind their [limitations](/guides/full-site-delivery/dictionaries/about-dictionaries#limitations-and-considerations), dictionary containers and the items within them can be deleted via the Dictionaries page.
#### Deleting a dictionary container
You can delete a dictionary container that was created via the Dictionaries page in any unlocked service version:
1. [Find a dictionary](#viewing-dictionaries-created-using-the-dictionaries-page) associated with an unlocked version of your service.
1. Click the trash 
in the top right corner of the dictionary.
1. Click **Confirm and delete**.
1. From the **Activate** menu, select **Activate on Production** to deploy your configuration changes to the service version you're editing.
#### Deleting a dictionary entry
You can delete the dictionary entries within a container at any time.
> **WARNING:** Dictionary entry deletions are permanent and immediate. They cannot be recovered. Deleting a dictionary entry immediately impacts all service versions associated with the dictionary container holding the deleted entries, including the active service version.
To delete a key-value pair included in a dictionary container that was created via the Dictionaries page:
1. Find [any dictionary associated with your service](#viewing-dictionaries-created-using-the-dictionaries-page) in which the key-value pairs appear. Because dictionary items are versionless, the service version you choose doesn't matter. Choose the one that makes the most sense to you.
1. Hover your cursor over a dictionary item, then click the trash that appears.
1. Click **Confirm and delete**.
## Working with dictionaries using VCL snippets
You can create and interact with dictionaries using custom VCL snippets. 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.
### Viewing dictionaries created by VCL snippets
To view a dictionary under the VCL Snippets link, follow the steps below:
1.
1.
1.
1. Click **VCL Snippets**.
1. To view the contents of the dictionary, click **View source**.
### Creating a dictionary using VCL snippets
To create a dictionary using [VCL snippets](/guides/full-site-delivery/fastly-vcl/vcl-snippets/using-vcl-snippets), follow the steps below:
1.
1.
1.
1. Click **VCL snippets**.
1. Click **Add snippet**.
1. Fill out the **Add VCL snippet** fields as follows:
* Using the **Type** controls, select **Regular** to create a regular VCL snippet.
* In the **Name** field, enter an appropriate name (e.g., `Example Dictionary`).
* From the **Subroutine** menu, select **Init**.
* *(Optional)* In the **Priority** field, enter the order in which you want the snippet to execute. Lower numbers execute first.
* In the VCL editor, create a table and add key-value pairs to it. For example, if you wanted to create a table that redirects a URL to another path, you could use this VCL:
```vcl
table redirects {
"/source1": "/dest1",
"/source2": "/dest2"
}
```
where `"/source1": "/dest1"` and `"/source2": "/dest2"` represent key-value pairs for the source URL that you're redirecting to the destination URL.
1. Click **Add** to create the snippet.
1.
### Using a dictionary with VCL snippets
Once you've created a dictionary, you can start using it.
To start using your dictionary with VCL snippets, follow the steps below:
1.
1.
1.
1. Click **VCL**.
1. Click **VCL snippets**.
1. Click **Add snippet**.
1. Fill out the **Add VCL snippet** fields as follows:
* Using the **Type** controls, select **Regular** to create a regular VCL snippet.
* In the **Name** field, enter an appropriate name (e.g., `URL redirect`).
* From the **Placement** controls, select **Within subroutine**.
* From the **Subroutine** menu, select **recv (`vcl_recv`)**.
* *(Optional)* In the **Priority** field, enter the order in which you want the snippet to execute. Lower numbers execute first.
* In the VCL editor, add a condition to use the table you created in [Creating a dictionary using VCL snippets](#creating-a-dictionary-using-vcl-snippets). For example, if you needed to rewrite your URL destination, you could use this VCL:
```vcl
if (table.lookup(redirects, req.url)) {
set req.url = table.lookup(redirects, req.url);
}
```
where [`table.lookup`](/reference/vcl/functions/table/table-lookup/) checks the dictionary for the contents you want. The first parameter is the table being looked in and the second parameter is the key you're looking for. If the key exactly matches the second parameter, that value is returned. Be aware that regex doesn't work with a dictionary lookup.
1. Click **Add** to create the snippet.
1.
### Editing a dictionary using VCL snippets
You can edit the dictionary name and the condition that was created using VCL snippets in any unlocked service version:
1. Find a [dictionary](#viewing-dictionaries-created-by-vcl-snippets) associated with an unlocked version of your service.
1. Click the pencil next to the dictionary. You can now make changes to the name and the condition.
1. Click **Update** once you’re finished with your changes.
1. From the **Activate** menu, select **Activate on Production** to activate the version you made the edits in and view the changes in your VCL.
### Deleting a dictionary using VCL snippets
You can delete a dictionary using VCL snippets by following the steps below. Keep in mind the [limitations](/guides/full-site-delivery/dictionaries/about-dictionaries#limitations-and-considerations) involved when deleting a dictionary.
1. [Find a dictionary](#viewing-dictionaries-created-by-vcl-snippets) associated with an unlocked version of your service.
1. Click the trash on the top right corner of the snippet
1. Click **Confirm and delete**.
1. From the **Activate** menu, select **Activate on Production** to deploy your configuration changes to the service version you're editing.
## Private dictionaries
Private dictionaries store dictionary items that can't be listed or read via the Fastly control panel or the API.
### Limitations and considerations
When creating private dictionaries, keep the following things in mind:
* You can create, read, update, and delete a private dictionary. Private dictionaries can only be created via the API.
* You cannot update the `write_only` attribute of a dictionary after it has been created.
* You can create, update, and delete items that belong to a private dictionary. After you've activated a service version, you can only update the values of existing private dictionary items via API. You can add new items to a private dictionary via the Fastly control panel or the API.
* You cannot view items that belong to a private dictionary via the API. After you've activated a service version, you cannot use the Fastly control panel to view items that belong to a private dictionary.
* Depending on how your [service](/guides/getting-started/services/about-services) is configured, data stored in private dictionaries can be sent in [headers](/guides/full-site-delivery/headers/adding-or-modifying-headers-on-http-requests-and-responses) and to [log streaming endpoints](/guides/integrations/streaming-logs/setting-up-remote-log-streaming).
> **HINT:** To edit or delete dictionary items in a private dictionary, you'll need to remember [the keys of the dictionary items](/reference/api/dictionaries/dictionary-item/).
### Creating a private dictionary container
To use a private dictionary container, start by creating an empty one within an unlocked version of a service.
Before a private dictionary can be manipulated, its private dictionary container must be associated with at least one service version that is not locked and not active so that the service becomes aware of the private dictionary's existence.
For example, if you were creating a `my_example_dictionary` private dictionary via the API, you would make an API call by running this command:
```term copy
$ curl -X POST -H 'Fastly-Key: FASTLY_API_TOKEN' -d 'name=my_example_dictionary&write_only=true' https://api.fastly.com/service//version//dictionary
```
which would return:
```json
{
"created_at": "2017-05-03T16:11:41+00:00",
"deleted_at": null,
"id": "",
"name": "my_example_dictionary",
"service_id": "",
"updated_at": "2017-05-03T16:11:41+00:00",
"version": ,
"write_only": true
}
```
You can [add dictionary items](/guides/full-site-delivery/dictionaries/working-with-dictionaries#creating-a-dictionary-item) after you've created the dictionary. Don't forget to [activate the service](/guides/getting-started/services/working-with-cdn-services#editing-and-activating-versions-of-services) when you're finished.
### Viewing private dictionaries in VCL
The contents of private dictionaries are hidden in VCL. The private dictionary's metadata is displayed, as shown below:
```vcl
table my_example_dictionary {
# REDACTED dictionary content
# last_updated: 2017-10-16 20:44:43
# item_count: 2
# digest: 8f92141234567890da30ba9cea7d98ef614
}
```
## What's next
Explore custom VCL examples for using dictionaries on [Developer Hub](/solutions/examples/vcl/).
> **IMPORTANT:**
## Related content
* [Dictionaries API documentation](/reference/api/dictionaries/)
* [Dictionaries CLI documentation](/reference/cli/service/dictionary/)