|
|
Line 1: |
Line 1: |
− | This [[Module Library|XQuery Module]] provides functions for organizing running commands and queries (mor to come). | + | This [[Module Library|XQuery Module]] provides functions for organizing running commands and queries (…more to come). |
| | | |
| =Conventions= | | =Conventions= |
Revision as of 11:47, 26 June 2016
This XQuery Module provides functions for organizing running commands and queries (…more to come).
Conventions
All functions in this module are assigned to the http://basex.org/modules/jobs
namespace, which is statically bound to the jobs
prefix. Errors will be bound to the same prefix.
Asynchronous Execution
Asynchronous query execution is recommendable if a client does not, or cannot, wait until a request is fully processed. This is e. g. the case with web browsers, which will usually cancel a request after a specific timeout. In such cases, you can use asynchronous execution to trigger another server-side process, which will start the time-consuming process, and fetch the result later on as soon as it is available.
jobs:eval
Signatures
|
jobs:eval($query as xs:string) as xs:string
jobs:eval($query as xs:string, $bindings as map(*)) as xs:string
jobs:eval($query as xs:string, $bindings as map(*), $options as map(xs:string, xs:string)) as xs:string
|
Summary
|
Prepares the supplied $query string for asynchronous execution and returns a query id. The query will be queued as described in the article on Transaction Management, and the result will be cached in main-memory until it is fetched via jobs:result, or until ASYNCTIMEOUT is exceeded. Queries may be updating. Variables and context items can be declared via $bindings (see xquery:eval for more details). The $options parameter contains evaluation options:
cache : indicates if the query result will be cached or ignored (default: true ). If the query result will not be cached, the query id will immediately be discarded after query execution, too.
base-uri : set base-uri property for the query. This URI will be used when resolving relative URIs by functions such as fn:doc (default: empty string).
|
Errors
|
overflow : Too many queries or query results are queued. To fix this, the query results should be retrieved.
|
Examples
|
jobs:eval("1+3") returns a query id, e.g. Query-abc . The result can be retrieved via a second query in the same BaseX context: jobs:result("Query-abc")
- 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:
declare %rest:POST("{$query}") %rest:path('/eval') function local:eval($query) {
jobs:eval($query)
};
|
jobs:result
Signatures
|
jobs:result($id as xs:string) as item()*
|
Summary
|
Returns the result of an asynchronously executed query with the specified query $id :
- Results can only be retrieved once. After retrieval, the cached result will be discarded.
- If the query raised an error, the error will be raised instead.
|
Errors
|
running : the query is still running.
unknown : the supplied query id is unknown: The query result may already have been retrieved, or query execution may have been stopped.
|
Examples
|
- The following RESTXQ function will either return the result of a previously started query or an error:
declare %rest:path('/result/{$id}') function local:result($id) {
jobs:result($id)
};
- The following query demonstrates how the results of an asynchronously executed query can be returned in a single query. Please remember that this is not the common way how these functions are used in practice:
let $query := jobs:eval('(1 to 10000000)[. = 1]')
return (
hof:until(
function($result) { jobs:finished($query) },
function($curr) { prof:sleep(10) },
()
),
jobs:result($query)
)
|
jobs:finished
Signatures
|
jobs:finished($id as xs:string) as xs:boolean
|
Summary
|
Indicates if the evaluation of a query with the specified query $id has finished. If false is returned, the query is still running. An error will be raised if the query result was not cached or has already been retrieved.
|
Errors
|
unknown : the supplied query id is unknown: The query result may already have been retrieved, or query execution may have been stopped.
|
jobs:stop
Signatures
|
jobs:stop($id as xs:string) as empty-sequence()
|
Summary
|
Cancels the execution of a query with the specified query $id , or drops the query result if it has already been executed.
|
Errors
|
unknown : the supplied query id is unknown: The query result may already have been retrieved, or query execution may have been stopped.
|
jobs:ids
Signatures
|
jobs:ids() as xs:string*
|
Summary
|
Returns the ids of all queries that are either being executed asynchronously, or that have been executed and the results of which have been cached.
|
Examples
|
jobs:ids() ! jobs:stop(.) stops and invalidates all asynchronous queries and results.
|
Errors
Code
|
Description
|
unknown
|
The supplied query id is unknown or not available anymore.
|
running
|
A query is still running.
|
overflow
|
Too many queries or query results are queued.
|
Changelog
The module was introduced with Version 8.5.