Load balancing#

Note

The previous name of the Starburst Control Plane was Starburst Portal.

Starburst Control Plane increases query performance and workload capacity by distributing queries across multiple Starburst Enterprise platform (SEP) clusters.

Overview#

When a routing group contains two or more active and healthy SEP clusters, Starburst Control Plane routes each query to the cluster that can best serve the query based on current conditions. This routing happens automatically to optimize query performance, and it does not require changes to your applications.

By default, Starburst Control Plane routes all queries to a routing group named adhoc. If a routing group named adhoc does not exist or if it contains no active and healthy clusters, queries fail unless you define routing rules that direct them to a different routing group.

Important

For Starburst Control Plane to make optimal routing decisions, all clusters in a routing group must have the same configuration, including version, processing power, and worker node count.

Add or remove capacity#

To add capacity, add a cluster to the routing group using the Starburst Control Plane Clusters page. Once Starburst Control Plane detects that the cluster is active and healthy, the Control Plane includes the cluster in subsequent routing decisions.

To remove capacity, delete a cluster from the routing group or set the cluster’s status to inactive.

Verify query distribution#

Check the RoutedTo column on the Starburst Control Plane Query insights page to see which cluster and routing group handled each query.

Troubleshooting#

If you experience unexpected query behavior, check the following common issues.

All queries route to one cluster#

If all queries route to one cluster:

  • Verify the routing group contains more than one cluster.

  • Check if the queries share a transaction ID. Starburst Control Plane routes all queries in a transaction to the same cluster.

One cluster receives no queries#

If one cluster receives no queries, verify the cluster is active and healthy.

Queries are not evenly distributed#

If queries are not evenly distributed across clusters:

  • Allow more time for distribution to balance out.

  • Check if one cluster is servicing workloads directly, bypassing Starburst Control Plane.

Tail latencies are higher than expected#

If tail latencies are higher than expected, consider configuring resource groups or session properties on your clusters.

Queries fail with object not found error#

If queries fail with object not found or similar errors, confirm that all catalog configurations, database objects, authorizations, and privileges are identical across all clusters in the routing group.