Doradus In The Wild

Just learning about Doradus? Here are some links to recent presentations:

What is Doradus?

New to Doradus? There's a quick overview in this wiki page: Doradus Overview. The Wiki pages also have detailed information on these key topics: Doradus OLAP, Doradus Spider, and Doradus Administration. If you like nice big PDF files, see the docs folder. Keep reading to find out what's new and tips for downloading, building, and running Doradus.

What's New?

The v2.4 release is now available! Here's a summary of some of the new features:

Doradus Components

Doradus consists of following components:

Requirements

Doradus requires Java 1.8 or higher and Cassandra 2.x.

Installing Cassandra

You can use an existing Cassandra installation or download Cassandra on your own. Any 2.x release should work, though we've tested Doradus the most with 2.0.x. The protocol that Doradus uses to communicate with Cassandra (Thrift or CQL) as well as the Cassandra host name(s) and port are configured in the doradus.yaml.

Building Doradus

Doradus supports Maven and Ant builds, though each places binaries and config files in slightly different directory structures. To build using Maven, from the root folder enter:

mvn clean install dependency:copy-dependencies -Dgpg.skip=true

To build Doradus using Ant, just enter ant from the root directory. See the Doradus Administration document for more details on building Doradus.

Configuring Doradus

All default configuration come from the doradus.yaml file. You can edit it directly or override parameters in command line arguments by prefixing each parameter name with a '-' and specifying the parameter value next. For example, doradus.yaml defines restport: 1123, which sets the REST API listening port number. To override this to 5711, add the command line argument:

java -cp ... com.dell.doradus.core.DoradusServer -restport 5711

When Doradus runs, it connects to the Cassandra server(s) as configured in doradus.yaml. If Cassandra is not running when the server starts, it will try connecting every 5 seconds until successful. In the mean time, REST requests that require the database connection will receive a 503 response.

See the Doradus Administration documentation for more information about configurating and running Doradus.

Running Doradus

If you build Doradus with Maven, you can run Doradus as a stand-alone process using the embedded Jetty server to handle REST commands. From the doradus-jetty folder enter:

java -cp ../doradus-server/target:target/classes:target/dependency/* com.dell.doradus.core.DoradusServer

For historic reasons, the Ant build uses a slightly different folder structure. To run Doradus with the embedded Jetty server after an Ant build, from the doradus-server folder enter:

java -cp ./lib/*:./config/* com.dell.doradus.core.DoradusServer

Since Doradus is stateless, multiple instances can be run against the same Cassandra cluster.

Accessing Doradus

A browser can be used to access Doradus REST API commands. For example, to list applications that have been defined:

http://localhost:1123/_applications

An application is the name Doradus uses for what other databases might call a schema. To create a minimal application (managed by Doradus Spider by default), you can use the following curl command:

curl -H "content-type: text/xml" -d '<application name="Stuff"/>' http://localhost:1123/_applications

Doradus supports XML and JSON for all commands; below is the same command using JSON:

curl -H "content-type: application/json" -d '{"Stuff": {}}' http://localhost:1123/_applications

These commands create a Spider-managed application called Stuff. Initially, the application has no predefined tables. However, an application option called AutoTables defaults to true, so new tables are created automatically as they are referenced. Spider also supports dynamically-added fields, so you can immediately create a new table and add some objects to it with the following POST command and message. We'll use JSON for this example:

POST /Stuff/Messages
{"batch": {
    "docs": [
        {"doc": {
            "Subject": "Here's a subject",
            "Body": "Here a body"
        }},
        {"doc": {
            "Subject": "Here's another subject",
            "Body": "Here's another body"
        }}
    ]
}}

This command creates a new table called Messages and adds two new objects. The Subject and Body fields are indexed as full text fields, and each object is assigned a default _ID. You can fetch all objects in the table using this REST command:

GET /Stuff/Message/_query?q=*

You can use a browser or your favorite HTTP library to send REST commands. Alternatively, Java applications can use the Doradus Client library to hide the REST API and use plain old Java objects (POJOs). See the doradus-client Java docs for more information.

Running Regression Tests

The doradus-regression-tests folder contains a custom regression test application and a set of test scripts. To run regression tests, first modify the file ./doradus-regression-tests/src/main/resources/config.xml, if necessary, to point to the regression-tests base directory. Example:

<DEFINE name="tests.root" value="/Users/JDoe/Doradus/doradus-regression-tests/src/main/regression-tests"/>

Under the regression-tests folder, subfolders have names such as bugs and features. Within a subfolder, a test is defined by the following files:

The regression test processor's main is com.dell.doradus.testprocessor.Program and requires no parameters. Here's a simple script that can be used from the ./doradus-regression-tests folder to run the tests:

java -cp ./target/classes:./target/dependency/* com.dell.doradus.testprocessor.Program

If a test fails, the test processor will create two files:

The test processor also creates an HTML report with the file name defined in config.xml as <report>. This provides a quick overview of the test run, including differences for failed tests.

You can limit the test suite to specific tests by modifying config.xml. For example, to run only test bd.010.SPIDER in the bugs directory only:

<DEFINE name="tests.root"
   value="C:\DELL-OSS\Doradus\doradus-regression-tests\src\main\regression-tests\bugs"/>
<test-suite root="${tests.root}">
    <include>
        <dir path=".">
            <test name="bd.010.SPIDER"/>
        </dir>
    </include>
</test-suite>

Resources

The following are the primary Doradus resources:

License

Doradus is available under the Apache License Version 2.0. See LICENSE.txt or http://www.apache.org/licenses/ for a copy of this license.