Workload isolation#

Starburst Portal prevents competing workloads from interfering with each other and enables you to use workload-optimized clusters for specific use cases.

Overview#

Starburst Portal routes queries to specific routing groups based on Trino client tags. When you send a query to Starburst Portal, the Portal checks the query’s HTTP request header for client tags. If the header contains tags that match a routing rule, Starburst Portal routes the query to the routing group specified by that rule. Otherwise, Starburst Portal routes the query to the default adhoc routing group.

After Starburst Portal selects a routing group, load balancing determines which cluster within that group handles the query. For more information, see Load balancing.

Important

You must set Trino client tags using your client application. This may require client-side changes. For example, in the Trino CLI, include the --client-tags flag in your SQL statements. If an application cannot set client tags, Starburst Portal routes all queries from that application to the default adhoc routing group.

Routing rule matching#

Assign each routing rule a priority. Starburst Portal evaluates rules in priority order, with lower numbers first. If a query’s client tags match multiple rules, the last matching rule wins. To control which rule takes precedence, assign it a higher priority number.

Workload-optimized clusters#

Once you isolate workloads to specific routing groups, size and configure the clusters within each group to meet the requirements of the workload. For example, for a customer-facing application that requires low latency, enable Warp Speed on the clusters in that routing group.

Verify routing#

To verify routing behavior, check the Starburst Portal Query insights page. The page shows each query and the matching routing rule.

Troubleshooting#

If your queries do not route as expected, check the following common issues.

Queries route to the wrong routing group#

If queries route to different routing groups than you expect:

  • Confirm you defined your routing rules correctly.

  • Verify your client application sets Trino client tags with every query.

Inconsistent query performance within routing group#

If some queries in a routing group perform worse than you expect:

  • Check the query history on each cluster in the routing group to confirm no workloads bypass Starburst Portal and send queries directly to the cluster.

  • Confirm queries in the routing group are compatible and unlikely to interfere with each other. Consider moving incompatible queries to a different routing group.