There are two cache types: adhoc and scheduled.
The adhoc cache triggers its update when the next request comes in after cache has expired.
The scheduled cache triggers its update based on its own schedule, regardless of activity.
Cache configuration is passed via query string parameter cache, for example:
cache=ttl:3600@max_ttl:7200@idle_timeout:86400@wake:sync@disk@interval:1200@@update_time:1h00m-9h00m@update_days:mon,tue,wed,thu,fri
Scheduled cache is used when option @interval:nnn is present and its value is greater than 0.
In the example above, cache is configured with expiration time of 3600 seconds. Cache update will be attempted every 1200 seconds. Not every cache update attempt will result in SQL query execution and updating cache data. Cache update process checks first if cache has expired. If cache did not yet expire, cache update process will not proceed with execution of SQL query. If cache has expired, the cache update process checks permitted days and time to run the update. In the example above, cache update process will be executing SQL query for expired cache only between 1am and 9am (UTC) during business days, excluding weekends.
Cache may be served only if it is not expired or is within its grace period, defined by option @max_ttl (7200 seconds in this example).
Expired cache outside of grace period cannot be served, unless option @old is used (this option is not used in the example above).
Option @wake:sync allows first time cache creation when scheduled cache update process did not yet run (for example, because it is outside of permitted days/time). This will initialize cache instance, but will make the requestor to wait for the query to complete before getting results. Option @disk creates a disk copy of the cache instance metadata and data, which is used as a backup to automatically restore the cache instance state, including its schedule, when the system is restarted.
With option @idle_timeout:86400, cache is evicted if there are no requests within 86400 seconds since the last request.