If you use Databricks APIs to create a SQL warehouse, it is serverless by default if the serverless feature is enabled for your workspace. To create a pro or classic SQL warehouse, add the enable_serverless_compute parameter in the API request and set it to false. You can add this parameter both the Create API and Edit API request.
To downgrade a serverless SQL warehouse to a pro or classic SQL warehouse, edit the warehouse and set enable_serverless_compute to false.
For serverless SQL warehouses, spot instance policies (spot_instance_policy) are unsupported and ignored.
Note that for the Auto Stop field (auto_stop_mins), the default and minimum values are different for serverless, pro, and classic SQL warehouses.
SQL Warehouses API
Use this API to create, edit, list, and get SQL warehouses.
Name of the SQL warehouse. Must be unique. This field is required.
cluster_size
STRING
The size of the clusters allocated to the warehouse: "2X-Small", "X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large", "3X-Large", "4X-Large". For the mapping from cluster to instance size, see Cluster size. This field is required.
min_num_clusters
INT32
Minimum number of clusters available when a SQL warehouse is running. The default is 1.
max_num_clusters
INT32
Maximum number of clusters available when a SQL warehouse is running. This field is required. If multi-cluster load balancing is not enabled, this is limited to 1.
auto_stop_mins
INT32
Time in minutes until an idle SQL warehouse terminates all clusters and stops. This field is optional. Setting this to 0 disables Auto Stop. For pro and classic SQL warehouses, the default value is 15 and the minimum is 10. For serverless SQL warehouses, the default value is 10 and the minimum is 1. Databricks recommends setting to 10 minutes for typical use. Lower values (such as 1) cause Databricks to restart the warehouse more often and is not recommended. Note that the minimum is 5 minutes when creating the warehouse in the UI. This only applies to idle warehouses in the RUNNING state. If a warehouse is unable to acquire underlying compute resources and stays in the STARTING state, it is auto-stopped after 75 minutes.
Key-value pairs that describe the warehouse. Azure Databricks tags all warehouse resources with these tags. This field is optional.
enable_photon
BOOLEAN
Whether queries are executed on a native vectorized engine that speeds up query execution. This field is optional. The default is true.
enable_serverless_compute
BOOLEAN
Whether this SQL warehouse is a serverless SQL warehouse. Databricks strongly recommends that you always explicitly set this field. If serverless SQL warehouses are disabled for the workspace, the default is false. If serverless SQL warehouses are enabled for the workspace, the default is true. IMPORTANT: If you set this to true, you must also set the warehouse_type to pro. See the row for warehouse_type.
warehouse_type
WarehouseType
The SQL warehouse type of the warehouse. This field is optional. For a non-serverless SQL warehouse, both classic and pro warehouse types are viable options, and the default warehouse type is classic. For a serverless warehouse, this field can only be pro. See the row for warehouse_type.
Whether to use the current SQL warehouse compute version or the preview version. Preview versions let you try out functionality before it becomes the Databricks SQL standard. Typically, preview versions are promoted to the current version two weeks after initial preview release, but some previews may last longer. You can learn about the features in the latest preview version by reviewing the release notes. Databricks does not recommend using preview versions for production workloads. This field is optional. The default is CHANNEL_NAME_CURRENT.
The spot policy to use for allocating instances to clusters. This field is optional. This field is not used if the SQL warehouse is a serverless SQL warehouse.
Modify a SQL warehouse. All fields are optional. Missing fields default to the current values.
Field Name
Type
Description
id
STRING
ID of the SQL warehouse.
name
STRING
Name of the SQL warehouse.
cluster_size
STRING
The size of the clusters allocated to the warehouse: "2X-Small", "X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large", "3X-Large", "4X-Large". For the mapping from cluster to instance size, see Cluster size.
min_num_clusters
INT32
Minimum number of clusters available when a SQL warehouse is running.
max_num_clusters
INT32
Maximum number of clusters available when a SQL warehouse is running. This field is required. If multi-cluster load balancing is not enabled, limited to 1.
auto_stop_mins
INT32
Time in minutes until an idle SQL warehouse terminates all clusters and stops. Setting this to 0 disables Auto Stop. For pro and classic SQL warehouses, the default value is 15 and the minimum is 10. For serverless SQL warehouses, the default value is 10 and the minimum is 1. Databricks recommends setting to 10 minutes for typical use. Lower values (such as 1) cause Databricks to restart the warehouse more often and is not recommended. Note that the minimum is 5 minutes when creating the warehouse in the UI. This only applies to idle warehouses in the RUNNING state. If a warehouse is unable to acquire underlying compute resources and stays in the STARTING state, it is auto-stopped after 75 minutes.
The SQL warehouse type of the warehouse. This field is optional. For a non-serverless SQL warehouse, both classic and pro warehouse types are viable options, and the default warehouse type is classic. For a serverless warehouse, this field can only be pro. For a list of valid values, see the "WarehouseType" section later in this article.
Whether to use the current SQL warehouse compute version or the preview version. Preview versions let you try out functionality before it becomes the Databricks SQL standard. Typically, preview versions are promoted to the current version two weeks after initial preview release, but some previews may last longer. You can learn about the features in the latest preview version by reviewing the release notes. Databricks does not recommend using preview versions for production workloads. This field is optional. The default is CHANNEL_NAME_CURRENT.
The size of the clusters allocated to the warehouse: "2X-Small", "X-Small", "Small", "Medium", "Large", "X-Large", "2X-Large", "3X-Large", "4X-Large". For the mapping from cluster to instance size, see Cluster size.
auto_stop_mins
INT32
The number of minutes until an idle SQL warehouse terminates all clusters and stops.
Whether queries are executed on a native vectorized engine that speeds up query execution.
enable_serverless_compute
BOOLEAN
Whether this SQL warehouse is a serverless SQL warehouse. To use a serverless SQL warehouse, you must enable serverless SQL warehouses for the workspace. This field is optional. If serverless SQL warehouses are disabled for the workspace, the default is false. If serverless SQL warehouses are enabled for the workspace, the default is true.
warehouse_type
WarehouseType
The SQL warehouse type of the warehouse. This field is optional. For a non-serverless SQL warehouse, both classic and pro warehouse types are viable options, and the default warehouse type is classic. For a serverless warehouse, this field can only be pro. For a list of valid values, see the "WarehouseType" section later in this article.
Whether the SQL warehouse uses the current SQL warehouse compute version or the preview version. Preview versions let you try out functionality before it becomes the Databricks SQL standard. Typically, preview versions are promoted to the current version two weeks after initial preview release, but some previews may last longer. You can learn about the features in the latest preview version by reviewing the release notes. Databricks does not recommend using preview versions for production workloads. This field is optional. The default is CHANNEL_NAME_CURRENT.
Use an on-demand instance for the cluster driver and spot instances for cluster executors. The maximum spot price is 100% of the on-demand price. This is the default policy.
RELIABILITY_OPTIMIZED
Use on-demand instances for all cluster nodes.
WarehouseState
State of a SQL warehouse. The allowable state transitions are:
STARTING -> STARTING, RUNNING, STOPPING, DELETING
RUNNING -> STOPPING, DELETING
STOPPING -> STOPPED, STARTING
STOPPED -> STARTING, DELETING
DELETING -> DELETED
State
Description
STARTING
The warehouse is in the process of starting.
RUNNING
The starting process is done and the warehouse is ready to use.
STOPPING
The warehouse is in the process of being stopped.
STOPPED
The warehouse is stopped. Start by calling start or by submitting a JDBC or ODBC request.
DELETING
The warehouse is in the process of being destroyed.
DELETED
The warehouse has been deleted and cannot be recovered.
WarehouseStatus
State
Description
HEALTHY
Warehouse is functioning normally and there are no known issues.
DEGRADED
Warehouse might be functional, but there are some known issues. Performance might be affected.
FAILED
Warehouse is severely affected and will not be able to serve queries.