Read balance behavior



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.
  • 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: 
// ===============================================

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.

  • 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:
// ====================================================================

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