Skip to content

Commit d718d0f

Browse files
russcamrusscam
committed
Update documentation
1 parent 1036308 commit d718d0f

File tree

10 files changed

+223
-28
lines changed

10 files changed

+223
-28
lines changed

‎docs/aggregations/bucket/significant-terms/significant-terms-aggregation-usage.asciidoc‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -221,3 +221,57 @@ sigNames.Should().NotBeNull();
221221
sigNames.DocCount.Should().BeGreaterThan(0);
222222
----
223223

224+
[[significant-terms-numeric-field]]
225+
[float]
226+
== Numeric fields
227+
228+
A significant terms aggregation on a numeric field
229+
230+
==== Fluent DSL example
231+
232+
[source,csharp]
233+
----
234+
a => a
235+
.SignificantTerms("commits", st => st
236+
.Field(p => p.NumberOfContributors)
237+
)
238+
----
239+
240+
==== Object Initializer syntax example
241+
242+
[source,csharp]
243+
----
244+
new SignificantTermsAggregation("commits")
245+
{
246+
Field = Field<Project, int>(p => p.NumberOfContributors)
247+
}
248+
----
249+
250+
[source,javascript]
251+
.Example json output
252+
----
253+
{
254+
"commits": {
255+
"significant_terms": {
256+
"field": "numberOfContributors"
257+
}
258+
}
259+
}
260+
----
261+
262+
==== Handling Responses
263+
264+
[source,csharp]
265+
----
266+
response.ShouldBeValid();
267+
var commits = response.Aggregations.SignificantTerms<int>("commits");
268+
commits.Should().NotBeNull();
269+
commits.Buckets.Should().NotBeNull();
270+
commits.Buckets.Count.Should().BeGreaterThan(0);
271+
foreach (var item in commits.Buckets)
272+
{
273+
item.Key.Should().BeGreaterThan(0);
274+
item.DocCount.Should().BeGreaterOrEqualTo(1);
275+
}
276+
----
277+

‎docs/aggregations/matrix/matrix-stats/matrix-stats-aggregation-usage.asciidoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ response.ShouldBeValid();
8787
var matrix = response.Aggregations.MatrixStats("matrixstats");
8888
matrix.Should().NotBeNull();
8989
matrix.Fields.Should().NotBeNull().And.HaveCount(2);
90+
matrix.DocCount.Should().BeGreaterThan(0);
9091
9192
AssertField(matrix, "numberOfCommits");
9293
AssertField(matrix, "numberOfContributors");

‎docs/client-concepts/certificates/working-with-certificates.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ the certificate the server presented was generated using it
9393
[IntegrationOnly]
9494
public class CertgenCaCluster : SslAndKpiXPackCluster
9595
{
96+
public CertgenCaCluster() : base() { }
97+
public CertgenCaCluster(SslAndKpiClusterConfiguration configuration) : base(configuration) { }
9698
protected override ConnectionSettings ConnectionSettings(ConnectionSettings s) => s
9799
.ServerCertificateValidationCallback(
98100
CertificateValidations.AuthorityIsRoot(new X509Certificate(this.ClusterConfiguration.FileSystem.CaCertificate))

‎docs/client-concepts/connection/modifying-default-connection.asciidoc‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -97,16 +97,28 @@ to the request, change the maximum number of connections allowed to an endpoint,
9797
By deriving from `HttpConnection`, it is possible to change the behaviour of the connection. The following
9898
provides some examples
9999

100+
On .NET full framework the overrides on HttpConnection are different as they are geared towards using HttpWebRequest.
101+
Here are two examples for .NET full framework
102+
100103
[source,csharp]
101104
----
102105
public class MyCustomHttpConnection : HttpConnection
103106
{
104-
protected override HttpRequestMessage CreateRequestMessage(RequestData requestData)
107+
protected override void AlterServicePoint(ServicePoint requestServicePoint, RequestData requestData)
105108
{
106-
var message = base.CreateRequestMessage(requestData);
107-
var header = string.Empty;
108-
message.Headers.Authorization = new AuthenticationHeaderValue("Negotiate", header);
109-
return message;
109+
base.AlterServicePoint(requestServicePoint, requestData);
110+
requestServicePoint.ConnectionLimit = 10000;
111+
requestServicePoint.UseNagleAlgorithm = true;
112+
}
113+
}
114+
115+
public class X509CertificateHttpConnection : HttpConnection
116+
{
117+
protected override HttpWebRequest CreateHttpWebRequest(RequestData requestData)
118+
{
119+
var request = base.CreateHttpWebRequest(requestData);
120+
request.ClientCertificates.Add(new X509Certificate("file_path_to_cert"));
121+
return request;
110122
}
111123
}
112124
----
@@ -124,17 +136,3 @@ var client = new ElasticClient(settings);
124136

125137
See <<working-with-certificates, Working with certificates>> for further details.
126138

127-
[source,csharp]
128-
----
129-
public class KerberosConnection : HttpConnection
130-
{
131-
protected override HttpRequestMessage CreateRequestMessage(RequestData requestData)
132-
{
133-
var message = base.CreateRequestMessage(requestData);
134-
var header = string.Empty;
135-
message.Headers.Authorization = new AuthenticationHeaderValue("Negotiate", header);
136-
return message;
137-
}
138-
}
139-
----
140-

‎docs/client-concepts/troubleshooting/diagnostic-source.asciidoc‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/7.0
2+
3+
:github: https://github.com/elastic/elasticsearch-net
4+
5+
:nuget: https://www.nuget.org/packages
6+
7+
////
8+
IMPORTANT NOTE
9+
==============
10+
This file has been generated from https://github.com/elastic/elasticsearch-net/tree/7.x/src/Tests/Tests/ClientConcepts/Troubleshooting/DiagnosticSource.doc.cs.
11+
If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
12+
please modify the original csharp file found at the link and submit the PR with that change. Thanks!
13+
////
14+
15+
[[diagnostic-source]]
16+
=== Diagnostic Source
17+
18+
Elasticsearch.Net and by proxy NEST ship with support for DiagnosticSource and Activity out of the box.
19+
20+
To aid with their discover the topics you can subscribe on and the event names they emit are exposed as
21+
strongly typed strings under `Elasticsearch.Net.Diagnostics.DiagnosticSources`
22+
23+
Subscribing to DiagnosticSources means implementing `IObserver<DiagnosticListener>`
24+
or use `.Subscribe(observer, filter)` to opt in to the correct topic.
25+
26+
Here we choose the more verbose `IObserver<>` implementation.
27+
28+
[source,csharp]
29+
----
30+
private class ListenerObserver : IObserver<DiagnosticListener>, IDisposable
31+
{
32+
private long _messagesWrittenToConsole = 0;
33+
public long MessagesWrittenToConsole => _messagesWrittenToConsole;
34+
35+
public Exception SeenException { get; private set; }
36+
public void OnError(Exception error) => SeenException = error;
37+
38+
public bool Completed { get; private set; }
39+
public void OnCompleted() => Completed = true;
40+
41+
private void WriteToConsole<T>(string eventName, T data)
42+
{
43+
var a = Activity.Current;
44+
Interlocked.Increment(ref _messagesWrittenToConsole);
45+
}
46+
47+
private List<IDisposable> Disposables { get; } = new List<IDisposable>();
48+
49+
/**
50+
* By inspecting the name we selectively subscribe only to topics `Elasticsearch.Net` emits.
51+
*
52+
* Thanks to `DiagnosticSources` you do not have to guess the topics we emit under.
53+
*
54+
* `DiagnosticListener.Subscribe` expects an `IObserver<KeyValuePair<string, object>>` which is useful to create
55+
* a decoupled messaging contract but as a subscriber you would like to know what `object` is.
56+
*
57+
* Therefor each topic we ship with has a dedicated `Observer` implementation that takes an `onNext` lambda
58+
* which is typed to the context object we actually emit.
59+
*
60+
*/
61+
public void OnNext(DiagnosticListener value)
62+
{
63+
void TrySubscribe(string sourceName, Func<IObserver<KeyValuePair<string, object>>> listener)
64+
{
65+
if (value.Name != sourceName) return;
66+
67+
var subscription = value.Subscribe(listener());
68+
Disposables.Add(subscription);
69+
}
70+
71+
TrySubscribe(DiagnosticSources.AuditTrailEvents.SourceName,
72+
() => new AuditDiagnosticObserver(v => WriteToConsole(v.EventName, v.Audit)));
73+
74+
TrySubscribe(DiagnosticSources.Serializer.SourceName,
75+
() => new SerializerDiagnosticObserver(v => WriteToConsole(v.EventName, v.Registration)));
76+
/**
77+
* RequestPipeline emits a different context object for the start of the `Activity` then it does
78+
* for the end of the `Activity` therefor `RequestPipelineDiagnosticObserver` accepts two `onNext` lambda's.
79+
* One for the `.Start` events and one for the `.Stop` events.
80+
*/
81+
TrySubscribe(DiagnosticSources.RequestPipeline.SourceName,
82+
() => new RequestPipelineDiagnosticObserver(
83+
v => WriteToConsole(v.EventName, v.RequestData),
84+
v => WriteToConsole(v.EventName, v.Response)
85+
));
86+
87+
TrySubscribe(DiagnosticSources.HttpConnection.SourceName,
88+
() => new HttpConnectionDiagnosticObserver(
89+
v => WriteToConsole(v.EventName, v.RequestData),
90+
v => WriteToConsole(v.EventName, v.StatusCode)
91+
));
92+
}
93+
94+
public void Dispose()
95+
{
96+
foreach(var d in Disposables) d.Dispose();
97+
}
98+
}
99+
----
100+
101+
Here we hook into all diagnostic sources and use `ListenerObserver` to only listen to the ones
102+
from `Elasticsearch.Net`
103+
104+
[source,csharp]
105+
----
106+
using(var listenerObserver = new ListenerObserver())
107+
using (var subscription = DiagnosticListener.AllListeners.Subscribe(listenerObserver))
108+
{
109+
110+
/**
111+
* We'll use a Sniffing connection pool here since it sniffs on startup and pings before
112+
* first usage, so our diagnostics are involved enough to showcase most topics.
113+
*/
114+
var pool = new SniffingConnectionPool(new []{ TestConnectionSettings.CreateUri() });
115+
var connectionSettings = new ConnectionSettings(pool)
116+
.DefaultMappingFor<Project>(i => i
117+
.IndexName("project")
118+
);
119+
120+
var client = new ElasticClient(connectionSettings);
121+
122+
/**
123+
* After issuing the following request
124+
*/
125+
var response = client.Search<Project>(s => s
126+
.MatchAll()
127+
);
128+
129+
listenerObserver.SeenException.Should().BeNull();
130+
listenerObserver.Completed.Should().BeFalse();
131+
listenerObserver.MessagesWrittenToConsole.Should().BeGreaterThan(0);
132+
}
133+
----
134+

‎docs/code-standards/naming-conventions.asciidoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,7 @@ var typesNotIElasticsearchNetNamespace = types
192192
.Where(t => t.Namespace != "Elasticsearch.Net" && !t.Namespace.StartsWith("Elasticsearch.Net.Specification"))
193193
.Where(t => !t.Namespace.StartsWith("Elasticsearch.Net.Utf8Json"))
194194
.Where(t => !t.Namespace.StartsWith("Elasticsearch.Net.Extensions"))
195+
.Where(t => !t.Namespace.StartsWith("Elasticsearch.Net.Diagnostics"))
195196
.Where(t => !t.Namespace.StartsWith("Elasticsearch.Net.CrossPlatform"))
196197
.Where(t => !t.Name.StartsWith("<"))
197198
.Where(t => IsValidTypeNameOrIdentifier(t.Name, true))

‎docs/code-standards/responses.asciidoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,14 @@ var exceptions = new HashSet<PropertyInfo>
2525
typeof(ITypeMapping).GetProperty(nameof(ITypeMapping.Meta)),
2626
typeof(TypeMapping).GetProperty(nameof(TypeMapping.DynamicDateFormats)),
2727
typeof(TypeMapping).GetProperty(nameof(TypeMapping.Meta)),
28+
typeof(DynamicDictionary).GetProperty(nameof(DynamicDictionary.Keys)),
29+
typeof(DynamicDictionary).GetProperty(nameof(DynamicDictionary.Values)),
2830
typeof(BulkResponse).GetProperty(nameof(BulkResponse.ItemsWithErrors)),
2931
typeof(StartBasicLicenseResponse).GetProperty(nameof(StartBasicLicenseResponse.Acknowledge)),
3032
typeof(FieldCapabilitiesResponse).GetProperty(nameof(FieldCapabilitiesResponse.Fields)),
3133
typeof(MultiSearchResponse).GetProperty(nameof(MultiSearchResponse.AllResponses)),
34+
typeof(DynamicDictionary).GetProperty(nameof(DynamicDictionary.Keys)),
35+
typeof(DynamicDictionary).GetProperty(nameof(DynamicDictionary.Values)),
3236
};
3337
3438
var responseInterfaceTypes = from t in typeof(IResponse).Assembly.Types()

‎docs/search/request/highlighting-usage.asciidoc‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -210,29 +210,29 @@ new SearchRequest<Project>
210210
----
211211
response.ShouldBeValid();
212212
213-
foreach (var highlightsInEachHit in response.Hits.Select(d => d.Highlights))
213+
foreach (var highlightsInEachHit in response.Hits.Select(d => d.Highlight))
214214
{
215215
foreach (var highlightField in highlightsInEachHit)
216216
{
217217
if (highlightField.Key == "name.standard")
218218
{
219-
foreach (var highlight in highlightField.Value.Highlights)
219+
foreach (var highlight in highlightField.Value)
220220
{
221221
highlight.Should().Contain("<tag1>");
222222
highlight.Should().Contain("</tag1>");
223223
}
224224
}
225225
else if (highlightField.Key == "leadDeveloper.firstName")
226226
{
227-
foreach (var highlight in highlightField.Value.Highlights)
227+
foreach (var highlight in highlightField.Value)
228228
{
229229
highlight.Should().Contain("<name>");
230230
highlight.Should().Contain("</name>");
231231
}
232232
}
233233
else if (highlightField.Key == "leadDeveloper.lastName")
234234
{
235-
foreach (var highlight in highlightField.Value.Highlights)
235+
foreach (var highlight in highlightField.Value)
236236
{
237237
highlight.Should().Contain("<name>");
238238
highlight.Should().Contain("</name>");

‎docs/search/request/inner-hits-usage.asciidoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -157,11 +157,11 @@ foreach (var hit in response.Hits)
157157
princes.Should().NotBeEmpty();
158158
foreach (var princeHit in hit.InnerHits["princes"].Hits.Hits)
159159
{
160-
var highlights = princeHit.Highlights;
160+
var highlights = princeHit.Highlight;
161161
highlights.Should().NotBeNull("princes should have highlights");
162162
highlights.Should().ContainKey("fullTextField", "we are highlighting this field");
163163
var hl = highlights["fullTextField"];
164-
hl.Highlights.Should()
164+
hl.Should()
165165
.NotBeEmpty("all docs have the same text so should all highlight")
166166
.And.Contain(s => s.Contains("<em>default</em>"), "default to be highlighted as its part of the query");
167167

‎docs/search/writing-queries.asciidoc‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -383,11 +383,12 @@ var searchResponse = client.Search<Project>(s => s
383383
var projects = searchResponse.Documents;
384384
----
385385

386-
`.Documents` is a convenient shorthand for
386+
`.Documents` is a convenient shorthand for retrieving the `_source`
387+
for each hit
387388

388389
[source,csharp]
389390
----
390-
searchResponse.HitsMetadata.Hits.Select(h => h.Source);
391+
var sources = searchResponse.HitsMetadata.Hits.Select(h => h.Source);
391392
----
392393

393394
and it's possible to retrieve other metadata about each hit from the hits collection. Here's
@@ -396,7 +397,7 @@ an example that retrieves the highlights for a hit, when using <<highlighting-us
396397
[source,csharp]
397398
----
398399
var highlights = searchResponse.HitsMetadata.Hits.Select(h => h
399-
.Highlights <1>
400+
.Highlight <1>
400401
);
401402
----
402403
<1> Get the highlights for the hit, when using highlighting

0 commit comments

Comments
 (0)