User role-based routing #

Starburst Galaxy’s user role-based routing lets you define routing rules that automatically direct queries to the most appropriate clusters based on a user’s role and any Trino client tags attached to the query.

With user role-based routing, a single endpoint per Galaxy account is added to which queries can be dispatched. You can send all queries to a single URL and queries are routed to the geographically closest dispatcher. Queries are evaluated against the user-defined routing rules and dispatched to the appropriate cluster from the first rule that matches.

Requirement #

To create and manage routing rules in Galaxy, your role must have the Manage query routing account-level privilege.

Create a routing rule #

To create a routing rule, navigate to Admin > Routing rules, then click Create rule.

In the Create routing rule dialog:

• In the Rule details section, enter a priority, name, and description for this routing rule. Rule priority controls the order in which routing decisions are made. When multiple rules apply, higher-priority rules are applied first.

• In the Routing rules section, define the conditional logic for your rule.

  • In the Roles drop-down menu, select the applicable role.

  • In the Query tag field, you can optionally include one or more Trino client tags to direct queries to specific clusters based on tag values. x-trino-client-tag is a supported request header for the Trino client REST API. Trino client tags are simple strings that can include alphanumeric characters and are case insensitive. They can be used as identifiers in routing rule logic. Click + Add tag to include additional tags.

  • In the Cluster drop-down menu, select the appropriate cluster to route your query to when the rule conditions are met.

• Click Save.

Use the more_vert options menu at the end of each row in the list of your configured routing rules to edit or delete a rule. Note that changes made to routing rules are not immediate and take approximately five minutes to take effect.

If you have more than one routing rule configured, you can click Re-order rules to open a dialog and change the order of your rules. When there are multiple rules that apply for a query, Galaxy evaluates them based on the order field.

Routing rule logic #

Each Galaxy account has a single set of ordered rules. A routing rule consists of a role, an optional list of Trino client tags, and a single cluster.

A role or non-empty client tag list must be present to create a routing rule. Rules are ordered and evaluated sequentially. The first rule that matches is selected. The cluster configured for the matched rule runs the query.

The Trino client tags present on a query submission match with a routing rule if they are the same as, or a superset of, the client tags defined in the routing rule. The presence of additional client tags in a query does not prevent it from matching a rule.

If multiple rules match, the rule with the highest priority is applied.

Route a query #

After you configure routing rules in Galaxy, you can use the Trino command line interface to submit queries that are routed based on the role and any associated Trino client tags that are set as part of the request headers when sending a query through the Trino CLI.

For example, assume you have created a routing rule in Galaxy named test-analyst with the role analyst, and the rule is configured to route queries to a cluster named analyst-cluster for adhoc analytics workloads.

The following example demonstrates running a query from the Trino CLI that would be routed to the analyst-cluster because of a matching role:

trino --server https://<account-url> --user 'username@example.com/analyst' --password -e "SELECT 'analyst';"

As another example, if you created a routing rule named test-etl with no role specified, but a Trino client tag called etl, and the rule was configured to route a matching query to a cluster named etl-cluster, the following query routes to the appropriate cluster because the client tag etl is included in the request:

trino --server https://<account-url> --user 'username@example.com/analyst' --password --client-tags etl -e "SELECT 'etl-tags';"

Queries are not analyzed nor validated by the routing feature. Therefore, you are responsible for ensuring that candidate clusters are properly configured, the catalog is accessible, and the current user’s role has the necessary privileges to access the data in the catalogs of all candidate clusters.