Sodar Cache Usage¶
Usage instructions for the sodarcache
app are detailed in this document.
NOTE: When viewing this document in GitLab critical content will by default be missing. Please click “display source” if you want to read this in GitLab.
Backend API for Data Caching¶
The API for logging events is located in sodarcache.api
. For the full API
documentation, see here.
Invoking the API¶
The API is accessed through a backend plugin. This means you can write calls to the API without any hard-coded imports and your code should work even if the sodarcache app has not been installed on the site.
Initialize the API using projectroles.plugins.get_backend_api()
as follows:
from projectroles.plugins import get_backend_api
projectcache = get_backend_api('sodar_cache')
if projectcache: # Only proceed if the backend was successfully initialized
pass
Setting and getting Cache Items¶
Once you can access the sodarcache backend, you should set up the
update_cache()
function in the ProjectAppPlugin
of the app with which
you want to cache or aggregate data. The update process can be limited by two
parameters: cached item name and project. If neither are specified, the function
should update cached data for all known items within all projects.
def update_cache(self, name=None, project=None):
"""
Update cached data for this app, limitable to item ID and/or project.
:param project: Project object to limit update to (optional)
:param name: Item name to limit update to (string, optional)
"""
# TODO: Implement this in your app plugin
return None
Updating a specific cache item within the update_cache()
function (or
elsewhere) should be done using sodarcache.api.set_cache_item()
. A minimal
example is as follows:
cache_item = projectcache.set_cache_item(
project=project, # Project object
app_name=APP_NAME, # Name of the current app
user=request.user, # The user triggering the cache update
name='some_item', # Cached item ID
data_type='json', # Data type ("json" currently supported)
data={'key': 'val'}, # The actual data that should be cached
)
Note
The item ID in the name
argument is not unique, but it is expected to
be unique together with the project
and app_name
arguments.
Retrieve items with sodarcache.get_cache_item()
or just check the
time the item was last updated with sodarcache.get_update_time()
like
this:
projectcache.get_cache_item(
app_name='yourapp',
name='some_item',
project=project,
data_type='json'
) # Returns a JsonCacheItem
projectcache.get_update_time(
app_name='yourapp',
name='some_item',
project=project
)
It is also possible to retrieve a Queryset with all cached items for a specific
project with sodarcache.get_project_cache()
projectcache.get_project_cache(
project=project, # Project object
data_type='json' # must be 'json' for JsonCacheItem
)
Using the Management commands¶
To create or update the data cache for all apps and projects, you can use a management command.
$ ./manage.py synccache
To limit the sync to a specific project, you can provide the -p
or
--project
argument with the project UUID.
$ ./manage.py synccache -p e9701604-4ccc-426c-a67c-864c15aff6e2
Similarly, there is a command to delete all cached data:
$ ./manage.py deletecache