Query String Caching Rules
Last update：2026-04-28 11:21:37
When users request contents from your website, they might include special parameters in the URL after a question mark to achieve the desired logic, e.g., http://domain/1.jpg?version=1. By default, the CDNetworks CDN platform caches the entire URL request at CDN servers, meaning different parameter values in the query strings will result in multiple cached copies of the contents. The URL requested by the user must fully match the cached URL to hit the cache at the CDN servers.
When there are many parameters in the query string, it can increase the number of cached files at the CDN servers, potentially decreasing the cache hit rate. This can lead to more requests back to your origin server, increasing response latency to user requests, ultimately impacting user experience and the load on your origin server as well as your operational costs.
If users requesting contents from your website use URLs where the path before the question mark is the same but the parameters after the question mark differ, and your website returns the same file to the user, it is recommended to configure the CDN platform to ignore the parameters after the question mark for caching purposes. This will improve the cache hit rate at the CDN servers, ensuring a better user experience and reducing the load and costs on your origin server.
How to Configure Query String Caching Rules
- Log in to the CDNetworks Console and select the appropriate product.
- Navigate to the Configuration, locate the domain you wish to configure, and click on Edit Configuration at the top or the Edit button to the right of the domain
. - Enter the configuration modification page, find the Query String under Cache Optimization, and click the Add button;
- On the rule editing page, you can easily add the following configuration options based on your needs.
Apply to
CDNetworks CDN platform provides the following options for the rule’s applicable scope, and you can specify what requests that the rule will apply to.
| Parameter | Description |
|---|---|
| All Requests | Indicates that all requests initiated to the associated domain are applicable to this rule. |
| Specific File Type | This rule applies to the requests for specified file types, you can choose from listed ones or customize your file types in this field. Separate multiple file types with ;, e.g., ace;aac. |
| Specific URL Path | You can set the rule for specific URI requests. Only one specified URI can be configured per rule; Note that the URIs you enter do not include http:// or https://, only configure the URI part, e.g., the complete URL is https://domain/browse/index.html, you only need to configure /browse/index.html, and specially, it cannot include query string. |
| Specific Directory | This rule applies to all requests aimed at specified directories while directories must begin and end with a / and can be composed of any combination of letters, numbers, and certain special symbols (including underscores, hyphens, percentage signs, and dots), e.g., /file/1%1/, indicates that the rule applies to requests for the directory http://domain/file/1%1/ and all files within it. Please note that, you need to separate multiple directories with a line break. |
| URL Pattern (Regex) | You can also choose to directly enter a regular expression, not required to start with /. The platform will automatically prefix the URL with ^https?://[^/]/, e.g., .*.jpg$, indicating that requests for JPG files across all domains associated with this rule will match this policy. |
Query String Caching
After configuring the Apply to, you can configure whether the query string in the URL should be part of the CDN servers’ caching and response criteria. The CDNetworks CDN platform provides three options:
-
Ignore Query String- Cache Without Query String Parameters
This option ignores the query string in the request URL. Even if the parameters in the query strings differ, CDN servers will only cache the URL before the question mark. Different parameters after the question mark in the user-requested URL will hit the same cached file at the CDN servers;
Additionally, you can also configure whether to ignore the query string when CDN servers have no cached file and need to fetch contents from the origin server. Like the previous setting for user requests to CDN servers, if you select Yes here, the request URL from the CDN servers back to the origin server will ignore the query string. Conversely, if you select No, the CDN server will send the request to the origin server with the query string.
-
Cache on Full Query String- Cache With All Query String Parameters
This option does not ignore the query string in the request URL. The entire URL, including all query string parameters, will be used as criteria for CDN caching. If any parameter value of query string in the URL changes, the CDN servers will cache a separate file. User requests with different query string parameters will hit different cached files at the CDN servers. When CDN servers need to fetch the file from the origin server, it will retain all the query string parameters in the request URL.
-
Cache on Specific Parameters - Cache With Selected Query String Parameters
Similar to the previous option, this one does not ignore the query string in the request URL when caching and responding to user requests. However, you can customize which parameters of the query string will be used as caching and response criteria. Only when the specified parameters’ values differ will the CDN servers have separate cache objects and respond to specific user requests with the corresponding cache entity.
And in Parameter Caching Options section, you can choose to Include Specific Parameters, using some query string parameters as caching criteria, or Exclude Specific Parameters, excluding some parameters and only keeping others as caching criteria. You can define multiple parameters, separated by semicolons, e.g.,
name;year.Additionally, you can also define whether to retain the query string parameters in the request URL when fetching the contents from the origin server, including Forward Full Query String, Include Specific Parameters, or Exclude Specific Parameters in Origin Parameter Options field. The meanings of these options are consistent with those mentioned earlier. If you enter
-when configuring Exclude Specific Parameters, it means the request URL to the origin server will not include any parameters. You can define multiple parameters, separated by semicolons.
Case-Insensitive Match
The default value of this field is Yes.
- In this field, if you select Yes, it will ignore case sensitivity for your defined rule in the Apply to, meaning two request URLs differing only in letter case of the field you defined in Apply to will match the same rule. For example, if you configure
http://domain/a.jpg?version=1to ignore query string for caching, thenhttp://domain/A.jpg?version=1will also be effective. - Conversely, if you select No, meaning case sensitivity in the Apply to is not ignored, it will strictly follow the settings in the Apply to configuration to match user requests, only caching files at the CDN edge servers according to the rule for URLs that meet the case configured.
Priority
In the Priority field, you could specify the priority level of this rule. Based on the user’s request, the system matches the rules you have configured. If multiple rules apply, the rule with the higher priority will be applied first.
After you have completed setting the configurations, please click OK and then select Next to submit your settings. To minimize any potential disruptions to your production environment, we strongly recommend conducting a Pre-deploy test in a staging environment. This crucial step ensures that your configurations are accurate before they go live. Once you have verified the accuracy of the settings, click Deploy Now to implement them in the live environment. The configurations typically become effective within 3-5 minutes. For comprehensive guidance on pre-deployment testing and to verify the effectiveness of your configurations, please consult the tutorial Deploy the Configurations to Staging Environment for Validation.
Best Practices
Example 1: Ignore Query String - Cache Without Query String and Ignore Query String When Fetching from Origin
In the rule configuration shown below, query string parameters in the URL are not used as caching criteria. As long as the path before the question mark in the request URL is the same, there will be only one cache object on CDN platform, meaning all requests for the domain associated with this rule will ignore the query string for caching or fetching the file from the origin. When a user accesses http://domain/a.jpg?version=1, if there is no cache hit at the CDN side, the CDN servers will fetch the file from http://domain/a.jpg and cache it on the CDN servers. The next time the user requests the URL http://domain/a.jpg?version=2, it will directly hit the cache at the CDN side.
Example 2: Cache on Full Query String - Cache With All Query String Parameters
In the rule configuration shown below, when the user requests files of type jpg, all query string parameters in the URL will be used as caching criteria. If any parameter value in the query string is different, a separate cache entity will be cached at the CDN side. When there is no cache hit at the CDN, the complete request URL will be used to fetch the file from the origin. When a user accesses http://domain/1.jpg?version=1&name=john, if there is no cache hit at the CDN, the CDN servers will fetch the file from http://domain/1.jpg?version=1&name=john and cache it at the platform. The next time the user requests the URL http://domain/1.jpg?version=1&name=john, it will directly hit the cache at the CDN. If the next user request URL is http://domain/1.jpg?version=2&name=john, it will not hit the cache.
Example 3: Cache on Specific Parameters - Include Specific Parameters
In the rule configuration shown below, when the user requests a URL in the /directory/ directory, the parameter name in the query string will be used as a caching criteria. If the value of the name parameter in the query string is different, a separate cache entity will be cached at the CDN side. When there is no cache hit at the CDN, the complete request URL will be used to fetch the file from the origin. When a user accesses http://domain/1.jpg?version=1&name=john&year=1991, if there is no cache hit at the CDN, the CDN servers will fetch the file http://domain/1.jpg?version=1&name=john&year=1991 from origin and cache it on the platform. The next time the user requests the URL http://domain/1.jpg?version=2&name=john&year=1991, it will directly hit the cache at the CDN. If the next user request URL is http://domain/1.jpg?version=1&name=sam&year=1991, it will not hit the cache.
Example 4: Cache on Specific Parameters - Exclude Specific Parameters
In the rule configuration shown below, when the user requests a URL with the URL path /query/1.jpg , the parameter version in the query string will not be used as a caching criterion. If only the version parameter value in the query string is different, the file will be cached as the same object on CDN servers. If the name or year parameter values are different, a separate object will be cached on CDN servers. When there is no cache hit at the CDN, the complete request URL will be used to fetch the file from the origin. When a user accesses http://domain/query/1.jpg?version=1&name=john&year=1991, if there is no cache hit at the CDN, the CDN servers will fetch the file http://domain/query/1.jpg?version=1&name=john&year=1991 from origin and cache it at the CDN. The next time the user requests the URL http://domain/query/1.jpg?version=2&name=john&year=1991, it will directly hit the cache at the CDN. If the next user request URL is http://domain/query/1.jpg?version=1&name=sam&year=1991, it will not hit the cache.
Notes
If you configure not to ignore all query string parameters for caching, a separate object will be cached on CDN servers for any different query string parameter value. This can affect the cache hit rate of user requests on CDN platform and increase number of requests to the origin server, leading to more origin access for your website. Therefore, if it is not necessary for your business to use all query string parameters as caching conditions, it is recommended to ignore the query string parameters for caching or use only some parameters as caching conditions.