Client Functions
This module contains functions to access BaseX server instances from XQuery. With this module, you can execute database commands and evaluate XQuery expressions.
Please note that the client module should always be used to address independent BaseX server instances. You can create deadlocks if you evaluate a query with a server instance, and if you are addressing the same server instance in your query. See the following example:
(: Retrieve documents from database :)
let $client-id := client:connect('localhost', 1984, 'admin', '...')
let $docs := client:query($client-id, 'db:get("conflict")')
(: Create database with same name :)
return db:create('conflict', $docs, $docs ! db:path(.))
The read-only query cannot be processed, because the conflict database is currently write-locked by the main query. See Transaction Management for more background information.
All functions and errors in this module are assigned to the
http://basex.org/modules/client namespace, which is statically bound to the
client prefix.
| Signature | client:connect(
$host as xs:string,
$port as xs:integer,
$username as xs:string,
$password as xs:string
) as xs:anyURI |
|---|
| Summary | This function establishes a connection to a remote BaseX server, creates a new client session, and returns a session ID. The parameter $host is the name of the database server, $port specifies the server port, and $username and $password represent the login data. |
|---|
| Errors | connect | An error occurred while creating a new session (possible reasons: server not available, access denied). |
|
|---|
| Signature | client:execute(
$id as xs:anyURI,
$command as xs:string
) as xs:string |
|---|
| Summary | This function executes a command and returns the result as a string. The parameter $id contains the session ID returned by client:connect. The $command argument represents a single command, which will be executed by the server. |
|---|
| Errors | command | An error occurred while executing a command. | error | An I/O error occurred while transferring data from or to the server. |
|
|---|
| Examples | client:connect('basex.server.org', 8080, 'admin', '...')
=> client:execute('create database TEST')
Creates a new database TEST on a remote BaseX server. |
|---|
| Signature | client:info(
$id as xs:anyURI
) as xs:string |
|---|
| Summary | This function returns an information string, created by the last call of client:execute. $id specifies the session ID. |
|---|
Updated: Clark notation replaced with Expanded QNames notation.
| Signature | client:query(
$id as xs:anyURI,
$query as xs:string,
$bindings as map(*)? := ()
) as item()* |
|---|
| Summary | Evaluates a query and returns the result as sequence. The parameter $id contains the session ID returned by client:connect, and $query represents the query string, which will be evaluated by the server. Variables and the context item can be declared via $bindings. The specified keys must be QNames or strings:
- If a key is a QName, it will be directly adopted as variable name.
- If a key is a string, it may be prefixed with a dollar sign. A namespace can be specified using the Expanded QNames notation. If the specified string is empty, the value will be bound to the context item.
|
|---|
| Errors | error | An I/O error occurred while transferring data from or to the server. | function | Function items (including maps and arrays) cannot be returned. | query | An error occurred while evaluating a query. Will only be raised if the XQuery error cannot be extracted from the returned error string. |
|
|---|
| Examples | let $c := client:connect('localhost', 1984, 'admin', '...')
return client:query($c, "declare variable $n external; $n * 2", { 'n': 123 })
Sends a query on a local server instance, binds the integer 123 to the variable $n and returns 246.
let $c1 := client:connect('basex1.server.org', 8080, 'jack', 'C0S19tt2X')
let $c2 := client:connect('basex2.server.org', 8080, 'john', '465wFHe26')
for $it in client:query($c1, '1 to 10')
return client:query($c2, $it || '* 2')
Performs a query on a first server, the results of which are passed on to a second server. |
|---|
| Signature | client:close(
$id as xs:anyURI
) as empty-sequence() |
|---|
| Summary | This function closes a client session. $id specifies the session ID. Opened connections will automatically be closed after the XQuery expression has been evaluated, but it is recommendable to explicitly close them with this function if you open many connections. |
|---|
| Errors | error | An I/O error occurred while transferring data from or to the server. |
|
|---|
| Code | Description |
|---|
command | An error occurred while executing a command. |
connect | An error occurred while creating a new session (possible reasons: server not available, access denied). |
error | An I/O error occurred while transferring data from or to the server. |
function | Function items (including maps and arrays) cannot be returned. |
id | The ID with the specified session is unknown, or has already been closed. |
query | An error occurred while evaluating a query. Will only be raised if the XQuery error cannot be extracted from the returned error string. |
Version 11.0Version 9.0- Updated: error codes updated; errors now use the module namespace
Version 8.0- Updated: Bound values may now contain no or more than one item in
client:query.
Version 7.5Version 7.3
⚡Generated with XQuery
