Skip to content

Commit 2785ccd

Browse files
stevejgordonstevejgordon
authored
Sync docs with main (#6596)
1 parent edc25a9 commit 2785ccd

File tree

10 files changed

+300
-29
lines changed

10 files changed

+300
-29
lines changed

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ test-results/*
3030
*.sbr
3131
*.DotSettings.user
3232
obj/
33-
[Rr]elease*/
33+
[Rr]elease/
3434
_ReSharper*/
3535
_NCrunch*/
3636
[Tt]est[Rr]esult*

‎docs/client-concepts/connection-pooling/exceptions/unrecoverable-exceptions.asciidoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ but by exiting the pipeline.
3333

3434
By default, the client won't throw on any `TransportException` but instead return an invalid response
3535
that can be detected by checking the `.IsValid` property on the response. You can change this behaviour with
36-
by using `ThrowExceptions()` on <<configuration-options, `ConnectionSettings`>>.
36+
by using `ThrowExceptions()` on <<configuration, `ConnectionSettings`>>.
3737

3838
[source,csharp]
3939
----

‎docs/client-concepts/high-level/getting-started.asciidoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ var client = new ElasticClient(settings);
4141
----
4242

4343
In this example, a default index was also specified to use if no other index is supplied for the request or can be inferred for the
44-
POCO generic type parameter in the request. There are many other <<configuration-options,Configuration options>> on `ConnectionSettings`.
44+
POCO generic type parameter in the request. There are many other <<configuration,configuration options>> on `ConnectionSettings`.
4545

4646
TIP: Specifying a default index is _optional_ but NEST may throw an exception if no index can be inferred for a given request. To understand more around how
4747
an index can be specified for a request, see <<index-name-inference,Index name inference>>.

‎docs/configuration.asciidoc

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
[[configuration]]
2+
== Configuration
3+
4+
Connecting to {es} with the client is easy, but it's possible that you'd like to
5+
change the default connection behaviour. There are a number of configuration
6+
options available on `ElasticsearchClientSettings` that can be used to control how the
7+
client interact with {es}.
8+
9+
=== Options on ElasticsearchClientSettings
10+
11+
The following is a list of available connection configuration options on
12+
`ElasticsearchClientSettings`:
13+
14+
`Authentication`::
15+
16+
An implementation of `IAuthenticationHeader` describing what http header to use
17+
to authenticate with the product.
18+
+
19+
`BasicAuthentication` for basic authentication
20+
+
21+
`ApiKey` for simple secret token
22+
+
23+
`Base64ApiKey` for Elastic Cloud style encoded api keys
24+
25+
`ClientCertificate`::
26+
27+
Use the following certificates to authenticate all HTTP requests. You can also
28+
set them on individual request using `ClientCertificates`.
29+
30+
`ClientCertificates`::
31+
32+
Use the following certificates to authenticate all HTTP requests. You can also
33+
set them on individual request using `ClientCertificates`.
34+
35+
`ConnectionLimit`::
36+
37+
Limits the number of concurrent connections that can be opened to an endpoint.
38+
Defaults to 80 (see `DefaultConnectionLimit`).
39+
+
40+
For Desktop CLR, this setting applies to the `DefaultConnectionLimit` property
41+
on the `ServicePointManager` object when creating `ServicePoint` objects,
42+
affecting the default `IConnection` implementation.
43+
+
44+
For Core CLR, this setting applies to the `MaxConnectionsPerServer` property on
45+
the `HttpClientHandler` instances used by the `HttpClient` inside the default
46+
`IConnection` implementation.
47+
48+
`DeadTimeout`::
49+
50+
The time to put dead nodes out of rotation (this will be multiplied by the
51+
number of times they've been dead).
52+
53+
`DefaultDisableIdInference`::
54+
55+
Disables automatic Id inference for given CLR types.
56+
+
57+
The client by default will use the value of a property named `Id` on a CLR type
58+
as the `_id` to send to {es}. Adding a type will disable this behaviour for that
59+
CLR type. If `Id` inference should be disabled for all CLR types, use
60+
`DefaultDisableIdInference`.
61+
62+
`DefaultFieldNameInferrer`::
63+
64+
Specifies how field names are inferred from CLR property names.
65+
+
66+
By default, the client camel cases property names. For example, CLR property
67+
`EmailAddress` will be inferred as "emailAddress" {es} document field name.
68+
69+
`DefaultIndex`::
70+
71+
The default index to use for a request when no index has been explicitly
72+
specified and no default indices are specified for the given CLR type specified
73+
for the request.
74+
75+
`DefaultMappingFor`::
76+
77+
Specify how the mapping is inferred for a given CLR type. The mapping can infer
78+
the index, id and relation name for a given CLR type, as well as control
79+
serialization behaviour for CLR properties.
80+
81+
`DisableAutomaticProxyDetection`::
82+
83+
Disabled proxy detection on the webrequest, in some cases this may speed up the
84+
first connection your appdomain makes, in other cases it will actually increase
85+
the time for the first connection. No silver bullet! Use with care!
86+
87+
`DisableDirectStreaming`::
88+
89+
When set to true will disable (de)serializing directly to the request and
90+
response stream and return a byte[] copy of the raw request and response.
91+
Defaults to false.
92+
93+
`DisablePing`::
94+
95+
This signals that we do not want to send initial pings to unknown/previously
96+
dead nodes and just send the call straightaway.
97+
98+
`DnsRefreshTimeout`::
99+
100+
DnsRefreshTimeout for the connections. Defaults to 5 minutes.
101+
102+
`EnableDebugMode`::
103+
104+
Turns on settings that aid in debugging like `DisableDirectStreaming()` and
105+
`PrettyJson()` so that the original request and response JSON can be inspected.
106+
It also always asks the server for the full stack trace on errors.
107+
108+
`EnableHttpCompression`::
109+
110+
Enable gzip compressed requests and responses.
111+
112+
`EnableHttpPipelining`::
113+
114+
Whether HTTP pipelining is enabled. The default is `true`.
115+
116+
`EnableTcpKeepAlive`::
117+
118+
Sets the keep-alive option on a TCP connection.
119+
+
120+
For Desktop CLR, sets `ServicePointManager`.`SetTcpKeepAlive`.
121+
122+
`EnableTcpStats`::
123+
124+
Enable statistics about TCP connections to be collected when making a request.
125+
126+
`GlobalHeaders`::
127+
128+
Try to send these headers for every request.
129+
130+
`GlobalQueryStringParameters`::
131+
132+
Append these query string parameters automatically to every request.
133+
134+
`MaxDeadTimeout`::
135+
136+
The maximum amount of time a node is allowed to marked dead.
137+
138+
`MaximumRetries`::
139+
140+
When a retryable exception occurs or status code is returned this controls the
141+
maximum amount of times we should retry the call to {es}.
142+
143+
`MaxRetryTimeout`::
144+
145+
Limits the total runtime including retries separately from `RequestTimeout`.
146+
When not specified defaults to `RequestTimeout` which itself defaults to 60
147+
seconds.
148+
149+
`MemoryStreamFactory`::
150+
151+
Provides a memory stream factory.
152+
153+
`NodePredicate`::
154+
155+
Register a predicate to select which nodes that you want to execute API calls
156+
on. Note that sniffing requests omit this predicate and always execute on all
157+
nodes. When using an `IConnectionPool` implementation that supports reseeding of
158+
nodes, this will default to omitting master only node from regular API calls.
159+
When using static or single node connection pooling it is assumed the list of
160+
node you instantiate the client with should be taken verbatim.
161+
162+
`OnRequestCompleted`::
163+
164+
Allows you to register a callback every time a an API call is returned.
165+
166+
`OnRequestDataCreated`::
167+
168+
An action to run when the `RequestData` for a request has been created.
169+
170+
`PingTimeout`::
171+
172+
The timeout in milliseconds to use for ping requests, which are issued to
173+
determine whether a node is alive.
174+
175+
`PrettyJson`::
176+
177+
Provide hints to serializer and products to produce pretty, non minified json.
178+
+
179+
Note: this is not a guarantee you will always get prettified json.
180+
181+
`Proxy`::
182+
183+
If your connection has to go through proxy, use this method to specify the
184+
proxy url.
185+
186+
`RequestTimeout`::
187+
188+
The timeout in milliseconds for each request to {es}.
189+
190+
`ServerCertificateValidationCallback`::
191+
192+
Register a `ServerCertificateValidationCallback` per request.
193+
194+
`SkipDeserializationForStatusCodes`::
195+
196+
Configure the client to skip deserialization of certain status codes, for
197+
example, you run {es} behind a proxy that returns an unexpected json format.
198+
199+
`SniffLifeSpan`::
200+
201+
Force a new sniff for the cluster when the cluster state information is older
202+
than the specified timespan.
203+
204+
`SniffOnConnectionFault`::
205+
206+
Force a new sniff for the cluster state every time a connection dies.
207+
208+
`SniffOnStartup`::
209+
210+
Sniff the cluster state immediately on startup.
211+
212+
`ThrowExceptions`::
213+
214+
Instead of following a c/go like error checking on response. `IsValid` do throw
215+
an exception (except when `SuccessOrKnownError` is false) on the client when a
216+
call resulted in an exception on either the client or the {es} server.
217+
+
218+
Reasons for such exceptions could be search parser errors, index missing
219+
exceptions, and so on.
220+
221+
`TransferEncodingChunked`::
222+
223+
Whether the request should be sent with chunked Transfer-Encoding.
224+
225+
`UserAgent`::
226+
227+
The user agent string to send with requests. Useful for debugging purposes to
228+
understand client and framework versions that initiate requests to {es}.
229+
230+
231+
==== ElasticsearchClientSettings with ElasticsearchClient
232+
233+
Here's an example to demonstrate setting configuration options using the client.
234+
235+
[source,csharp]
236+
----
237+
var settings= new ElasticsearchClientSettings()
238+
.DefaultMappingFor<Project>(i => i
239+
.IndexName("my-projects")
240+
.IdProperty(p => p.Name)
241+
)
242+
.EnableDebugMode()
243+
.PrettyJson()
244+
.RequestTimeout(TimeSpan.FromMinutes(2));
245+
246+
var client = new ElasticsearchClient(settings);
247+
----

‎docs/high-level.asciidoc

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,6 @@ include::{output-dir}/getting-started.asciidoc[]
5252
NEST uses sensible defaults for connecting to and interacting with an Elasticsearch cluster but provides numerous
5353
configuration options and components to change this behaviour
5454

55-
* <<configuration-options, Configuration options>>
56-
5755
* <<connection-pooling, Connection pools>>
5856

5957
* <<modifying-default-connection, Modifying the default connection>>
@@ -62,8 +60,6 @@ configuration options and components to change this behaviour
6260

6361
* <<function-as-a-service-environments, Using the Client in a Function-as-a-Service Environment>>
6462

65-
include::client-concepts/connection/configuration-options.asciidoc[]
66-
6763
include::client-concepts/connection-pooling/building-blocks/connection-pooling.asciidoc[]
6864

6965
include::client-concepts/connection/modifying-default-connection.asciidoc[]

‎docs/index.asciidoc

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,8 @@
33
[[elasticsearch-net-reference]]
44
= Elasticsearch .NET Client
55

6-
////
7-
IMPORTANT NOTE
8-
==============
9-
This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/index.asciidoc.
10-
If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
11-
please modify the original csharp file found at the link and submit the PR with that change. Thanks!
12-
////
6+
:net-client: Elasticsearch .NET Client
7+
138

149
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
1510

@@ -19,6 +14,8 @@ include::install.asciidoc[]
1914

2015
include::connecting.asciidoc[]
2116

17+
include::configuration.asciidoc[]
18+
2219
include::breaking-changes.asciidoc[]
2320

2421
include::conventions.asciidoc[]
@@ -32,3 +29,7 @@ include::search.asciidoc[]
3229
include::query-dsl.asciidoc[]
3330

3431
include::aggregations.asciidoc[]
32+
33+
include::redirects.asciidoc[]
34+
35+
include::release-notes/release-notes.asciidoc[]

‎docs/redirects.asciidoc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
["appendix",role="exclude",id="redirects"]
2+
= Deleted pages
3+
4+
The following pages have moved or been deleted.
5+
6+
[role="exclude",id="configuration-options"]
7+
== Configuration options
8+
9+
This page has moved. See <<configuration>>.

‎docs/release-notes/breaking-change-policy.asciidoc

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
[[breaking-changes-policy]]
2+
== Breaking changes policy
3+
4+
The {net-client} source code is generated from a https://github.com/elastic/elasticsearch-specification[formal specification of the Elasticsearch API]. This API specification is large, and although it is tested against hundreds of Elasticsearch test files, it may have discrepancies with the actual API that result in issues in the {net-client}.
5+
6+
Fixing these discrepancies in the API specification results in code changes in the {net-client}, and some of these changes can require code updates in your applications.
7+
8+
This section explains how these breaking changes are considered for inclusion in {net-client} releases.
9+
10+
[discrete]
11+
==== Breaking changes in patch releases
12+
13+
Some issues in the API specification are properties that have an incorrect type, such as a `long` that should be a `string`, or a required property that is actually optional. These issues can cause the {net-client} to not work properly or even throw exceptions.
14+
15+
When a specification issue is discovered and resolved, it may require code updates in applications using the {net-client}. Such breaking changes are considered acceptable, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), as they introduce stability to APIs that may otherwise be unusable.
16+
17+
[discrete]
18+
==== Breaking changes in minor releases
19+
20+
Along with these bug fixes, the API specification is constantly refined, more precise type definitions are introduced to improve developer comfort and remove ambiguities. The specification of often-used APIs is fairly mature, so these changes happen generally on less often used APIs. These changes can also cause breaking changes requiring code updates which are considered _acceptable in minor releases_ (e.g. 8.0 -> 8.1).
21+
22+
[discrete]
23+
==== Breaking changes in major releases
24+
25+
Major releases (e.g. 7.x -> 8.x) can include larger refactorings of the API specification and the framework underlying the {net-client}. These refactorings are considered carefully and done only when they unlock new important features or new developments.
26+
27+
[discrete]
28+
==== Elasticsearch API stability guarantees
29+
30+
All Elasticsearch APIs have stability indicators, which imply potential changes. If an API is `stable` only additional non-breaking changes are added. In case of `experimental` APIs, breaking changes can be introduced any time, which means that these changes, will also be reflected in the {net-client}.

‎docs/release-notes/release-notes-8.0.0.asciidoc

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,4 @@
22
[[release-notes-8.0.0]]
33
== Release-Notes 8.0.0
44

5-
include::release-notes-8.0.0-human.asciidoc[]
6-
include::release-notes-8.0.0-generated.asciidoc[]
7-
8-
5+
Coming soon!

‎docs/release-notes/release-notes.asciidoc

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,6 @@
11
[[release-notes]]
22
= Release notes
33

4-
[partintro]
5-
--
6-
Review important information about 8.0.x releases.
7-
8-
* <<release-notes-8.0.0>>
9-
--
10-
11-
12-
13-
include::release-notes-8.0.0.asciidoc[]
14-
4+
* <<breaking-changes-policy,Breaking changes policy>>
155

6+
include::breaking-change-policy.asciidoc[]

0 commit comments

Comments
 (0)