The Open Database Connectivity (ODBC) driver is a read-only ODBC driver for Windows and macOS that lets you connect business intelligence (BI) and data visualization applications like Tableau, Microsoft Excel, and Power BI to the SQL plugin.
For information on downloading and using the driver, see the SQL repository on GitHub.
The ODBC driver is compatible with ODBC version 3.51.
Supported OS versions
The following operating systems are supported:
|Windows||Windows 10, Windows 11|
|macOS||Catalina 10.15.4, Mojave 10.14.6, Big Sur 11.6.7, Monterey 12.4|
|DSN||A DSN (Data Source Name) is used to store driver information in the system. By storing the information in the system, the information does not need to be specified each time the driver connects.|
|.tdc file||The TDC file contains configuration information that Tableau applies to any connection matching the database vendor name and driver name defined in the file. This configuration allows you to fine-tune parts of your ODBC data connection and turn on/off certain features not supported by the data source.|
To install the driver, download the bundled distribution installer from here or by build from the source.
Open the downloaded
OpenSearch SQL ODBC Driver-<version>-Windows.msiinstaller.
The installer is unsigned and shows a security dialog. Choose More info and Run anyway.
Choose Next to proceed with the installation.
Accept the agreement, and choose Next.
The installer comes bundled with documentation and useful resource files to connect to various BI tools (for example, a
.tdcfile for Tableau). You can choose to keep or remove these resources. Choose Next.
Choose Install and Finish.
The following connection information is set up as part of the default DSN:
Host: localhost Port: 9200 Auth: NONE
To customize the DSN, use ODBC Data Source Administrator which is pre-installed on Windows 10.
Before installing the ODBC Driver on macOS, install the iODBC Driver Manager.
Open the downloaded
OpenSearch SQL ODBC Driver-<version>-Darwin.pkginstaller.
The installer is unsigned and shows a security dialog. Right-click on the installer and choose Open.
Choose Continue several times to proceed with the installation.
Choose the Destination to install the driver files.
The installer comes bundled with documentation and useful resources files to connect to various BI tools (for example, a
.tdcfile for Tableau). You can choose to keep or remove these resources. Choose Continue.
Choose Install and Close.
Currently, the DSN is not set up as part of the installation and needs to be configured manually. First, open
sudo /Applications/iODBC/iODBC\ Administrator64.app/Contents/MacOS/iODBC\ Administrator64
This command gives the application permissions to save the driver and DSN configurations.
- Choose ODBC Drivers tab.
- Choose Add a Driver and fill in the following details:
- Description of the Driver: Enter the driver name that you used for the ODBC connection (for example, OpenSearch SQL ODBC Driver).
- Driver File Name: Enter the path to the driver file (default:
- Setup File Name: Enter the path to the setup file (default:
- Choose the user driver.
- Choose OK to save the options.
- Choose the User DSN tab.
- Select Add.
- Choose the driver that you added above.
- For Data Source Name (DSN), enter the name of the DSN used to store connection options (for example, OpenSearch SQL ODBC DSN).
- For Comment, add an optional comment.
- Add key-value pairs by using the
+button. We recommend the following options for a default local OpenSearch installation:
localhost- OpenSearch server endpoint
9200- The server port
NONE- The authentication mode
(blank)- The username used for BASIC auth
(blank)- The password used for BASIC auth
10- The number of seconds to wait for a response from the server
0- Do not use SSL for connections
- Choose OK to save the DSN configuration.
- Choose OK to exit the iODBC Administrator.
Customizing the ODBC driver
The driver is in the form of a library file:
opensearchsqlodbc.dll for Windows and
libopensearchsqlodbc.dylib for macOS.
If you’re using with ODBC compatible BI tools, refer to your BI tool documentation for configuring a new ODBC driver. Typically, all that’s required is to make the BI tool aware of the location of the driver library file and then use it to set up the database (i.e., OpenSearch) connection.
Connection strings and other settings
The ODBC driver uses an ODBC connection string. The connection strings are semicolon-delimited strings that specify the set of options that you can use for a connection. Typically, a connection string will either:
- Specify a Data Source Name (DSN) that contains a pre-configured set of options (
- Or, configure options explicitly using the string (
You can configure the following driver options using a DSN or connection string:
All option names are case-insensitive.
| ||Data source name that you used for configuring the connection.|| ||-|
| ||Hostname or IP address for the target cluster.|| ||-|
| ||Port number on which the OpenSearch cluster’s REST interface is listening.|| ||-|
| ||Authentication mechanism to use.|| || |
| ||[ || ||-|
| ||[ || ||-|
| ||[ || ||-|
| ||Whether to establish the connection over SSL/TLS.|| || |
| ||Indicates whether certificate hostname verification should be performed for an SSL/TLS connection.|| || |
| ||The maximum time to wait for responses from the host, in seconds.|| || |
| ||Severity level for driver logs.|| || |
| ||Location for storing driver logs.|| || |
You need administrative privileges to change the logging options.
Connecting to Tableau
- Make sure the DSN is already set up.
- Make sure OpenSearch is running on host and port as configured in DSN.
- Make sure the
.tdcis copied to
<user_home_directory>/Documents/My Tableau Repository/Datasourcesin both macOS and Windows.
Start Tableau. Under the Connect section, go to To a Server and choose Other Databases (ODBC).
In the DSN drop-down, select the OpenSearch DSN you set up in the previous set of steps. The options you added will be automatically filled in under the Connection Attributes.
Select Sign In. After a few seconds, Tableau connects to your OpenSearch server. Once connected, you will be directed to the Datasource window. The Database will be already be populated with the name of the OpenSearch cluster. To list all the indices, click the search icon under Table.
Start experimenting with data by dragging the table to the connection area. Choose Update Now or Automatically Update to populate the table data.
See more detailed instructions in the GitHub repository.
Unable to connect to server.
This is most likely due to OpenSearch server not running on host and post configured in DSN. Confirm host and post are correct and OpenSearch server is running with OpenSearch SQL plugin. Also make sure
.tdc that was downloaded with the installer is copied correctly to
<user_home_directory>/Documents/My Tableau Repository/Datasources directory.