Name

qizx — Qizx command line tool

Synopsis

qizx argument...

Description

qizx is a simple command-line interface for administrative and development use.

It provides basic operations on XML libraries, in particular:

  • Creating XML Libraries, and performing administrative tasks (like re-indexing, backup).

  • Importing XML documents into a Library, by parsing files or URL's.

  • Executing XQuery expressions from files.

  • Outputting the results of a XQuery execution to a file, with a number of options.

  • Exporting a XML document or a collection from a Library.

The command-line option switches allow all these basic operations. For more complex problems, it is still possible to benefit of the full power of the XQuery language (and of extension functions provided by Qizx) by executing a script.

Options

Option switches always start with a minus sign. They can be followed by an argument. The letter case is generally significant.

An argument not starting with '-' is considered a XQuery source file to be executed.

Attention: processing of options has changed in version 4.0. The order of options is no more relevant. This makes it simpler to use, but induces some limitations: some operations (import, backup) can be performed only once in a launch.

General

-group path, -g path

Specifies the location of a group of XML Libraries - or the address of a remote server.

  • Local Library group on disk: the path points to the root directory of the Group.

  • Server: the path is an HTTP URL like http://somehost:8080/qizx/api.

    A default installation of a Qizx Server would end with "/qizx/api" which corresponds to the Qizx REST API connector. But this path - of course the host and the port too - depend on the configuration of the server. See the Server installation documentation for more details.

-library library_name, -l library_name

Specifies the name of a XML Library inside the selected group. The library must exist, unless the option -create is used (see below), otherwise the tool will stop in error.

Most operations, like executing queries, require an XML Library.

In local group mode, the XML Library will be locked for exclusive access.

-login username:password

Used when connecting to a Qizx server that requires authentication. Since the password may appear on the command-line, this is not recommended for the best security. You may want to use the following switch -auth:

-auth secret-file

Specify login credentials read from a file for better security. If authentication is required, credentials will be read from this file. The file should contain the following values:

login=admin                                                                                           
password=xxxx

Of course the file should be protected from reading by other users.

Administration operations

-create

Using this option, the group specified with option -group is created if it does not exist, and the library specified with option -library is created if it does not exist.

The option has no effect if both exist.

In client/server mode, only a Library can be created, this would not create a group since it is defined by the server.

-import collection XML-file-or-directory...XML-file-or-directory

Import one or several XML documents into a collection (the collection is created if it does not yet exist): documents are parsed (they must be valid), stored and automatically indexed.

Several XML file paths or directory paths can follow this option switch. Directories are scanned recursively, plain files encountered are considered XML and tentatively stored (the -include and -exclude options below can be used to filter files). A parsing error does not stop the load process.

The path of the collection can be a document pattern containing a character '*': this character is replaced by an integer incremented on each document stored, providing an automatic naming mechanism for new documents. For example:

qizx -g mygroup -l mylib -import /a/collection/doc*.xml files...

would create documents /a/collection/doc1027.xml, /a/collection/doc1028.xml, /a/collection/doc1030.xml, etc. The numbers are of course guaranteed to be unique, and always increasing, but no other assumption can be made about their values.

-include suffix

Used together with -import: restricts the importing operation to files ending with this suffix (case insensitive). Can be used before or after -import, but must precede the XML file list. For example -include .xml would select only the files whose name ends with .xml or .XML or .Xml, etc.

This option can be repeated: -include .xml -include .xsd would select both files ending with .xml and .xsd. By default all plain files are taken, unless a -exclude option is present (see below)

-exclude suffix

Used together with -import: eliminates form a storing operation files ending with this suffix (case insensitive). Can be used before or after -import, but must precede the XML file list. For example -exclude .txt would eliminate the files whose name ends with .txt or .TXT, etc.

This option can be repeated: -exclude .jpg -exclude .png would eliminate files ending with either .jpg or .png.

-export member_path

Exports a member of the selected library (Collection or Document) using its path.

-indexing path

Defines an Indexing specification for the Library. An Indexing specification is used for customizing the way XML documents are indexed in the Library. For more information, see Chapter 9, Configuring the indexing process.

If documents were already imported with a different indexing specification, it is strongly recommended to use the option -reindex (see below) to rebuild indexes.

-reindex

Rebuilds all the indexes from scratch, without altering documents.

-optimize

Forces the compaction of indexes, without altering the contents of the Library.

-delete-library

Using this option, a library is specified with -library will be removed from the group and physically deleted.

-delete member_path

Deletes a member of the selected library (Collection or Document) using its path.

-backup backup_group_path

complete backup of the specified Library to the location specified: this location must correspond to a directory on a file-system, where a group will be created if necessary, and in which a XML Library with the same name will be created (if it already exists, it is first erased).

Example:

qizx -c mygroup -library mylib -backup /backups/my-group

This creates a backup group at /backups/my-group (if necessary), then copies the Library mylib into the backup group.

-check log_file

Performs a structural check of all the Libraries of the group and report errors to the log file. This is intended for debugging purpose.

Note

This operation is currently not able to repair a damaged XML Library.

XQuery execution and settings

-q query-file, query-file

Executes the XQuery expression contained in that file(s). The -q option switch is optional (it has to be used only if the file path starts with a dash, which is rarely the case). Several query files can be executed in order. Notice that if you specify the value of XQuery variables (option -D), this applies to all scripts, whatever their respective order.

-base-uri URI

Define the base URI for locating parsed XML documents. Unless a query redefines this base-URI, it will be used for resolving relative document locations as in the function doc().

This option has no effect when connecting to a server.

-module-base-uri URI

Define the base URI for locating XQuery modules.

This option has no effect when connecting to a server.

-i collection

Defines the ``Implicit Collection'' i.e the set of documents or Nodes used as search roots when a XQuery Path Expression has no explicit root.

For example the expression //ELEM has no explicit root, while collection("/mycollec")//ELEM has the explicit root collection("/mycollec"), a Collection of the current XML Library.

Using this option is quite useful, as it allows writing XQuery scripts which are independent on the actual data used as input. Furthermore it makes scripts more concise.

If the Implicit Collection is defined through this option, for example -i /mycollec , the expression //ELEM is equivalent to collection("/mycollec")//ELEM.

Values: acceptable values for this option are the same as the argument of function fn:collection (Attention: this is different in Qizx/open):

  • the path of a Document or a Collection inside an XML Library ,

  • a file path or an URL: for example dir1/doc1.xml or http://foobar.com/docs/summary.xml

  • a file pattern: dir/*.xml

  • a semicolon-separated list of the above elements: dir1/*.xml;dir2/doc2.xsl

Note

If you want to use a single document, append a comma or semicolon after its path or URL.

Note

The function collection() without argument, or the deprecated XQuery function input() can also be used instead of an implicit root.

-domain collection

Alias for option -i above.

-Dvariable_name=value

Defines the value of a global variable. For example if the variable is declared like this:

declare variable $output external;

then the option -Doutput=foo initializes $output with the string value "foo".

If the variable is declared with a type, an attempt to cast the string value to the declared type is made.

If the variable is declared with an initial value, this value is overridden.

-- argument ... argument

The double dash switch is used to pass command-line arguments to a XQuery script. It stores all following command-line tokens into the predefined variable $arguments. For example:

qizx myscript.xq -- arg1 arg2 arg3

runs the script myscript.xq after putting the sequence of 3 string items ("arg1", "arg2", "arg3") into variable $arguments.

Note

Because of this option, the scripts are always executed after interpretation of all other options.

-timezone duration

Defines the implicit timezone in the dynamic XQuery context. The value must be in xs:duration form, for example -timezone -PT5H.

This option has no effect when connecting to a server.

-collation uri

Defines the default collation for string comparisons.

Collations are supported through Java collators based on a locale name, for example "/en" or "/fr-CH". There is currently no support for plugging user-defined collators.

Syntax of the URI of a collation:

  • Leading slash (so that the URI is absolute, otherwise it could be dereferenced relatively to the base-uri property of the static context).

  • Name of a locale following the Java conventions.

  • An optional URI fragment (beginning with a '#') whose value is "primary", "secondary" or "tertiary", defining the "strength" of the collator (see the Java documentation for more details). The value "primary" is less specific than "tertiary".

    If the strength is absent, it is in general equivalent to "tertiary".

For example, the expression contains("The next café", "CAFE", "/en#primary") should return true, because the collation with strength primary ignores case and accents.

The special URIs codepoint and "http://www.w3.org/2003/05/xpath-functions/collation/codepoint" refer to the basic Unicode codepoint matching (or absence of collation). This is the default collation, unless redefined in the static context.

Output options

-Xoption=value

Defines a serialization option for result output. For example -Xmethod=html produces results in HTML markup.

For details of serialization options, see the documentation of the x:serialize() XQuery extension function.

-out file

output the result of a XQuery expression to a file (defaults to standard output).

-wrap

wraps the displayed results in description tags. For example with -wrap the expression 1, "a" would display:

Query ? 1, "a"
<?xml version='1.0' encoding='UTF-8'?>
<query-results>
  <item type="xs:integer">1</item>
  <item type="xs:string">a</item>
</query-results>

instead of:

Query ? 1, "a"
1 a
-> 2 item(s)
-jt

trace use of Java extension functions (for debugging).

This option has no effect when connecting to a server.

-tex

verbose display of run-time exceptions (for debugging).

Note

In Qizx/open, only the query execution options and output options are available

Examples

This section is an How-To for some common operations with the qizx command line tool:

Create a group with a single XML Library
qizx -group D:\xmldb\group1 -library orders -create

This creates a group in the directory D:\xmldb\group1 (which must be non-existent or empty), containing a single XML Library named 'orders'.

Create an empty group
qizx -group D:\xmldb\group1 -create

This creates a group in the directory D:\xmldb\group1, without any XML Library inside.

Connect to a server
qizx -login me:mypassword -group http://localhost:8080/qizx/api script.xq

This connects to a Qizx server and executes the script on this server. Most other commands and options can be used in this mode.

Authentication, if required, can be provided by option -login, or by -auth (use of a secret file), or would be read on the console.

Import XML documents into an existing XML Library
qizx -group D:\xmldb\group1 -library orders -import /2007/june c:\data\orders\june2007\*.xml

This assumes that the group at D:\xmldb\group1 already exists and contains a Library named 'orders'. Then the specified XML documents are stored into the Collection /2007/june. For example the document c:\data\orders\june2007\A.xml will be stored in the library at /2007/june/A.xml.

Create a group with a single XML Library and store XML documents
qizx -group D:\xmldb\group1 -library orders -create -import /2007/june c:\data\orders\june2007\*.xml

This is a combination of the previous commands: the group and library are created and immediately after the documents are stored into the Library 'orders'.

Import XML documents into an existing XML Library with filters
qizx -group D:\xmldb\group1 -library data -import /2007/june -include .xml -include .xsl \
    c:\data\orders\june2007

Assuming that the group at D:\xmldb\group1 already exists and contains a Library named 'orders', then all XML documents contained within directory c:\data\orders\june2007 (at any depth), and whose name ends with .xml or .xsl are stored into the Collection /2007/june.

qizx -group D:\xmldb\group1 -library data -import /2007/june -exclude .jpg \
    c:\data\orders\june2007

Assuming that the group at D:\xmldb\group1 already exists and contains a Library named 'orders', then all XML documents contained within directory c:\data\orders\june2007 (at any depth), and whose name does not end with .jpg are stored into the Collection /2007/june.

Delete an XML Library within a group
qizx -group D:\xmldb\group1 -library dataLib -delete-library

Deletes the library 'dataLib' (selected by -library dataLib) and all its contents. Beware, this operation is irreversible.

Delete a Document or a Collection within a Library
qizx -group D:\xmldb\group1 -library dataLib -delete /2007/june

Deletes the collection /2007/june in library 'dataLib' and all its contents (documents and sub-collections). Beware, this operation is irreversible.

qizx -group D:\xmldb\group1 -library dataLib -delete /2007/june/order1.xml

Deletes the document /2007/june/order1.xml in library 'dataLib'. Beware, this operation is irreversible.