> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# load_balancing_* session settings

> ClickHouse session settings in the load_balancing_* generated group.

export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
  return <div className="not-prose" style={{
    display: "flex",
    flexWrap: "wrap",
    alignItems: "baseline",
    columnGap: "0.5rem",
    rowGap: "0.125rem",
    margin: "0.375rem 0",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <div style={{
    fontWeight: 600,
    opacity: 0.72
  }}>Type</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>Default</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          Changeable without restart
        </div>}
      {changeable_without_restart && <div style={{
    overflowWrap: "anywhere"
  }}>
          {changeable_without_restart}
        </div>}
    </div>;
};

These settings are available in [system.settings](/docs/reference/system-tables/settings) and are autogenerated from [source](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp).

<h2 id="load_balancing">
  load\_balancing
</h2>

<SettingsInfoBlock type="LoadBalancing" default_value="random" />

Specifies the algorithm of replicas selection that is used for distributed query processing.

ClickHouse supports the following algorithms of choosing replicas:

* [Random](/docs/reference/settings/session-settings/load-balancing#load_balancing-random) (by default)
* [Nearest hostname](/docs/reference/settings/session-settings/load-balancing#load_balancing-nearest_hostname)
* [Hostname levenshtein distance](/docs/reference/settings/session-settings/load-balancing#load_balancing-hostname_levenshtein_distance)
* [Hostname longest common prefix](/docs/reference/settings/session-settings/load-balancing#load_balancing-hostname_longest_common_prefix)
* [Hostname longest common suffix](/docs/reference/settings/session-settings/load-balancing#load_balancing-hostname_longest_common_suffix)
* [In order](/docs/reference/settings/session-settings/load-balancing#load_balancing-in_order)
* [First or random](/docs/reference/settings/session-settings/load-balancing#load_balancing-first_or_random)
* [Round robin](/docs/reference/settings/session-settings/load-balancing#load_balancing-round_robin)

See also:

* [distributed\_replica\_max\_ignored\_errors](/docs/reference/settings/session-settings/distributed-replica#distributed_replica_max_ignored_errors)

<h3 id="load_balancing-random">
  Random (by Default)
</h3>

```sql theme={null}
load_balancing = random
```

The number of errors is counted for each replica. The query is sent to the replica with the fewest errors, and if there are several of these, to anyone of them.
Disadvantages: Server proximity is not accounted for; if the replicas have different data, you will also get different data.

<h3 id="load_balancing-nearest_hostname">
  Nearest Hostname
</h3>

```sql theme={null}
load_balancing = nearest_hostname
```

The number of errors is counted for each replica. Every 5 minutes, the number of errors is integrally divided by 2. Thus, the number of errors is calculated for a recent time with exponential smoothing. If there is one replica with a minimal number of errors (i.e. errors occurred recently on the other replicas), the query is sent to it. If there are multiple replicas with the same minimal number of errors, the query is sent to the replica with a hostname that is most similar to the server's hostname in the config file (for the number of different characters in identical positions, up to the minimum length of both hostnames).

For instance, example01-01-1 and example01-01-2 are different in one position, while example01-01-1 and example01-02-2 differ in two places.
This method might seem primitive, but it does not require external data about network topology, and it does not compare IP addresses, which would be complicated for our IPv6 addresses.

Thus, if there are equivalent replicas, the closest one by name is preferred.
We can also assume that when sending a query to the same server, in the absence of failures, a distributed query will also go to the same servers. So even if different data is placed on the replicas, the query will return mostly the same results.

<h3 id="load_balancing-hostname_levenshtein_distance">
  Hostname levenshtein distance
</h3>

```sql theme={null}
load_balancing = hostname_levenshtein_distance
```

Just like `nearest_hostname`, but it compares hostname in a [levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) manner. For example:

```text theme={null}
example-clickhouse-0-0 ample-clickhouse-0-0
1

example-clickhouse-0-0 example-clickhouse-1-10
2

example-clickhouse-0-0 example-clickhouse-12-0
3
```

<h3 id="load_balancing-hostname_longest_common_prefix">
  Hostname longest common prefix
</h3>

```sql theme={null}
load_balancing = hostname_longest_common_prefix
```

Just like `nearest_hostname`, but the replica whose hostname shares the longest common prefix with the local hostname is preferred (the longer the common prefix, the higher the priority). Unlike `nearest_hostname`, which counts differing characters position by position, this strategy is not confused by hostnames whose numeric segments have different lengths. For example, for the local hostname `sfe301`:

```text theme={null}
sfe301 sde301
1

sfe301 sfe10101
3

sfe301 sde505
1
```

Here `sfe10101` is preferred because it shares the longest common prefix (`sfe`, length 3) with `sfe301`.

Replicas with equal common prefix length are chosen at random. In particular, when no replica shares any prefix with the local hostname (all common prefix lengths are zero), this strategy behaves exactly like `random`.

<h3 id="load_balancing-hostname_longest_common_suffix">
  Hostname longest common suffix
</h3>

```sql theme={null}
load_balancing = hostname_longest_common_suffix
```

Just like `hostname_longest_common_prefix`, but the longest common *suffix* is compared instead of the prefix. This is useful when the data center identity is encoded as a suffix of the hostname. For example, for the local hostname `et46gtghn.qc.localdomain`:

```text theme={null}
et46gtghn.qc.localdomain tr676ddgh.td.localdomain
12

et46gtghn.qc.localdomain ab999.qc.localdomain
15
```

Here `ab999.qc.localdomain` is preferred because it shares the longest common suffix (`.qc.localdomain`, length 15) with `et46gtghn.qc.localdomain`.

Replicas with equal common suffix length are chosen at random. In particular, when no replica shares any suffix with the local hostname (all common suffix lengths are zero), this strategy behaves exactly like `random`.

<h3 id="load_balancing-in_order">
  In Order
</h3>

```sql theme={null}
load_balancing = in_order
```

Replicas with the same number of errors are accessed in the same order as they are specified in the configuration.
This method is appropriate when you know exactly which replica is preferable.

<h3 id="load_balancing-first_or_random">
  First or Random
</h3>

```sql theme={null}
load_balancing = first_or_random
```

This algorithm chooses the first replica in the set or a random replica if the first is unavailable. It's effective in cross-replication topology setups, but useless in other configurations.

The `first_or_random` algorithm solves the problem of the `in_order` algorithm. With `in_order`, if one replica goes down, the next one gets a double load while the remaining replicas handle the usual amount of traffic. When using the `first_or_random` algorithm, the load is evenly distributed among replicas that are still available.

It's possible to explicitly define what the first replica is by using the setting `load_balancing_first_offset`. This gives more control to rebalance query workloads among replicas.

<h3 id="load_balancing-round_robin">
  Round Robin
</h3>

```sql theme={null}
load_balancing = round_robin
```

This algorithm uses a round-robin policy across replicas with the same number of errors (only the queries with `round_robin` policy is accounted).

<h2 id="load_balancing_first_offset">
  load\_balancing\_first\_offset
</h2>

<SettingsInfoBlock type="UInt64" default_value="0" />

Which replica to preferably send a query when FIRST\_OR\_RANDOM load balancing strategy is used.