Bureaucrats, editor, reviewer, Administrators
13,551
edits
Changes
Jump to navigation
Jump to search
declare %restjobs:POSTschedule("{$query}1+3", () %rest:path(, map { '/schedule-querycache') function local:scheduletrue($query) { jobs:schedule($query})};
→jobs:schedule
|-
| '''Summary'''
|Schedules the execution of the supplied {{Code|$query}} and returns a query id. The query will be queued, and the result will optionally be cached. Queries may be updating. Variables and context items can be declared via {{Code|$bindings}} (see [[XQuery Module#xquery:eval|xquery:eval]] for more details). The {{Code|$options}} parameter contains schedules scheduling options:
* {{Code|cache}}: indicates if the query result will be cached or ignored (default: <code>false</code>):
** The result will be cached in main-memory until it is fetched via [[#jobs:result|jobs:result]], or until {{Option|CACHETIMEOUT}} is exceeded.
** If the query raises an error, it will be cached and returned instead.** If the result will not be cached, the query id will immediately be discarded after query execution.
* {{Code|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: <code>P1D</code> (1 day), <code>PT5M</code> (5 minutes), <code>PT0.1S</code> (100 ms). An error will be raised if a negative value is specified.
** If a time is specified, the query will be queued executed at this timeof the day. Examples for valid times are: <code>02:00:00</code> (2am), <code>12:00:00</code> (noon). If the time lies in the past, the query will be executed next day.** If a dateTime is specified, the query will be queued executed at this date. Examples for valid values are: <code>2018-12-31T23:59:59</code> (New Year's Eve 2018, close to midnight). An error will be raised if the specified time lies in the past.
* {{Code|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 (<code>PT1S</code>). If the next scheduled call is due, and if a query with the same id is still running, it will be skipped.
* {{Code|base-uri}}: set the [https://www.w3.org/TR/xquery-31/#dt-static-base-uri base-uri property] for the query. This URI will be used when resolving relative URIs by functions , such as with {{Code|fn:doc}} (default: ''empty string'').
|-
| '''Errors'''
|{{Error|overflow|#Errors}} Too Query execution is rejected, because too many queries or query results jobs are queuedor being executed. {{Option|CACHETIMEOUT}} can be decreased if the default setting is too restrictive.<br/>{{Error|range|#Errors}} A specified time or duration is out of range.
|-
| '''Examples'''
|
* {{Code|jobs:schedule("1+3", (), map { 'cache': true() })}} returns a Cache query result. An idwill be returned, e.g. {{Code|Job-123}}. The result which can be retrieved used to pick up the result via a second query in the same BaseX context[[#jobs: {{Coderesult|jobs:result("Job-123")}}<br />* The following [[RESTXQ]] function will return the id of the query thread, which evaluates the query that has been specified in the body of a POST request):
<pre class='brush:xquery'>
</pre>
* A maintenance function happy birthday mail will be called sent at 2am every daythe given date:
<pre class="brush:xquery">
jobs:schedule("import module namespace mmail='maintainmail'; mmail:cleanupsend('Happy birthday!')", (), map { 'start': '022018-09-01T06:00:00', 'interval': 'P1D' })}}
</pre>
* Query execution is scheduled for every second. As the query itself will take 1.5 seconds, it will only be executed every second time:
<pre class="brush:xquery">
jobs:schedule("prof:sleep(1500)", (), map { 'interval': 'PT1S' })
</pre>
* The following [[RESTXQ]] functions can be called to execute a specified query at 2am every day. An id will be returned, which can be used to stop the scheduler again:
<pre class='brush:xquery'>
declare %rest:POST("{$query}") %rest:path('/start-scheduling') function local:start($query) {
jobs:schedule($query, (), map { 'start': '02:00:00', 'interval': 'P1D' })
};
declare %rest:path('/stop-scheduling/{$id}') function local:stop($id) {
jobs:stop($id)
};
</pre>
|}
