Summary
|
Schedules the evaluation a new query job for the supplied $query (of type xs:string , or of type xs:anyURI if points to a resource), and returns a job ID. The job will be queued until a free slot is available, and the query result can be cached. Queries can be updating, and variables and the context value can be declared via $bindings (see xquery:eval for more details). The following $options can be supplied:
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
job:result , or until CACHETIMEOUT is exceeded.
- If the query raises an error, it will be cached and returned instead.
start : a dayTimeDuration, time, dateTime or integer 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 of 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 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.
- If a time is specified, the query will be executed at this time of the day. Examples of 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.
- An integer will be interpreted as minutes. If the specified number is greater than the elapsed minutes of the current hour, the query will be executed one hour later.
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.
service : additionally registers the job as service. Registered services must have no variable bindings.
log : writes the specified string to the database logs. Two log entries are stored, one at the beginning and another one after the execution of the job.
|
Examples
|
- Cache query result. The returned ID can be used to pick up the result with
job:result :
job:eval("1+3", (), map { 'cache': true() })
- A happy birthday mail will be sent at the given date:
job: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) {
job:eval($query, (), map { 'start': '02:00:00', 'interval': 'P1D' })
};
declare %rest:path('/stop-scheduling/{$id}') function local:stop($id) {
job:remove($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:
job:eval("prof:sleep(1500)", (), map { 'interval': 'PT1S', 'end': 'PT10S' })
- The query in the specified file will be evaluated once:
job:eval(xs:anyURI('cleanup.xq'))
- The following expression, if stored in a file, will be evaluated every 5 seconds:
job:eval(
static-base-uri(),
map { },
map { 'start': 'PT5S' }
)
|