When you log in to Databricks SQL for the first time, an onboarding panel appears to help you get started quickly. If you are not an administrator, running your first query is the first onboarding task.
If you have dismissed the onboarding panel, you can run this query by following the steps in Create a query later in this article.
If you don’t see the onboarding panel, look for Tasks Completed in the sidebar, and click it.
In the onboarding panel, click Run your first query. The SQL editor appears, loaded with the following query:
-- We've given you a sample query below to help get started. -- Just hit "Run" to run the query and get your results. SELECT concat(pickup_zip, '-', dropoff_zip) as route, AVG(fare_amount) as average_fare FROM `samples`.`nyctaxi`.`trips` GROUP BY 1 ORDER BY 2 DESC LIMIT 1000
This query runs against the
nyctaxidatabase in the
SAMPLEScatalog, which is readable in all workspaces.
Click Run. After a few seconds, the query results are shown below the query.
Queries can be viewed in one of two ways:
New queries can now be viewed in the workspace browser by clicking Workspace in the sidebar. These queries are viewable, by default, in the Home folder. Users can organize queries into folders in the workspace browser along with other Databricks objects. To view and organize currently existing queries, users (or admins) must migrate them into the workspace browser. For information on the Databricks SQL workspace browser, including migration, see Databricks SQL Workspace browser.
All queries, regardless of creation time or migration status, can also be viewed by clicking the Queries in the sidebar.
By default, objects are sorted in reverse chronological order. You can reorder the list by clicking the column headings.
You can now organize new and existing queries into folders in the workspace browser along with other Databricks objects. For more information, see [_](../workspace-browser/index.md.
Do one of the following:
Click SQL Editor in the sidebar.
Click Create in the sidebar and select Query.
In the sidebar, click Queries and then click + Create Query.
In the sidebar, click Workspace and then click + Create Query.
The SQL editor displays.
In the data warehouses drop-down list, select a SQL warehouse. To filter the list, enter text in the text box.
The first time you create a query the list of available SQL warehouses displays in alphabetical order. The next time you create a query, the last used SQL warehouse is selected.
The icon next to the SQL warehouse indicates the status:
If there are no SQL warehouses, contact your Databricks SQL administrator.
You can also create a query with the Databricks Terraform provider and databricks_sql_query. You can create a visualization for a query with databricks_sql_visualization. You can create a sample dashboard with queries by using dbsql-nyc-taxi-trip-analysis.
If you have metadata read permission, the schema browser displays the available databases and tables.
If there are no data objects, contact your Databricks SQL administrator.
You can also browse data objects in Data Explorer.
You must select a running SQL warehouse.
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 .
You can filter the schema by typing filter strings in the search box:
Click a table to shows its columns.
You construct a query by inserting elements from the schema browser or typing in the SQL editor.
In the schema browser, click the double arrow on the right of a data object to insert the object into the SQL editor.
Type in the SQL editor.
The SQL 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
tis an alias for
tableand suggests the columns inside
When you are done editing, click Save.
By default, the SQL editor uses tabs so you can edit multiple queries at the same time.
Click Open existing query to see your list of saved queries.
Optionally click My Queries or Favorites to filter the list of queries.
In the row containing the query you want to view, click Open.
To open a new tab, click +, then select Create new query or Open existing query. To run the query, click Run. If you right click on a tab, you’ll see options to Close others, Close left, Close right, and Close all. If you right click on the first or last tab, the options to Close left or Close right are not available.
To disable the tabbed editor, open Queries in the sidebar and click the toggle next to Tabbed editor.
To execute a query:
Select a SQL warehouse.
Specify a query in the SQL editor.
Press Ctrl/Cmd + Enter or click (Run All limit 1000).
If a warehouse is stopped and you execute a query, the warehouse is started. To manually start a warehouse, follow the steps in Start a warehouse.
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 toggle the checkbox and modify the
LIMITclause in your query.
The query result displays in the Table tab.
To terminate a query while it is executing, click Cancel. An administrator can terminate an executing query that was started by another user by viewing the Terminate an executing query.
To set a query description:
Click the kebab menu next to the query and click Edit query info.
In Description, enter a description and then click Save.
When you edit a query, a Revert changes option appears in the context menu for the query.
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.
To move a query to Trash, click the kebab menu next to the query in SQL Editor and select Move to Trash. Confirm by clicking Move to trash.
In the All Queries list, click <Trash>.
Click a query.
Click the kebab menu at the top-right of the SQL editor and select Restore.
In the All Queries list, click <Trash>.
Click a query.
Click the context menu for the query and select Delete.
To create a copy of a query (created by you or someone else), click the context menu for the query and select Clone:
To view when a query was created or updated, click the next to the query and click Edit query info:
To view past executions performed in the SQL editor, click the past executions tab:
This tab does not show scheduled executions.
You can download a query result as a CSV, TSV, or Excel file. Users can now download up to approximately 1GB of results data from Databricks SQL in CSV and TSV format, and up to 64,000 rows to an Excel file.
Click the kebab menu beneath the results pane.
Select Download as [CSV | TSV | Excel] File.
If you cannot download a query, your administrator has disabled download for your Databricks SQL instance.
An administrator can transfer ownership of a query. See Transfer ownership of a query.
To configure who can manage and run queries, see Query access control.
A Databricks admin user has view access to all queries. In this view, an admin can view and delete any queries. However, an admin can’t edit a query if it is not shared with the admin.
To view all queries:
Click Queries in the sidebar.
Click Admin View on the right panel.
To toggle the schema browser, press Alt/Option + D or click the pane handle between the schema browser and query pane.
When the tabbed editor is enabled you can easily switch between multiple queries. To enable and disable the tabbed editor, click the Tabbed Editor toggle on the Queries page:
The SQL editor has live autocomplete, which makes writing queries faster. Live autocomplete can complete schema tokens,
query syntax identifiers (like
JOIN), and the titles of query snippets.
Live autocomplete is enabled by default unless your database schema exceeds five thousand tokens (tables or columns).
To disable live autocomplete, press Ctrl + Space or click beneath the SQL editor:
To enable live autocomplete, press Ctrl + Space or click beneath the SQL editor.