Update to the latest Databricks SQL API version

This page describes changes to the Queries, Alerts, Permissions, Data Sources, and Visualizations APIs included in the latest version of the Databricks SQL API. The legacy API is deprecated and support will end soon. Use this page to migrate your applications and integrations to the new API version.

Changes to the Queries API

The new Queries API includes a more user-friendly experience with more descriptive names, paginated responses, and list responses automatically sorted by creation time. The following list describes the changes to the Queries API:

• The API path is now api/2.0/sql/queries, replacing the legacy path of /api/2.0/preview/sql/queries.
• Includes a new query definition with more descriptive field names and types.
• The update endpoint now supports partial updates by using PATCH instead of POST.
• The update endpoint now supports transferring the ownership of queries. Previously, this was only allowed using the transfer object ownership API.
• The list endpoint responses are now paginated using token-based pagination.
• The list endpoint no longer supports filtering by name or custom ordering. Instead, all accessible queries are returned and sorted in ascending order by their creation time.
• The restore endpoint is no longer supported. Trashed queries can continue to be restored through the Azure Databricks UI.

For complete documentation on the updated Queries API, see Queries.

Changes to the Alerts API

The new Alerts API includes a more user-friendly experience with more descriptive field names and types, paginated responses to list endpoints, and support for partial updates. The following list describes the changes to the Alerts API:

• The API path is now api/2.0/sql/alerts, replacing the legacy path of /api/2.0/preview/sql/alerts.
• Includes a new alert definition with more descriptive field names and types is used.
• The update endpoint now supports partial updates by using PATCH instead of POST.
• The update endpoint now supports transferring the ownership of queries. Previously, this was only allowed using the transfer object ownership API.
• The list endpoint responses are now paginated using token-based pagination.
• The delete endpoint now moves the alert to the trash instead of permanently deleting the alert. Trashed alerts will be automatically cleaned up after 30 days. Trashed alerts can be restored within 30 days of deletion through the Azure Databricks UI.

For complete documentation on the updated Alerts API, see Alerts.

Permissions API deprecated

The Permissions API is now marked as deprecated. Use the Workspace API to manage object permissions. Use the queries and alerts update APIs to transfer object ownership.

Data Sources API deprecated

The Data Sources API is now marked as deprecated. Currently, its functionality is limited to getting a list of SQL warehouses. Because the new Queries API supports passing in and returning SQL warehouse IDs instead of data source IDs, a separate API call to convert between data sources and SQL warehouses is no longer required.

Upgrading SDK versions

If you're accessing the legacy Databricks SQL API through Databricks SDKs, upgrade to the latest SDK version and migrate to the new APIs. See Databricks SDKs for SDK documentation.

Migrating CLI commands

If you're accessing the legacy Databricks SQL API through the Databricks CLI, migrate from these deprecated command groups:

Deprecated	Use Instead
queries-legacy	queries
alerts-legacy	alerts
data-sources	No replacement

Migrating Terraform resources

If you use Terraform to manage your Databricks SQL resources, migrate to the new resource definitions:

Deprecated Resource	Use Instead	Migration Guide
databricks_sql_query	databricks_query	Migration guide
databricks_sql_alert	databricks_alert	Migration guide
databricks_sql_visualization	databricks_dashboard	No migration guide

For databricks_sql_endpoint and databricks_sql_warehouse:

Upgrade to Databricks Terraform provider v1.105.0 or later. The data_source_id field is deprecated. Upgrade to prevent errors when the deprecated data sources API is turned off.