Connect to Azure Data Explorer with ODBC

Open Database Connectivity (ODBC) is a widely accepted application programming interface (API) for database access. Azure Data Explorer is compatible with a subset of the SQL Server communication protocol (MS-TDS). This compatibility enables the use of the ODBC driver for SQL Server with Azure Data Explorer.

Consequently, you can establish a connection to Azure Data Explorer from any application that is equipped with support for the ODBC driver for SQL Server.

Watch the following video to learn to create an ODBC connection.

Alternatively, follow the steps to connect to your cluster with ODBC.

Note

We recommend using dedicated connectors whenever possible. For a list of available connectors, see Connectors overview.

Prerequisites

• Microsoft ODBC Driver for SQL Server version 17.2.0.1 or later for your operating system.

Connect to your cluster with ODBC

You can connect to your cluster in the following ways.

Connection string

From an application that supports ODBC connection, you can connect to your cluster with a connection string of the following format:

"Driver={ODBC Driver 17 for SQL Server};Server=mykustocluster.kusto.windows.net;Database=mykustodatabase;Authentication=ActiveDirectoryIntegrated"

DSN (Windows only)

To configure an ODBC data source using the ODBC driver for SQL Server:

1. In Windows, search for ODBC Data Sources, and open the ODBC Data Sources desktop app.

2. Select Add.

1. Select ODBC Driver 17 for SQL Server then Finish.

   

2. Enter a name and description for the connection and the cluster you want to connect to, then select Next. The cluster URL should be in the form <ClusterName>.<Region>.kusto.windows.net.

   Note

   When entering the cluster URL, do not include the prefix "https://".

   

3. Select Active Directory Integrated then Next.

   

4. Select the database with the sample data then Next.

   

5. On the next screen, leave all options as defaults then select Finish.

6. Select Test Data Source.

   

7. Verify that the test succeeded then select OK. If the test didn't succeed, check the values that you specified in previous steps, and ensure you have sufficient permissions to connect to the cluster.

   

Note

Azure Data Explorer considers string values as NVARCHAR(MAX), which may not work well with some ODBC applications. Cast the data to NVARCHAR(n) using the Language parameter in the connection string. For example, Language=any@MaxStringSize:5000 will encode strings as NVARCHAR(5000). For more information, see tuning options.

Application authentication

To use application principal authentication with ODBC, you must provide the Microsoft Entra tenant ID. You can set this configuration in the connection string, the Windows registry, or the odbc.ini file. See examples in the following tabs. For more information, see tuning options.

Connection string

Set the application principal with Language=any@AadAuthority:<aad_tenant_id> in the connection string. Replace <aad_tenant_id>, <aad_application_id>, and <aad_application_secret> with the Microsoft Entra tenant ID, Microsoft Entra application ID, and the Microsoft Entra application secret respectively.

"Driver={ODBC Driver 17 for SQL Server};Server=<adx_cluster_name>.<region_name>.kusto.windows.net;Database=<adx_database_name>;Authentication=ActiveDirectoryServicePrincipal;Language=any@AadAuthority:<aad_tenant_id>;UID=<aad_application_id>;PWD=<aad_application_secret>"

Windows registry

Edit the Language field in the ODBC data source (DSN) in the registry for Windows as follows.

[HKEY_CURRENT_USER\SOFTWARE\ODBC\ODBC.INI\MyUserDSN]
"Language"="any@AadAuthority:<aad_tenant_id>"

odbc.ini file

For Linux and macOS, edit the odbc.ini file, as follows.

# [DSN name]
[MSSQLTest]
Driver = ODBC Driver 17 for SQL Server
# Server = [protocol:]server[,port]
Server = tcp:<adx_cluster_name>.<region_name>.kusto.windows.net,1433
Language = any@AadAuthority:<aad_tenant_id>

Related content

• SQL Server emulation in Azure Data Explorer
• Run KQL queries and call stored functions