In short. Fastly maps old URL paths to destinations with VCL table lookup and maintains the entries through its dictionary API.
Definition: A Fastly edge dictionary is a VCL data table that stores key-value pairs available during request processing. For old URL paths, the documented pattern uses each path as a key, looks up its destination, and returns a redirect at the edge.
Key facts
- Fastly's edge redirect example describes a dictionary of URL mappings for redirects and places the solution in a VCL service.
- The embedded Fastly Fiddle maps
/source1to/dest1and/source2to/dest2insolution_redirects. - Fastly's VCL table reference says dictionary content is transformed into a table declaration that is prepended to the service's VCL.
- The Dictionary API reference says items in an installed dictionary can be updated through API calls without activating a new service configuration version.
- Fastly's Dictionary item reference lists endpoints for listing, inserting, updating, and deleting dictionary items.
How does the documented VCL lookup work?
The embedded Fastly Fiddle starts with a map whose keys are old paths and whose values are destination paths:
table solution_redirects{
"/source1": "/dest1",
"/source2": "/dest2"
}
In vcl_recv, the example checks whether the requested path is a key. A matching request raises error 618 with the response text redirect:
if (table.contains(solution_redirects, req.url.path)) {
error 618 "redirect";
}
Fastly's table reference describes table.contains as a presence check and table.lookup as a lookup for a string value. The example therefore separates the match from the redirect response, while using the same path key for both operations.
How is the redirect response assembled?
In vcl_error, the same Fiddle handles only the internal marker it created. It changes the response status to 308, then builds Location from https://, the request host, the looked-up destination, and the original query string when req.url.qs has a nonzero length:
if (obj.status == 618 && obj.response == "redirect") {
set obj.status = 308;
set obj.http.Location = "https://" + req.http.host + table.lookup(solution_redirects, req.url.path) + if (std.strlen(req.url.qs) > 0, "?" req.url.qs, "");
return (deliver);
}
The path lookup excludes the query string because it uses req.url.path. The conditional suffix adds ? followed by req.url.qs only when the query string is present. A path absent from the map does not enter this branch, so the request continues through the service's ordinary handling.
How can the map be maintained after installation?
Fastly's Dictionary API reference defines a dictionary as a VCL data table containing key-value pairs accessible during request processing. A new empty dictionary is attached to a draft service version and that version must be activated before the dictionary is included in VCL. After installation, Fastly documents API updates to dictionary items without activation of a new service configuration version.
The Dictionary item reference identifies a dictionary item as one key-value pair. Its documented API includes PUT to insert or update an item, PATCH to update one, DELETE to remove one, and PATCH on the items collection to update multiple entries:
PUT/service/service_id/dictionary/dictionary_id/item/dictionary_item_key
PATCH/service/service_id/dictionary/dictionary_id/item/dictionary_item_key
DELETE/service/service_id/dictionary/dictionary_id/item/dictionary_item_key
PATCH/service/service_id/dictionary/dictionary_id/items
The VCL map in the example is therefore the lookup shape: path keys identify old URLs and string values provide destinations. The installed dictionary is the maintenance layer for changing those key-value entries through the documented API.
FAQ
Which request value should be the redirect map key?
The Fastly Fiddle uses req.url.path with table.contains and table.lookup, so the documented map keys are URL paths such as /source1.
Which status does the example return?
The example changes the internal 618 marker to HTTP status 308 before delivering the response.
Are query strings included in the lookup key?
No. The lookup uses req.url.path. When req.url.qs is nonempty, the example appends it to the destination in the Location header.
Does changing a dictionary item require a new service activation?
After the dictionary is installed, Fastly's Dictionary API reference documents item updates through API calls without activating a new service configuration version.
Sources
- Fastly Documentation, "Redirect old URLs at the edge", undated
- Fastly Fiddle, "Redirects", undated
- Fastly Documentation, "Table", undated
- Fastly Documentation, "Dictionary", undated
- Fastly Documentation, "Dictionary item", undated
Check how a page reads to answer engines. Open the GEO score analyzer