Core+ Flight SQL ODBC

The Deephaven Enterprise Flight SQL ODBC Driver enables ODBC-compliant applications such as PowerBI, Microsoft Excel, and Tableau to connect to Deephaven Core+ servers. The driver is built on Flight SQL, a protocol on top of Arrow Flight that exposes SQL-like capabilities. Deephaven Core+ workers provide a built-in Flight SQL server that makes tables in the global query scope available as named tables, queryable through the default Flight SQL catalog using standard SQL.

Important

The Deephaven Enterprise Flight SQL ODBC Driver is currently available for Windows only (64-bit). Linux and macOS are not supported at this time.

Note

Only SELECT queries are supported; INSERT, UPDATE, and DELETE queries are not currently supported.

While Flight SQL / ODBC may be a convenient starting point for BI tool integration, the Flight SQL APIs are not Live Dataframe APIs. If you need to receive real-time updates, use a Deephaven-native client instead, such as the Deephaven Core+ Python client or the Deephaven Core+ Java client.

Quick start

  1. Install the driver — Run the MSI installer. The installer registers the driver automatically. See Installation.
  2. Configure a DSN — Open odbcad32.exe, create a new DSN, and fill in your connection details. See Configure a DSN.
  3. Test your connection — Click Test Connection in the DSN configuration dialog to verify connectivity. See Create a DSN for details.
  4. Connect from an application — Open PowerBI, Excel, or another ODBC-compliant tool and select your DSN. See Application integration.

Prerequisites

  • Operating system: Windows 10 or Windows 11 (64-bit).
  • Administrator privileges for installation.
  • Access to a running Deephaven Core+ instance with Flight SQL enabled (Grizzly version 1.20240517.491 or later).
  • The name of a running Persistent Query (PQ) you want to connect to.

Installation

Download and run the MSI installer

  1. Obtain Deephaven-Enterprise-Flight-SQL-ODBC-<version>-win64.msi from your Deephaven administrator or download location.

  2. Double-click the MSI file. If prompted by User Account Control (UAC), click Yes to allow the installation.

  3. Follow the installation wizard:

    • Click Next on the welcome screen.

      Installation Welcome

    • Review and accept the Apache 2.0 license agreement.

      Installation License

    • Choose the installation directory (default: C:\Program Files\Deephaven Enterprise Flight SQL ODBC\).

    • Verify the program is signed by Deephaven when prompted by UAC.

      UAC Verify Publisher

    • Click Yes to allow the installer to make changes to your system and complete the installation.

Verify installation

  1. Open ODBC Data Source Administrator (64-bit):
    • Press Win + R, type odbcad32.exe, and press Enter; or
    • Search for "ODBC Data Sources (64-bit)" in the Start menu.
  2. Go to the Drivers tab.
  3. Confirm that Deephaven Enterprise Flight SQL appears in the list with version information and a file path.

Important

Always use the 64-bit ODBC Administrator (C:\Windows\System32\odbcad32.exe). Do not use the 32-bit version ( C:\Windows\SysWOW64\odbcad32.exe). The driver is 64-bit only.

Configure a DSN

A Data Source Name (DSN) stores your connection settings so you don't have to enter them every time you connect from an application. Windows supports two types of DSN:

  • User DSN — Available only to the current Windows user. Recommended for personal workstations.
    • System DSN — Available to all users on the machine. Recommended for shared servers and service accounts.

Create a DSN

  1. Open ODBC Data Source Administrator (64-bit) (see Verify installation).

  2. Go to the User DSN tab or the System DSN tab, depending on the scope you need.

  3. Click Add..., select Deephaven Enterprise Flight SQL, and click Finish.

  4. Fill in the connection fields:

    DSN Configuration Window

    FieldRequiredDescription
    Data Source NameYesA descriptive name (e.g., Deephaven Production). This is the name you select in applications like PowerBI.
    DescriptionNoOptional description (e.g., Production analytics cluster).
    Host NameYesDeephaven server hostname or IP address (e.g., deephaven.mycompany.com).
    PortYesServer port. Contact your Deephaven administrator for the correct value.
    Persistent Query NameYesName of the Persistent Query to connect to (e.g., my_analytics_pq).
    Authentication TypeYesBasic Authentication (username/password) or Private Key Authentication (key file). See Authentication.

  5. Click Test Connection. If successful, you'll see a Test Connection Succeeded dialog.

  6. Click OK to save the DSN.

Authentication

The driver supports two mutually exclusive authentication methods:

Basic Authentication

Enter your User and Password in the DSN dialog. Both fields are enabled when Basic Authentication is selected.

Private Key Authentication

When Private Key Authentication is selected, the User and Password fields are disabled. Instead, provide the * Private Key File Path* — the full path to your Deephaven-format private key file (e.g., C:\Users\yourusername\deephaven_key.txt). See private key authentication for more details on how private key authentication works in Deephaven. Your Deephaven administrator should provide you with a private key file if your environment is configured to use this authentication method.

Connection string format

To connect programmatically (without a pre-configured DSN), use an ODBC connection string:

Basic Authentication:

Private Key Authentication:

Connection string parameters:

ParameterRequiredDefaultDescription
HOSTYes—Server hostname or IP address.
PORTYes—Server port.
UIDBasic auth only—Username.
PWDBasic auth only—Password.
PrivateKeyFilePathKey auth only—Path to Deephaven-format private key file. Mutually exclusive with UID/PWD.
PQNameYes—Persistent Query name.

Application integration

PowerBI Desktop

  1. Open PowerBI Desktop.

  2. Click Home → Get Data → Other.

  3. Search for ODBC, select ODBC, and click Connect.

    PowerBI Get Data

  4. Select your DSN from the Data source name (DSN) dropdown. Expand Advanced options and enter a SQL SELECT statement in the SQL statement input box to query a specific table on load.

    Note

    Do not include a trailing semicolon (;) in the SQL statement.

    PowerBI From ODBC

  5. Click OK. The query result is displayed directly in PowerBI.

    PowerBI Query Result

    Example query result loaded from a Deephaven Core+ Persistent Query.

Microsoft Excel

  1. Open Excel.

  2. Go to Data → New Query → From Other Sources → From ODBC.

    Excel Import Data

  3. Select your DSN from the Data source name (DSN) dropdown. Expand Advanced options and enter a SQL SELECT statement in the SQL statement input box.

    Note

    Do not include a trailing semicolon (;) in the SQL statement.

    Excel From ODBC

  4. Click OK. The query result is displayed directly in Excel.

    Excel Query Result

    Example query result loaded from a Deephaven Core+ Persistent Query.

Python

Use the pyodbc library to connect to Deephaven Core+ from Python on Windows.

Important

Always pass autocommit=True to pyodbc.connect(). The driver does not implement the SQL_ATTR_AUTOCOMMIT attribute, so omitting this parameter will cause a HYC00 Optional feature not implemented error.

Install pyodbc

Connect using a DSN

Connect using a connection string

Basic Authentication:

Private Key Authentication: