Time Series Database:JDBC-based TSQL queries

Step 1: Add the JDBC driver dependency

The TSQL JDBC driver is built on Apache Drill and published to a Maven repository. Add the following to your pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.alibaba.tsdb.tsql</groupId>
    <artifactId>tsql_jdbc_app</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <!-- https://mvnrepository.com/artifact/org.apache.drill.exec/drill-jdbc -->
        <dependency>
            <groupId>org.apache.drill.exec</groupId>
            <artifactId>drill-jdbc-all</artifactId>
            <version>1.15.0</version>
            <exclusions>
                <exclusion>
                    <groupId>org.slf4j</groupId>
                    <artifactId>log4j-over-slf4j</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <configuration>
                    <archive>
                        <manifest>
                            <mainClass>com.alibaba.tsdb.tsql.TsqlJdbcSampleApp</mainClass>
                        </manifest>
                    </archive>
                    <descriptorRefs>
                        <descriptorRef>jar-with-dependencies</descriptorRef>
                    </descriptorRefs>
                </configuration>
                <executions>
                    <execution>
                        <id>make-assembly</id>
                        <phase>package</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

This configuration packages your application and all its dependencies into a single JAR file.

Step 2: Write the connection code

The JDBC URL for TSDB uses the following format:

jdbc:drill:drillbit=<host>:<port>

In your Java project, create the com.alibaba.tsdb.tsql package and add the following TsqlJdbcSampleApp class:

package com.alibaba.tsdb.tsql;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class TsqlJdbcSampleApp {
    public static void main(String[] args) throws Exception {
        Connection connection = null;
        Statement stmt = null;

        try {
            // Step 1: Register the JDBC driver
            Class.forName("org.apache.drill.jdbc.Driver");

            // Replace with your TSDB instance hostname or IP address
            String host = "ts-uf64t3199j58j8251.tsql.hitsdb.rds.aliyuncs.com";
            // JDBC port for the TSQL service (default: 3306)
            int port = 3306;

            String jdbcUrl = String.format("jdbc:drill:drillbit=%s:%s", host, port);

            // Step 2: Open a connection
            System.out.println("Connecting to database @ " + jdbcUrl + "  ...");
            connection = DriverManager.getConnection(jdbcUrl);

            // Step 3: Create a statement
            System.out.println("Creating statement ...");
            stmt = connection.createStatement();

            // Step 4: Execute a TSQL query
            String sql = "select hostname, `timestamp`, `value` " +
                "from tsdb.`cpu.usage_system` " +
                "where `timestamp` between '2019-03-01' and '2019-03-01 00:05:00'";

            ResultSet rs = stmt.executeQuery(sql);

            // Step 5: Iterate over the ResultSet
            int row = 0;
            System.out.println("hostname\ttimestamp\tvalue");
            System.out.println("-----------------------------------------------------");
            while (rs.next()) {
                row++;
                System.out.println(rs.getString("hostname") + "\t" + rs.getTimestamp("timestamp") + "\t" + rs.getDouble("value"));
            }
            System.out.println("-----------------------------------------------------");
            System.out.println(row + " rows returned");

        } catch (SQLException se) {
            // Handle JDBC errors
            se.printStackTrace();
        } catch (Exception e) {
            // Handle driver registration errors
            e.printStackTrace();
        } finally {
            // Close resources
            try {
                if (stmt != null) stmt.close();
            } catch (SQLException se2) {
                // Nothing to do
            }
            try {
                if (connection != null) connection.close();
            } catch (SQLException se) {
                se.printStackTrace();
            }
        }
        System.out.println("Goodbye!");
    }
}

Step 3: Build and run

From the project root directory, build the application:

maven clean install

This produces tsql_jdbc_app-1.0-SNAPSHOT-jar-with-dependencies.jar in the target/ directory.

Run the JAR file:

java -jar target/tsql_jdbc_app-1.0-SNAPSHOT-jar-with-dependencies.jar

Functional limitations

• TSQL supports queries of time series data and metadata only (SELECT). Write, modify, and delete operations are not supported.

• TSDB does not support transactions.

JDBC API limitations

The following table lists the Connection API methods that are restricted or unsupported.