Connect to Imply Polaris over JDBC

Java database connectivity (JDBC) is an application programming interface (API) for connecting and executing SQL queries on database management systems. You can use a JDBC connection to integrate Imply Polaris with your Java applications and business intelligence tools.

Prerequisites

To establish a connection to Polaris using JDBC, you need the following:

• The organization name represents the custom domain through which you access Polaris. For example, in https://example.app.imply.io, the organization name is example.
• Bearer token of your OAuth client with the AccessQueries permission. See Authenticate with OAuth to obtain an access token.

Connect from Java applications

You can connect to Imply Polaris from your custom Java code. Verify that you have an OAuth token as described in the Prerequisites. Additionally, download the Avatica JDBC driver available from Imply. Load the JDBC driver when running the Java program.

The following steps are required to establish a JDBC connection with Polaris:

1. Define the JDBC connection string. The JDBC connection string uses the following syntax:

   jdbc:avatica:remote:url=https://ORGANIZATION_NAME.jdbc.REGION.CLOUD_PROVIDER.api.imply.io/druid
   

   In the connection URL, set ORGANIZATION_NAME to your organization name. Replace REGION with the cloud region of your Polaris project and CLOUD_PROVIDER with the cloud service for your Polaris infrastructure.

2. Authenticate your connection by defining a password connection property and passing your bearer token as the property value.

The following example shows a Java program that connects to Polaris and issues a SQL query to the "Koalas to the Max" table. In the example below, the environment variable IMPLY_TOKEN stores the token value.

import java.sql.*;
import java.util.Properties;
public class JdbcPolaris {

    public static void main(String args[]) {

        // define the JDBC URL; be sure to specify your own organization name
        String url = "jdbc:avatica:remote:url=https://ORGANIZATION_NAME.jdbc.REGION.CLOUD_PROVIDER.api.imply.io/druid";

        // get the bearer token from the environment variable
        String token = System.getenv("IMPLY_TOKEN");

        // define query directed to "Koalas to the Max" table
        String query = "SELECT continent, COUNT(*) AS counts FROM \"Koalas to the Max\" GROUP BY 1 ORDER BY counts DESC";

        // instantiate a Properties object and store the token in the "password" key
        Properties connectionProperties = new Properties();
        connectionProperties.setProperty("password", token);

        // establish a connection to the database
        try (Connection connection = DriverManager.getConnection(url, connectionProperties)) {
            try (

                // create a Statement object for sending SQL statements and execute query 
                final Statement statement = connection.createStatement();
                final ResultSet rs = statement.executeQuery(query);
            ) {
                // iterate over each row of results and print to stdout
                while (rs.next()) {
                    String location = rs.getString("continent");
                    int amount = rs.getInt("counts");
                    System.out.println(location + ":\t\t" + amount);
                }
            }
        } catch (Exception e) {
            System.out.println(e.toString());
        }
    }
}

Token revocation

If your application becomes compromised, contact Polaris Support to revoke access tokens and remove the OAuth client.

Learn more

• For information on how to query tables in Polaris, see the Query API.
• To connect Polaris to Looker or Tableau, see Connect from business intelligence applications.