Add more examples to the documentation

Author: flobernd

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}
 

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<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)
+	);
+----
+
+[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<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)
+	);
+----
+
+[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}");
+}
+----

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<Person>(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<Person>(mappings => mappings
+	.Indices("index")
+	.Properties(properties => properties
+		.IntegerNumber(x => x.Age!)
+		.Keyword(x => x.FirstName!, keyword => keyword.Index(false))
+	)
+);
+----

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<Person>(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<Person>(new SearchRequest<Person>("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);
+}
+----