OpenSearch.Net is a low-level .NET client that provides the foundational layer of communication with OpenSearch. It is dependency free, and it can handle round-robin load balancing, transport, and the basic request/response cycle. OpenSearch.Net contains all OpenSearch API endpoints as methods. When using OpenSearch.Net, you need to construct the queries yourself.
This getting started guide illustrates how to connect to OpenSearch, index documents, and run queries. For the client source code, see the [opensearch-net repo](https://github.com/opensearch-project/opensearch-net).
This documentation reflects the latest updates available in the [GitHub repository](https://github.com/opensearch-project/opensearch-net) and may include changes unavailable in the current stable release. The current stable release in NuGet is [1.2.0](https://www.nuget.org/packages/OpenSearch.Net.Auth.AwsSigV4/1.2.0).
The following example illustrates connecting to OpenSearch, indexing documents, and sending queries on the data. It uses the Student class to represent one student, which is equivalent to one document in the index.
To install Opensearch.Net, download the [Opensearch.Net NuGet package](https://www.nuget.org/packages/OpenSearch.Net) and add it to your project in an IDE of your choice. In Microsoft Visual Studio, follow the steps below:
- In the **Solution Explorer** panel, right-click on your solution or project and select **Manage NuGet Packages for Solution**.
- Search for the OpenSearch.Net NuGet package, and select **Install**.
Alternatively, you can add OpenSearch.Net to your .csproj file:
To connect to your OpenSearch cluster through a single node with a known address, create a ConnectionConfiguration object with that address and pass it to the OpenSearch.Net constructor:
```cs
var nodeAddress = new Uri("http://myserver:9200");
var config = new ConnectionConfiguration(nodeAddress);
var client = new OpenSearchLowLevelClient(config);
You can also use a [connection pool]({{site.url}}{{site.baseurl}}/clients/dot-net-conventions#connection-pools) to manage the nodes in the cluster. Additionally, you can set up a connection configuration to have OpenSearch return the response as formatted JSON.
```cs
var uri = new Uri("http://localhost:9200");
var connectionPool = new SingleNodeConnectionPool(uri);
var settings = new ConnectionConfiguration(connectionPool).PrettyJson();
var client = new OpenSearchLowLevelClient(settings);
To connect to your OpenSearch cluster using multiple nodes, create a connection pool with their addresses. In this example, a [`SniffingConnectionPool`]({{site.url}}{{site.baseurl}}/clients/dot-net-conventions#connection-pools) is used because it keeps track of nodes being removed or added to the cluster, so it works best for clusters that scale automatically.
```cs
var uris = new[]
{
new Uri("http://localhost:9200"),
new Uri("http://localhost:9201"),
new Uri("http://localhost:9202")
};
var connectionPool = new SniffingConnectionPool(uris);
var settings = new ConnectionConfiguration(connectionPool).PrettyJson();
var client = new OpenSearchLowLevelClient(settings);
`ConnectionConfiguration` is used to pass configuration options to the OpenSearch.Net client. `ConnectionSettings` inherits from `ConnectionConfiguration` and provides additional configuration options.
The following example uses `ConnectionSettings` to:
- Set the default index name for requests that don't specify the index name.
- Enable gzip-compressed requests and responses.
- Signal to OpenSearch to return formatted JSON.
- Make field names lowercase.
```cs
var uri = new Uri("http://localhost:9200");
var connectionPool = new SingleNodeConnectionPool(uri);
var settings = new ConnectionSettings(connectionPool)
.DefaultIndex("students")
.EnableHttpCompression()
.PrettyJson()
.DefaultFieldNameInferrer(f => f.ToLower());
var client = new OpenSearchLowLevelClient(settings);
You can send the request body as an anonymous object, string, byte array, or stream in APIs that take a body. For APIs that take multiline JSON, you can send the body as a list of bytes or a list of objects, like in the example above. The `PostData` class has static methods to send the body in all of these forms.
## Searching for a document
To construct a Query DSL query, use anonymous types within the request body. The following query searches for all students who graduated in 2021:
```cs
var searchResponseLow = client.Search<StringResponse>("students",
By default, OpenSearch.Net does not throw exceptions when an operation is unsuccessful. In particular, OpenSearch.Net does not throw exceptions if the response status code has one of the expected values for this request. For example, the following query searches for a document in an index that does not exist:
```cs
var searchResponse = client.Search<StringResponse>("students1",
The response contains an error status code 404, which is one of the expected error codes for search requests, so no exception is thrown. You can see the status code in the `status` field:
```json
{
"error" : {
"root_cause" : [
{
"type" : "index_not_found_exception",
"reason" : "no such index [students1]",
"index" : "students1",
"resource.id" : "students1",
"resource.type" : "index_or_alias",
"index_uuid" : "_na_"
}
],
"type" : "index_not_found_exception",
"reason" : "no such index [students1]",
"index" : "students1",
"resource.id" : "students1",
"resource.type" : "index_or_alias",
"index_uuid" : "_na_"
},
"status" : 404
}
```
To configure OpenSearch.Net to throw exceptions, turn on the `ThrowExceptions()` setting on `ConnectionConfiguration`:
```cs
var uri = new Uri("http://localhost:9200");
var connectionPool = new SingleNodeConnectionPool(uri);
var settings = new ConnectionConfiguration(connectionPool)
.PrettyJson().ThrowExceptions();
var client = new OpenSearchLowLevelClient(settings);
-`Success` returns true if the response code is in the 2xx range or the response code has one of the expected values for this request.
-`SuccessOrKnownError` returns true if the response is successful or the response code is in the 400–501 or 505–599 ranges. If SuccessOrKnownError is true, the request is not retried.
-`OriginalException` holds the original exception for the unsuccessful responses.
## Sample program
The following program creates an index, indexes data, and searches for documents.
```cs
using OpenSearch.Net;
using OpenSearch.Client;
namespace NetClientProgram;
internal class Program
{
public static void Main(string[] args)
{
// Create a client with custom settings
var uri = new Uri("http://localhost:9200");
var connectionPool = new SingleNodeConnectionPool(uri);
var settings = new ConnectionSettings(connectionPool)
.PrettyJson();
var client = new OpenSearchLowLevelClient(settings);
Console.WriteLine("Indexing one student......");
var student = new Student {
Id = 100,
FirstName = "Paulo",
LastName = "Santos",
Gpa = 3.93,
GradYear = 2021 };v
var response = client.Index<StringResponse>("students", "100",
PostData.Serializable(student));
Console.WriteLine(response.Body);
Console.WriteLine("Indexing many students......");
var studentArray = new object[]
{
new { index = new { _index = "students", _type = "_doc", _id = "200"}},
new {
Id = 200,
FirstName = "Shirley",
LastName = "Rodriguez",
Gpa = 3.91,
GradYear = 2019},
new { index = new { _index = "students", _type = "_doc", _id = "300"}},
new {
Id = 300,
FirstName = "Nikki",
LastName = "Wolf",
Gpa = 3.87,
GradYear = 2020}
};
var manyResponse = client.Bulk<StringResponse>(PostData.MultiJson(studentArray));
Console.WriteLine(manyResponse.Body);
Console.WriteLine("Searching for students who graduated in 2019......");
var searchResponseLow = client.Search<StringResponse>("students",
PostData.Serializable(
new
{
from = 0,
size = 20,
query = new
{
term = new
{
gradYear = new
{
value = 2019
}
}
}
}));
Console.WriteLine(searchResponseLow.Body);
Console.WriteLine("Searching for a student with the last name Santos......");
var searchResponse = client.Search<StringResponse>("students",