Introduction
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 purging many images that match a provided pattern all at once.
Please note that each Engine maintains its own cache.
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.
Examples:
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?
The Cache Purge interface can be accessed from the control panel’s left-hand menu in an engine's dropdown list:
Or by clicking the 'Purge Cache' option on an engine’s overview:
When opened, the purge interface looks like this:
Purge process
To start a purge,
- Enter an Expression defining the desired image(s).
- As an optional step, click the box next to the Expression box to open a path validation modal:
- As an optional step, click the box next to the Expression box to open a path validation modal:
- Click "Submit Purge Request" 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: The purge execution time is impacted by the number of purge requests in the queue. DO NOT execute duplicate purges in rapid succession.
Expression Usage
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
/media/this/path/images/12345.jpg
would purge all image variants (size and format) of the same name
/media/this/path/images/12345.jpg
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.
Examples:
To purge all PNG files under `/images`, non-recursive.
(Files under `/images/today/`, for example, will not be purged.)
/images/*.png
Purge an object with a query string:
Because `?` is an operator in the pattern, the `?` must be escaped using the `\` operator:
/images/image.jpeg\?v=2
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 will 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/this/path/images/12345.jpg
and /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.jpg
and /media/this/path/images/12345.png
, you could use: /media/this/path/images/12345.*
To purge all images sharing a name
To purge all copies of a given image, you could use
use /**/2431122043.png
. To do the same but for any file type, /**/2431122043.*
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:
Operator | Description |
---|---|
* |
Match any number of characters in a single section of the path e.g. /foo/*.jpg will match /foo/test.jpg but not /foo/bar/test.jpg |
** |
Match any character, any number of times, recursively e.g. /foo/**.jpg will match both /foo/test.jpg and /foo/bar/test.jpg |
[...] |
Match any character out of a set of characters e.g. /foo/img[0-9][0-9].jpg matches /foo/img01.jpg and /foo/img32.jpg |
? |
Match the proceeding character or range zero or one time e.g. /foo/img\?.jpg matches both /foo/img.jpg and /foo/imgA.jpg e.g. /foo/img[0-9]?.jpg matches both /foo/img.jpg and /foo/img1.jpg |
{a,b,...} |
Match any of the patterns a or b or ... e.g. /foo/img.{jpg,png,jpeg} matches /foo/img.jpg , /foo/img.png , and /foo/img.jpeg |
\ |
Escape the special character e.g. /foo/img.jpg\?thumbnail=true literally matches /foo/img.jpg?thumbnail=true , as opposed to /foo/img.jpgthumbnail=true |
Pattern examples
Pattern | Description |
---|---|
**/* |
All files in all directories, recursively |
**/*.jpg |
All files in all directories, recursively, ending in .jpg |
/files/* |
All files in the "files" directory |
/files/*.jpg |
All files in the "files" or "other" directory ending in .jpg |
/{files,other}/*.jpg |
All files in all directories, recursively |
/files/[a-zA-Z0-9].jpg |
Files in the "files" directory ending in .jpg where the filename is a single alphanumeric character, case-insensitive |
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.
EXPRESSION: *
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.
EXPRESSION: /media//*
Using a double // anywhere in the pattern is incorrect and will result in an error
An 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 note that ImageEngine cannot control whether a visitor has an old file saved in their browser's cache, as no one can programmatically erase a visitor's cache. This potential issue can be avoided by using image versioning, as discussed in the introduction of this article.
Please get in touch with us at support@imageengine.com if you are experiencing any issues after attempting a purge. We will be happy to assist you in determining the issue.
Comments
0 comments
Please sign in to leave a comment.