Administration#

The Starburst Portal UI helps you coordinate tasks across multiple SEP clusters.

For tasks that involve only one cluster, use the SEP web ui.

The Starburst Portal UI contains the following pages.

Query editor#

Use the Query editor page to run SQL queries directly in Starburst Portal. Starburst Portal routes all queries from the query editor to the default adhoc routing group.

Limitations#

  • If no adhoc clusters are defined, the query editor displays an error.

  • Worksheets are not persistent. When you refresh the page, your queries are lost. Save your SQL queries in a separate document before you refresh.

Clusters#

Use the Clusters page to associate SEP clusters with Starburst Portal and assign clusters to routing groups. A routing group is a set of clusters that Starburst Portal treats as interchangeable.

Important

  • Ensure all clusters across all routing groups have the same catalog, access control, and authentication configurations.

  • Ensure all clusters within a routing group have the same physical properties (size, worker node count), execution modes (such as FTE or Warp Speed), and database objects (tables, materialized views, data products). These properties can vary across routing groups.

To associate a cluster with Starburst Portal and assign it to a routing group, click Create cluster.

Note

The cluster’s coordinator environment name must match the cluster name you specify. Otherwise, Starburst Portal marks the cluster as unhealthy.

In the Create cluster dialog, enter the cluster details. In the Routing group field, enter the name of an existing routing group to add the cluster to that group, or enter a new name to create a new routing group. In the Shared secret field, enter the shared secret that your cluster uses for internal communication. For more information, see Secure internal communication.

To remove a shared secret from an existing cluster, select Delete shared secret from the cluster’s menu. Leaving the Shared secret field empty when editing a cluster does not remove the existing secret.

To remove a shared secret from an existing cluster, use the action menu on the cluster row. Leaving the Shared secret field empty when editing a cluster does not remove the existing secret.

Click the Active toggle to enable Starburst Portal to monitor the cluster status. Starburst Portal checks the status every few seconds and reports one of the following:

  • PENDING: The cluster is starting up.

  • HEALTHY: The cluster is ready and available.

  • UNHEALTHY: The cluster failed health checks, or the shared secret does not match the cluster’s internal communication secret.

  • UNKNOWN: Starburst Portal cannot communicate with the cluster. Possible reasons include the cluster going offline or a typo in the cluster URL.

  • UNSUPPORTED: The cluster is not a supported SEP cluster.

Limitations#

  • If you are using legacy mode, you must manually configure health status monitoring. For more information, see Health checks.

  • Otherwise, health status monitoring works automatically.

Query insights#

Use the Query insights page to view all queries processed by Starburst Portal, including failed queries. The page shows each query’s routing group and the cluster that processed the query. Use this information to test and verify routing rules.

To run SQL queries directly against an individual SEP cluster, select the cluster from the Clusters page, then navigate to the query editor. Queries you run this way appear on the Query insights page.

Limitations#

  • Starburst Portal automatically deletes query history older than 4 hours. This does not affect query history on individual SEP clusters. To change the retention time, configure the persistence.query-history.retention-time property.

Routing rules#

Use the Routing rules page to create, view, and update the rules that Starburst Portal uses to route queries to routing groups.

To create a routing rule, click Create routing rule.

In the Create routing rule dialog, specify a condition and an action for the routing rule:

  • The condition consists of one or more Trino client tags that the query’s HTTP request header must include, such as application name or user ID. To set Trino client tags, use the Trino CLI.

  • The action specifies which routing group receives the query when the condition matches.

Click Save.

Note

To use routing rules from legacy Trino Gateway-compatible files, configure Starburst Portal to run in legacy mode. Otherwise, Starburst Portal ignores these files and uses only routing rules you create through the Routing rules page. In legacy mode, you can view file-based rules on this page, but you cannot create or update them. Edit the files directly instead.