Help:Wikifunctions/Provenance metadata and result freshening

This page explains the content of the Provenance section of the function-call result Details dialog, including cache-usage reporting and the result-freshening (Run with latest data) capability.

Background and Motivation

A cache is a temporary storage place for results that have been previously computed, or data that's been retrieved from some source. Caches are designed and located so they can be accessed very quickly. In Wikifunctions, there are two types of caching discussed here: caching of entire results from previous function-calls, and caching of entities fetched from Wikidata.

Why caching?

Wikifunctions, like most Websites showing results that involve substantial processing to produce, relies heavily on caching to improve responsiveness and lessen the consumption of computing and networking resources.

For example, running a particular function Z1234, with particular inputs Z1234K1 and Z1234K2, might take several seconds, in the case of a complex function. However, if the same function has already been run recently, with the exact same inputs, and the result of that previous run has been cached, the cached result can be retrieved in milliseconds.
Similarly, if a function-call requires fetching several entities from Wikidata, those fetches might take a second or more, depending on the sizes of the entities, but if they have been recently cached, they can be retrieved in milliseconds.

What's the downside of caching?

Unfortunately, the use of cached results and entities sometimes causes the presentation of stale results. A stale result is one which is not completely up-to-date with recent changes made to ZObjects or Wikidata entities used in the generation of the result. Stale results can be a significant hindrance to the development and maintenance of Wikifunctions functions.

For example, if you are developing a new function to generate text for Abstract Wikipedia articles, you may find that a Wikidata item or lexeme required by your function needs to be created or extended. If you make that change in Wikidata, and return to testing your new function, the use of caching might prevent you from seeing the benefit of your change right away.

And the solution?

The solution is in 2 parts:

reporting cache-usage along with the result (in the Details dialog that accompanies each result), and
allowing for rerunning a possibly-stale function without any cache usage, so as to guarantee a completely fresh result.

Cache-usage reporting

The use of cached data in producing a function-call result is indicated in the Provenance section of the Details dialog, which is available under the result after running a function.

If cached data has been used, the Provenance section's English summary will be This response was retrieved from the cache. In this case, the Provenance section can be opened to reveal additional details:

A bullet like

Cached function call: 17 hours ago

indicates that the same function-call was run, and its result cached, 17 hours ago. In such cases, the entire result has been retrieved from a cache.

A bullet like

Cached Wikidata entities: Q2028564, Q199

indicates that those Wikidata entities, involved in generating the result, were retrieved from a cache.

If no cached data has been used, the Provenance section's English summary will be This response was not retrieved from the cache.

We emphasize that the use of cached data does not, by itself, indicate that the result is stale with respect to the data sources; it only indicates the possibility that the result may be stale. In fact, most of the time cached data is up-to-date with respect to the data sources.

Limitations

When reporting retrieval of a Wikidata entity from a cache, we are unable at present to show the date/time at which the entity was cached.

Result-freshening (Run with latest data)

When a function-call result, or Wikidata entities used in a result, have been retrieved from a cache, and there is reason to believe the result is not completely fresh, it may be useful to rerun the function without the use of any caches. For this purpose, Wikifunctions provides the Run with latest data button, in the Provenance section. This button appears there when cached content has been used in the result.

Note: It currently appears for function calls invoked in the UI, but not for test results. There are plans to add it to test results.

What it does: When this button is pressed, the Details dialog disappears and the function-call is immediately rerun without retrieving any content from caches. The function-call result is regenerated from scratch, and any required Wikidata entities are re-fetched from Wikidata, so the result is guaranteed to be completely fresh. Caches are then updated with the re-fetched and regenerated content, so the latest content will be available for subsequent function calls.
Permissions group requirement: Because it's important to avoid overuse of this capability, the button is only made available to logged in users, in the autoconfirmed group or above.
Rate limiting: For the same reason, it's also necessary to limit the frequency of use per user. Currently, users in the autoconfirmed group can use it 2 times per minute; those in functioneer can use it 5 times per minute.

Important: Please use this button sparingly, to help minimize its impact on network and computing resources! It is meant to be used when you know, or suspect, that a ZObject or Wikidata entity relevant to the result has changed recently, and you believe that change may produce a different result.

Additional (more technical) information about caching for Wikifunctions and Abstract Wikipedia can be found at [1].