.NET client considerations and best practices
The following sections provide information regarding the considerations and best practices for using .NET clients.
Registering OpenSearch.Client as a singleton
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.
The following are the types of exceptions that may be thrown by .NET clients:
OpenSearchClientExceptionis 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
ServerErrorresponse property contains the error that OpenSearch returns.
UnexpectedOpenSearchClientExceptionis 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:
var uri = new Uri("http://example.org/opensearch");
var node = new Node(uri);
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 are instances of
IConnectionPool and are responsible for managing the nodes in the OpenSearch cluster. We recommend creating a singleton client with a single
ConnectionSettings object. The lifetime of both the client and its
ConnectionSettings is the lifetime of the application.
The following are connection pool types.
SingleNodeConnectionPool is the default connection pool that is used if no connection pool is passed to the
ConnectionSettings 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 is a subclass of
SingleNodeConnectionPool that takes a Cloud ID and credentials. Like
CloudConnectionPool does not support sniffing or pinging.
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 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
StickyConnectionPool does not support sniffing but supports pinging.
StickySniffingConnectionPool is a subclass of
StickyConnectionPool, it returns the first live node2, which then persists between requests.
StickySniffingConnectionPool supports sniffing and sorting so that each instance of your application can favor a different node. Nodes have weights associated with them and can be sorted by weight.
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
var settings = new ConnectionSettings(connectionPool).MaximumRetries(5);
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,
RequestTimeout is set to 4 seconds, and
MaxRetryTimeout is set to 12 seconds, so the maximum number of attempts for a query is 3.
var settings = new ConnectionSettings(connectionPool)
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.
A response is considered valid if the response code is in the 2xx range or the response code has one of the expected values for this request. For example, 404 (Not Found) is a valid response for a request that checks whether an index exists.