Working with dictionaries using the web interface

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, custom VCL snippets, or Fastly API. You can also create private dictionaries.

Before you begin

Before working with dictionaries, be sure to review our 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. Log in to the Fastly web interface.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.
4. 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.

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. Log in to the Fastly web interface.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.
4. Click Dictionaries under Data.
5. Click Create a dictionary.
6. In the Name of dictionary field, enter a descriptive name for the dictionary (e.g., Example Dictionary).
7. Click Add.
8. Click Activate 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.

2. In the Key field, enter the unique identifier for some item of data (e.g., example.com).

3. In the Value field, enter the value associated with the unique identifier (e.g., yes)

4. Click Add. The key-value pair appears in the dictionary container. This addition will become effective immediately.

   

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. Follow the steps below:

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.
4. Click Content.

5. Click Create header.

   

6. 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.

7. 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 to specify when to use the dictionary:

1. Click Attach a condition next to new header you just created.

2. Click Create a new request condition.

   

3. In the Name field, enter a name for your condition (e.g., My dictionary condition)

4. In the Apply if field, enter a condition (e.g., table.lookup(redirects, req.url))

5. Click Save and apply to.

6. Click Activate to deploy your configuration changes.

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 associated with an unlocked version of your service.
2. Click the pencil next to the dictionary container name.
3. 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 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.
2. Hover your cursor over a dictionary item, then click the pencil that appears.
3. Edit the key or value as necessary.
4. 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.

Deleting a dictionary via the Dictionaries page

Keeping in mind their limitations, 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 associated with an unlocked version of your service.
2. Click the trash in the top right corner of the dictionary.
3. Click Confirm and delete.
4. Click Activate 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. 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 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.
2. Hover your cursor over a dictionary item, then click the trash that appears.
3. 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. Log in to the Fastly web interface.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.
4. Click VCL Snippets.
5. To view the contents of the dictionary, click View source.

Creating a dictionary using VCL snippets

To create a dictionary using VCL snippets, follow the steps below:

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL snippets.

5. Click Create snippet.

   

6. In the Name field, enter an appropriate name (e.g., Example Dictionary).

7. From the Type (placement of the snippet), select init.

8. In the VCL field, create a table and add key-value pairs. For example, if you want to create a table that redirects a URL to another path:

   1
   2
   3
   4

   table redirects {
     "/source1": "/dest1",
     "/source2": "/dest2"
   }

   where the table is a set of key-value pairs that you can reference in your code. You can replace the contents of this table with different key-value pairs.

9. Click Create to create the snippet.

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. Log in to the Fastly web interface.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL snippets.

5. Click Create snippet.

   

6. Fill out the Create a VCL snippet fields as follows:

   • In the Name field, enter an appropriate name (e.g., URL redirect).
   • From the Type (placement of the snippet) controls, select within subroutine.
   • From the Select subroutine menu, select recv (vcl_recv).
   • In the VCL field, add a condition to use the table you created in Creating a dictionary using VCL Snippets. For example, if you need to rewrite your URL destination, you could use:

   1
   2
   3

   if (table.lookup(redirects, req.url)) {
      set req.url = table.lookup(redirects, req.url);
   }

   where 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.

7. Click Create to create the snippet.

8. Click Activate to deploy your configuration changes.

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 associated with an unlocked version of your service.
2. Click the pencil next to the dictionary. You can now make changes to the name and the condition.
3. Click Update once you’re finished with your changes.
4. Click Activate 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 involved when deleting a dictionary.

1. Find a dictionary associated with an unlocked version of your service.
2. Click the trash on the top right corner of the snippet
3. Click Confirm and delete.
4. Click Activate 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 web interface 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 web interface 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 web interface to view items that belong to a private dictionary.
• Depending on how your service is configured, data stored in private dictionaries can be sent in headers and to log streaming endpoints.

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:

$ curl -X POST -H 'Fastly-Key: FASTLY_API_TOKEN' -d 'name=my_example_dictionary&write_only=true' https://api.fastly.com/service/<service_id>/version/<version_number>/dictionary

which would return:

1
2
3
4
5
6
7
8
9
10

{
  "created_at": "2017-05-03T16:11:41+00:00",
  "deleted_at": null,
  "id": "<dictionary_id>",
  "name": "my_example_dictionary",
  "service_id": "<service_id>",
  "updated_at": "2017-05-03T16:11:41+00:00",
  "version": <version_number>,
  "write_only": true
}

You can start adding dictionary items after you've created the dictionary. Don't forget to activate the service 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:

1
2
3
4
5
6

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.