Add more examples to the documentation

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,131 @@
+[[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]
+==== Object initializer API
+
+[source,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
+});
+----
+
+[discrete]
+==== Consume 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]
+==== Object initializer API
+
+[source,csharp]
+----
+var topLevelAggregation = Aggregation.Terms(new TermsAggregation
+{
+	Field = Infer.Field<Person>(x => x.FirstName)
+});
+
+topLevelAggregation.Aggregations = new Dictionary<string, Aggregation>
+{
+	{ "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
+});
+----
+
+[discrete]
+==== Consume 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/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[]

docs/usage/mappings.asciidoc

@@ -0,0 +1,34 @@
+[[mappings]]
+== Custom mapping 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(Infer.Field<Person>(x => x.FirstName))
+		{
+			Value = "Florian"
+		}),
+		Size = 10
+	});
+----
+
+
+[discrete]
+=== Consume the response
+
+[source,csharp]
+----
+foreach (var person in response.Documents)
+{
+	Console.WriteLine(person.FirstName);
+}
+----