Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
Jobs A job can additionally be registered as persistent services. An additional ''service'' by supplying the {{Code|service}} option has been added to the options list of {{Function|Jobs|jobs:eval}} and {{Function|Jobs|jobs:invoke}}:
{{Mark|Updated with Version 9.1:}} registration time added
Asynchronous query execution is recommendable if There are cases in which a client does not, or cannot, wait until a request is fully processed. This is e. g. the case with web browsersThe client may be a browser, which will usually cancel a sends an HTTP request after a specific timeout. In such cases, you can use asynchronous execution to trigger another the server-side process, which will in order to start the another time-consuming processquery job. The functions in this section allow you to register a new query job from a running query. Jobs can be executed immediately (i.e., and fetch the result later on as soon as the [[Transaction Management#Concurrency Control|Concurrency Control]] allows it is available) or scheduled for repeated execution. Each registered job gets a job id, and the id can be used to retrieve a query result, stop a job, or wait for its termination.
file:read-text(static-base-uri()),
</pre>
|}
==jobs:invoke==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|jobs:invoke|$uri as xs:string|xs:string}}<br />{{Func|jobs:invoke|$uri as xs:string, $bindings as map(*)?|xs:string}}<br />{{Func|jobs:invoke|$uri as xs:string, $bindings as map(*)?, $options as map(*)?|xs:string}}<br />
|-
| '''Summary'''
|Schedules the evaluation of the XQuery expression located at {{Code|$uri}} and returns a query id. For further details, see [[#jobs:eval|jobs:eval]].
|-
| '''Errors'''
|{{Error|overflow|#Errors}} Query execution is rejected, because too many jobs are queued or 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.<br/>{{Error|id|#Errors}} The specified id is invalid or has already been assigned.<br/>{{Error|options|#Errors}} The specified options are conflicting.
|-
| '''Examples'''
| Run XQuery expression that may perform some cleanups:
<pre class='brush:xquery'>
jobs:invoke("cleanup.xq", (), ())
Please note that queries Queries of this kind can cause deadlocks. For example, if both ! If the original query and the new query to be executed asynchronously perform updates on the same database, the second query would will only be run after the first one has been executed, and the first query will wait for the second query forever. This is why you You should avoid this pattern in practice and resort to [[XQuery Module#xquery:fork-join|xquery:fork-join]] if you want to do things in have full control on parallelquery execution.
→jobs:eval
=Services=
<pre class="brush:xquery">
(: register job, which as service; will be run every day at 1 am :)
jobs:eval('db:drop("tmp")', (), map { 'id':'cleanup', 'start':'01:00:00', 'interval':'P1D', 'service': true() }),
'''Some more notes:'''
* All registered jobs job services will be scheduled for evaluation when the BaseX server or BaseX HTTP server is started.
* If a job service is outdated (e.g. because a supplied end time has been exceeded), it will be removed from the jobs file at startup time.
* Job services can be updated: If a new job is registered, and if there is already a job with the same id, the old entry will be replaced.
==jobs:list-details==
{| width='100%'
</pre>
|}
==jobs:finished==
=Execution=
==jobs:eval==
|-
| width='120' | '''Signatures'''
|{{Func|jobs:eval|$query as xs:stringanyAtomicItem|xs:string}}<br />{{Func|jobs:eval|$query as xs:stringanyAtomicItem, $bindings as map(*)?|xs:string}}<br />{{Func|jobs:eval|$query as xs:stringanyAtomicItem, $bindings as map(*)?, $options as map(*)?|xs:string}}<br />
|-
| '''Summary'''
|Schedules the evaluation of the supplied {{Code|$query}} and returns a query id. The query will be queued, and the result will optionally be cached. Queries can be updating. Variables The query can be a URI or a string, and variables and context items can be declared via {{Code|$bindings}} (see [[XQuery Module#xquery:eval|xquery:eval]] for more details). The following {{Code|$options}} can be supplied:
* {{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.
* {{Code|base-uri}}: sets 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, such as with {{Code|fn:doc}}.
* {{Code|id}}: sets a custom job id. The id must not start with the standard <code>job</code> prefix, and it can only be assigned if no job with the same name exists.
* {{Code|service}}: additionally registers the job as [[#Services|service]]. Registered services must have no variable bindings.
|-
| '''Errors'''
jobs:eval("prof:sleep(1500)", (), map { 'interval': 'PT1S', 'end': 'PT10S' })
</pre>
* The query in the specified file will be evaluated once:<pre class='brush:xquery'>jobs:eval(xs:anyURI('cleanup.xq'))</pre>* The following expression, if stored as in a file, calls and evaluates itself will be evaluated every 5 seconds:
<pre class="brush:xquery">
jobs:eval(
map { },
map { 'start': 'PT5S' }
)
</pre>
|}
};
</pre>
* The following query demonstrates how the results of an asynchronously executed query can be returned within the same query(see below why you should avoid this pattern in practice):
<pre class='brush:xquery'>
let $query := jobs:eval('(1 to 10000000)[. = 1]', map{}, map{ 'cache': true() })
return (
jobs:wait($query),
)
</pre>
|}
=Changelog=
;Version 9.2
* Deleted: jobs:invoke (merged with [[#jobs:eval|jobs:eval]])
;Version 9.1
