

FastBit Front Page	Research Publications	Software Documentation	Software Download	Software License

Organization: LBNL » CRD » SDM » FastBit » Documentation » Example

FastBit Example Code: rara.cpp

This page explains the small example in file examples/rara.cpp.

Command line arguments

The program rara.cpp accepts the following command line arguments (in fixed order)

examples/rara data-dir query-conditions [column-to-print [column-to-print ...]]

For example, after running 'make check', one can issue the following command

examples/rara tests/tmp/t1 "c between 10 and 20"

and see the following output

SELECT count(*) FROM tests/tmp/t1 WHERE c between 10 and 20
--> 22

The next command

examples/rara tests/tmp/t1 "c between 10 and 20" c

produces the following output

SELECT c FROM tests/tmp/t1 WHERE c between 10 and 20
--> c (with counts)
10,     2
11,     2
12,     2
13,     2
14,     2
15,     2
16,     2
17,     2
18,     2
19,     2
20,     2

Annotated Code

    // construct a data partition from the given data directory.
    ibis::part apart(argv[1], static_cast<const char*>(0));

This statement creates an ibis::part object that encapsulates a data partition. The second nil pointer is required because there is another constructor that takes a single string but performs a very different function.

    // create a query object with the current user name.
    ibis::query aquery(ibis::util::userName(), &apart);

This statement creates an ibis::query object which represent our query. A FastBit query is always associated with a data partition.

    // assign the query conditions as the where clause.
    int ierr = aquery.setWhereClause(argv[2]);

A query object is required to have a where clause (query conditions) before being evaluated. This function returns 0 to indicate success and a negative number to indicate error. This is often the case when an integer is returned from a FastBit function.

	ierr = aquery.setSelectClause(sel.c_str());

If any column to print is specified on the command line, they are concatenated together into a single string (named sel in rara.cpp). The pointer to the characters is passed to setSelectClause to be recorded as a part of the query.

	ierr = aquery.evaluate(); // evaluate the query

The primary function to evaluate a query is ibis::query::evaluate. This function evaluate the query conditions and identify the records that satisfy the conditions. In some cases, it may be faster to use ibis::query::estimate to get an approximate answer first.

	    std::cout << aquery.getNumHits();

After the function ibis::query::evalaute is called, one may find out how many records satisfy the query conditions by calling ibis::query::getNumHits.

	    aquery.printSelected(std::cout);

If a select clause was successfully set, the function ibis::query::printSelected will print the columns of the selected records to standard output.

Note

The file examples/rara.cpp contains additional code for error checking and optional command-line arguments. The Doxygen documentation of the file is available on-line.