Why purge images?
ImageEngine retains an image in its cache for the length of time specified by the image's Time-To-Live (TTL). When the TTL expires, ImageEngine will refresh the image from the origin. Users can modify the TTL by Customizing An Engine's Settings. Users can also purge an image to immediately force a refresh. We provide an interface that allows purging a single image or many images all at once.
Why you might not want to purge images
Especially with time-sensitive items, Image versioning should be used wherever possible instead of relying on purging old versions of images.
For instance, these two URLs will link to the same image name but each is treated as its own instance. Using image versioning ensures that the newest version is pulled from the origin when the change occurs on your site.
Note the new number following the “?v=” sign for the second URL
You do not necessarily need to version at the origin. You may update the image at the origin, and increment their version(s) in the site code that references the image.
How can I purge the cache?
An Engine’s cache purge interface can be accessed from the control panel’s left-hand menu while an Engine is selected
Or by clicking the Purge Cache option on an engine’s overview:
When opened, the purge interface looks like this:
To start a purge,
- Using the drop-down menu locate and select the Delivery Address for your Engine.
- Enter a pattern defining the desired image(s).
- Click "purge" to initiate the process. This will put the cache purge request in ImageEngine’s queue for completion.
- You can check the status of the purge request in the list of purge requests. Please allow a moment for the purge request to be executed in all regions.
Note: ImageEngine’s purge execution time is impacted by the number of purge requests in the queue. DO NOT execute duplicate purges in rapid succession.
ImageEngine uses patterns to identify what images to purge from its cache. A pattern defines a single image or a group of images.
When cache-purging, each request must contain only one pattern (no multiples, no spaces). Images with matching URIs will be removed from the ImageEngine cache.
All cached image variants of the same name will be purged.
For example, purging
would purge all image variants (size and format) of the same name
See below for a full list of pattern values
Any query string parameters on the desired URI may also be specified. If the file name is static, and the query string changes dynamically, make sure to use the patterns described below to target your purge request. For example: `image.jpeg*` will purge all image.jpeg variants regardless of any query string.
To purge all PNG files under `/images`, non-recursive.
(Files under `/images/today/`, for example, will not be purged.)
Purge an object with a query string:
Because `?` is an operator in the pattern, the `?` must be escaped using the `\` operator:
The above will match `/images/image.jpeg?v=2`.
To purge everything, recursively:
Warning!: Invalidating your entire cache is not advisable. Purging everything all at once may result in performance degradation temporarily as images are being re-cached. To avoid this, only purge subsections at a time.
To purge images from two different locations but with the same name
For the image "12345.jpg", present in two locations,
/media/that/path/images/12345.jpg, you could use:
/media/**/path/images/12345.jpg. To purge both files.
To purge images with the same name but different file types
Given two files with the same name, but different formats, such as
/media/this/path/images/12345.png, you could use:
To purge all images sharing a name
To purge all copies of a given image, you could use
/**/2431122043.png. To do the same but for any file type,
Sample use case:
Replacing a single image
- A new image has been uploaded, at foo.com/media/brands/example.jpg. The content is being served through ImageEngine using the delivery address "images.foo.com"
- A cache purge is performed using "/media/brands/example.jpg", making sure to select the correct delivery address (images.foo.com as mentioned above). The purge is then started
- A short time afterward executing the purge, the old example.jpg image has been removed and the new image is beginning to be cached.
Note: If replacing all images under the "brands folder" was desired, the pattern "/media/brands/**/*" may have been used instead to purge all of the images present there in one action.
Full list of Pattern operators and examples
ImageEngine will use patterns in an expression to identify which images will be purged. ImageEngine will attempt to match the image path and file name relative to the pattern provided in the purge interface.
A number of operators are supported:
||Match any number of characters in a single section of the path e.g.
||Match any character, any number of times, recursively e.g.
||Match any character out of a set of characters e.g.
||Match the proceeding character or range zero or one time e.g.
||Match any of the patterns a or b or ... e.g.
||Escape the special character e.g.
||All files in all directories, recursively|
||All files in all directories, recursively, ending in
||All files in the "files" directory|
||All files in the "files" or "other" directory ending in
||All files in all directories, recursively|
||Files in the "files" directory ending in
Possible issues in usage
Incorrect Pattern definition
The following is a selection of potential errors that might be made while attempting to execute a purge. In all the following cases, the path provided would not purge the requested image.
While valid, the * pattern will only cover images at the root (e.g. https://foo.com/img.jpg and not https://Foo.com/imgs/img.jpg)
Use /**/* instead, if purging the entire cache is desired.
Using a double // anywhere in the pattern is incorrect and will result in an error
Old image still being served after the purge
- Check whether the pattern being used is valid for the image
- Some other caches may still have the image cached. For example, some CMS systems retain their own image cache and may need to be cleared before ImageEngine has access to the new image. In such a case, you will need to clear the cache outside of ImageEngine
Please get in touch with us at firstname.lastname@example.org if you are experiencing any issues after attempting a purge. We will be happy to assist you in determining the issue.