.NET client considerations and best practices

    As a rule, you should set up your OpenSearch.Client as a singleton. OpenSearch.Client manages connections to the server and the states of the nodes in a cluster. Additionally, each client uses a lot of configuration for its setup. Therefore, it is beneficial to create an OpenSearch.Client instance once and reuse it for all OpenSearch operations. The client is thread safe, so the same instance can be shared by multiple threads.

    Exceptions

    The following are the types of exceptions that may be thrown by .NET clients:

    • is a known exception that occurs either in the request pipeline (for example, timeout reached) or in OpenSearch (for example, malformed query). If it is an OpenSearch exception, the ServerError response property contains the error that OpenSearch returns.
    • UnexpectedOpenSearchClientException is an unknown exception (for example, an error during deserialization) and is a subclass of OpenSearchClientException.
    • System exceptions are thrown when the API is not used properly.

    To create a node, pass a Uri object into its constructor:

    copy

    When first created, a node is master eligible, and its HoldsData property is set to true. The AbsolutePath property of the node created above is "/opensearch/": A trailing forward slash is appended so that the paths can be easily combined. If not specified, the default Port is 80.

    Nodes are considered equal if they have the same endpoint. Metadata is not taken into account when checking nodes for equality.

    Connection pools

    The following are connection pool types.

    SingleNodeConnectionPool is the default connection pool that is used if no connection pool is passed to the constructor. Use SingleNodeConnectionPool if you have only one node in the cluster or if your cluster has a load balancer as an entry point. SingleNodeConnectionPool does not support sniffing or pinging and does not mark nodes as dead or alive.

    • CloudConnectionPool

    CloudConnectionPool is a subclass of SingleNodeConnectionPool that takes a Cloud ID and credentials. Like SingleNodeConnectionPool, CloudConnectionPool does not support sniffing or pinging.

    • StaticConnectionPool

    StaticConnectionPool is used for a small cluster when you do not want to turn on sniffing to learn about cluster topology. StaticConnectionPool does not support sniffing, but can support pinging.

    • SniffingConnectionPool

    SniffingConnectionPool is a subclass of StaticConnectionPool. It is thread safe and supports sniffing and pinging. SniffingConnectionPool can be reseeded at run time, and you can specify node roles when seeding.

    • StickyConnectionPool

    is set up to return the first live node, which then persists between requests. It can be seeded using an enumerable of Uri or Node objects. StickyConnectionPool does not support sniffing but supports pinging.

    If a request does not succeed, it is automatically retried. By default, the number of retries is the number of nodes known to OpenSearch.Client in your cluster. The number of retries is also limited by the timeout parameter, so OpenSearch.Client retries requests as many times as possible within the timeout period.

    To set the maximum number of retries, specify the number in the MaximumRetries property on the ConnectionSettings object.

    copy

    You can also set a RequestTimeout that specifies a timeout for a single request and a MaxRetryTimeout that specifies the time limit for all retry attempts. In the example below, is set to 4 seconds, and MaxRetryTimeout is set to 12 seconds, so the maximum number of attempts for a query is 3.

    copy

    Failover

    If you are using a connection pool with multiple nodes, a request is retried if it returns a 502 (Bad Gateway), 503 (Service Unavailable), or 504 (Gateway Timeout) HTTP error response code. If the response code is an error code in the 400–501 or 505–599 ranges, the request is not retried.