Query tasks

Preview

This feature is in Public Preview. Contact your Databricks representative to request access.

Create a query

  1. Do one of the following:

    • Click the Create Icon icon in the sidebar and select Query.
    • Click the Queries Icon icon in the sidebar and click the + New Query button.

    The query editor displays.

  2. In the box below New Query, click the Down Arrow Icon icon and select a SQL endpoint. To filter the list, enter text in the text box.

    Select endpoint

    The first time you create a query the list of available SQL endpoints displays in alphabetical order. The next time you create a query, the last used SQL endpoint is selected.

    The icon next to the SQL endpoint indicates the status:

    • Running Running
    • Starting Starting
    • Stopped Stopped

    Note

    If there are no SQL endpoints, contact your SQL Analytics administrator.

Browse data objects

If you have metadata read permission, the schema browser displays the available databases and tables.

Note

If there are no data objects, contact your SQL Analytics administrator.

  1. In the box below a SQL endpoint, click the Down Arrow Icon icon and select a database.

    Default database

    Note

    • You must select a running SQL endpoint.
    • In order to see a data object in the schema browser, you must either be the data object owner or be granted privileges to the object.

    To refresh the schema, click the Refresh Schema Icon button.

    Refresh schema

    You can filter the schema by typing filter strings in the search box:

    Filter schema

  2. Click a table to shows its columns.

    Table columns

Construct a query

You construct a query by inserting elements from the schema browser or typing in the query editor.

  • In the schema browser, click the double arrow on the far right of a data object.

    Insert schema item

  • Type in the query editor.

    The query editor supports autocomplete. As you type, autocomplete suggests valid completions. For example, if a valid completion at the cursor location is a column, autocomplete suggests a column name. If you type select * from table as t where t., autocomplete recognizes that t is an alias for table and suggests the columns inside table.

    Autocomplete alias

When you are done editing, click Save.

Execute a query

To execute a query:

  1. Select a SQL endpoint.

  2. Specify a query in the query editor.

  3. Press Ctrl/Cmd + Enter or click the Execute button.

    Execute query

Note

  • If an endpoint is stopped and you execute a query, the endpoint is started. To manually start an endpoint, follow the steps in Start an endpoint.
  • The Limit 1000 checkbox is selected by default to ensure that the query returns at most 1000 rows. If you know that there are more rows, you can unselect the checkbox and specify a LIMIT clause in your query.

The query result displays in the Table tab.

Execute query result

Refresh a query

If your query has a schedule it will refresh automatically. To manually refresh a query in between automatic refreshes, click the Refresh button.

Refresh query

Save a query

To save a query, press Ctrl/Cmd + S or click the Save button. Only saved queries display in the Queries list.

Revert to a saved query

When you edit a query, a Revert link displays next to the Save button.

Revert link

You can click Revert to go back to your saved version. Your changes are persisted to browser storage when you leave, but the browser may still display warnings about losing work.

Move a query to Trash

To move a query to Trash, click the vertical ellipsis Vertical Ellipsis at the top-right of the query editor and select Move to Trash. Confirm by clicking Move to Trash.

Restore a query from Trash

  1. In the All Queries list, click Trash Button.
  2. Click a query.
  3. Click the vertical ellipsis Vertical Ellipsis at the top-right of the query editor and select Restore.

Permanently delete a query

  1. In the All Queries list, click Trash Button.
  2. Click a query.
  3. Click the vertical ellipsis Vertical Ellipsis at the top-right of the query editor and select Delete.

Copy a query

To create a copy of a query (created by you or someone else), you can fork it. To fork a query, click the vertical ellipsis Vertical Ellipsis at the top-right of the query editor and select Fork:

Fork query

Download a query result

You can download a query result as a CSV, TSV, or Excel file.

  1. Click the vertical ellipsis Vertical Ellipsis button beneath the results pane.
  2. Select Download as [CSV | TSV | Excel] File.
Download query result

If you cannot download a query, your administrator has disabled download for your SQL Analytics instance.

Query editor tools

Schema browser

To toggle the schema browser, press Alt/Option + D or click the pane handle Pane Handle between the schema browser and query pane.

Auto Complete

The query editor has Auto Complete, which makes writing queries faster. Auto Complete can complete schema tokens, query syntax identifiers (like SELECT and JOIN), and the titles of query snippets.

Auto Complete is enabled by default unless your database schema exceeds five thousand tokens (tables or columns).

  • To disable Auto Complete, press Ctrl + Space or click the Auto Complete Enabled button beneath the query editor:
  • To enable Auto Complete, press Ctrl + Space or click the Auto Complete Disabled button beneath the query editor.

Configure query permissions

To configure who can manage and run queries, see Query access control.