Create routing rules#
To open the Routing rules pane, go to the sidebar, and under Admin, click Routing rules. Use the pane to create, view, and update the rules that the Starburst control plane uses to route queries to cluster groups. Control plane evaluates the rules in priority order. See Routing rule matching.
Before you begin#
Make sure that you have the
MANAGE_QUERY_ROUTING_RULESprivilege. The privilege exists whengateway.enabledistrue. You can grant it to a role in the privileges UI.To send the queries of a rule to a cluster group, you need one of the privileges
MANAGE_QUERY_ROUTING_RULES,MANAGE_SECURITY, orCREATE_CLUSTER. With one of them, you can choose any group. Without one, you can edit a rule, but you cannot change its cluster group.
Create a routing rule#
In the sidebar, under Admin, click Routing rules.
Click Create routing rule.
Under Rule details, enter the following information:
Name: a unique label for the rule.
Description: optional text.
Under Routing rules, build the rule:
WHEN: click + Add new condition, and define when the rule applies. See Write a condition.
THEN route to: select the cluster group that receives the query when the condition matches. Or select the checkbox Route to default routing group. See Choose the cluster group.
Click Save.
Control plane applies the rule to the next query that it routes.
Write a condition#
The WHEN part of a rule is a condition. In auto tag-based routing, a condition is a list of groups. A query matches if it satisfies any group. Within a group, the query must satisfy every expression. Each expression compares a tag with a value, by an exact match or by a regular expression. See Condition syntax.
A condition can match against these tags:
The system tags
system.request.source,system.request.clientTag,system.identity.user,system.identity.group, andsystem.identity.role.Any custom tag that your tagging rules produce.
Control plane does not check the tag names in a condition. A name that no tag has, for example a typo, saves without an error, and the rule never matches.
For example, this rule sends the queries of the users in the group finance to
the cluster group finance:
Field |
Value |
|---|---|
Name |
|
WHEN |
|
THEN route to |
Cluster group |
This rule sends the scheduled refresh of materialized views to the cluster group
refresh:
Field |
Value |
|---|---|
Name |
|
WHEN |
|
THEN route to |
Cluster group |
Choose the cluster group#
The THEN route to menu lists the cluster groups that you can use. To send queries to the group that is the default at that moment, select the checkbox Route to default routing group instead of a group.
If you edit a rule and do not change its cluster group, the rule keeps its
group. If you choose a group that you cannot use, or that no longer exists,
control plane shows the error Cluster group not found. The two cases look the
same. You cannot delete a cluster group that a routing rule routes to. See
Manage cluster groups.
Change the order of the rules#
You reorder the rules in the Routing rules pane. See Routing rule matching.
The rule Default routing is at the end of the list. It matches every query, and it sends the queries that no other rule matches to the default cluster group. You can reorder it or delete it. If you delete it, a query that matches no rule is rejected. See The default routing rule.
Edit or delete a routing rule#
New rules go to the end of the list, and editing a rule keeps its position. When you delete a rule, control plane adjusts the priorities of the remaining rules, so that no gap is left. If another administrator changed the rules after you opened the pane, control plane refuses your reordering. Reload the pane, and reorder again.