Hi Steve,
Thanks for asking.
The RESTXQ cache was introduced to avoid parsing the local directories for XQuery modules with each single HTTP request. As you have already observed, parsing can be disabled completely on productive environments by setting PARSERESTXQ to -1, and rest:init() can be called to invalidate the internal module cache.
However, the RESTXQ function itself will be compiled and evaluated every time it’s invoked by a request. You will always get the current contents of a database, regardless of how much caching takes place. In short, no data will be cached, only code.
In many use cases, it makes no difference how often the local directories are parsed for RESTXQ modules. It can be relevant, though, if numerous HTTP requests per second need to be processed, or if you have fairly complex RESTXQ applications with hundreds of endpoints.
Talking about the new module, we noticed that the name was both restrictive and misleading, as caching usually implies that no action is required to speed up operations, and that contents are dropped whenever a system is restarted. But it can indeed be used to speed up the evaluation of repeated requests if you know that computation is expensive and that the underlying data doesn’t change. store:get-or-put can be helpful here (which was inspired by Java’s computeIfAbsent function). The function to compute the result will only be invoked if the store does not contain the requested value:
store:get-or-put('max-price', function() { max(db:open('huge')//items/@price) })
Hope this helps, Christian