Chapter 15. Administration extension functions

Table of Contents

1. Server Functions reference
2. Admin Functions reference

These XQuery functions allow writing administration scripts.

Note: to ensure proper execution of the operations below in XQuery, it is recommended to use

(Remember that XQuery is a functional language that does not guarantee any evaluation order and relies heavily on lazy evaluation.)

1. Server Functions reference

These function have the predefined prefix server: .

They are available only within Qizx Server and require the user to have Administrator permissions.

See also: Admin Functions.

server:info( )

Returns information about the server, in XML form.

The XML format is examplified hereafter:

<info>
  <property><Name>server-name</Name><Value>Qizx Server</Value>
  </property>
  <property><Name>product-name</Name><Value>Qizx</Value>
  </property>
  <property><Name>product-version</Name><Value>4.4</Value>
  </property>
...
</info>

Returned value [ type node() ]: A XML document whose main element name is info.

server:reload( )

Restarts the server and reloads its configuration.

Returned value [ type empty() ]: none.

server:backup( $library-name as xs:string, $path as xs:string )

Performs a backup of the XML Library (given by its name $library-name) to a directory of the server's file-system.

Parameter $library-name [ type xs:string ]: Name of an XML Library handled by this server.

Parameter $path [ type xs:string ]: Backup directory in the server's file-system.

Returned value [ type empty() ]: none.

server:incremental-backup( $library-name as xs:string, $path as xs:string )

Performs an incremental backup of the XML Library (given by its name $library-name) to a directory of the server's file-system.

The former contents of the target directory are kept when possible (compatible databases), then the function computes the differences with the source database and updates only the documents, collections and indexes that have changed since the latest incremental or full backup.

Caution

the incremental backup cannot be used to synchronize 2 databases created separately. The target database must have been created by backup (full or incremental) of the source database, otherwise the backed up database could become inconsistent.

Parameter $library-name [ type xs:string ]: Name of an XML Library handled by the server.

Parameter $path [ type xs:string ]: Backup directory in the server's file-system.

Returned value [ type empty() ]: none.

server:optimize( $library-name as xs:string )

Performs an optimization of the XML Library (given by its name $library-name).

Parameter $library-name [ type xs:string ]: Name of an XML Library handled by the server.

Returned value [ type empty() ]: none.

server:quick-optimize( $library-name as xs:string, $max-time as xs:int )

Performs an optimization of the XML Library (given by its name $library-name) in limited time.

Parameter $library-name [ type xs:string ]: Name of an XML Library handled by the server.

Parameter $max-time [ type xs:int ]: Maximum time in seconds spent for the optimize operation (per XML Library).

Returned value [ type empty() ]: none.

server:reindex( $library-name as xs:string )

Performs a complete reindexing of the XML Library (given by its name $library-name).

Parameter $library-name [ type xs:string ]: Name of an XML Library handled by the server.

Returned value [ type empty() ]: none.

server:get-indexing( $library-name as xs:string )

Returns the indexing specifications of the specified XML Library.

Parameter $library-name [ type xs:string ]: Name of an XML Library handled by the server.

Returned value [ type node() ]: indexing specifications in XML form.

server:set-indexing( $library-name as xs:string, $indexing-spec as node() )

Define the indexing specifications of the specified XML Library.

Parameter $library-name [ type xs:string ]: Name of an XML Library handled by the server.

Parameter $indexing-spec [ type node() ]: The indexing specification in XML form.

Returned value [ type empty() ]: none.

server:get-configuration( $expert as xs:boolean )

Returns the configuration of the server in XML form.

The XML format is examplified hereafter:

<configuration>
  <property>
    <Name>POST_limit</Name>
    <Category>Server</Category>
    <Level>admin</Level>
    <Type>Integer</Type>
    <Value>-1</Value>
    <DefaultValue>-1</DefaultValue>
    <Description>Maximum size in Mb of a POST request.</Description>
  </property>
  <property>
    <Name>logging_level</Name>
    <Category>Database</Category>
    <Level>admin</Level>
    <Type>String</Type>
    <Value>INFO</Value>
    <DefaultValue>INFO</DefaultValue>
    <Description>Logging level applied to all XML Libraries</Description>
  </property>
...
</configuration>                                                                                     

Parameter $expert [ type xs:boolean ]: If true, return value include properties of level "expert" in addition to standard "admin" properties.

Returned value [ type node() ]: A XML document whose main element name is configuration.

server:change-configuration($name1 as xs:string, $value1 as item()[, $name2, $value2...] )

Modifies the configuration of the server: can specify one or several properties.

Parameter $nameN [ type xs:string ]: Name of a defined property of the configuration.

Parameter $valueN [ type xs:object* ]: Value of the property.

Returned value [ type xs:boolean ]: true if the configuration has actually been modified.

server:list-tasks( $timeline as xs:int )

Returns a list of maintenance tasks executed on the server, past or active, in XML form.

The XML format is examplified hereafter:

<tasks>
  <task>
    <Type>backup</Type>
    <Database>mydb (session 123)</Database>
    <StartTime>2011-10-07 21:51:36.600</StartTime>
    <FinishTime>2011-10-07 21:51:36.879</FinishTime>
    <Duration>0.27</Duration>
    <Progress>100.0%</Progress>
  </task>
 ...
</tasks>

Parameter $timeline [ type xs:int ]: A duration in hours: if 0, return currently active tasks; if > 0, return all tasks that started within this number of hours before now.

Returned value [ type node() ]: A XML document whose main element name is tasks.

server:get-stats( $expert as xs:boolean )

Returns statistics of the server as XML.

The XML format of statistics is examplified hereafter: a list of <stat> elements enclosed inside a <statistics> wrapper.

<statistics>
  <stat>
    <Id>collections</Id>
    <Type>count</Type>
    <Value>20</Value>
    <Family>Data</Family>
    <Description>total number of Collections</Description>
  </stat>
 ...
  <stat>
    <Id>index|compaction</Id>
    <Type>time</Type>
    <Value>1345 ms</Value>
    <Family>Activity</Family>
    <Description>Index optimizations</Description>
  </stat>
 ...
</statistics>

Parameter $expert [ type xs:boolean ]: if true return a fully detailed set of statistics, if false return an aggregated subset relevant for an administrator.

Returned value [ type node() ]: statistics as an XML fragment.

server:list-queries( )

Returns a list in XML form of queries currently executing on the server.

The XML format is examplified hereafter:

<queries>
  <query>
    <Id>s2-e1</Id>
    <User>user</User>
    <Elapsed>9.53</Elapsed>
    <Source>count(//Product[@id > 40000000])</Source>
  </query>
  <query>
    <Id>s3-e14</Id>
    <User>admin</User>
    <Elapsed>0.0</Elapsed>
    <Source>server:list-queries()</Source>
  </query>
</queries>

Returned value [ type node() ]: A XML document whose top element name is queries.

server:cancel-query( $expr-id as xs:string )

Cancels a running XQuery specified by its identifier.

Parameter $expr-id [ type xs:string ]: Identifier as returned by function server:list-queries()

Returned value [ type xs:string ]: a status equal to "OK", "idle" or "unknown" .

"idle" means that the query is not currently being executed.

server:create-library( $library-name as xs:string )

Creates a new XML Library.

Parameter $library-name [ type xs:string ]: Name of the library to create.

Returned value [ type empty() ]: none.

server:delete-library( $library-name as xs:string )

Deletes an XML Library.

Parameter $library-name [ type xs:string ]: Name of the library to delete.

Returned value [ type empty() ]: none.

2. Admin Functions reference

These function have the predefined prefix admin: .

They are always available in embedded mode; within Qizx Server they require the user to have Administrator permissions.

admin:info( )

Returns information about the current Library Group.

The XML format is examplified hereafter:

<info>
  <property><Name>server-name</Name><Value>Qizx Server</Value>
  </property>
  <property><Name>product-name</Name><Value>Qizx</Value>
  </property>
  <property><Name>product-version</Name><Value>4.4</Value>
  </property>
...
</info>

Returned value [ type node() ]: A XML fragment whose top element name is info.

admin:backup( $path as xs:string )

Performs a backup of the current XML Library to a directory of the server's file-system.

The former contents of the target directory are deleted before performing the backup.

Parameter $path [ type xs:string ]: Backup directory in the server's file-system.

Returned value [ type empty() ]: none.

admin:incremental-backup( $path as xs:string )

Performs an incremental backup of the current XML Library to a directory of the server's file-system.

The former contents of the target directory are kept when possible (compatible databases), then the function computes the differences with the source database and updates only the documents, collections and indexes that have changed since the latest incremental or full backup.

Caution

the incremental backup cannot be used to synchronize 2 databases created separately. The target database must have been created by backup (full or incremental) of the source database, otherwise the backed up database could become inconsistent.

Parameter $path [ type xs:string ]: Backup directory in the server's file-system.

Returned value [ type empty() ]: none.

admin:optimize( )

Performs an optimization of the current XML Library.

Returned value [ type empty() ]: 

admin:quick-optimize( $max-time as xs:int )

Performs an optimization of the current XML Library in limited time.

Parameter $max-time [ type xs:int ]: Maximum time in seconds spent for the optimize operation (per XML Library).

Returned value [ type empty() ]: 

admin:reindex( )

Performs a complete reindexing of the current XML Library.

Returned value [ type empty() ]: 

admin:get-indexing( )

Returns the indexing specifications of the current XML Library.

Returned value [ type node() ]: indexing specifications in XML form.

admin:set-indexing( $indexing-spec as node() )

Define the indexing specifications of the current XML Library.

Parameter $indexing-spec [ type node() ]: The indexing specification in XML form.

Returned value [ type empty() ]: none.

admin:get-configuration( $expert as xs:boolean )

Returns the configuration of the current Library in XML form.

The XML format is examplified hereafter:

<configuration>
  <property>
    <Name>logging_level</Name>
    <Category>Database</Category>
    <Level>admin</Level>
    <Type>String</Type>
    <Value>INFO</Value>
    <DefaultValue>INFO</DefaultValue>
    <Description>Logging level applied to all XML Libraries</Description>
  </property>
...
</configuration>                                                                                     

Parameter $expert [ type xs:boolean ]: If true, return value include properties of level "expert" in addition to standard "admin" properties.

Returned value [ type node() ]: A XML document whose main element name is configuration.

admin:change-configuration($name1 as xs:string, $value1 as item()[, $name2, $value2...] )

Modifies the configuration of current Library: can specify one or several properties.

Parameter $nameN [ type xs:string ]: Name of a defined property of the configuration.

Parameter $valueN [ type xs:object* ]: Value of the property.

Returned value [ type xs:boolean ]: true if the configuration has actually been modified.

admin:list-tasks( $timeline as xs:int )

Returns a list of maintenance tasks executed on the current Library, past or active, in XML form.

The XML format is examplified hereafter:

<tasks>
  <task>
    <Type>backup</Type>
    <Database>mydb (session 123)</Database>
    <StartTime>2011-10-07 21:51:36.600</StartTime>
    <FinishTime>2011-10-07 21:51:36.879</FinishTime>
    <Duration>0.27</Duration>
    <Progress>100.0%</Progress>
  </task>
 ...
</tasks>

Parameter $timeline [ type xs:int ]: A duration in hours: if 0, return currently active tasks; if > 0, return all tasks that started within this number of hours before now.

Returned value [ type node() ]: A XML document whose main element name is tasks.

admin:get-stats( $expert as xs:boolean )

Returns statistics of the current Library as XML.

The XML format of statistics is examplified hereafter: a list of <stat> elements enclosed inside a <statistics> wrapper.

<statistics>
  <stat>
    <Id>collections</Id>
    <Type>count</Type>
    <Value>20</Value>
    <Family>Data</Family>
    <Description>total number of Collections</Description>
  </stat>
 ...
  <stat>
    <Id>index|compaction</Id>
    <Type>time</Type>
    <Value>1345 ms</Value>
    <Family>Activity</Family>
    <Description>Index optimizations</Description>
  </stat>
 ...
</statistics>

Parameter $expert [ type xs:boolean ]: if true return a fully detailed set of statistics, if false return an aggregated subset relevant for an administrator.

Returned value [ type node() ]: statistics as an XML fragment.

admin:list-queries( )

Returns a list in XML form of queries currently executing on the current Library.

The XML format is examplified hereafter:

<queries>
  <query>
    <Id>s2-e1</Id>
    <User>user</User>
    <Elapsed>9.53</Elapsed>
    <Source>count(//Product[@id > 40000000])</Source>
  </query>
  <query>
    <Id>s3-e14</Id>
    <User>admin</User>
    <Elapsed>0.0</Elapsed>
    <Source>server:list-queries()</Source>
  </query>
</queries>

Returned value [ type node() ]: A XML document whose top element name is queries.

admin:cancel-query( $expr-id as xs:string )

Cancels a running XQuery specified by its identifier.

Parameter $expr-id [ type xs:string ]: Identifier as returned by function server:list-queries()

Returned value [ type xs:string ]: a status equal to "OK", "idle" or "unknown" .

"idle" means that the query is not currently being executed.