XQuery Function Documentation

Search and Browse

http://exist-db.org/xquery/xmldb

java:org.exist.xquery.functions.xmldb.XMLDBModule

A module for database manipulation functions.

copy-collection

copy-collection($source-collection-uri as xs:string, $target-collection-uri as xs:string) as xs:string

Copy the collection $source-collection-uri to the collection $target-collection-uri.

Parameters:
$source-collection-uri The source URI
$target-collection-uri The target URI
Returns:
xs:string : The path to the newly copied collection

copy-collection

copy-collection($source-collection-uri as xs:string, $target-collection-uri as xs:string, $preserve as xs:boolean) as xs:string

Copy the collection $source-collection-uri to the collection $target-collection-uri.

Parameters:
$source-collection-uri The source URI
$target-collection-uri The target URI
$preserve Cause the copy process to preserve the following attributes of each source in the copy: modification time, file mode, user ID, and group ID, as allowed by permissions. Access Control Lists (ACLs) will also be preserved
Returns:
xs:string : The path to the newly copied collection

copy-resource

copy-resource($source-collection-uri as xs:string, $source-resource-name as xs:string, $target-collection-uri as xs:string, $target-resource-name as xs:string?) as xs:string

Copy the resource $source-collection-uri/$source-resource-name to collection $target-collection-uri/$target-resource-name. If the $target-resource-name is omitted, the $source-resource-name will be used.

Parameters:
$source-collection-uri The source URI
$source-resource-name The name of the resource to copy
$target-collection-uri The target URI
$target-resource-name? The name of the resource for the target
Returns:
xs:string : The path to the newly copied resource

copy-resource

copy-resource($source-collection-uri as xs:string, $source-resource-name as xs:string, $target-collection-uri as xs:string, $target-resource-name as xs:string?, $preserve as xs:boolean) as xs:string

Copy the resource $source-collection-uri/$source-resource-name to collection $target-collection-uri/$target-resource-name. If the $target-resource-name is omitted, the $source-resource-name will be used.

Parameters:
$source-collection-uri The source URI
$source-resource-name The name of the resource to copy
$target-collection-uri The target URI
$target-resource-name? The name of the resource for the target
$preserve Cause the copy process to preserve the following attributes of each source in the copy: modification time, file mode, user ID, and group ID, as allowed by permissions. Access Control Lists (ACLs) will also be preserved
Returns:
xs:string : The path to the newly copied resource

xmldb:authenticate

xmldb:authenticate($collection-uri as xs:string, $user-id as xs:string?, $password as xs:string?) as xs:boolean

Check if the user, $user-id, can authenticate against the database collection $collection-uri. The function simply tries to read the collection $collection-uri, using the credentials $user-id and $password. Collection URIs can be specified either as a simple collection path or an XMLDB URI. It returns true if the authentication succeeds, false otherwise.

Parameters:
$collection-uri The collection URI
$user-id? The user-id
$password? The password
Returns:
xs:boolean : true() on successful authentication, false() otherwise

xmldb:clear-lock

xmldb:clear-lock($collection-uri as xs:string, $resource as xs:string) as xs:string?

Removes the user lock on the resource $resource in the collection $collection-uri. If no lock is in place, the empty sequence is returned. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
$resource The resource
Returns:
xs:string? : the user id of the previous lock owner, otherwise if not locked the empty sequence

xmldb:collection-available

xmldb:collection-available($collection-uri as xs:string) as xs:boolean

Returns true() if the collection $collection-uri exists and is available, otherwise false(). Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
Returns:
xs:boolean : true() if the collection exists and is available, false() otherwise

xmldb:create-collection

xmldb:create-collection($target-collection-uri as xs:string, $new-collection as xs:string) as xs:string?

Create a new collection with name $new-collection as a child of $target-collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.Returns the path to the new collection if successfully created, otherwise the empty sequence.

Parameters:
$target-collection-uri The target collection URI
$new-collection The name of the new collection to create
Returns:
xs:string? : the path to the new collection if successfully created, otherwise the empty sequence

xmldb:created

xmldb:created($collection-uri as xs:string) as xs:dateTime

Returns the creation date of the collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
Returns:
xs:dateTime : the creation date

xmldb:created

xmldb:created($collection-uri as xs:string, $resource as xs:string) as xs:dateTime

Returns the creation date of the resource $resource in $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
$resource The resource
Returns:
xs:dateTime : the creation date

xmldb:decode

xmldb:decode($string as xs:string) as xs:string

Decodes the string $string such that any percent encoded octets will be translated to their decoded UTF-8 representation.

Parameters:
$string The input string
Returns:
xs:string : the decoded string

xmldb:decode-uri

xmldb:decode-uri($uri as xs:anyURI) as xs:string

Decodes the URI $uri such that any percent encoded octets will be translated to their decoded UTF-8 representation.

Parameters:
$uri The URI
Returns:
xs:string : the decoded $uri as xs:string

xmldb:defragment

xmldb:defragment($nodes as node()+) as item()

Start a defragmentation run on each document which has a node in $nodes. Fragmentation may occur if nodes are inserted into a document using XQuery update extensions. Please note that defragmenting a document changes its internal structure, so any references to this document will become invalid, in particular, variables pointing to some nodes in the document.

Parameters:
$nodes+ The sequence of nodes from the documents to defragment
Returns:
item()

xmldb:defragment

xmldb:defragment($nodes as node()+, $integer as xs:integer) as item()

Start a defragmentation run on each document which has a node in $nodes. Fragmentation may occur if nodes are inserted into a document using XQuery update extensions. The second argument specifies the minimum number of fragmented pages which should be in a document before it is considered for defragmentation. Please note that defragmenting a document changes its internal structure, so any references to this document will become invalid, in particular, variables pointing to some nodes in the document.

Parameters:
$nodes+ The sequence of nodes from the documents to defragment
$integer The minimum number of fragmented pages required before defragmenting
Returns:
item()

xmldb:document-has-lock

xmldb:document-has-lock($collection-uri as xs:string, $resource as xs:string) as xs:string?

Returns the user-id of the user that holds a write lock on the resource $resource in the collection $collection-uri. If no lock is in place, the empty sequence is returned. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
$resource The resource
Returns:
xs:string? : the user id of the lock owner, otherwise if not locked the empty sequence

xmldb:encode

xmldb:encode($string as xs:string) as xs:string

Encodes the string $string such that it will be a valid collection or resource path. Provides similar functionality to java's URLEncoder.encode() function, with some enhancements.

Parameters:
$string The input string
Returns:
xs:string : the URL encoded string

xmldb:encode-uri

xmldb:encode-uri($string as xs:string) as xs:anyURI

Encodes the string $string such that it will be a valid collection or resource path. Provides similar functionality to java's URLEncoder.encode() function, with some enhancements. Returns an xs:anyURI object representing a valid XmldbURI

Parameters:
$string The input string
Returns:
xs:anyURI : the XmldbURI encoded from $string

xmldb:find-last-modified-since

xmldb:find-last-modified-since($node-set as node()*, $since as xs:dateTime) as node()*

Filters the given node set to only include nodes from resources which were modified since the specified date time.

Parameters:
$node-set* A node set
$since Date
Returns:
node()* : the filtered node set.

xmldb:find-last-modified-until

xmldb:find-last-modified-until($node-set as node()*, $until as xs:dateTime) as node()*

Filters the given node set to only include nodes from resources which were modified until the specified date time.

Parameters:
$node-set* A node set
$until Date
Returns:
node()* : the filtered node set.

xmldb:get-child-collections

xmldb:get-child-collections($collection-uri as xs:string) as xs:string*

Returns the names of the child collections in the collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
Returns:
xs:string* : the sequence of child collection names

xmldb:get-child-resources

xmldb:get-child-resources($collection-uri as item()) as xs:string*

Returns the names of the child resources in collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
Returns:
xs:string* : the sequence of resource names

xmldb:get-mime-type

xmldb:get-mime-type($resource-uri as xs:anyURI) as xs:string?

Returns the MIME type if available of the resource $resource-uri, otherwise the empty sequence. Resource URIs can be specified either as a simple collection path, an XMLDB URI or any URI.

Parameters:
$resource-uri The resource URI
Returns:
xs:string? : the mime-type if available, otherwise the empty sequence

xmldb:last-modified

xmldb:last-modified($collection-uri as item(), $resource as xs:string) as xs:dateTime?

Returns the last-modification date of resource $resource in collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
$resource The resource
Returns:
xs:dateTime? : the last modification date

xmldb:login

xmldb:login($collection-uri as xs:string, $user-id as xs:string?, $password as xs:string?) as xs:boolean

Login the user, $user-id, and set it as the owner of the currently executing XQuery. Collection URIs can be specified either as a simple collection path or an XMLDB URI. It returns true if the authentication succeeds, false otherwise. If called from a HTTP context the login is cached for the lifetime of the HTTP session and may be used for any XQuery run in that session. If an HTTP session does not already exist, none will be created.

Parameters:
$collection-uri The collection URI
$user-id? The user-id
$password? The password
Returns:
xs:boolean : true() on successful authentication and owner elevation, false() otherwise

xmldb:login

xmldb:login($collection-uri as xs:string, $user-id as xs:string?, $password as xs:string?, $create-session as xs:boolean?) as xs:boolean

Login the user, $user-id, and set it as the owner of the currently executing XQuery. Collection URIs can be specified either as a simple collection path or an XMLDB URI. It returns true() if the authentication succeeds, false() otherwise. If called from a HTTP context the login is cached for the lifetime of the HTTP session and may be used for any XQueryrun in that session. $create-session specifies whether to create an HTTP session on successful authentication or not. If $create-session is false() or the empty sequence no session will be created if one does not already exist.

Parameters:
$collection-uri The collection URI
$user-id? The user-id
$password? The password
$create-session? whether to create the session or not on successful authentication, default false()
Returns:
xs:boolean : true() on successful authentication and owner elevation, false() otherwise

xmldb:match-collection

xmldb:match-collection($regexp as xs:string) as xs:string*

Looks for collection names in the collection index that match the provided regexp

Parameters:
$regexp The expression to use for matching collection names
Returns:
xs:string* : The names of the collections that match the expression

xmldb:move

xmldb:move($source-collection-uri as xs:string, $target-collection-uri as xs:string) as item()

Moves the collection $source-collection-uri into the collection $target-collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$source-collection-uri The source collection URI
$target-collection-uri The target collection URI
Returns:
item()

xmldb:move

xmldb:move($source-collection-uri as xs:string, $target-collection-uri as xs:string, $resource as xs:string) as item()

Moves the resource $resource from the collection $source-collection-uri into collection $target-collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$source-collection-uri The source collection URI
$target-collection-uri The target collection URI
$resource The resource
Returns:
item()

xmldb:register-database

xmldb:register-database($driver as xs:string, $create-db as xs:boolean) as xs:boolean

Registers an XMLDB driver class with the XMLDB Database Manager. This is only required if you want to access a database instance different from the one that executes the XQuery.

Parameters:
$driver The DB driver
$create-db The flag to create the db if it does not exist
Returns:
xs:boolean : true() if successfully registered, false() otherwise

xmldb:reindex

xmldb:reindex($collection-uri as xs:string) as xs:boolean

Reindex collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI. The XQuery owner must have appropriate privileges to do this, e.g. having DBA role.

Parameters:
$collection-uri The collection URI
Returns:
xs:boolean : true() if successfully reindexed, false() otherwise

xmldb:reindex

xmldb:reindex($collection-uri as xs:string, $doc-uri as xs:string) as xs:boolean

Reindex document $doc-uri from $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI. Resource URIs can be specified either as a simple collection path, an XMLDB URI or any URI. The XQuery owner must have appropriate privileges to do this, e.g. having DBA role.

Parameters:
$collection-uri The collection URI
$doc-uri The document URI
Returns:
xs:boolean : true() if successfully reindexed, false() otherwise

xmldb:remove

xmldb:remove($collection-uri as xs:string) as item()

Removes the collection $collection-uri and its contents from the database. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
Returns:
item()

xmldb:remove

xmldb:remove($collection-uri as xs:string, $resource as xs:string) as item()

Removes the resource $resource from the collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
$resource The resource
Returns:
item()

xmldb:rename

xmldb:rename($source-collection-uri as xs:string, $new-collection-name as xs:string) as item()

Renames the collection $source-collection-uri with new name $new-collection-name. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$source-collection-uri The source collection URI
$new-collection-name The new collection name
Returns:
item()

xmldb:rename

xmldb:rename($collection-uri as xs:string, $resource as xs:string, $new-resource-name as xs:string) as item()

Renames the resource $resource in collection $collection-uri with new name $new-resource-name. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
$resource The resource
$new-resource-name The new resource name
Returns:
item()

xmldb:set-mime-type

xmldb:set-mime-type($resource-uri as xs:anyURI, $mime-type as xs:string?) as empty-sequence()

Set the MIME type of the resource $resource-uri.Resource URIs can be specified either as a simple collection path, an XMLDB URI or any URI.

Parameters:
$resource-uri The resource URI
$mime-type? The new mime-type, use empty sequence to set default value.
Returns:
empty-sequence()

xmldb:size

xmldb:size($collection-uri as xs:string, $resource as xs:string) as xs:long

Returns the estimated size of the resource $resource (in bytes) in the collection $collection-uri. The estimation is based on the number of pages occupied by the resource. If the document is serialized back to a string, its size may be different, since parts of the structural information are stored in compressed form. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uri The collection URI
$resource The resource
Returns:
xs:long : the size of the pages, occupied by the resource, in bytes

xmldb:store

xmldb:store($collection-uri as xs:string, $resource-name as xs:string?, $contents as item()) as xs:string?

Stores a new resource into the database. The resource is stored in the collection $collection-uri with the name $resource-name. Collection URIs can be specified either as a simple collection path or an XMLDB URI. The contents $contents, is either a node, an xs:string, a Java file object or an xs:anyURI. A node will be serialized to SAX. It becomes the root node of the new document. If $contents is of type xs:anyURI, the resource is loaded from that URI. Returns the path to the new document if successfully stored, otherwise an XPathException is thrown.

Parameters:
$collection-uri The collection URI
$resource-name? The resource name
$contents The contents
Returns:
xs:string? : the path to new resource if sucessfully stored, otherwise the emtpty sequence

xmldb:store

xmldb:store($collection-uri as xs:string, $resource-name as xs:string?, $contents as item(), $mime-type as xs:string) as xs:string?

Stores a new resource into the database. The resource is stored in the collection $collection-uri with the name $resource-name. Collection URIs can be specified either as a simple collection path or an XMLDB URI. The contents $contents, is either a node, an xs:string, a Java file object or an xs:anyURI. A node will be serialized to SAX. It becomes the root node of the new document. If $contents is of type xs:anyURI, the resource is loaded from that URI. The final argument $mime-type is used to specify a mime type. If the mime-type is not a xml based type, the resource will be stored as a binary resource.Returns the path to the new document if successfully stored, otherwise an XPathException is thrown.

Parameters:
$collection-uri The collection URI
$resource-name? The resource name
$contents The contents
$mime-type The mime type
Returns:
xs:string? : the path to new resource if sucessfully stored, otherwise the emtpty sequence

xmldb:store-as-binary

xmldb:store-as-binary($collection-uri as xs:string, $resource-name as xs:string?, $contents as item()) as xs:string?

Stores a new resource into the database. The resource is stored in the collection $collection-uri with the name $resource-name. Collection URIs can be specified either as a simple collection path or an XMLDB URI. The contents $contents, is either a node, an xs:string, a Java file object or an xs:anyURI. A node will be serialized to SAX. It becomes the root node of the new document. If $contents is of type xs:anyURI, the resource is loaded from that URI. Returns the path to the new document if successfully stored, otherwise an XPathException is thrown.

Parameters:
$collection-uri The collection URI
$resource-name? The resource name
$contents The contents
Returns:
xs:string? : the path to new resource if sucessfully stored, otherwise the emtpty sequence

xmldb:store-files-from-pattern

xmldb:store-files-from-pattern($collection-uri as xs:string, $directory as xs:string, $pattern as xs:string+) as xs:string*

Stores new resources into the database. Resources are read from the server's file system, using file patterns. The function returns a sequence of all document paths added to the db. These can be directly passed to fn:doc() to retrieve the document(s).

Parameters:
$collection-uri The collection-uri where resources should be stored. Collection URIs can be specified either as a simple collection path or an XMLDB URI.
$directory The directory in the file system from where the files are read.
$pattern+ The file matching pattern. Based on code from Apache's Ant, thus following the same conventions. For example: *.xml matches any file ending with .xml in the current directory, **/*.xml matches files in any directory below the current one
Returns:
xs:string* : the sequence of document paths

xmldb:store-files-from-pattern

xmldb:store-files-from-pattern($collection-uri as xs:string, $directory as xs:string, $pattern as xs:string+, $mime-type as xs:string?) as xs:string*

Stores new resources into the database. Resources are read from the server's file system, using file patterns. The function returns a sequence of all document paths added to the db. These can be directly passed to fn:doc() to retrieve the document(s).

Parameters:
$collection-uri The collection-uri where resources should be stored. Collection URIs can be specified either as a simple collection path or an XMLDB URI.
$directory The directory in the file system from where the files are read.
$pattern+ The file matching pattern. Based on code from Apache's Ant, thus following the same conventions. For example: *.xml matches any file ending with .xml in the current directory, **/*.xml matches files in any directory below the current one
$mime-type? If the mime-type is something other than 'text/xml' or 'application/xml', the resource will be stored as a binary resource.
Returns:
xs:string* : the sequence of document paths

xmldb:store-files-from-pattern

xmldb:store-files-from-pattern($collection-uri as xs:string, $directory as xs:string, $pattern as xs:string+, $mime-type as xs:string?, $preserve-structure as xs:boolean) as xs:string*

Stores new resources into the database. Resources are read from the server's file system, using file patterns. The function returns a sequence of all document paths added to the db. These can be directly passed to fn:doc() to retrieve the document(s).

Parameters:
$collection-uri The collection-uri where resources should be stored. Collection URIs can be specified either as a simple collection path or an XMLDB URI.
$directory The directory in the file system from where the files are read.
$pattern+ The file matching pattern. Based on code from Apache's Ant, thus following the same conventions. For example: *.xml matches any file ending with .xml in the current directory, **/*.xml matches files in any directory below the current one
$mime-type? If the mime-type is something other than 'text/xml' or 'application/xml', the resource will be stored as a binary resource.
$preserve-structure If preserve-structure is true(), the filesystem directory structure will be mirrored in the collection. Otherwise all the matching resources, including the ones in sub-directories, will be stored in the collection given in the first argument flatly.
Returns:
xs:string* : the sequence of document paths

xmldb:store-files-from-pattern

xmldb:store-files-from-pattern($collection-uri as xs:string, $directory as xs:string, $pattern as xs:string+, $mime-type as xs:string?, $preserve-structure as xs:boolean, $exclude as xs:string*) as xs:string*

Stores new resources into the database. Resources are read from the server's file system, using file patterns. The function returns a sequence of all document paths added to the db. These can be directly passed to fn:doc() to retrieve the document(s).

Parameters:
$collection-uri The collection-uri where resources should be stored. Collection URIs can be specified either as a simple collection path or an XMLDB URI.
$directory The directory in the file system from where the files are read.
$pattern+ The file matching pattern. Based on code from Apache's Ant, thus following the same conventions. For example: *.xml matches any file ending with .xml in the current directory, **/*.xml matches files in any directory below the current one
$mime-type? If the mime-type is something other than 'text/xml' or 'application/xml', the resource will be stored as a binary resource.
$preserve-structure If preserve-structure is true(), the filesystem directory structure will be mirrored in the collection. Otherwise all the matching resources, including the ones in sub-directories, will be stored in the collection given in the first argument flatly.
$exclude* A sequence of file patterns to exclude
Returns:
xs:string* : the sequence of document paths

xmldb:touch

xmldb:touch($collection-uri as xs:string, $resource as xs:string) as xs:boolean

Sets the modification time of a resource to the current system time. If not resource does not exist it is not created.

Parameters:
$collection-uri The collection URI
$resource The name of the resource in the collection
Returns:
xs:boolean : true if the modification time was updated, false otherwise.

xmldb:touch

xmldb:touch($collection-uri as xs:string, $resource as xs:string, $modification-time as xs:dateTime) as xs:boolean

Sets the modification time of a resource. If not resource does not exist it is not created.

Parameters:
$collection-uri The collection URI
$resource The name of the resource in the collection
$modification-time The modification time to set on the resource
Returns:
xs:boolean : true if the modification time was updated, false otherwise.

xmldb:update

xmldb:update($collection-uri as xs:string, $modifications as node()) as xs:integer

Processes an XUpdate request, $modifications, against a collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.The modifications are passed in a document conforming to the XUpdate specification. http://rx4rdf.liminalzone.org/xupdate-wd.html#N1a32e0The function returns the number of modifications caused by the XUpdate.

Parameters:
$collection-uri The collection URI
$modifications The XUpdate modifications to be processed
Returns:
xs:integer : the number of modifications, as xs:integer, caused by the XUpdate

xmldb:xcollection

xmldb:xcollection($collection-uris as xs:string+) as node()*

Returns the document nodes in the collections $collection-uris non-recursively, i.e. does not include document nodes found in sub-collections. C.f. fn:collection(). Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:
$collection-uris+ The collection URIs
Returns:
node()* : the document nodes from the specified collections excluding sub-collections