Galax Manual: Tutorial

# Chapter 3 Tutorial

## 3.1 Executing a query

The simplest way to use Galax is by calling the galax-run interpreter from the command line. This chapter describes the most frequently used command-line options. Chapter 5 enumerates all the command-line options.

Before you begin, follow the instructions in Section 2.2 and run the following query to make sure your environment is set-up correctly:

    % echo '<two>{ 1+1 }</two>' > test.xq
    % galax-run test.xq
    <two>2</two>

Galax evaluates expression `<two>{ 1+1 }</two>` in file `test.xq` and prints the result `<two>2</two>`.

By default, Galax parses and evaluates an XQuery main module, which contains both a prolog and an expression. Sometimes it is useful to separate the prolog from an expression, for example, if the same prolog is used by multiple expressions. The `-context` option specifies a file that contains a query prolog.

All of the XQuery use cases in `$GALAXHOME/usecases` are implemented by separating the query prolog from the query expressions. Here is how to execute the Parts usecase:

    % cd $GALAXHOME/usecases
    % galax-run -context parts_context.xq parts_usecase.xq

The other use cases are executed similarly, for example:

    % galax-run -context rel_context.xq rel_usecase.xq

## 3.2 Accessing Input

You can access an input document by calling the `fn:doc()` function and passing the file name as an argument:

    % cd $GALAXHOME/usecases
    % echo ’fn:doc("docs/books.xml")’ > doc.xq
    % galax-run doc.xq

You can access an input document by referring to the context item (the “.” dot variable), whose value is the document’s content:

    % echo ’.’ >dot.xq
    % galax-run -context-item docs/books.xml dot.xq

You can also access an input document by using the `-doc` argument, which binds an external variable to the content of the given document file:

    % echo ’declare variable $x external; $x’ > var.xq
    % galax-run -doc x=docs/books.xml var.xq

## 3.3 Controlling Output

By default, Galax serializes the result of a query in a format that reflects the precise data model instance. For example, the result of this query is serialized as the literal `2`:

    % echo "document { 1+1 }"> docnode.xq
    % galax-run docnode.xq
    document { 2 }

If you want the output of your query to be as the standard prescribes, then use the `-serialize standard` option:

    % galax-run docnode.xq -serialize standard
    2

By default, Galax serializes the result value to standard output. Use the `-output-xml` option to serialize the result value to an output file.

    % galax-run docnode.xq -serialize standard -output-xml output.xml
    % cat output.xml
    2

## 3.4 Controlling Compilation

By default, Galax compiles the given query an returns the corresponding result. The following options can be set to print the query as it progresses through the compilation pipeline .

      -print-expr [on/off] Print input expression
      -print-normalized-expr [on/off] Print expression after normalization
      -print-rewritten-expr [on/off] Print expression after rewriting
      -print-logical-plan [on/off] Print logical plan
      -print-optimized-plan [on/off] Print logical plan after optimization
      -print-physical-plan [on/off] Print physical plan

As the output for the compiled query can be quite large, it is often convenient to set the output to verbose using `-verbose on`, which prints headers for each phase. For instance, the following command prints the original query, and the optimized logical plan for the query.

    % galax-run docnode.xq -verbose on -print-expr on -print-optimized-plan on

## 3.5 Updates and Procedural Extensions

Galax supports several extensions to XQuery 1.0, notably XML updates and a procedural extensions. To enable one of those extensions, you must use the corresponding language level option on the command line:

    galax-run -language ultf       (: W3C Update Facility :)
    galax-run -language xquerybang (: XQuery! Language :)
    galax-run -language xqueryp    (: XQueryP Language :)

Some examples of each of the three languages are provided in the `$GALAXHOME/examples/extensions` directory.