Skip to main content
Last updated on

STATEMENT_TIMEOUT

Applies to: check marked yes Databricks SQL

The STATEMENT_TIMEOUT configuration parameter specifies a timeout duration in seconds. The count starts at the beginning of the SQL statement's execution. Any Databricks SQL statement with a run time exceeding the value is timed out.

You can set this parameter at three scopes:

  • Session: Applies to statements in the current session. Use the SET statement.
  • Warehouse (Beta): Applies to all statements that run on a specific SQL warehouse. Use the SQL warehouses API.
  • Workspace: Applies to all SQL warehouses in the workspace. Use workspace admin settings or the SQL warehouses API.

Setting​

Set a timeout value in seconds between 0 and 172800 seconds (2 days). Any Databricks SQL statement that has an execution time exceeding the set value is halted.

System default​

The system default is 172800 seconds (2 days).

Precedence​

When the timeout is set at more than one scope, the first non-null value in the following order applies:

  1. Session
  2. Warehouse (Beta)
  3. Workspace

If the timeout is not set at any scope, the system default applies.

Examples​

The following example sets a session-level timeout and then resets it.

SQL
-- Set a session-level timeout
> SET STATEMENT_TIMEOUT = 86400;
> SELECT * FROM DIAMONDS;

-- Reset the timeout duration
> RESET STATEMENT_TIMEOUT;
> SELECT * FROM DIAMONDS;

To set a workspace-level timeout, go to the workspace admin settings, click Compute, then click Manage next to SQL warehouses. In the SQL Configuration Parameters setting, add a configuration parameter where the timeout value is in seconds.

SQL
-- Set a workspace-level timeout
> STATEMENT_TIMEOUT 86400

Warehouse-level timeout​

You can set a statement timeout on a single SQL warehouse so that different warehouses can apply different timeouts to their queries. For example, set a longer timeout on an ETL warehouse and a shorter timeout on a BI warehouse.

Beta

Warehouse-level statement timeouts are in Beta. A workspace admin must enable the Warehouse Statement Timeout preview from the Previews page. See Manage Databricks previews.

Set a warehouse-level timeout with the statement_timeout field in the Create or Update warehouse APIs. The value is in seconds. To remove a warehouse-level timeout, set the field to 0.

When you change statement_timeout with the Update warehouse API, the warehouse restarts automatically so the new value takes effect.

To check the timeout that is currently in effect on the warehouse you are connected to, run the following:

SQL
SET STATEMENT_TIMEOUT;
note

Turning off the Warehouse Statement Timeout preview does not clear statement_timeout values already set on warehouses. A previously set warehouse-level value continues to apply until you restart the warehouse.

On this page