From 1d0683ab2dd99ec65f361d26168bc6fabef616dd Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Tue, 1 Oct 2024 12:13:18 +0200 Subject: [PATCH 01/17] Add more examples to the documentation --- docs/index.asciidoc | 2 +- docs/usage/aggregations.asciidoc | 83 ++++++++++++++++++++++++++++++++ docs/usage/mappings.asciidoc | 34 +++++++++++++ docs/usage/query.asciidoc | 50 +++++++++++++++++++ 4 files changed, 168 insertions(+), 1 deletion(-) create mode 100644 docs/usage/aggregations.asciidoc create mode 100644 docs/usage/mappings.asciidoc create mode 100644 docs/usage/query.asciidoc diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 59a48269c40..b1202f34de2 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -6,7 +6,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :doc-tests-src: {docdir}/../tests/Tests/Documentation :net-client: Elasticsearch .NET Client -:latest-version: 8.1.0 +:latest-version: 8.15.8 :es-docs: https://www.elastic.co/guide/en/elasticsearch/reference/{branch} diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc new file mode 100644 index 00000000000..4227964b12c --- /dev/null +++ b/docs/usage/aggregations.asciidoc @@ -0,0 +1,83 @@ +[[aggregations]] +== Aggregation Examples + +This page demonstrates how to use aggregations. + +[discrete] +=== Top Level Aggreggation + +[discrete] +==== Fluent API + +[source,csharp] +---- +var response = await client + .SearchAsync(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) + ); +---- + +[discrete] +==== Consuming the Response + +[source,csharp] +---- +var max = response.Aggregations!.GetMax("agg_name")!; +Console.WriteLine(max.Value); +---- + +[discrete] +=== Sub Aggregation + +[discrete] +==== Fluent API + +[source,csharp] +---- +var response = await client + .SearchAsync(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) + ); +---- + +[discrete] +==== Consuming the Response + +[source,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}"); +} +---- diff --git a/docs/usage/mappings.asciidoc b/docs/usage/mappings.asciidoc new file mode 100644 index 00000000000..980f82deb41 --- /dev/null +++ b/docs/usage/mappings.asciidoc @@ -0,0 +1,34 @@ +[[mappings]] +== Custom Mappings Examples + +This page demonstrates how to configure custom mappings on an index. + +[discrete] +=== Configure Mappings during Index Creation + +[source,csharp] +---- +await client.Indices.CreateAsync(index => index + .Index("index") + .Mappings(mappings => mappings + .Properties(properties => properties + .IntegerNumber(x => x.Age!) + .Keyword(x => x.FirstName!, keyword => keyword.Index(false)) + ) + ) +); +---- + +[discrete] +=== Configure Mappings after Index Creation + +[source,csharp] +---- +await client.Indices.PutMappingAsync(mappings => mappings + .Indices("index") + .Properties(properties => properties + .IntegerNumber(x => x.Age!) + .Keyword(x => x.FirstName!, keyword => keyword.Index(false)) + ) +); +---- diff --git a/docs/usage/query.asciidoc b/docs/usage/query.asciidoc new file mode 100644 index 00000000000..5fd4f6c1065 --- /dev/null +++ b/docs/usage/query.asciidoc @@ -0,0 +1,50 @@ +[[query]] +== Query Examples + +This page demonstrates how to perform a search request. + +[discrete] +=== Fluent API + +[source,csharp] +---- +var response = await client + .SearchAsync(search => search + .Index("persons") + .Query(query => query + .Term(term => term + .Field(x => x.FirstName) + .Value("Florian") + ) + ) + .Size(10) + ); +---- + +[discrete] +=== Object Initializer API + +[source,csharp] +---- +var response = await client + .SearchAsync(new SearchRequest("persons") + { + Query = Query.Term(new TermQuery("firstName"!) + { + Value = "Florian" + }), + Size = 10 + }); +---- + + +[discrete] +=== Consuming the Response + +[source,csharp] +---- +foreach (var person in response.Documents) +{ + Console.WriteLine(person.FirstName); +} +---- From 392be392e9f3e402afbdde8e97c67c1985cd5126 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Wed, 2 Oct 2024 19:11:03 -0400 Subject: [PATCH 02/17] Update index.asciidoc --- docs/usage/index.asciidoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/usage/index.asciidoc b/docs/usage/index.asciidoc index 1d5aa7e086b..c6ae095064a 100644 --- a/docs/usage/index.asciidoc +++ b/docs/usage/index.asciidoc @@ -16,4 +16,7 @@ NOTE: This is still a work in progress, more sections will be added in the near include::recommendations.asciidoc[] include::examples.asciidoc[] +include::query.asciidoc[] +include::mappings.asciidoc[] +include::aggregations.asciidoc[] include::esql.asciidoc[] \ No newline at end of file From caa1b86f531d8dd0e85f1775876bbcf1e2db8d31 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:22:13 +0200 Subject: [PATCH 03/17] Update docs/usage/aggregations.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/aggregations.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index 4227964b12c..48c9489c3a7 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -4,7 +4,7 @@ This page demonstrates how to use aggregations. [discrete] -=== Top Level Aggreggation +=== Top-level aggreggation [discrete] ==== Fluent API From 8822fce062efac5d5455018935cf61aaff72f803 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:22:18 +0200 Subject: [PATCH 04/17] Update docs/usage/aggregations.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/aggregations.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index 48c9489c3a7..9b25e83ffe4 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -29,7 +29,7 @@ var response = await client ---- [discrete] -==== Consuming the Response +==== Consume the response [source,csharp] ---- From b87cb984750f411854e525d5b62ac7d677e029e3 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:22:24 +0200 Subject: [PATCH 05/17] Update docs/usage/aggregations.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/aggregations.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index 9b25e83ffe4..9708aeb1ad8 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -38,7 +38,7 @@ Console.WriteLine(max.Value); ---- [discrete] -=== Sub Aggregation +=== Sub-aggregation [discrete] ==== Fluent API From 70c3903ecb5f171ecfb4c40caaae110539a72d45 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:22:29 +0200 Subject: [PATCH 06/17] Update docs/usage/aggregations.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/aggregations.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index 9708aeb1ad8..63607396ef9 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -70,7 +70,7 @@ var response = await client ---- [discrete] -==== Consuming the Response +==== Consume the response [source,csharp] ---- From 86901a2114c87c025dea176b0ac679993cd3e984 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:22:36 +0200 Subject: [PATCH 07/17] Update docs/usage/mappings.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/mappings.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/mappings.asciidoc b/docs/usage/mappings.asciidoc index 980f82deb41..00e56624c77 100644 --- a/docs/usage/mappings.asciidoc +++ b/docs/usage/mappings.asciidoc @@ -20,7 +20,7 @@ await client.Indices.CreateAsync(index => index ---- [discrete] -=== Configure Mappings after Index Creation +=== Configure mappings after index creation [source,csharp] ---- From ea6a7ca2996c93ea95b76fe318e883159faf961a Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:22:43 +0200 Subject: [PATCH 08/17] Update docs/usage/query.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/query.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/query.asciidoc b/docs/usage/query.asciidoc index 5fd4f6c1065..8d8999968f4 100644 --- a/docs/usage/query.asciidoc +++ b/docs/usage/query.asciidoc @@ -39,7 +39,7 @@ var response = await client [discrete] -=== Consuming the Response +=== Consume the response [source,csharp] ---- From ca6d8b7f409922c1b15da5d2700e4eb02970025e Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:22:49 +0200 Subject: [PATCH 09/17] Update docs/usage/mappings.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/mappings.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/mappings.asciidoc b/docs/usage/mappings.asciidoc index 00e56624c77..1ae13cd33cc 100644 --- a/docs/usage/mappings.asciidoc +++ b/docs/usage/mappings.asciidoc @@ -1,5 +1,5 @@ [[mappings]] -== Custom Mappings Examples +== Custom mapping examples This page demonstrates how to configure custom mappings on an index. From 87502b9acc4c21a8dfd49411cbe97d03ae4b6ce6 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:22:54 +0200 Subject: [PATCH 10/17] Update docs/usage/query.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/query.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/query.asciidoc b/docs/usage/query.asciidoc index 8d8999968f4..ac16f76ee77 100644 --- a/docs/usage/query.asciidoc +++ b/docs/usage/query.asciidoc @@ -1,5 +1,5 @@ [[query]] -== Query Examples +== Query examples This page demonstrates how to perform a search request. From 998adecd65d0f62668869c81dd62ae3c28b9b20a Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:22:59 +0200 Subject: [PATCH 11/17] Update docs/usage/aggregations.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/aggregations.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index 63607396ef9..c52c950048c 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -1,5 +1,5 @@ [[aggregations]] -== Aggregation Examples +== Aggregation examples This page demonstrates how to use aggregations. From 0fd895c65f2dd4fbb37d4c04686cda60019bdd2c Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:23:04 +0200 Subject: [PATCH 12/17] Update docs/usage/mappings.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/mappings.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/mappings.asciidoc b/docs/usage/mappings.asciidoc index 1ae13cd33cc..13d62f63147 100644 --- a/docs/usage/mappings.asciidoc +++ b/docs/usage/mappings.asciidoc @@ -4,7 +4,7 @@ This page demonstrates how to configure custom mappings on an index. [discrete] -=== Configure Mappings during Index Creation +=== Configure mappings during index creation [source,csharp] ---- From bf7233061c1e4a3081f7cc9d09bc623f8f063dd5 Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:23:08 +0200 Subject: [PATCH 13/17] Update docs/usage/query.asciidoc Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- docs/usage/query.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/query.asciidoc b/docs/usage/query.asciidoc index ac16f76ee77..e4c6b5118e5 100644 --- a/docs/usage/query.asciidoc +++ b/docs/usage/query.asciidoc @@ -22,7 +22,7 @@ var response = await client ---- [discrete] -=== Object Initializer API +=== Object initializer API [source,csharp] ---- From 34e07e1b521b72e03feb2f4c43dbfc8b5d9bb58e Mon Sep 17 00:00:00 2001 From: Florian Bernd Date: Fri, 4 Oct 2024 15:25:42 +0200 Subject: [PATCH 14/17] Add more object initializer API examples --- docs/usage/aggregations.asciidoc | 50 ++++++++++++++++++++++++++++++++ docs/usage/query.asciidoc | 2 +- 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index c52c950048c..44f2f6d342e 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -29,6 +29,26 @@ var response = await client ---- [discrete] +==== Object initializer API + +[source,csharp] +---- +var response = await client.SearchAsync(new SearchRequest("persons") +{ + Query = Query.MatchAll(new MatchAllQuery()), + Aggregations = new Dictionary + { + { "agg_name", Aggregation.Max(new MaxAggregation + { + Field = Infer.Field(x => x.Age) + })} + }, + Size = 10 +}); +---- + +[discrete] +==== Consuming the Response ==== Consume the response [source,csharp] @@ -70,6 +90,36 @@ var response = await client ---- [discrete] +==== Object initializer API + +[source,csharp] +---- +var topLevelAggregation = Aggregation.Terms(new TermsAggregation +{ + Field = Infer.Field(x => x.FirstName) +}); + +topLevelAggregation.Aggregations = new Dictionary +{ + { "avg_age", new MaxAggregation + { + Field = Infer.Field(x => x.Age) + }} +}; + +var response = await client.SearchAsync(new SearchRequest("persons") +{ + Query = Query.MatchAll(new MatchAllQuery()), + Aggregations = new Dictionary + { + { "firstnames", topLevelAggregation} + }, + Size = 10 +}); +---- + +[discrete] +==== Consuming the Response ==== Consume the response [source,csharp] diff --git a/docs/usage/query.asciidoc b/docs/usage/query.asciidoc index e4c6b5118e5..b365825cdbd 100644 --- a/docs/usage/query.asciidoc +++ b/docs/usage/query.asciidoc @@ -29,7 +29,7 @@ var response = await client var response = await client .SearchAsync(new SearchRequest("persons") { - Query = Query.Term(new TermQuery("firstName"!) + Query = Query.Term(new TermQuery(Infer.Field(x => x.FirstName)) { Value = "Florian" }), From 3bf78612bb6107f581b8052b1ab89dbc94429862 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Fri, 4 Oct 2024 12:13:43 -0400 Subject: [PATCH 15/17] Fix double heading --- docs/usage/aggregations.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index 44f2f6d342e..e748cfa9d54 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -48,7 +48,7 @@ var response = await client.SearchAsync(new SearchRequest("persons") ---- [discrete] -==== Consuming the Response +==== Consume the response ==== Consume the response [source,csharp] From d736bc3dcf33ecb4b0747cbbb360756e7c521002 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Fri, 4 Oct 2024 12:15:22 -0400 Subject: [PATCH 16/17] Fix double heading --- docs/usage/aggregations.asciidoc | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index e748cfa9d54..648b422188d 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -49,7 +49,6 @@ var response = await client.SearchAsync(new SearchRequest("persons") [discrete] ==== Consume the response -==== Consume the response [source,csharp] ---- From 1271ba148f658a0cf7256d713be8aa814714b515 Mon Sep 17 00:00:00 2001 From: Marci W <333176+marciw@users.noreply.github.com> Date: Fri, 4 Oct 2024 12:15:35 -0400 Subject: [PATCH 17/17] Fix double heading 2 --- docs/usage/aggregations.asciidoc | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index 648b422188d..1f159763aaa 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -118,7 +118,6 @@ var response = await client.SearchAsync(new SearchRequest("persons") ---- [discrete] -==== Consuming the Response ==== Consume the response [source,csharp]