qizx — Qizx command line tool
qizx
argument...
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.
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.
-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.
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:
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.
-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_pathDeletes a member of the selected library (Collection or Document) using its path.
-backup
backup_group_pathcomplete 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.
This operation is currently not able to repair a damaged XML Library.
-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
If you want to use a single document, append a comma or semicolon after its path or URL.
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
.
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.
-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).
In Qizx/open, only the query execution options and output options are available
This section is an How-To for some common operations with the qizx command line tool:
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
'.
qizx -group D:\xmldb\group1 -create
This creates a group in the directory D:\xmldb\group1
, without any XML Library inside.
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.
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
.
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
'.
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
.
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.
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.