Read balance behavior

None (default option)

• Read-balance
  No read balancing will occur.
  The client will always send Read requests to the preferred node.
• Failover
  The client will failover nodes in the order they appear in the topology nodes list.

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)
    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.
• Failover
  In case of a failure, a speed test will be triggered again,
  and in the meantime the client will use the preferred node.

• 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.

// Initialize 'ReadBalanceBehavior' on the client:
var documentStore = new DocumentStore
{
    Urls = new[] { "ServerURL_1", "ServerURL_2", "..." },
    Database = "DefaultDB",
    Conventions = new DocumentConventions
    {
        // With ReadBalanceBehavior set to: 'FastestNode':
        // Client READ requests will address the fastest node
        // Client WRITE requests will address the preferred node
        ReadBalanceBehavior = ReadBalanceBehavior.FastestNode
    }
}.Initialize();

Set ReadBalanceBehavior on the server - by operation:

• The ReadBalanceBehavior configuration can be set on the server by sending an operation.

• 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.

// Setting 'ReadBalanceBehavior' on the server by sending an operation:
using (documentStore)
{
    // Define the client configuration to put on the server
    var clientConfiguration = new ClientConfiguration
    {
        // Replace 'FastestNode' (from example above) with 'RoundRobin'
        ReadBalanceBehavior = ReadBalanceBehavior.RoundRobin
    };
    
    // Define the put configuration operation for the DEFAULT database
    var putConfigurationOp = new PutClientConfigurationOperation(clientConfiguration);
    
    // Execute the operation by passing it to Maintenance.Send
    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
}

// Setting 'ReadBalanceBehavior' on the server by sending an operation:
using (documentStore)
{
    // Define the client configuration to put on the server
    var clientConfiguration = new ClientConfiguration
    {
        // Replace 'FastestNode' (from example above) with 'RoundRobin'
        ReadBalanceBehavior = ReadBalanceBehavior.RoundRobin
    };
    
    // Define the put configuration operation for the ALL databases
    var putConfigurationOp = new PutServerWideClientConfigurationOperation(clientConfiguration);
    
    // Execute the operation by passing it to Maintenance.Server.Send
    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.
  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.

• 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.