A Brief Guide for Using Galax on DICE

An open source XQuery implementation Galax is recommended for DBS homework. Currently Galax0.5.0 is installed on DICE.

1. What is Galax?

Galax is an open-source implementation of XQuery 1.0 specifications, with completeness, strict conformance to the specifications, and semantic integrity as first goals. Galax 0.5.0 implements the XQuery 1.0 working draft published in October 2004. For more information, see Galax website.

2. Where to find Galax on DICE?

2.1. Galax commands

The following Galax commands are installed under /usr/bin on DICE machines:
galax-compile        galax-mapwsdl        galax-project
galax-compile.opt    galax-mapwsdl.opt    galax-project.opt
galax-mapschema      galax-parse          galax-run
galax-mapschema.opt  galax-parse.opt      galax-run.opt

Too many commands? Don't worry. Although there are twelve commands, only galax-run (galax-run.opt is an optimized version of galax-run) is needed for DBS homework.

2.2. Galax documentation

  • /usr/share/doc/galax-0.5.0/

The documentation is also accessible online at galaxquery.org.

2.3. Galax library

  • /usr/lib/galax/lib

You won't need it if you do not want to use Galax API to evaluate XQuery in your Java or C++ codes.

2.4. Galax examples

  • /usr/lib/galax/usecases
  • /usr/lib/galax/examples

3. A Short Tutorial

The following examples assume you are using a DICE machine. The examples are extracted from Galax user's manual.

The simplest way to run a query written in XQuery is to use the command 'galax-run'. Since 'galax-run' is already installed under /usr/bin/, you can simply type 'galax-run' on your terminal to run the command.

3.1. Getting help

Try:

% galax-run -help
You should see the following output:
Usage: /usr/bin/galax-run [options] input-queries (or '-' for stdin)
...

It tells you that you must give a file containing input queries to run Galax.

3.2. A simple example without touching any XML document

Here is a simple example from Galax user's manual:

%  echo "<two> { 1+1 } </two>" > test.xq
%  $(GALAXHOME)/bin/galax-run test.xq
<two>2</two>

This example evaluates the simple query { 1+1 } and prints the XML value 2.

Galax uses .xq as the XQuery file name suffix. In this example, it is "test.xq".

The query result is displayed on screen (stdout). It is usually an XML document (as in example), but not always. The result could be a number, a string or even a boolean value. Try another query "1+1" and you will find your get a number "2", instead of an XML document, as the result.

These two queries are contained in the example file "/usr/lib/galax/examples/tutorial/test.xq" and "/usr/lib/galax/examples/tutorial/sum.xq", respectively.

3.3. Specify a source XML document to be queried on

I will now explain a little bit more about 'galax-run' command. In fact, the practical queries are usually not as simple as the above one: Galax need to touch a source XML document in order to answer the query. Generally speaking, you need to specify one or more XML document to be queried on.

But how to specify a source XML file name if the query need to touch an XML document?

3.3.1. Specify a source XML document in the query

The simplest way is to put it in your query. You can use the XQuery predefined function doc() to load the source XML document.

Try:

cat /usr/lib/galax/examples/tutorial/doc.xq

You will get 'fn:doc("../docs/xml-example.xml")' on the screen, which is an example query to load an XML document with path of "../docs/xml-example.xml".

Then try:

galax-run /usr/lib/galax/examples/tutorial/doc.xq

You will get the content of the XML file "xml-example.xml" as output.

More XQuery function could be found here.

3.3.2. Specify a context node with 'galax-run' command

Try:

galax-run /usr/lib/galax/examples/tutorial/dot.xq

You will get the following error message:

Internal Error: Variable not found in context during code selection: fs:dot

This is because the query in dot.xq is just a dot ".", which means print out the current node. But there is no context node when the query is executing. You need to use the "galax-run" command options to specify a context node. The correct way to run it is:

% galax-run -context-item /usr/lib/galax/examples/docs/xml-example.xml /usr/lib/galax/examples/tutorial/dot.xq

This query will produce the same result as the one in 3.3. Here you see, you can access an input document by referring to the context item (the ``.'' dot variable), whose value is the document's content.

3.3.3. Specify variable bindings with 'galax-run' command

Try:

% galax-run -var doc=/usr/lib/galax/examples/docs/xml-example.xml /usr/lib/galax/examples/tutorial/var.xq

You will get the same result as the above two. But here you use an external variable binding to specify the source XML document.

Now you have seen, there are three methods to specify the source XML document for a query in Galax: 1) use doc() function in your query; 2) use '-context-item' command option; 3) use '-var' command option.

3.4. Controlling output

3.4.1. Saving result to a file

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

/usr/bin/galax-run /usr/lib/galax/examples/tutorial/sum.xq -output-xml output.xml

3.4.2. Making result a well-formed XML value

If you want the output of your query to be a well-formed XML value, then use the -serialize wf option:

/usr/bin/galax-run /usr/lib/galax/examples/tutorial/sum.xq -serialize wf

More examples are under /usr/lib/galax/usecases directory.

4. More resources

  1. Online User's Manual for Galax 0.5.0. Including:
  2. VLDB2003 Demo: Mary F. Fernández, Jérôme Siméon, Byron Choi, Amélie Marian, Gargi Sur: Implementing Xquery 1.0: The Galax Experience. VLDB 2003: 1077-1080
  3. W3C's list of XQuery related links
  4. W3C XQuery 1.0 Candidate Recommendation
  5. A useful reference for predefined XQuery funtions and operators: XQuery 1.0 and XPath 2.0 Functions and Operators
  6. A Brief Explanation for Carwin's Python and PostgreSQL Examples
Topic revision: r4 - 07 Feb 2006 - 21:28:56 - XibeiJia
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies