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 the Edit configuration button and then select the option to clone the active version. The Domains page appears.
  4. Click the Dictionaries link under Data. Existing dictionaries, if any, associated with the currently selected service version appear.

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 the Edit configuration button and then select the option to clone the active version. The Domains page appears.
  4. Click the Dictionaries link under Data. The Dictionaries page appears.
  5. Click Create a dictionary. The dictionary container name field appears.
  6. In the Name of dictionary field, enter a descriptive name for the dictionary (e.g., Example Dictionary).
  7. Click the Add button. The empty dictionary container you created appears.
  8. Click the Activate button 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 the Add item link. The dictionary item fields appear.
  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 the Add button. The key-value pair appears in the dictionary container. This addition will become effective immediately.

    an example dictionary container with one dictionary item, as it appears in the Fastly web interface

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 the Edit configuration button and then select the option to clone the active version. The Domains page appears.
  4. Click the Content link. The Content page appears.
  5. Click the Create header button. The Create a header window appears.

    Using a dictionary using web interface

  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 the Create button 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 the Attach a condition link next to new header you just created. The Add a condition message appears.
  2. Click the Create a new request condition button. The Create a new condition page appears.

    adding condition on a dictionary

  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 the Save and apply to button.
  6. Click the Activate button 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 icon next to the dictionary container name.
  3. Change the name, then click the Save button.

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 icon that appears.
  3. Edit the key or value as necessary.
  4. Click the Save button. 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 can icon in the top right corner of the dictionary.
  3. Click the Confirm and delete button.
  4. Click the Activate button 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 can icon that appears.
  3. Click the Confirm and delete button.

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 the Edit configuration button and then select the option to clone the active version. The Domains page appears.
  4. Click the VCL Snippets link. The snippet titles associated with the currently selected service version appear.
  5. To view the contents of the dictionary, click the View source button.

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 the Edit configuration button and then select the option to clone the active version. The Domains page appears.
  4. Click the VCL snippets link. The VCL Snippets page appears.
  5. Click Create snippet. The Create a VCL snippet page appears.

    an example dictionary container created with VCL 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 the Edit configuration button and then select the option to clone the active version. The Domains page appears.
  4. Click the VCL snippets link. The VCL Snippets page appears.
  5. Click Create snippet. The Create a VCL snippet page appears.

    an example dictionary container with subroutine

  6. In the Name field, enter an appropriate name (e.g., URL redirect).
  7. From the Type (placement of the snippet) controls, select within subroutine.
  8. From the Select subroutine menu, select recv (vcl_recv).
  9. 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.

  10. Click Create to create the snippet.
  11. Click the Activate button 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 icon next to the dictionary. You can now make changes to the name and the condition.
  3. Click the Update button once you’re finished with your changes.
  4. Click the Activate button 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 can icon on the top right corner of the snippet
  3. Click the Confirm and delete button.
  4. Click the Activate button 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
  • You cannot update the write_only attribute of a dictionary
  • You can create, update, and delete items that belong to a private dictionary
  • You cannot view items that belong to a private dictionary via the API
  • 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:

1
$ 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.

Back to Top