---
title: "Read balance behavior"
url: "https://docs.ravendb.net/6.2/client-api/configuration/load-balance/read-balance-behavior"
version: "6.2"
language: "nodejs"
---

# Read balance behavior

> Client language: Node.js. Also available for [C#](https://docs.ravendb.net/6.2/client-api/configuration/load-balance/read-balance-behavior.md), [Python](https://docs.ravendb.net/6.2/client-api/configuration/load-balance/read-balance-behavior.python.md), [PHP](https://docs.ravendb.net/6.2/client-api/configuration/load-balance/read-balance-behavior.php.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - When set, the `readBalanceBehavior` configuration will be in effect according to the  
>   conditional flow described in [Client logic for choosing a node](https://docs.ravendb.net/6.2/client-api/configuration/load-balance/overview.md#client-logic-for-choosing-a-node).
>
> - Once configuration is in effect then:
>   - ***Read*** requests - will be sent to the node determined by the configured option - see below.
>   - ***Write*** requests - are always sent to the preferred node.  
>     The data will then be replicated to all the other nodes in the database group.
>   - Upon a node failure, the node to failover to is also determined by the defined option.
>
> - In this page:
>   - [readBalanceBehavior options](#readbalancebehavior-options)
>   - [Initialize readBalanceBehavior on the client](#initialize-readbalancebehavior-on-the-client)
>   - [Set readBalanceBehavior on the server:](#set-readbalancebehavior-on-the-server)
>     - [By operation](#set-readbalancebehavior-on-the-server---by-operation)
>     - [From Studio](#set-readbalancebehavior-on-the-server---from-studio)
>   - [When to use](#when-to-use)

## readBalanceBehavior options

### `None` (default option)

- **Read-balance**  
  No read balancing will occur.  
  The client will always send *Read* requests to the [preferred node](https://docs.ravendb.net/6.2/client-api/configuration/load-balance/overview.md#the-preferred-node).
- **Failover**  
  The client will failover nodes in the order they appear in the [topology nodes list](https://docs.ravendb.net/6.2/studio/database/settings/manage-database-group.md#database-group-topology---actions).

### `RoundRobin`

- **Read-balance**
  - Each session opened is assigned an incremental session-id number.  
    **Per session**, the client will select the next node from the topology list based on this internal session-id.
  - All *Read* requests made on the session (i.e a query or a load request, etc.)  
    will address the calculated node.
  - A *Read* request that is made on the store (i.e. executing an [operation](https://docs.ravendb.net/6.2/client-api/operations/what-are-operations.nodejs.md))  
    will go to the preferred node.
- **Failover**  
  In case of a failure, the client will try the next node from the topology nodes list.

### `FastestNode`

- **Read-balance**  
  All *Read* requests will go to the fastest node.  
  The fastest node is determined by a [Speed Test](https://docs.ravendb.net/6.2/client-api/cluster/speed-test.md).
- **Failover**  
  In case of a failure, a speed test will be triggered again,  
  and in the meantime the client will use the preferred node.

## Initialize readBalanceBehavior on the client

- The `readBalanceBehavior` convention can be set **on the client** when initializing the Document Store.  
  This will set the read balance behavior for the default database that is set on the store.

- This setting can be **overriden** by setting 'readBalanceBehavior' on the server, see [below](#set-readbalancebehavior-on-the-server).

```javascript
// Initialize 'readBalanceBehavior' on the client: 
// ===============================================

const documentStore = new DocumentStore(["serverUrl_1", "serverUrl_2", "..."], "DefaultDB");

// For example:
// With readBalanceBehavior set to: 'FastestNode':
// Client READ requests will address the fastest node
// Client WRITE requests will address the preferred node
documentStore.conventions.readBalanceBehavior = "FastestNode";

documentStore.initialize();
```

## Set readBalanceBehavior on the server

#### Set readBalanceBehavior on the server - by operation:

- The `readBalanceBehavior` configuration can be set **on the server** by sending an [operation](https://docs.ravendb.net/6.2/client-api/operations/what-are-operations.nodejs.md).

- The operation can modify the default database only, or all databases - see examples below.

- Once configuration on the server has changed, the running client will get updated with the new settings.  
  See [keeping client up-to-date](https://docs.ravendb.net/6.2/client-api/configuration/load-balance/overview.md#keeping-the-client-topology-up-to-date).

##### Operation\_For\_Default\_Database

```javascript
// Setting 'readBalanceBehavior' on the server by sending an operation:
// ====================================================================

// Define the client configuration to put on the server
const configurationToSave = {
  // Replace 'FastestNode' (from example above) with 'RoundRobin'
  readBalanceBehavior: "RoundRobin"
};

// Define the put configuration operation for the DEFAULT database
const putConfigurationOp = new PutClientConfigurationOperation(configurationToSave);

// Execute the operation by passing it to maintenance.send
await documentStore.maintenance.send(putConfigurationOp);

// After the operation has executed:
// All WRITE requests will continue to address the preferred node 
// READ requests, per session, will address a different node based on the RoundRobin logic
```

##### Operation\_For\_All\_Databases

```javascript
// Setting 'readBalanceBehavior' on the server by sending an operation:
// ====================================================================

// Define the client configuration to put on the server
const configurationToSave = {
  // Replace 'FastestNode' (from example above) with 'RoundRobin'
  readBalanceBehavior: "RoundRobin"
};

// Define the put configuration operation for ALL databases
const putConfigurationOp = new PutServerWideClientConfigurationOperation(configurationToSave);

// Execute the operation by passing it to maintenance.server.send
await documentStore.maintenance.server.send(putConfigurationOp);

// After the operation has executed:
// All WRITE requests will continue to address the preferred node 
// READ requests, per session, will address a different node based on the RoundRobin logic
```

#### Set readBalanceBehavior on the server - from Studio:

- The `readBalanceBehavior` configuration can be set from the Studio's [Client Configuration view](https://docs.ravendb.net/6.2/studio/database/settings/client-configuration-per-database.md).  
  Setting it from the Studio will set this configuration directly **on the server**.

- Once configuration on the server has changed, the running client will get updated with the new settings.  
  See [keeping client up-to-date](https://docs.ravendb.net/6.2/client-api/configuration/load-balance/overview.md#keeping-the-client-topology-up-to-date).

## When to use

- Setting the read balance behavior is beneficial when you only care about distributing the *Read* requests among the cluster nodes,
  and when all *Write* requests can go to the same node.

- Using the 'FastestNode' option is beneficial when some nodes in the system are known to be faster than others,
  thus letting the fastest node serve each read request.

## See also

- [What are operations](https://docs.ravendb.net/6.2/client-api/operations/what-are-operations.nodejs.md)
- [Load balancing client requests - overview](https://docs.ravendb.net/6.2/client-api/configuration/load-balance/overview.md)
- [Load balance behavior](https://docs.ravendb.net/6.2/client-api/configuration/load-balance/load-balance-behavior.nodejs.md)
- [Conventions](https://docs.ravendb.net/6.2/client-api/configuration/conventions.nodejs.md)
- [Requests Configuration in Studio](https://docs.ravendb.net/6.2/studio/server/client-configuration.md)
- [Requests Configuration per Database](https://docs.ravendb.net/6.2/studio/database/settings/client-configuration-per-database.md)
- [Database-group-topology](https://docs.ravendb.net/6.2/studio/database/settings/manage-database-group.md#database-group-topology---view)
