Skip to main content
Last updated on

Driver capability settings for the Databricks ODBC Driver

This page describes how to configure special and advanced driver capability settings for the Databricks ODBC Driver.

The Databricks ODBC Driver provides the following special and advanced driver capability settings.

Set the initial schema in ODBC​

The ODBC driver allows you to specify the schema by setting Schema=<schema-name> as a connection configuration. This is equivalent to running USE <schema-name>.

Query tags for tracking​

Attach key-value tags to your SQL queries for tracking and analytics purposes. Query tags appear in the system.query.history table for query identification and analysis.

To add query tags to your connection, include the ssp_query_tags parameter in your ODBC connection configuration:

Define query tags as comma-separated key-value pairs, where each key and value is separated by a colon. For example, ssp_query_tags=team:engineering,env:prod.

You must also set ApplySSPWithQueries=0 in your ODBC driver connection configuration.

ANSI SQL-92 query support in ODBC​

Legacy Spark ODBC drivers accept SQL queries in ANSI SQL-92 dialect and translate them to Databricks SQL before sending them to the server.

If your application generates Databricks SQL directly or uses non-ANSI SQL-92 syntax specific to Databricks, set UseNativeQuery=1 in your connection configuration. This setting passes SQL queries verbatim to Databricks without translation.

Extract large query results in ODBC​

To achieve the best performance when you extract large query results, use the latest version of the ODBC driver, which includes the following optimizations.

Arrow serialization in ODBC​

ODBC driver version 2.6.15 and above supports an optimized query results serialization format that uses Apache Arrow.

Cloud Fetch in ODBC​

ODBC driver version 2.6.17 and above supports Cloud Fetch, a capability that fetches query results through the cloud storage configured in your Databricks deployment.

When you run a query, Databricks stores the results in your workspace's cloud storage as Arrow-serialized files of up to 20 MB. After the query completes, the driver sends fetch requests, and Databricks returns signed URLs to the result files. The driver then uses these URLs to download results directly from Google Cloud Storage (GCS).

Cloud Fetch only applies to query results larger than 1 MB. The driver retrieves smaller results directly from Databricks.

Databricks automatically garbage collects accumulated files by marking them for deletion after 24 hours and permanently removing them 24 hours later.

Network prerequisites​

Cloud Fetch downloads result files directly from GCS. If the client machine can't reach GCS, Cloud Fetch fails. Verify the following:

  • Proxy and firewall rules must allow HTTPS traffic to storage.googleapis.com.
  • If your workspace's storage bucket uses bucket IP filtering, the filter must allow the client machine's IP addresses.
  • If your workspace's storage bucket is inside a VPC Service Controls perimeter, the perimeter must have an access level or ingress rule that allows requests from the client machine.

To disable Cloud Fetch, set EnableQueryResultDownload=0 in your connection configuration.

Diagnose slow downloads​

Set LogLevel to 4 (INFO) and LogPath to the full path of a log folder to see Cloud Fetch download speed metrics. The driver logs download speed per chunk, so large result sets generate multiple log lines. The driver also logs a warning when speed falls below approximately 1 MB/s. This feature is available in ODBC driver versions released after November 2025.

If downloads are slow or stalled, signed URLs can expire before the driver finishes downloading all result files. Check for bandwidth throttling or network congestion between the client and GCS.

Enable logging​

To enable logging in the ODBC driver, set the LogLevel property to a value between 1 (severe events only) and 6 (all driver activity). Set the LogPath property to the full path of the folder where you want to save log files.

For more information, see Configuring Logging Options in a Non-Windows Machine in the Databricks ODBC Driver Guide.

On this page