Routers#

Starburst Gateway provides routing options to distribute queries across backend clusters.

Random routing#

The StochasticRoutingManager is the default routing mechanism. This option randomly distributes incoming queries across available clusters.

Load-based routing#

The QueryCountBasedRouterProvider routing mechanism uses real-time, user-level load statistics reported in ClusterStats.

This option analyzes running query counts and queue lengths to direct incoming queries to the backend with the fewest queries running or queued from a particular user.

Custom routing#

Use the following steps to create a custom routing mechanism.

Create a router provider module#

  1. Create a class derived from RouterBaseModule.

  2. Instantiate the router. The module must contain a reference to the router.

  3. Add the module name to the modules section of your configuration provider.

See the following example configuration:

modules:
  - io.trino.gateway.ha.module.QueryCountBasedRouterProvider

Create a router class#

  1. Create a class derived from StochasticRoutingManager.

  2. Override the routing methods provideAdhocBackend and provideBackendForRoutingGroup and implement your custom logic.

Cluster statistics#

  • The router class receives cluster load information through the updateBackEndStats method.

  • Statistics update at intervals you define in the monitor.taskDelaySeconds property.

  • Only healthy clusters report statistics. If you have three backends and one is unhealthy, the statistics list contains only two elements.

  • Set the parameter clusterStatsConfiguration.monitorType property to either UI_API or JDBC.

  • You must also configure the properties in the backendState section of your configuration file.

See the following example configuration:

backendState:
  username: <username>
  password: <password>
  ssl: <false/true>

clusterStatsConfiguration:
  monitorType: UI_API

monitor:
  taskDelaySeconds: 10

modules:
  - io.trino.gateway.ha.module.QueryCountBasedRouterProvider