Routing#

Starburst control plane routes each query to a cluster group. Use routing to keep competing workloads from interfering with each other, and to send a workload to clusters that are sized and configured for it. After control plane selects a cluster group, load balancing picks a cluster within the group. For the two use cases that routing serves, see Workload isolation and Load balancing.

How routing works#

When a query arrives, control plane handles it in the following way with auto tag-based routing:

  1. Control plane builds a set of tags for the query. The tags come from the request, from the user who submitted it, and from your tagging rules.

  2. Control plane evaluates your routing rules in priority order against the tags. The first rule that matches selects the cluster group.

  3. If no routing rule that you created matches, the query matches the Default routing rule, which sends it to the default cluster group. If you deleted the Default routing rule, control plane rejects the query. See The default routing rule.

  4. Control plane puts the statement in the statement queue. When a cluster in the group has capacity, load balancing picks the cluster that runs the query. See Smart load balancing and How load balancing works.

Control plane routes its own background queries, such as the scheduled refresh of a materialized view, with the same routing rules. A scheduled refresh has the source scheduled-mv-refresh and the client tags catalog=<name>, schema=<name>, materialized_view=<name>, and update_type=REFRESH MATERIALIZED VIEW. A routing rule can match the source with system.request.source, and a client tag with system.request.clientTag. To send every refresh to one cluster group without evaluating the routing rules, set background-work.materialized-view-refresh.routing-group.explicit-override to the group. If a refresh matches no rule, control plane tries it again later, because you can fix the rules. Background work needs the smart load balancing statement queue.

Auto tag-based routing#

Auto tag-based routing derives higher-level routing tags by pattern matching. It lets you route by user identity without requiring clients to set any headers.

When you use auto tag-based routing, control plane routes each query in two stages. First, control plane builds a set of tags for the query by combining system tags and custom tags.

  • System tags. Control plane extracts these automatically:

    • From the HTTP request: system.request.source (from X-Trino-Source) and system.request.clientTag (from X-Trino-Client-Tags).

    • From the identity of the user: the user name (system.identity.user), the groups of the user (system.identity.group), and the roles of the user (system.identity.role).

  • Custom tags. Control plane generates these by evaluating your tagging rules against the system tags. Tag names that start with system. are reserved for system tags, and control plane rejects a tagging rule that uses one.

After control plane computes all the tags, it evaluates your routing rules in priority order against the full set of tags. The first matching rule determines the cluster group.

Note

The upgrade to 2026.6.0 renames the system tags source, clientTag, user, group, and role to system.request.source, system.request.clientTag, system.identity.user, system.identity.group, and system.identity.role. The upgrade rewrites your routing rules and tagging rules to the new names. If a tagging rule produces a tag key that starts with system., the upgrade stops with an error that lists the rules by ID and name. Change those rules, and run the upgrade again. Also update the scripts that create rules through the API, so that they use the new names.

Routing rule matching#

Control plane evaluates routing rules in priority order, and the first matching rule wins. To reorder the rules, go to the sidebar, and under Admin, click Routing rules. Click more_vert options > Re-order rules, and then drag and drop the rules in the grid. You cannot set a priority number for a rule.

The default routing rule#

Control plane keeps a rule named Default routing at the end of your routing rules. It matches every query, and it sends a query that no other rule matches to the default cluster group. The default cluster group is whichever group is the default when control plane routes the query.

You can reorder or delete this rule. If you delete it, and a query matches no other rule, control plane rejects the query with HTTP status 503. The message is No routing rule matched this query, so it could not be assigned to a cluster for execution. Please contact your administrator. This applies to queries that clients submit, to queries in the statement queue, and to background queries. In Query insights, the Routing rule column shows Default routing for a query that went to the default cluster group.

Set the routing method#

Use the gateway.routing.type property to set how control plane routes queries to cluster groups. The default is AUTO_TAGS. To manage individual clusters, use the Clusters pane.

Property

Description

Default

gateway.routing.type

Routing mode for query distribution. AUTO_TAGS routes queries based on tagging rules that derive custom tags from HTTP headers and the identity of the authenticated user (user name, groups, and roles).

AUTO_TAGS