qizx
Prev | Part V. Tools | Next

## 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 ???.

  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 (for Qizx/open, see here):

  - 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.

`-D` `variable_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 would 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

`-X` `option`=`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.

Prev | Up | Next
Part V. Tools | Home | Qizx Studio Help