Read balance behavior
-
When set, the
ReadBalanceBehavior
configuration will be in effect according to the
conditional flow described in 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
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.
- Each session opened is assigned an incremental session-id number.
- 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.
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.
// 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
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.
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.