6.9. Java¶

6.9.1. Introduction¶

This document is an introduction to the quasardb Java API. It is primarily focused on timeseries, and will guide you through the various ways you can interact with the QuasarDB backend.

Note

If you are looking for a more comprehensive reference, please refer directly to our Javadoc.

6.9.2. Installation¶

The quasardb Java API is available in our Maven repositiory.

To use it in your project, you need to add the repository maven.quasardb.net

Then, you must add a dependency to net.quasardb:qdb

For example, if you’re using Maven, your pom.xml should look like:

<project>
[...]
<repositories>
<repository>
<id>quasardb</id>
<name>Quasardb Official Repository</name>
<url>http://maven.quasardb.net</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>net.quasardb</groupId>
<artifactId>qdb</artifactId>
<version>2.3.0</version>
</dependency>
</dependencies>
</project>


Or, if you use Gradle, your build.gradle should look like:

apply plugin: 'java'

repositories {
maven {
url "http://maven.quasardb.net"
}
}

dependencies {
compile 'net.quasardb:qdb:2.3.0'
}


6.9.3. Connecting to the database¶

QuasarDB provides thread-safe access to a cluster using the Session class. This class comes with a built-in, high-performance connection pool that can be shared between multiple threads. You are encourage to reuse this object as often as possible, ideally only creating a single instance during the lifetime of your JVM process.

Establishing a connection¶

You connect to a QuasarDB cluster by calling the connect function of the Session class and establishing a connection with a QuasarDB cluster like this:

try {
Session mySession = Session.connect(uri);
} catch (ConnectionRefusedException ex) {
System.err.println("Failed to connect to " + uri +
", make sure server is running!");
System.exit(1);
}


Establishing a secure connection¶

By providing additional SecurityOptions when establishing a connection, we get a secure connection to the cluster:

try {
"userPrivateKey",
"clusterPublicKey"),
uri);
} catch (ConnectionRefusedException ex) {
System.err.println("Failed to connect to " + uri +
", make sure server is running!");
System.exit(1);
}


6.9.4. Table management¶

The Java API exposes its timeseries using the Table class.

Create¶

You can invoke the create to create a new timeseries table:

Column[] columns = {
new Column.Double("double_val"),
new Column.Int64("int_val"),
new Column.Timestamp("ts_val")
};

Table myTable = Table.create(session, "my_table", columns, 3600000);


The example above will create a table my_table with three different columns with a shard size of 1 hour. You can choose to omit the shard size, in which case the default shard size of 1 day will be chosen. Please refer to the Column class to see a full overiew of the supported column types.

6.9.5. Writing data¶

When writing data to a Table, QuasarDB maintains a local buffer before writing data. This approach ensures batches of data are written in bulk, minimalising overhead and improving performance.

We provide several mechanisms for you to write data. Which mechanism works best for you depends upon your use case, but when in doubt you should use the AutoFlushWriter.

Note

Individual batches are always written atomically, which means that a buffer is either completely visible to other clients, or not at all.

Explicit flushing¶

The most basic write access is to make use of a Writer and periodically calling flush on that Writer. You can create a new Writer by calling the writer method of the Table class like this:

Writer w = Table.writer(session, myTable);
for (long i = 0; i < 10000; ++i) {
w.append(generateRow());
}
w.flush();
w.close(); // call when done


The code above will locally buffer all 10,000 rows before writing them all in a single, atomic batch operation when flush is called. Naturally, these rows will not be visible to any other client until the flush operation completes.

Implicit flushing¶

If all you care about is that the buffer is flushed periodically every N rows, we provide an AutoFlushWriter which you can create by calling the autoFlushWriter method of the Table class like this:

Writer w = Table.autoFlushWriter(session, myTable);
for (long i = 0; i < 75000; ++i) {
w.append(generateRow());
}
w.flush(); // otherwise some data might not be fully flushed!
w.close();


The code above initialises an AutoFlushWriter with default arguments. By default, this means 50,000 rows. If you would like to excercise more control over flush interval behaviour, you can customise the flush interval like this:

Writer w = Table.autoFlushWriter(session, myTable, 1);
for (long i = 0; i < 1000; ++i) {
w.append(generateRow());
}
// flush not necessary in this case!


As a means of example, the code above will flush the buffer every 1 rows (i.e. every write is a flush). In practice, we recommend you to use as high a number as possible that works for your use case.

The Java API provides access to both a bulk Reader class which should be used for large table scans, and a Reader class which can be used for more refined querying.

Assuming you already have a reference to a Reader, you can scan this table as follows:

Reader r = Table.reader(session, myTable, myTimeRange);
while (r.hasNext() == true) {
Row row = r.next();
System.out.println(row.toString());
}


As you can see above, the Reader exposes a simple Iterator interface that allows you to iterate over Row objects. When you prefer a more functional-style, we also expose the underlying dataset as a Java8 stream:

Table
.stream()
.parallel()
.filter(myClass::isValid)
.forEach(System.out::println);


Query¶

Note

For more ad-hoc analysis and aggregations, you can use our Query class:

Result r = Query.of("select double_val from "  + myTable.getName() + " in range(now, +1h)")
.execute(session);
for (Result.Table t : r.tables) {
System.out.println("has table with results: " + t.toString());
}


And the Query API also provides Stream-based access to the Result set:

Query.of("select double_val from "  + myTable.getName() + " in range(now, +1h)")
.execute(session)
.parallel()
.filter(myClass::isValid)
.forEach(System.out::println);


The code above will query the double_val column from your time range, and return the entire Result object. We also suggest you explore our Javadoc to see a more comprehensive overview on how to inspect the Result object.

6.9.7. Reference¶

This chapter contains a short summary of our Java API. For more a complete reference, please see our Javadoc.

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::Session::SecurityOptions” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::Session” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::ts::Table” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::ts::Column” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::ts::Writer” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::ts::AutoFlushWriter” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::ts::Reader” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::ts::Query” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::ts::TimeRange” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::ts::Row” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::ts::Value” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml

Warning

doxygenclass: Cannot find class “net::quasardb::qdb::ts::Result” in doxygen xml output for project “qdb_java_api” from directory: ../../apis/jni/output/xml