Starburst Documentation
Starburst Enterprise
  • Starburst Enterprise overview
  •   Try Starburst Enterprise
  •   Web UI
  • SQL
  •   Administration topics
  •   Kubernetes

    • starburst enterprise > web ui > Starburst Enterprise query editor overview

    Starburst Enterprise query editor overview #

    Explorer pane #

    Use the explorer pane to access the available catalogs.

    The explorer pane shows an expandable, hierarchical diagram with the following symbols:

    catalogs disks symbol
    schemas hub symbol
    tables table symbol
    views eye symbol
    columns two-column table symbol

    To expand an element, click its expand icon. To collapse an element, click its collapse icon.

    Click a catalog to collapse all schemas under it. Click a schema to collapse its table list.

    Click or hover over a table name in the explorer to show the full path of the table.

    Vertical ellipsis menus #

    The explorer displays a vertical ellipsis menu (︙) on the right of an object’s name when you select or hover over its name. The menu options apply only to the current object.

    The following table shows the menu options provided by the vertical ellipsis menus for the explorer objects.

    Object ︙menu options
    Catalog
    Copy name to clipboard
    Places the quoted catalog name in the clipboard. Example: "tpch"
    Select catalog
    Sets this catalog as the default for this editor tab.
    Schema
    Copy full path to clipboard
    Places the quoted path to this schema in the clipboard. Example: "tpch"."sf1000"
    Select schema
    Sets this schema and its catalog as the defaults for this editor tab.
    Table
    Copy full path to clipboard
    Places the quoted path to this table in the clipboard. Example: "tpch"."sf1000"."customers"
    Enter SELECT * from table LIMIT 10;
    Places the statement SELECT * from quoted-table-path LIMIT 10 in the first available line in the editor pane, and selects the line.
    Enter DESCRIBE table
    Places the statement DESCRIBE quoted-table-path; in the first available editor line and selects the line.
    View Same options as for a table, with the word view substituted.
    Column
    Copy name to clipboard
    Places the quoted column name in the clipboard. Example: "custkey"

    Editor pane #

    Use the editor pane to type your SQL query, then click the Run button to execute your query. You can also press Ctrl+Enter (⌘+Enter on Mac) to invoke the currently visible Run button.

    Multiple SQL statements can be present in a query tab. In this case, the Run button acts on the statement that contains the cursor, as long as the statement is closed with a semicolon. A statement with a missing semicolon prevents running that statement and all statements below it in the same query tab.

    As an alternative, you can execute one statement among several in a query tab by selecting that statement before clicking the Run… button. You can also select a valid portion of a long SQL statement to execute just that portion. When text is selected, the Run… button appends … selected to the button name.

    Run options #

    There are variations of the Run button, with the last one you used showing for all tabs. Use the drop-down arrow in the current Run button to select between the Run options:

    • Run (limit 1000): This default option retrieves up to 1000 rows of the query’s result set and places it in the results pane. Result sets longer than 1000 rows are truncated as if LIMIT 1000 was appended to the query. You can use the Download link to download a CSV file of this truncated result set as long as it is still visible in the results pane.

    • Run all (limit 1000): This default option retrieves up to 1000 rows of each of the result sets for all statements in the query tab, as long as the statements are closed with a semicolon.

    • Run and download: This option retrieves a query’s entire result set and streams it in CSV format to a file in the current user’s default downloads directory. The name of the file is browser-dependent. Chrome prompts for a filename; Firefox and Safari write to a file named results.csv, appending a digit or a timestamp if the target filename exists. While the download proceeds, a few rows of sample results appear in the results pane. Use this option when you expect a large result set from a query.

    • Run and troubleshoot: This option runs a query and downloads an archive that contains diagnostics files. The archive folder named starburst-query-troubleshooting-[QUERYID].zip is downloaded for successful, cancelled, or failed query runs. This option is only available to users assigned and currently switched to the sysadmin role, or an authorized user with privileges in Insights configuration.

    For more details about run options, refer to the query editor page.

    Tab completion #

    The query editor anticipates SQL commands and most function names as you type, and presents a dialog that suggests several ways to complete the command or function you started. Select an option and press the Tab key to accept one of the options, or keep typing to close the dialog.

    Separate query editor tabs #

    Organize your queries into separate query tabs. For example, with a long-running query active in one tab, click the + plus button to open another query tab for different queries. Rename a query tab by double-clicking the tab name. Tab contents and tab names persist across login sessions until the tab is closed.

    You can save query tabs to access later using Saved queries in the left navigation menu of the web UI. Share a query tab with other users based on their assigned built-in access control roles. Set the access level for a query tab to allow edits to the contents in the query tab, or to view and run only. You must be the owner of the query tab to grant or to remove role access.

    For more information on saved and shared queries, see the query editor reference documentation.

    Default location drop-downs #

    The right hand corner above the editor pane contains drop-down selectors that let you specify a default catalog and schema for those queries. Making these selections is analogous to using the USE command in a SQL client session.

    Conversely, if you specify an actual USE catalog.schema statement as an editor command, the specified catalog and schema display as current selections in these drop-downs.

    To the right of the three default location drop-downs is a vertical ellipsis ︙ menu button with the following options:

    • Copy: Copies the current editor selection to the clipboard.
    • Prettify: Formats the selected query to add spaces, tabs, and newlines where needed.
    • Command palette: Opens a dialog from which you can select editing commands to run at the current cursor location or run on the current editor selection. With the cursor in the editor pane, you can also press F1 to open the command palette. Press Esc to close the palette.

    Results pane #

    The results pane below the editor displays the query processing progress and results. Typically one or more rows and columns are returned by a query.

    Select the border between the editor and results panes to drag the results pane up or down.

    Above the results table on the left, the status bar displays current query processing statistics:

    • Status: displays progress while the query is processed, and final status when complete.
    • Avg. read speed: from all sources, in rows per second.
    • Elapsed time: in seconds since query processing started.
    • Rows: the number of rows returned.

    While a query is running, a progress estimate for that query is shown. If your result set is very wide, or is greater than 1000 rows, it is truncated.

    On the right are three active links:

    • Query details: opens the details page for the most recently run query.

    • Web UI: opens the Trino web UI to see information about recently run queries.

    • Download: if results are shown from the last query, initiates download of those results as a CSV file. Results are not stored, and are only available until a new query is run or your page is closed or refreshed, whichever comes first.

    Next steps:

    See the reference documentation for more in-depth information about the query editor in Starburst Enterprise.