Starburst Galaxy

  •  Get started

  •  Working with data

  •  Data engineering

  •  Developer tools

  •  Cluster administration

  •  Security and compliance

  •  Troubleshooting

  • Galaxy status

  •  Reference

  • Run SQL statements #

    You can use the query editor to access all clusters, and use their configured catalogs to run SQL statements against.

    Go to the query editor by clicking Query > Query editor in the navigation menu.

    Run a SQL statement #

    To run a SQL statement in the query editor, complete the following steps:

    1. Specify the correct cluster in the location drop-down menus of the editor pane.
    2. Determine which run option is appropriate. The default option is ▶ Run selected (limit 1000).
    3. Select one or more complete SQL statements in the canvas of the current, then click the ▶ Run button.

    Alternatively, the following keyboard and canvas menu run methods are also available:

    • Press Ctrl+Enter (⌘+Enter on Mac)
    • Right-click inside the canvas, and select Run query from the context menu.

    These alternative methods use the last-selected run option for the ▶ Run button.

    Query selection options #

    If you have multiple SQL statement in a tab, there are two ways to specify which one to run:

    • Click to select: Click to place the cursor anywhere in a complete SQL SQL statement, then use one of the Run methods.

      The click-to-select option is strict about requiring a terminating semicolon for SQL statements.

    • Highlight to select: Highlight a complete SQL statement or valid portion of a SQL statement, then use one of the Run methods. You can also highlight to select more than one complete SQL statement and run them all in sequence.

      When you use the cluster explorer options menu to place a SQL statement on the current tab, the SQL statement is highlighted. Highlight-to-select is more forgiving of semicolon placement.

    In both cases, the SQL statements are run in top down order, with the results of each SQL statement showing in sequence in the results pane. A navigation sub-pane opens in the results pane to show the status of each selected SQL statement. Click to select a row in this sub-pane to show the corresponding results from each SQL statement.

    If you click Cancel while a multiple SQL statement set is running, the cancellation applies to the currently running SQL statement. The execution of all following SQL statements in the set is stopped, with status showing Skipped.

    Run options #

    The Run button offers the following options:

    • ▶ Run selected (limit 1000)
    • ▶ Run all selected (limit 1000)
    • ▶ Run and download selected

    The Run button retains the last selection in each tab until you change it. Each tab also maintains a separate history of the state of the Run button. Use the drop-down arrow in the current Run button to select among the following Run options:

    • ▶ Run (limit 1000): Applies to the SQL statement in the current tab that contains the cursor. Retrieves up to 1000 rows of that statement’s result set, which appear in the results pane.

      Result sets longer than 1000 rows are truncated as if LIMIT 1000 was appended to the SQL statement. You can use the Download link at the top of the results pane to download a CSV file of this truncated result set as long as it is still visible in the results pane.

    • ▶ Run selected (limit 1000): Completes the same process as ▶ Run (limit 1000) for the selected SQL statement or statements.

    • ▶ Run all (limit 1000): Applies when the current tab has more than one valid SQL statement, each terminated by a semicolon. In this case, this option runs all SQL statements in order, top to bottom. The same 1000 row limit applies to this option for each statement run.

      When more than one statement is run, a navigation sub-pane opens in the results pane. Click to select a row in this sub-pane to show the results from previously run statements in the set. If you click Cancel while a multiple statement set is running, the cancellation applies to the currently running statement, and all subsequent statements are skipped.

    • ▶ Run and download: Retrieves a SQL statement’s entire result set and streams it in CSV format to a file in the current user’s default downloads directory. Use this option when you expect a large result set. The amount of data that can be downloaded with this option is browser-dependent. Use a different client to download very large result sets. The name of the results file is browser dependent. Chrome prompts for a filename. Firefox and Safari write to a file named results.csv and appends a digit or a timestamp if the target filename exists. As the download proceeds, a few rows of sample results appear in the results pane.

    Explore the editor pane menus #

    The editor pane has several menus, which are described in the following sections.

    Location drop-down menus #

    The left hand corner above the editor pane contains drop-down selectors that let you specify a cluster, catalog, and schema for SQL statements in the current editor tab. These settings persist for each tab separately, and are restored when you reopen a saved SQL statement.

    If you have more than one cluster in your Starburst Galaxy account, you must specify a cluster to activate the Run button. When you open a new tab, the cluster selection is empty and a message reminds you to select a cluster before querying.

    A green dot in the cluster drop-down means the cluster is currently running. Selecting a stopped cluster in the drop-down starts the cluster.

    Query location-drop-down-menus

    Options menu #

    To the right of the Run button is anmore_vertoptions menu that shows the following options:

    • Show SQL docs: Opens a pane containing the Starburst Galaxy SQL documentation.
    • Copy: Copies the current editor selection to the clipboard.
    • Prettify: Adds spaces, tabs, and newlines to the selected SQL statement 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.

    Context menu #

    Each query editor tab contains a context menu you can activate in the standard ways: right-click on a right-hand configured mouse, double tap on a trackpad, and so on. The context menu allows you perform the following actions:

    • Explain query: Opens the Query explanation pane containing an explanation of the currently selected SQL statement or part of a SQL statement.
    • Run query: Executes the SQL statement that contains the cursor, the fully selected SQL statement, or the set of fully selected SQL statements.
    • Change All Occurrences: Use to search and replace a string in a long SQL SQL statement being edited.
    • Prettify and Command palette: Works as described next in the options menu.
    • Cut, Copy, Paste: standard editing commands.

    Get SQL statement status #

    Some statuses are only visible when the cluster is running. Other SQL statement statuses are only visible in the query details page. The query editor statuses include:

    • Cancelling: The status that displays after a user clicks the Cancel button. Only visible in the query editor.
    • Failed: Indicates that the query execution has failed.
    • Finished: The query is finished executing and all output was consumed.
    • Queued: The query is waiting for other queries to execute.
    • Skipped: The query was run as part of a set of queries, but an earlier query in the set was cancelled.
    • Running: The query is executing and has at least one running task.
    • Starting server: The query processing is waiting for the cluster to start from a suspended state.

    Learn more #