Introduction

Executing

This tutorial will introduce you to the usage of the MXQuery Command Line Interface.

In the following it’s assumed that the user has already opened the command line interface with the current directory set to the path where the mxquery.jar file is located.

You can execute the MXQuery engine in the command line interface using

java -jar mxquery.jar

Executing this command without any parameters will output the usage text with a list of all possible options and its description.

MXQuery 0.6.0

usage: java -jar mxquery.jar

…

Now let’s look at some basic options and their usage.

Basics

Input / Output

The input option is required for every query. The MXQuery engine provides three different options for input

-  inline query -i

-  query file   -f <file>

-  query plan  -p <file>

and three  different options for output

-  discard result (no output) -d

-  standard out  -o -

-  output file  -o <file>

The standard out is set by default, meaning that if no output option is provided, the MXQuery engine will automatically write the result to the standard output stream.

Here are some examples:

1) inline query, standard out

java -jar mxquery.jar -i 1+1 -o -

will return the following in the standard output stream

MXQuery 0.6.0

<?xml version=’1.0′ encoding=’UTF-8′ ?>

2

The same would have been achieved with

java -jar mxquery.jar -i 1+1

will return the following in the standard out, since the standard output stream is set by default.

2)  query file,  output file

For this second example let’s write a little query file myInput.xq containing an arbitrary XQuery expression, say “hello world” for simplicity, and save the file in the same directory as mxquery.jar is located.

java -jar mxquery.jar -f myInput.xq -o myOutput.xml

will execute the query from the myInput.xq file and print the output

<?xml version=’1.0′ encoding=’UTF-8′ ?>

hello world

in myOutput.xml by either creating a new file or overwriting the existing one.

3)  query plan

TO DO

Print Options

Now that we have understand the input/output behavior of the MXQuery engine. We continue with some options providing additional information to the XQuery:

-  explain

- printStores

-  timing

-  verbose

Advanced

Serializer

The MXQuery Command Line Interface allows you to set the serializer parameters according to your preferences. We present you only a few parameter settings in order to keep the tutorial compact. You may want to refer to the MXQuery CLI Specification to get a full list of parameter options.

java -jar mxquery.jar -i “for $i in <person><name>John</name><surname>smith</surname></person>

return $i” -s indent=true

Will add whitespaces to the result for readability, and return

MXQuery 0.6.0

<?xml version=’1.0′ encoding=’UTF-8′ ?>

<person>

<name>

John

</name>

<surname>

smith

</surname>

</person>

Instead of the result we would have received without setting the indent parameter of the serializer

MXQuery 0.6.0

<?xml version=’1.0′ encoding=’UTF-8′ ?>

<person><name>John</name><surname>smith</surname></person>

To set several parameters of the serializer simply write several -s in your command, like

java -jar mxquery.jar -i “for $i in <person><name>John</name><surname>smith</surname></person>

return $i” -s indent=true -s omit-xml-declaration=true

Context

The MXQuery Command Line Interface also allows you to set the static context in which the XQuery will be executed. As with the serializer we only present a few context components and let you consult the MXQuery CLI Specification for a full list of context components.

By default MXQuery will preserve the node ordering, which might not be as efficient as if MXQuery could decide by himself in which order it want to process the document nodes. In these cases you can set the context parameter ordering to unordered.

-i “for $i in <parent><child>alice</child><child>bob</child>charlie<child> </child></parent> return $i/child” -c ordering=unordered

The result is now not deterministic and might be of any ordering

MXQuery 0.6.0

<?xml version=’1.0′ encoding=’UTF-8′ ?>

<child>alice</child><child>bob</child><child>charlie</child>

You can also bind external variables and execute a command like

-i “declare variable $a external;<result>{$a}</result>” -e a:=”<node>this node is bound externally</node>”

Which will return

MXQuery 0.6.0

<?xml version=’1.0′ encoding=’UTF-8′ ?>

<result><node>this node is bound externally</node></result>