Skip to content

Update documentation #8537

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 26, 2025
Merged

Update documentation #8537

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
789df63
Update documentation
flobernd May 22, 2025
44544b5
Update 9.x docs
flobernd May 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 1 addition & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@

Repository for **Elastic.Clients.Elasticsearch** the official .NET client for
[Elasticsearch](https://github.com/elastic/elasticsearch).
*Older branches include both previous clients, **NEST** and **Elasticsearch.Net**.*

**[Download the latest version of Elasticsearch](https://www.elastic.co/downloads/elasticsearch)**
or
Expand Down Expand Up @@ -61,40 +60,13 @@ for comprehensive information on installation, configuration and usage.

The API reference documentation is available [here](https://elastic.github.io/elasticsearch-net).

## Versions

### Elasticsearch 8.x Clusters

We have released the next generation of the .NET client for Elasticsearch, which
aligns with v8 of Elasticsearch. We have renamed this library
`Elastic.Clients.Elasticsearch`, and the packages are published on
[NuGet](https://www.nuget.org/packages/Elastic.Clients.Elasticsearch/). The
8.0.x versions do not offer complete feature parity with the existing `NEST`
client. We therefore recommend you thoroughly review our
[release notes and migration guidance](https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/release-notes-8.0.0.html)
before attempting to migrate existing applications to the
`Elastic.Clients.Elasticsearch` library.

Until the new client supports all endpoints and features your application
requires, you may continue to use the latest `7.17.x` client to communicate with
Elasticsearch v8 servers. Please review
[our documentation](https://www.elastic.co/guide/en/elasticsearch/client/net-api/7.17/connecting-to-elasticsearch-v8.html),
which describes how to enable compatibility mode and secure communications with
a v8 cluster.

### Elasticsearch 7.x Clusters

We recommend using the latest `7.17.x`
[NEST client](https://www.nuget.org/packages/Nest) to communicate with
Elasticsearch v7 servers.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md)

## Copyright and License

This software is Copyright (c) 2014-2022 by Elasticsearch BV.
This software is Copyright (c) 2014-2025 by Elasticsearch BV.

This is free software, licensed under
[The Apache License Version 2.0](https://github.com/elastic/elasticsearch-net/blob/main/LICENSE.txt).
13 changes: 2 additions & 11 deletions docs/reference/_options_on_elasticsearchclientsettings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,6 @@ The following is a list of available connection configuration options on `Elasti
`Base64ApiKey` for Elastic Cloud style encoded api keys
```


`ClientCertificate`
: Use the following certificates to authenticate all HTTP requests. You can also set them on individual request using `ClientCertificates`.

Expand All @@ -34,7 +33,6 @@ The following is a list of available connection configuration options on `Elasti

For Core CLR, this setting applies to the `MaxConnectionsPerServer` property on the `HttpClientHandler` instances used by the `HttpClient` inside the default `IConnection` implementation.


`DeadTimeout`
: The time to put dead nodes out of rotation (this will be multiplied by the number of times they’ve been dead).

Expand All @@ -43,13 +41,11 @@ The following is a list of available connection configuration options on `Elasti

The client by default will use the value of a property named `Id` on a CLR type as the `_id` to send to {{es}}. Adding a type will disable this behaviour for that CLR type. If `Id` inference should be disabled for all CLR types, use `DefaultDisableIdInference`.


`DefaultFieldNameInferrer`
: Specifies how field names are inferred from CLR property names.

By default, the client camel cases property names. For example, CLR property `EmailAddress` will be inferred as "emailAddress" {{es}} document field name.


`DefaultIndex`
: The default index to use for a request when no index has been explicitly specified and no default indices are specified for the given CLR type specified for the request.

Expand Down Expand Up @@ -82,7 +78,6 @@ The following is a list of available connection configuration options on `Elasti

For Desktop CLR, sets `ServicePointManager`.`SetTcpKeepAlive`.


`EnableTcpStats`
: Enable statistics about TCP connections to be collected when making a request.

Expand Down Expand Up @@ -110,8 +105,8 @@ The following is a list of available connection configuration options on `Elasti
`OnRequestCompleted`
: Allows you to register a callback every time a an API call is returned.

`OnRequestDataCreated`
: An action to run when the `RequestData` for a request has been created.
`OnBeforeRequest`
: An action to run before a request is made.

`PingTimeout`
: The timeout in milliseconds to use for ping requests, which are issued to determine whether a node is alive.
Expand All @@ -121,7 +116,6 @@ The following is a list of available connection configuration options on `Elasti

Note: this is not a guarantee you will always get prettified json.


`Proxy`
: If your connection has to go through proxy, use this method to specify the proxy url.

Expand All @@ -148,7 +142,6 @@ The following is a list of available connection configuration options on `Elasti

Reasons for such exceptions could be search parser errors, index missing exceptions, and so on.


`TransferEncodingChunked`
: Whether the request should be sent with chunked Transfer-Encoding.

Expand All @@ -171,5 +164,3 @@ var settings= new ElasticsearchClientSettings()

var client = new ElasticsearchClient(settings);
```


155 changes: 79 additions & 76 deletions docs/reference/aggregations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,124 +7,127 @@ mapped_pages:

This page demonstrates how to use aggregations.


## Top-level aggreggation [_top_level_aggreggation]


### Fluent API [_fluent_api]

```csharp
var response = await client
.SearchAsync<Person>(search => search
.Index("persons")
.Query(query => query
.MatchAll(_ => {})
)
.Aggregations(aggregations => aggregations
.Add("agg_name", aggregation => aggregation
.Max(max => max
.Field(x => x.Age)
)
)
)
.Size(10)
);
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)
);
```


### Object initializer API [_object_initializer_api]

```csharp
var response = await client.SearchAsync<Person>(new SearchRequest("persons")
{
Query = Query.MatchAll(new MatchAllQuery()),
Aggregations = new Dictionary<string, Aggregation>
{
{ "agg_name", Aggregation.Max(new MaxAggregation
{
Field = Infer.Field<Person>(x => x.Age)
})}
},
Size = 10
Query = new Query
{
MatchAll = new MatchAllQuery()
},
Aggregations = new Dictionary<string, Aggregation>
{
{ "agg_name", new Aggregation
{
Max = new MaxAggregation
{
Field = Infer.Field<Person>(x => x.Age)
}
}}
},
Size = 10
});
```


### Consume the response [_consume_the_response]

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


## Sub-aggregation [_sub_aggregation]


### Fluent API [_fluent_api_2]

```csharp
var response = await client
.SearchAsync<Person>(search => search
.Index("persons")
.Query(query => query
.MatchAll(_ => {})
)
.Aggregations(aggregations => aggregations
.Add("firstnames", aggregation => aggregation
.Terms(terms => terms
.Field(x => x.FirstName)
)
.Aggregations(aggregations => aggregations
.Add("avg_age", aggregation => aggregation
.Max(avg => avg
.Field(x => x.Age)
)
)
)
)
)
.Size(10)
);
var response = await client.SearchAsync<Person>(search => search
.Indices("persons")
.Query(query => query
.MatchAll(_ => {})
)
.Aggregations(aggregations => aggregations
.Add("firstnames", aggregation => aggregation <1>
.Terms(terms => terms
.Field(x => x.FirstName)
)
.Aggregations(aggregations => aggregations
.Add("avg_age", aggregation => aggregation <2>
.Max(avg => avg
.Field(x => x.Age)
)
)
)
)
)
.Size(10)
);
```

1. The top level `Terms` aggregation with name `firstnames`.
2. Nested aggregation of type `Max` with name `avg_age`.

### Object initializer API [_object_initializer_api_2]

```csharp
var topLevelAggregation = Aggregation.Terms(new TermsAggregation
{
Field = Infer.Field<Person>(x => x.FirstName)
});

topLevelAggregation.Aggregations = new Dictionary<string, Aggregation>
var response = await client.SearchAsync<Person>(new SearchRequest<Person>
{
{ "avg_age", new MaxAggregation
{
Field = Infer.Field<Person>(x => x.Age)
}}
};

var response = await client.SearchAsync<Person>(new SearchRequest("persons")
{
Query = Query.MatchAll(new MatchAllQuery()),
Aggregations = new Dictionary<string, Aggregation>
{
{ "firstnames", topLevelAggregation}
},
Size = 10
Query = new Query
{
MatchAll = new MatchAllQuery()
},
Aggregations = new Dictionary<string, Aggregation>
{
{ "firstnames", new Aggregation
{
Terms = new TermsAggregation
{
Field = Infer.Field<Person>(x => x.FirstName)
},
Aggregations = new Dictionary<string, Aggregation>
{
{ "avg_age", new Aggregation
{
Max = new MaxAggregation
{
Field = Infer.Field<Person>(x => x.Age)
}
}}
}
}}
}
});
```


### Consume the response [_consume_the_response_2]

```csharp
var firstnames = response.Aggregations!.GetStringTerms("firstnames")!;
foreach (var bucket in firstnames.Buckets)
{
var avg = bucket.Aggregations.GetAverage("avg_age")!;
Console.WriteLine($"The average age for persons named '{bucket.Key}' is {avg}");
var avg = bucket.Aggregations.GetAverage("avg_age")!;
Console.WriteLine($"The average age for persons named '{bucket.Key}' is {avg}");
}
```

2 changes: 0 additions & 2 deletions docs/reference/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,3 @@ mapped_pages:
# Configuration [configuration]

Connecting to {{es}} with the client is easy, but it’s possible that you’d like to change the default connection behaviour. There are a number of configuration options available on `ElasticsearchClientSettings` that can be used to control how the client interact with {{es}}.


14 changes: 5 additions & 9 deletions docs/reference/connecting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ This page contains the information you need to create an instance of the .NET Cl
It’s possible to connect to your {{es}} cluster via a single node, or by specifying multiple nodes using a node pool. Using a node pool has a few advantages over a single node, such as load balancing and cluster failover support. The client provides convenient configuration options to connect to an Elastic Cloud deployment.

::::{important}
Client applications should create a single instance of `ElasticsearchClient` that is used throughout your application for its entire lifetime. Internally the client manages and maintains HTTP connections to nodes, reusing them to optimize performance. If you use a dependency injection container for your application, the client instance should be registered with a singleton lifetime.
::::

Client applications should create a single instance of `ElasticsearchClient` that is used throughout your application for its entire lifetime. Internally the client manages and maintains HTTP connections to nodes, reusing them to optimize performance. If you use a dependency injection container for your application, the client instance should be registered with a singleton lifetime.

::::

## Connecting to a cloud deployment [cloud-deployment]

Expand All @@ -36,8 +36,6 @@ var client = new ElasticsearchClient("<CLOUD_ID>", new ApiKey("<API_KEY>")); <1>

1. Replace the placeholder string values above with your cloud ID and the API key configured for your application to access your deployment.



## Connecting to a single node [single-node]

Single node configuration is best suited to connections to a multi-node cluster running behind a load balancer or reverse proxy, which is exposed via a single URL. It may also be convenient to use a single node during local application development. If the URL represents a single {{es}} node, be aware that this offers no resiliency should the server be unreachable or unresponsive.
Expand Down Expand Up @@ -92,7 +90,6 @@ var client = new ElasticsearchClient(settings);

The preceding snippet demonstrates configuring the client to authenticate by providing a username and password with basic authentication. If preferred, you may also use `ApiKey` authentication as shown in the cloud connection example.


## Connecting to multiple nodes using a node pool [multiple-nodes]

To provide resiliency, you should configure multiple nodes for your cluster to which the client attempts to communicate. By default, the client cycles through nodes for each request in a round robin fashion. The client also tracks unhealthy nodes and avoids sending requests to them until they become healthy.
Expand All @@ -107,9 +104,9 @@ using Elastic.Transport;

var nodes = new Uri[]
{
new Uri("https://myserver1:9200"),
new Uri("https://myserver2:9200"),
new Uri("https://myserver3:9200")
new Uri("https://myserver1:9200"),
new Uri("https://myserver2:9200"),
new Uri("https://myserver3:9200")
};

var pool = new StaticNodePool(nodes);
Expand All @@ -120,4 +117,3 @@ var settings = new ElasticsearchClientSettings(pool)

var client = new ElasticsearchClient(settings);
```

Loading
Loading