Elasticsearch .NET Client

The Elasticsearch .NET client uses the Microsoft System.Text.Json library by default for all serialization and deserialization tasks.

It manages two distinct serialization responsibilities:

1. Library Types: Serialization of request and response types owned by the Elastic.Clients.Elasticsearch library. This is handled internally and does not require user configuration.
2. User POCO Types: Serialization and deserialization of your application's Plain Old CLR Objects (POCOs) used to represent documents stored in Elasticsearch. This responsibility is configurable, allowing you to customize how your domain models are mapped to JSON.

The client's major and minor versions are tied to the Elasticsearch server version.

Versioning Warning

The client does not strictly follow semantic versioning. Minor or patch updates may contain breaking changes. Always check the release notes before updating.

Compatibility Matrix

Clients are forward compatible with the same or next higher major version of Elasticsearch. They are never backward compatible with earlier Elasticsearch major versions.

Note: Compatibility does not imply feature parity. A client version may be compatible with a newer server but won't support new features introduced in that server version.

You can quickly set up a local instance of Elasticsearch and Kibana using the following command. This will host Elasticsearch at http://localhost:9200 and Kibana at http://localhost:5601.

curl -fsSL https://elastic.co/start-local | sh

When using LINQ to ES|QL, map your POCO (Plain Old CLR Object) classes to ES|QL columns using [JsonPropertyName] attributes. This ensures that C# property names correctly correspond to the column names in your Elasticsearch indices. The provider uses System.Text.Json for serialization.

using System.Text.Json.Serialization;

public class Product
{
    [JsonPropertyName("product_id")]
    public string Id { get; set; }
    public string Name { get; set; }
    [JsonPropertyName("price_usd")]
    public double Price { get; set; }
    [JsonPropertyName("in_stock")]
    public bool InStock { get; set; }
}

The built-in source serializer uses the Microsoft System.Text.Json library. You can apply standard System.Text.Json attributes to your POCO (Plain Old CLR Object) document classes to control property naming or ignore specific properties during serialization to Elasticsearch.

Common attributes include:

• [JsonPropertyName("name")]: Sets a specific JSON property name.
• [JsonIgnore]: Prevents a property from being serialized.

using System.Text.Json.Serialization;

public class Person
{
    [JsonPropertyName("forename")]
    public string FirstName { get; set; }

    [JsonIgnore]
    public int Age { get; set; }
}

// Usage
var person = new Person { FirstName = "Steve", Age = 35 };
var indexResponse = await Client.IndexAsync(person);
// Resulting JSON: { "forename": "Steve" }

The Elasticsearch .NET Client provides both synchronous and asynchronous methods. You should always prefer the asynchronous methods (identified by the Async suffix).

Because the client performs HTTP requests to Elasticsearch servers, operations can be subject to network latency or long execution times for complex queries. Using synchronous methods blocks the calling thread until the request completes, which can lead to thread exhaustion and reduced throughput in high-load applications. Using asynchronous methods allows application threads to remain available for other work while waiting for the network response.

You can perform top-level aggregations using either the Fluent API or the Object Initializer API. This allows you to calculate metrics (like Max, Min, Avg, etc.) across your entire result set. To retrieve the result, use the helper methods on the Aggregations property of the response, such as GetMax, GetAverage, or GetSum.

### Fluent API
```csharp
var response = await client.SearchAsync<Person>(search => search
    .Indices("persons")
    .Query(query => query
        .MatchAll()
    )
    .Aggregations(aggregations => aggregations
        .Add("agg_name", aggregation => aggregation
            .Max(max => max
                .Field(x => x.Age)
            )
        )
    )
    .Size(10)
);

Consume the response

var max = response.Aggregations!.GetMax("agg_name")!;
Console.WriteLine(max.Value);

For maximum flexibility and lower-level control, you can use the Elasticsearch ES|QL query API. This allows you to specify a response format such as csv, text, or json. Note that when using this approach, you are responsible for manually parsing the raw response data.

var response = await client.Esql.QueryAsync(r => r
    .Query("FROM index")
    .Format("csv")
);

var csvContents = Encoding.UTF8.GetString(response.Data);