DBToaster - Getting Started

Getting Started

The DBToaster compiler can generate C++ or Scala code in two different forms:

Standalone Binary - Generating a binary that incrementally evaluates a given SQL query requires invoking a second stage compiler (g++ or scalac).
Source Code - Generated code can be easily embedded into user applications.

1. Evaluating a simple query

DBToaster provides the -r flag that generates, compiles, and runs the generated program in one simple step. This is a convenient way to check whether DBToaster and its dependencies have been successfully installed.

The following command evaluates the rst query on the toy dataset that ships with DBToaster:

$> cat examples/queries/simple/rst.sql
CREATE STREAM R(A int, B int) 
  FROM FILE 'examples/data/simple/r.dat' LINE DELIMITED csv;

CREATE STREAM S(B int, C int) 
  FROM FILE 'examples/data/simple/s.dat' LINE DELIMITED csv;

CREATE STREAM T(C int, D int)
  FROM FILE 'examples/data/simple/t.dat' LINE DELIMITED csv;

SELECT sum(A*D) AS AtimesD FROM R,S,T WHERE R.B=S.B AND S.C=T.C;

$> bin/dbtoaster -r examples/queries/simple/rst.sql
<snap>
    <ATIMESD>306</ATIMESD>
</snap>

real  0m0.019s
user  0m0.002s
sys   0m0.002s

2. Generating Standalone Binaries

Invoke DBToaster with -c [binary name] to create a standalone binary. By default, the compiler uses the C++ backend to produce an executable binary. Once invoked, the program prints out the results of all the queries contained in the input file after processing the whole input data.

The following command uses the C++ backend to generate the rst executable:

$> bin/dbtoaster examples/queries/simple/rst.sql -c rst

Running the rst executable produces the following output:

$> ./rst
<snap>
    <ATIMESD>306</ATIMESD>
</snap>

To produce a Scala jar file, invoke DBToaster with -l scala and the -c [binary name] flag as above. DBToaster will produce [binary name].jar, which can be run as a normal Scala program. For more details, please refer to Scala Code Generation.

3. Generating Source Code

DBToaster's primary role is to generate code that can be embedded into user applications. To produce a source file in C++ or Scala, invoke the compiler with -l [language], replacing [language] with cpp or scala. If the optional -o flag is used to redirect the generated code into a file, the target language will be auto-detected from the file suffix (".scala" for Scala and ".h", ".hpp", or ".cpp" for C++).

$> bin/dbtoaster examples/queries/simple/rst.sql -o rst.cpp
$> bin/dbtoaster examples/queries/simple/rst.sql -o rst.scala
$> ls
rst.hpp      rst.scala

See C++ Code Generation and Scala Code Generation for details.

< Installation | Architecture >