Summary
|
Schedules the evaluation of the supplied $query and returns a query id. The query will be queued, and the result will optionally be cached. Queries can be updating. Variables and context items can be declared via $bindings (see xquery:eval for more details). The $options parameter contains scheduling options:
cache : indicates if the query result will be cached or ignored (default: false ):
- The result will be cached in main-memory until it is fetched via jobs:result, or until
CACHETIMEOUT is exceeded.
- If the query raises an error, it will be cached and returned instead.
start : a dayTimeDuration, time or dateTime can be specified to delay the execution of the query:
- If a dayTimeDuration is specified, the query will be queued after the specified duration has passed. Examples for valid values are:
P1D (1 day), PT5M (5 minutes), PT0.1S (100 ms). An error will be raised if a negative value is specified.
- If a time is specified, the query will be executed at this time of the day. Examples for valid times are:
02:00:00 (2am local time), 12:00:00Z (noon, UTC). If the time lies in the past, the query will be executed the next day.
- If a dateTime is specified, the query will be executed at this date. Examples for valid values are:
2018-12-31T23:59:59 (New Year's Eve 2018, close to midnight). An error will be raised if the specified time lies in the past.
interval : a dayTimeDuration string can be specified to execute the query periodically. An error is raised if the specified interval is less than one second (PT1S ). If the next scheduled call is due, and if a query with the same id is still running, it will be skipped.
end : scheduling can be stopped after a given time or duration. The string format is the same as for start . An error is raised if the resulting end time is smaller than the start time.
base-uri : sets the base-uri property for the query. This URI will be used when resolving relative URIs, such as with fn:doc .
id : sets a custom job id. The id must not start with the standard job prefix, and it can only be assigned if no job with the same name exists.
|
Examples
|
- Cache query result. The returned id can be used to pick up the result with jobs:result:
jobs:eval("1+3", (), map { 'cache': true() })
- A happy birthday mail will be sent at the given date:
jobs:eval("import module namespace mail='mail'; mail:send('Happy birthday!')",
(), map { 'start': '2018-09-01T06:00:00' })}}
- The following RESTXQ functions can be called to execute a query at 2 am every day. An id will be returned by the first function, which can be used to stop the scheduler via the second function:
declare %rest:POST("{$query}") %rest:path('/start-scheduling') function local:start($query) {
jobs:eval($query, (), map { 'start': '02:00:00', 'interval': 'P1D' })
};
declare %rest:path('/stop-scheduling/{$id}') function local:stop($id) {
jobs:stop($id)
};
- Query execution is scheduled for every second, and for 10 seconds in total. As the query itself will take 1.5 seconds, it will only be executed every second time:
jobs:eval("prof:sleep(1500)", (), map { 'interval': 'PT1S', 'end': 'PT10S' })
- The following expression, if stored as a file, calls and evaluates itself every 5 seconds:
jobs:eval(
file:read-text(static-base-uri()),
map { },
map { 'start': 'PT5S' }
)
|