Skip to main content
Kinetica provides a SQL interface through its ODBC & JDBC drivers, which run on Linux, Mac, & Windows. For details on the extent of SQL compliance, see the SQL section.

Connecting

KiSQL

KiSQL is a Kinetica JDBC-based SQL CLI client that is available on GitHub. Details can be found on the Kinetica SQL (KiSQL) page.

JDBC Applications

Java applications which use JDBC can reference the Kinetica JDBC driver in the Maven Central Repository as a pom.xml dependence:
Dependency
Gradle users may need to add the Kinetica Nexus Repository to their configuration:
To create a connection, using a connection string:
To create a connection, using properties:

JDBC Clients

JDBC connections require the Kinetica JDBC driver. Acquire the JDBC client JAR, kinetica-jdbc-7.2.<X>.<Y>-jar-with-dependencies.jar, from either:
  • the JDBC Client Project on GitHub
  • under /opt/gpudb/connectors/jdbc on default Kinetica installations
The following is the general driver and connection information that should be used when configuring a client.
  • Driver: <point to the downloaded JAR file>
  • Connection String:
  • Class Name: com.kinetica.jdbc.Driver
See ODBC/JDBC Configuration for additional configuration parameters.

Secure Connections

When connecting to a Kinetica instance over HTTPS, the connection string should reference the database’s secure address.
See SSL Parameters for additional parameters that may be necessary to use when connecting over SSL.
Set the URL parameter on the JDBC connection string to use the HTTPS-enabled database endpoint.

Failover Connections

When connecting to a Kinetica instance with one or more failover clusters, the connection string should be updated to contain a comma-delimited list of head node addresses for all clusters. The URL of the primary cluster can also be specified. Add a URL parameter to the JDBC connection string to contain all cluster head node addresses and add a PrimaryURL parameter designating the cluster that should be tried first.

ODBC

The ODBC Client must be installed for the environment in which it will be used. The following sections will detail how to install & configure the client in Windows. Kinetica provides both a 32-bit & 64-bit Windows ODBC Client driver. The 32-bit version of Windows requires the 32-bit driver. The 64-bit version of Windows can use either the 32-bit or 64-bit driver, or both, as needs warrant. For instance, a user running 64-bit Windows and wanting to make ODBC connections to Kinetica from a 32-bit version of Excel will need the 32-bit driver. A user with the same OS using the 64-bit Tableau will need the 64-bit driver. A user wanting to use both will need both drivers.
  1. Download & install the ODBC Client for Windows following the instructions provided there
  2. Launch ODBC Data Source Administrator (64-bit or 32-bit, as needed)
  3. Click the System DSN tab
  4. Click the Add button to add a DSN
  5. Choose Kinetica ODBC Client, and click Finish
  6. Fill in the DSN Setup parameters (the following settings are examples - you may have to change some for your environment):
    • Description: Kinetica
    • URL:
    • Leave User and Password blank
  7. Click OK
See ODBC/JDBC Configuration for additional configuration parameters.

Secure Connections

When connecting to a Kinetica instance over HTTPS, the connection string should reference the database’s secure address.
See SSL Parameters for additional parameters that may be necessary to use when connecting over SSL.
Set the URL parameter to use the HTTPS-enabled database endpoint.

Failover Connections

When connecting to a Kinetica instance with one or more failover clusters, the connection string should be updated to contain a comma-delimited list of head node addresses for all clusters. The URL of the primary cluster can also be specified. Modify the URL parameter to contain all cluster head node addresses and add a PrimaryURL parameter designating the cluster that should be tried first. URL:
PrimaryURL:

Tableau

  1. Install the ODBC Client - see ODBC Installation above
  2. In Tableau, connect to Other Databases (ODBC)
    • DSN: Kinetica
    • Click Connect
    • Click Sign In
    • Database: KINETICA
    • Schema: <choose one>
      • To use the user’s default schema, don’t choose a schema (leave as Select Schema)
    • Pick your table
Tableau may give a warning about not all features being supported by the ODBC driver; this should be able to be safely ignored for most applications.

Excel

  1. Install the ODBC Client - see ODBC Installation above
  2. In Excel, click the Data tab at the top
  3. Click the Get External Data > From Other Sources button, then click From Data Connection Wizard
  4. In the Connection Wizard, choose ODBC DSN and click Next >
  5. Select one of the ODBC data sources (i.e., DSNs) you created above (e.g., Kinetica), and click Next >
  6. Continue with the wizard to create a link to all the tables or a specific table, and save an ODC file, etc.
  7. Click the Finish button
To read in data using the ODC file created above:
  1. In Excel, click the Data tab at the top
  2. Click Get External Data > Existing Connections
  3. Choose the ODC file you created above, and click Open
  4. Select a Table to import
  5. Select where you want the data to appear, and click the OK button

DBeaver

  1. Acquire the JDBC Driver
  2. Download & install DBeaver
  3. Configure DBeaver with the Kinetica JDBC driver
    1. On the Database menu, select Driver Manager
    2. Click New to create a new driver connection
    3. Complete the driver configuration page:
      • Driver Name: Kinetica
      • Class Name: com.kinetica.jdbc.Driver
    4. Click the Libraries tab; then click Add File and select the downloaded JAR:
    5. Click OK
    6. Click Close to exit Driver Manager
  4. Configure a connection:
    1. On the File menu, select New
    2. Ensure that Database Connection is selected and click Next >
    3. Select Kinetica and click Next >
    4. Click Connection Details and name the connection
      • Connection name: name for the connection
    5. Click Back
    6. Complete the connection configuration
      • JDBC URL:
    7. Enter authentication credentials
      • Username/password style authentication
        • Username: name of connecting user (admin for database administrator connection)
        • Password: password for connecting user
      • OIDC/OAuth style authentication
        1. Disable username/password auth
          • Save password: check this box, leaving Username & Password blank
        2. Click the Driver Properties tab
        3. Enter OAuth credentials
          • OAuthToken: OAuth token to use for authentication
    8. Click Finish to complete the connection configuration

Other JDBC Clients

For other clients, see JDBC Applications for the general setup to use.
There are many Java SQL clients available; a list can be found here.

ODBC/JDBC Configuration

Unless noted, the configuration parameters are the same for ODBC & JDBC, though the locations of the configurations are not.
  • Windows ODBC - Settings are stored in the registry in HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\&lt;DSN NAME&gt;
  • JDBC - Settings are passed on the connection string, separated by semicolons; e.g.:
Some settings of note follow.

Standard Parameters

Server Override Parameters

The following are optional parameters that could be used to override the default settings, which are set by the server. See the Configuration Reference for more information on configuring the SQL Engine server-side. The default value for each of these options is 0.

Client Parameters

The following optional parameters may be used to change the ODBC/JDBC Client behavior.

SSL Parameters

The following optional parameters should be used when connecting over SSL.

Logging

Kinetica logs inbound SQL requests, internal calls made on behalf of those requests, and other debugging information. These logs can be found in the following log files:
  • /opt/gpudb/core/logs/host-manager-<hostname>-<datetime>.log: Contains all endpoint calls, including the initial call to /execute/sql and any endpoint calls made as a result of servicing the request
  • /opt/gpudb/sql/logs/sql-engine-<kinetica-hostname>.log: Contains detailed error messages