Query Interfaces

Contents

        *   Command Line

*   GUI

*   Whitespace Rules

 

 

Command Line

A user can interact with Timber directly through the Timber command line interface . The command line interface allows the loading of XML documents, building indices, and querying the document with either a physical or logical plan (Refer to Query the Database for types of queries supported by Timber). The command line interface does not provide an interface for XQuery, please use the GUI and Soap server for that purpose.

Table 1. Required options

Options

Option Parameters

 

Parameter Explanation

-m

load | append | reorganize| index | logical | physical

 
-a appendToFile required for append only, this is the internal filename (without path) to append the datafile to

-d

datafile

required for load only, full or relative path name

-i

indexfile

required for index only, full or relative path name
-id indexfile required for removing index only, full or relative path name

-q

queryfile

required for logical or physical only, full or relative path name

 

Table 2. Optional options

Options

Option Parameters

Parameter Explanation

-r

1 | 0 

initialize volume, 1 to initialize, 0 not to initialize, default 0

-u

2|1 | 0

used in load only; 1 to create updatable indices; 0 to create n on-updatable; 2 not to create index during loading; default 0

-o

physical | tree | xml | empty

what to output, default xml

 -v

volume

volume  is the volume file where the data will be stored, default is the one in Resource\example.conf

 -n

#repeats

default 1

 -f

output file

store the XML or Physical plan into a file, for xml or phsyical only, default null

 -ci

optional multi color index

for both load and index, default null

 -cr:

optional multi color root id

for both load and index, default null
-u 2 | 1 | 0  for load only. 2: not to create index during loading; 1: to create updatable indices; 0:  to create non-updatable. default 0

     
Important Note:

·        Provide a path (full or relative) for datafile, indexfile, and queryfile (except when building an index or reorganizing a file).

·        See the page here for an example of indexfile, and types of indices currently supported.

·        If outfile is specified, the result is put into outfile, and will not be shown on the screen .

·       Whitespace handling for both data parsing and query parsing in Timber follows the rules given here.

Back to top

 

Examples  

Following are simple examples of using Timber through the command line interface:

 

Example1: Load a data file and initialize the volume (an element tag name index will be created automatically during the loading process by default; you can change the default setting by set the optional parameter "-u" to "1" or "2". 2 indicates that no indices should be built, and 1 indicates that indices optimized for updates should be built): 

 timber -m load -r 1 -d ..\Data\sbook.xml

Example2: build index: 

               

                               timber -m index -i ..\Data\sbook.idx

 

The sample index file can be found here. Note that some indices may be created when loading data (depending on the -u option), and you may not require additional indices, depending on your queries.

 

Example3: query using physical plan: 

 

                              timber -m physical -q ..\Data\sbook.qry


Example4: query using logical plan and return physical plan: 

 

                             timber -m logical -o physical -q ..\Data\sbook.log

 

Back to top

 

GUI

Set up GUI

 

To use the GUI, first you have to follow the steps below:

 

  1. Compile TimberSoap in the Timber Project
  2. Compile XQueryParser
  3. Copy the file “xquery.cgt” under the folder “tobeReplacedByRealPath/XQueryParser/resources” into the folder where the MainGUI.exe located (“tobeReplacedByRealPath/XQueryParser/MainGUI”)
  4. Load any files that you would like to query into Timber, and build indices needed by your queries (from the command line or GUI), if you have not done so yet. Important note: You can only build the join index from the command line, not from the GUI. For information on how to load data and build indices using the command line, read the Command Line query interface for details.

Use the GUI

 

Start up the GUI by double-clicking the icon of MainGUI.exe.

 

 

The start-up GUI window appears as follows.

 

 

Start the soap server of Timber by choosing menu “main – Start Server” in the GUI.

 

 

The GUI will then prompt you to select the soap server executable – simply locate and choose TimberSoap.exe.

 

 

The GUI will then ask you to select the database device to use – simply locate and choose the device that contains the loaded file you would like to query.

 

 

The soap server should now be successfully started. 

 

 

 

Congratulations! You may now use the GUI to query (and build indices). Refer to Query the Database for the types of queries supported by Timber).

 

Rounded Rectangular Callout: 5. Result of your query Rounded Rectangular Callout: 3. Choose the type of output you want Rounded Rectangular Callout: 2. Choose the type of your input

1. Input your query here

Rounded Rectangular Callout: 1. Input your query here

Rounded Rectangular Callout: 4. Click Button to run the query  

Back to top

 

Whitespace rules

Timber will remove or transform whitespace characters for both data parsing and query parsing according to the following rules:

RULE 1: Leading/trailing whitespace characters are skipped (lf, space, tab, cr, new line, vertical tab, or formfeed).

Example 5: Skip leading whitespace characters 

      A data file with the following content:

          [CR][TAB]<book><title>Hello</title></book>

     is treated as 

<book><title>Hello</title></book>

      The two whitespace characters (cr, tab) at the beginning of the document is discarded at the data parsing time when the file is loaded into Timber.

RULE 2: For non-leading/trailing whitespace characters (lf, tab, cr, new line, vertical tab, or formfeed), if the character before or after it is also a whitespace character, it is removed; otherwise it is converted into space, all spaces are preserved.

Example 6: Non-leading whitespace characters

      A data file with the following content:

         <book>[CR]
   [TAB]<title>[TAB]Hello[SP] World[TAB]![TAB][SP] </title>[CR]
   </book>

     is treated as 

<book><title>[SP]Hello[SP]World[SP]![SP]</title></book>

The first two whitespace characters (cr, tab) in the document is discarded as they are neighbors to each other. All the spaces are preserved. The first tab is transformed into space, as it is in between non-whitespace characters, while the last tab is discarded because it is followed by a space.

 

Back to top

 

Last updated: 07/20/2004