Getting started with the high-level .NET client (OpenSearch.Client)

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.

To install OpenSearch.Client, download the OpenSearch.Client NuGet package 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.Client NuGet package, and select Install.

Alternatively, you can add OpenSearch.Client to your .csproj file:

copy

Example

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.


{
    public int Id { get; init; }
    public string FirstName { get; init; }
    public string LastName { get; init; }
    public int GradYear { get; init; }
    public double Gpa { get; init; }
}

copy

By default, OpenSearch.Client uses camel case to convert property names to field names.

Connecting to OpenSearch

Use the default constructor when creating an OpenSearchClient object to connect to the default OpenSearch host (http://localhost:9200).

var client  = new OpenSearchClient();

copy

To connect to your OpenSearch cluster through a single node with a known address, specify this address when creating an instance of OpenSearch.Client:

var nodeAddress = new Uri("http://myserver:9200");
var client = new OpenSearchClient(nodeAddress);

copy

var nodes = new Uri[]
{
    new Uri("http://myserver1:9200"),
    new Uri("http://myserver2:9200"),
    new Uri("http://myserver3:9200")
};
var pool = new StaticConnectionPool(nodes);
var settings = new ConnectionSettings(pool);
var client = new OpenSearchClient(settings);

copy

ConnectionConfiguration is used to pass configuration options to the low-level OpenSearch.Net client. ConnectionSettings inherits from ConnectionConfiguration and provides additional configuration options. To set the address of the node and the default index name for requests that don’t specify the index name, create a ConnectionSettings object:

copy

Indexing one document

Create one instance of Student:

var student = new Student { Id = 100, FirstName = "Paulo", LastName = "Santos", Gpa = 3.93, GradYear = 2021 };

copy

To index one document, you can use either fluent lambda syntax or object initializer syntax.

Index this Student into the students index using fluent lambda syntax:

var response = client.Index(student, i => i.Index("students"));

copy

Index this Student into the students index using object initializer syntax:

var response = client.Index(new IndexRequest<Student>(student, "students"));

copy

Indexing many documents

You can index many documents from a collection at the same time by using the OpenSearch.Client’s IndexMany method:

var studentArray = new Student[]
{
    new() {Id = 200, FirstName = "Shirley", LastName = "Rodriguez", Gpa = 3.91, GradYear = 2019},
    new() {Id = 300, FirstName = "Nikki", LastName = "Wolf", Gpa = 3.87, GradYear = 2020}
};
var manyResponse = client.IndexMany(studentArray, "students");

To search for a student indexed above, you want to construct a query that is analogous to the following Query DSL query:

The query above is a shorthand version of the following explicit query:

GET students/_search
{
  "query" : {
    "match": {
      "lastName": {
        "query": "Santos"
      }
    }
  }
}

In OpenSearch.Client, this query looks like this:

var searchResponse = client.Search<Student>(s => s
                                .Index("students")
                                    .Match(m => m
                                        .Field(fld => fld.LastName)

copy

You can print out the results by accessing the documents in the response:

if (searchResponse.IsValid)
{
    foreach (var s in searchResponse.Documents)
    {
        Console.WriteLine($"{s.Id} {s.LastName} {s.FirstName} {s.Gpa} {s.GradYear}");
    }
}

copy

The response contains one document, which corresponds to the correct student:

100 Santos Paulo 3.93 2021

Using OpenSearch.Client methods asynchronously

For applications that require asynchronous code, all method calls in OpenSearch.Client have asynchronous counterparts:

// synchronous method
var response = client.Index(student, i => i.Index("students"));
// asynchronous method
var response = await client.IndexAsync(student, i => i.Index("students"));

Falling back on the low-level OpenSearch.Net client

OpenSearch.Client exposes the low-level the OpenSearch.Net client you can use if anything is missing:

copy

using OpenSearch.Client;
using OpenSearch.Net;
namespace NetClientProgram;
internal class Program
{
    private static IOpenSearchClient osClient = new OpenSearchClient();
    public static void Main(string[] args)
    {       
        Console.WriteLine("Indexing one student......");
        var student = new Student { Id = 100, 
                                    FirstName = "Paulo", 
                                    LastName = "Santos", 
                                    Gpa = 3.93, 
                                    GradYear = 2021 };
        var response =  osClient.Index(student, i => i.Index("students"));
        Console.WriteLine(response.IsValid ? "Response received" : "Error");
        Console.WriteLine("Searching for one student......");
        SearchForOneStudent();
        Console.WriteLine("Searching using low-level client......");
        SearchLowLevel();
        Console.WriteLine("Indexing an array of Student objects......");
        var studentArray = new Student[]
        {
            new() { Id = 200, 
                    FirstName = "Shirley", 
                    LastName = "Rodriguez", 
                    Gpa = 3.91, 
                    GradYear = 2019},
            new() { Id = 300, 
                    FirstName = "Nikki", 
                    LastName = "Wolf", 
                    Gpa = 3.87, 
                    GradYear = 2020}
        };
    }
    private static void SearchForOneStudent()
    {
        var searchResponse = osClient.Search<Student>(s => s
                                .Index("students")
                                .Query(q => q
                                    .Match(m => m
                                        .Field(fld => fld.LastName)
                                        .Query("Santos"))));
        PrintResponse(searchResponse);
    }
    private static void SearchLowLevel()
    {
        // Search for the student using the low-level client
        var lowLevelClient = osClient.LowLevel;
        var searchResponseLow = lowLevelClient.Search<SearchResponse<Student>>
            ("students",
            PostData.Serializable(
                new
                {
                    query = new
                    {
                        match = new
                        {
                            lastName = new
                            {
                                query = "Santos"
                            }
                        }
                    }
                }));
        PrintResponse(searchResponseLow);
    }
    private static void PrintResponse(ISearchResponse<Student> response)
    {
        if (response.IsValid)
        {
            foreach (var s in response.Documents)
            {
                Console.WriteLine($"{s.Id} {s.LastName} " +
                    $"{s.FirstName} {s.Gpa} {s.GradYear}");
            }
        }
        else
        {
            Console.WriteLine("Student not found.");
        }
    }

copy