Caching
Caching is an important concept when authoring and running crul queries. The cache is where results of a query, stage, and a command are stored. These results are kept in the cache for a period of time and are reused for future queries/stages/commands when possible.
The crul query processor has built in query, stage, and command level caching. Let's explore these concepts further and how they impact our usage of crul.
Query Cache​
The query cache is the most simple to understand, if you run the exact same query multiple times, the query processor will return results from the cache of the last successful run of the query. It will not rerun the stages and commands of the query.
Example​
devices
|| contains name "iPhone"
|| sort name
Running this query will run the devices command, which will return a list of available devices to use to access web connect. Then search for device names which contains the keyword iPhone, then sort the results. If this exact query is run again, the results will be pulled directly from the cache.
Stage Cache​
The stage cache is fairly similar to the query cache, but operates on stages. For a simple example of how the stage cache operates, let's use the same query as before.
Example​
devices
|| contains name "iPhone"
|| sort name
Running this query will run the devices command, which will return a list of available devices to use to access web connect. Then search for device names which contains the keyword iPhone, then sort the results.
If we add an additional stage to this query, the query will no longer be the same, so the query cache will not be used, however, the first 3 stages have already run, and their results are in the cache, so if we add a new stage, we will use the stage cache for the first 3 stages, then run the new fourth stage on those cached results.
devices /* cache HIT - read cached results */
|| contains name "iPhone" /* cache HIT - read cached results */
|| sort name /* cache HIT - read cached results */
|| filter "viewport.width == 400" /* cache MISS - run stage */
Command Cache​
The command cache comes from the concept of stages that are composed of multiple commands. See expanding stages for an example. In a multi command stage, each command's results will be cached.
Cache Time to Live (TTL)​
The cache for a query will be refreshed while the query is either running, or open in the UI query page. If you dispatch a new query, or navigate to a different page in the crul UI, the query will be forgotten in ~30 seconds (configurable), once the query has been forgotten, the cache will be considered stale and will be forgotten in ~1 minute (configurable).
Overriding the Cache​
All caches (query, stage, and command) can be overridden by adding a --cache false flag to any stage. This tells the query processor to skip checking the cache for the entire query, the stage containing the flag, and the command(s) in that stage.
Example​
api get https://... --cache false
Every time this query is run, we will make a new GET request to https://.... This is because of the --cache false flag. If this flag is removed, the query/stage/command will check the cache and use cached results when possible.
Non-caching Commands​
Some commands will never get results from the cache, queries containing non-caching commands will always bypass the query cache, as well as the stage and command cache for the stage/command containing the non-caching command.
Example​
devices
|| timestamp /* non-caching command */
The second stage in this query containing the non-caching timestamp command, so the stage will always run, even if there is a matching cache entry for the stage/command. If this query is run again, stage 1 containing the devices command will read from the stage cache