Put Client Configuration Operation
(for database)

  • The client configuration is a set of configuration options applied during client-server communication.
  • The initial client configuration can be set by the client when creating the Document Store.
  • A database administrator can modify the current client configuration on the server using the PutClientConfigurationOperation operation or via Studio, to gain dynamic control over client-server communication.
    The client will be updated with the modified configuration the next time it sends a request to the database.

Client configuration overview and modification

  • What is the client configuration:
    The client configuration is a set of configuration options that apply to the client when communicating with the database. See what can be configured below.

  • Initializing the client configuration (on the client):
    This configuration can be initially customized from the client code when creating the Document Store via the Conventions.

  • Overriding the initial client configuration for the database (on the server):

    • From the client code:
      Use PutClientConfigurationOperation to set the client configuration options on the server.
      See the example below.

    • From the Studio:
      Set the client configuration from the Client Configuration view.

  • Updating the running client:

    • Once the client configuration is modified on the server, the running client will receive the updated settings the next time it makes a request to the database.

    • Setting the client configuration on the server enables administrators to dynamically control the client behavior after it has started running.
      e.g. manage load balancing of client requests on the fly in response to changing system demands.

  • The client configuration set for the database level overrides the server-wide client configuration.

What can be configured

The following client configuration options are available:

  • Identity parts separator:
    Set the separator used with automatically generated document identity IDs (default separator is /).
    Learn more about identity IDs creation here.

  • Maximum number of requests per session:
    Set this number to restrict the number of requests (Reads & Writes) per session in the client API.

  • Read balance behavior:
    Set the Read balance method the client will use when accessing a node with Read requests.
    Learn more in Balancing client requests - overview and Read balance behavior.

  • Load balance behavior:
    Set the Load balance method for Read & Write requests.
    Learn more in Load balance behavior.

Put client configuration (for database)

// You can customize the client-configuration options in the client
// when creating the Document Store (this is optional):
// =================================================================

var documentStore = new DocumentStore
    Urls = new[] { "ServerURL_1", "ServerURL_2", "..." },
    Database = "DefaultDB",
    Conventions = new DocumentConventions
        // Initialize some client-configuration options:
        MaxNumberOfRequestsPerSession = 100,
        IdentityPartsSeparator = '$'
        // ...

// Override the initial client-configuration in the server using the put operation:
// ================================================================================

using (documentStore)
    // Define the client-configuration object
    ClientConfiguration clientConfiguration = new ClientConfiguration
        MaxNumberOfRequestsPerSession = 200,
        ReadBalanceBehavior = ReadBalanceBehavior.FastestNode
        // ...
    // Define the put client-configuration operation, pass the configuration 
    var putClientConfigOp = new PutClientConfigurationOperation(clientConfiguration);
    // Execute the operation by passing it to Maintenance.Send


public PutClientConfigurationOperation(ClientConfiguration configuration)
Parameter Type Description
configuration ClientConfiguration Client configuration that will be set on the server (for the database)

public class ClientConfiguration
    public long Etag { get; set; }
    public bool Disabled { get; set; }
    public int? MaxNumberOfRequestsPerSession { get; set; }
    public ReadBalanceBehavior? ReadBalanceBehavior { get; set; }
    public LoadBalanceBehavior? LoadBalanceBehavior { get; set; }
    public int? LoadBalancerContextSeed { get; set; }
    public char? IdentityPartsSeparator;  // can be any character except '|'