Update to the latest Databricks SQL API version

  • Article

This article describes changes to the Queries, Alerts, Permissions, and Data Sources APIs included in the latest version of the Databricks SQL API. Use this article to help you migrate your applications and integrations to the new API version.

The legacy API will continue to be supported for six months. This transition period gives you time to migrate before the older version is phased out.

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.

Changes to the Permissions API

The Permissions API no longer supports Get object ACL and Set object ACL. Use the Workspace API to manage permissions for these actions.

Data Sources API marked as legacy

The Data Sources API is now marked as legacy. 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.