From 06b5bf952c62b1b8e59d042d35d90127a711ccf4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 24 May 2022 15:19:14 +0200 Subject: [PATCH 1/8] [DOCS] Adds Examples section to .NET docs. --- docs/examples.asciidoc | 91 ++++++++++++++++++++++++++++++++++++++++++ docs/index.asciidoc | 2 + 2 files changed, 93 insertions(+) create mode 100644 docs/examples.asciidoc diff --git a/docs/examples.asciidoc b/docs/examples.asciidoc new file mode 100644 index 00000000000..745542287e7 --- /dev/null +++ b/docs/examples.asciidoc @@ -0,0 +1,91 @@ +[[examples]] +== Examples + +This page contains the information you need to perform various {es} operations +by using the Client. + + +[discrete] +[[indexing-net]] +=== Indexing a document + +Indexing a document is as simple as: + +[source,csharp] +---- +var tweet = new Tweet +{ + Id = 1, + User = "kimchy", + PostDate = new DateTime(2009, 11, 15), + Message = "Trying out NEST, so far so good?" +}; + +var response = client.Index(tweet, idx => idx.Index("mytweetindex")); //or specify index via settings.DefaultIndex("mytweetindex"); +All the calls have async variants: + +var response = client.IndexAsync(tweet, idx => idx.Index("mytweetindex")); // returns a Task + +// Or, in an async-context +var response = await client.IndexAsync(tweet, idx => idx.Index("mytweetindex")); // awaits a Task +---- + + +[discrete] +[[getting-net]] +=== Getting a document + +[source,csharp] +---- +var response = client.Get(1, idx => idx.Index("mytweetindex")); // returns an IGetResponse mapped 1-to-1 with the Elasticsearch JSON response +var tweet = response.Source; // the original document +---- + + +[discrete] +[[searching-net]] +=== Searching for documents + +The client exposes a fluent interface and a powerful query DSL. + +[source,csharp] +---- +var response = client.Search(s => s + .Index("mytweetindex") //or specify index via settings.DefaultIndex("mytweetindex"); + .From(0) + .Size(10) + .Query(q => q + .Term(t => t.User, "kimchy") || q + .Match(mq => mq.Field(f => f.User).Query("nest")) + ) +); +---- + +As well as an object initializer syntax if lambdas aren't your thing: + +[source,csharp] +---- +var request = new SearchRequest +{ + Index = "mytweetindex", //or specify index via settings.DefaultIndex("mytweetindex"), + From = 0, + Size = 10, + Query = new TermQuery { Field = "user", Value = "kimchy" } || + new MatchQuery { Field = "description", Query = "nest" } +}; + +var response = client.Search(request); +---- + + +[discrete] +[[updating-net]] +=== Updating documents + + + +[discrete] +[[deleting-net]] +=== Deleting documents + + diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 1fed3da1e7b..686fcc797bf 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -21,6 +21,8 @@ include::connecting.asciidoc[] include::configuration.asciidoc[] +include::example.asciidoc[] + include::breaking-changes.asciidoc[] include::conventions.asciidoc[] From 19d567d1bb571cac5147634c3e78ae74647425e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 24 May 2022 15:44:08 +0200 Subject: [PATCH 2/8] [DOCS] Fixe index file. --- docs/index.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 686fcc797bf..aa86f65226d 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -21,7 +21,7 @@ include::connecting.asciidoc[] include::configuration.asciidoc[] -include::example.asciidoc[] +include::examples.asciidoc[]s include::breaking-changes.asciidoc[] From 6f3801eb2d87b2ddd657b2606d8e4deeba3ea3ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 24 May 2022 15:44:39 +0200 Subject: [PATCH 3/8] [DOCS] Fixes index file. --- docs/index.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index aa86f65226d..882c2e6d59b 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -21,7 +21,7 @@ include::connecting.asciidoc[] include::configuration.asciidoc[] -include::examples.asciidoc[]s +include::examples.asciidoc[] include::breaking-changes.asciidoc[] From 2f51e68922832b43664c32c4bcb3e6fb3c06beee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Tue, 24 May 2022 16:42:55 +0200 Subject: [PATCH 4/8] [DOCS] Further changes. --- docs/examples.asciidoc | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/examples.asciidoc b/docs/examples.asciidoc index 745542287e7..0ef7d8064cf 100644 --- a/docs/examples.asciidoc +++ b/docs/examples.asciidoc @@ -18,15 +18,9 @@ var tweet = new Tweet Id = 1, User = "kimchy", PostDate = new DateTime(2009, 11, 15), - Message = "Trying out NEST, so far so good?" + Message = "Trying out the client, so far so good?" }; -var response = client.Index(tweet, idx => idx.Index("mytweetindex")); //or specify index via settings.DefaultIndex("mytweetindex"); -All the calls have async variants: - -var response = client.IndexAsync(tweet, idx => idx.Index("mytweetindex")); // returns a Task - -// Or, in an async-context var response = await client.IndexAsync(tweet, idx => idx.Index("mytweetindex")); // awaits a Task ---- @@ -37,7 +31,7 @@ var response = await client.IndexAsync(tweet, idx => idx.Index("mytweetindex")); [source,csharp] ---- -var response = client.Get(1, idx => idx.Index("mytweetindex")); // returns an IGetResponse mapped 1-to-1 with the Elasticsearch JSON response +var response = client.Get(1, idx => idx.Index("mytweetindex")); // returns a GetResponse mapped 1-to-1 with the Elasticsearch JSON response var tweet = response.Source; // the original document ---- From 83e7892b653e97a4cfda84857d295d8431f6080f Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 29 Sep 2022 15:20:05 +0100 Subject: [PATCH 5/8] Expand documentation and add missing examples --- docs/examples.asciidoc | 128 ++++++++++++++++++++++++++++++++++------- 1 file changed, 107 insertions(+), 21 deletions(-) diff --git a/docs/examples.asciidoc b/docs/examples.asciidoc index 0ef7d8064cf..bedab14506b 100644 --- a/docs/examples.asciidoc +++ b/docs/examples.asciidoc @@ -1,29 +1,72 @@ [[examples]] == Examples -This page contains the information you need to perform various {es} operations -by using the Client. +This page helps you to understand how to perform various basic {es} CRUD operations +using the .NET client. It demonstrates how to create a document by indexing an object +into {es}, read the document back by retrieving it by ID or performing a search, update +one of the fields in a document and delete a specific document. +These examples assume you have an instance of the `ElasticsearchClient` accessible via a +local variable named `client` and several using directives in your C# file. + +[source,csharp] +---- +using System; +using Elastic.Clients.Elasticsearch; +using Elastic.Clients.Elasticsearch.QueryDsl; + +var client = new ElasticsearchClient(); <1> +---- +<1> The default constructor, assumes an unsecured {es} server is running and exposed on +'http://localhost:9200'. See <> for examples of connecting to secured +servers and https://www.elastic.co/cloud[Elastic Cloud] deployments. + +The examples operate on data representing tweets. Tweets are modelled in the client +application using a C# class named 'Tweet' containing several properties that map to the +document structure being stored in {es}. + +[source,csharp] +---- +public class Tweet +{ + public int Id { get; set; } <1> + public string User { get; set; } + public DateTime PostDate { get; set; } + public string Message { get; set; } +} +---- +<1> By default, the .NET client will try to find a property called `Id` on the class. When such a property is +present it will index the document into {es} using the ID specified by the value of this property. [discrete] [[indexing-net]] === Indexing a document -Indexing a document is as simple as: +Documents can be indexed by creating an instance representing a tweet and indexing it via the client. In these +examples, we will work with an index named 'my-tweet-index'. [source,csharp] ---- -var tweet = new Tweet +var tweet = new Tweet <1> { Id = 1, - User = "kimchy", + User = "stevejgordon", PostDate = new DateTime(2009, 11, 15), Message = "Trying out the client, so far so good?" }; -var response = await client.IndexAsync(tweet, idx => idx.Index("mytweetindex")); // awaits a Task ----- +var response = await client.IndexAsync(tweet, request => request.Index("my-tweet-index")); <2> +if (response.IsValid) <3> +{ + Console.WriteLine($"Index document with ID {response.Id} succeeded."); <4> +} + +---- +<1> Create an instance of the Tweet class with relevant properties set. +<2> Prefer the async APIs, which require awaiting the response. +<3> Check the `IsValid` property on the response to confirm that the request and operation succeeded. +<4> Access the `IndexResponse` properties, such as the ID, if necessary. [discrete] [[getting-net]] @@ -31,55 +74,98 @@ var response = await client.IndexAsync(tweet, idx => idx.Index("mytweetindex")); [source,csharp] ---- -var response = client.Get(1, idx => idx.Index("mytweetindex")); // returns a GetResponse mapped 1-to-1 with the Elasticsearch JSON response -var tweet = response.Source; // the original document +var response = await client.GetAsync(1, idx => idx.Index("my-tweet-index")); <1> +var tweet = response.Source; <2> ---- +<1> The `GetResponse` is mapped 1-to-1 with the Elasticsearch JSON response. +<2> The original document is deserialized as an instance of the Tweet class, accessible on the response +via the `Source` property. [discrete] [[searching-net]] === Searching for documents -The client exposes a fluent interface and a powerful query DSL. +The client exposes a fluent interface and a powerful query DSL for searching. [source,csharp] ---- -var response = client.Search(s => s - .Index("mytweetindex") //or specify index via settings.DefaultIndex("mytweetindex"); +var response = await client.SearchAsync(s => s <1> + .Index("my-tweet-index") <2> .From(0) .Size(10) .Query(q => q - .Term(t => t.User, "kimchy") || q - .Match(mq => mq.Field(f => f.User).Query("nest")) + .Term(t => t.User, "stevejgordon") <3> ) ); + +if (response.IsValid) +{ + var tweet = response.Documents.FirstOrDefault(); <4> +} ---- +<1> The generic type argument specifies the tweet class, which is used when deserialising the hits from the response. +<2> The index can be omitted if a `DefaultIndex` has been configured on `ElasticsearchClientSettings``, or a specific +index was configured when mapping this type. +<3> Execute a term query against the `user` field, searching for tweets authored by the user 'stevejgordon'. +<4> Documents matched by the query are accessible via the `Documents` collection property on the `SearchResponse`. -As well as an object initializer syntax if lambdas aren't your thing: +You may prefer using the object initializer syntax for requests if lambdas aren't your thing. [source,csharp] ---- -var request = new SearchRequest +var request = new SearchRequest("my-tweet-index") <1> { - Index = "mytweetindex", //or specify index via settings.DefaultIndex("mytweetindex"), From = 0, Size = 10, - Query = new TermQuery { Field = "user", Value = "kimchy" } || - new MatchQuery { Field = "description", Query = "nest" } + Query = new TermQuery("user") { Value = "stevejgordon" } }; -var response = client.Search(request); ----- +var response = await client.SearchAsync(request); <2> +if (response.IsValid) +{ + var tweet = response.Documents.FirstOrDefault(); +} +---- +<1> Create an instance of `SearchRequest`, setting properties to control the search operation. +<2> Pass the request to the `SearchAsync` method on the client. [discrete] [[updating-net]] === Updating documents +Documents can be updated in several ways, including by providing a complete replacement for an +existing document ID. + +[source,csharp] +---- +tweet.Message = "This is a new message"; <1> + +var response = await client.UpdateAsync("my-tweet-index", 1, u => u + .Doc(tweet)); <2> + +if (response.IsValid) +{ + Console.WriteLine("Update document succeeded."); +} +---- +<1> Update a property on the existing tweet instance. +<2> Send the updated tweet object in the update request. [discrete] [[deleting-net]] === Deleting documents +Documents can be deleted by providing the ID of the document to remove. +[source,csharp] +---- +var response = await client.DeleteAsync("my-tweet-index", 1); + +if (response.IsValid) +{ + Console.WriteLine("Delete document succeeded."); +} +---- \ No newline at end of file From 0c01bad6e5645d3f7ec01c60a436fa07239ef049 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 29 Sep 2022 15:29:38 +0100 Subject: [PATCH 6/8] Use consistant wording when referring to 'a' document. --- docs/examples.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples.asciidoc b/docs/examples.asciidoc index bedab14506b..498cb2d8dfb 100644 --- a/docs/examples.asciidoc +++ b/docs/examples.asciidoc @@ -3,7 +3,7 @@ This page helps you to understand how to perform various basic {es} CRUD operations using the .NET client. It demonstrates how to create a document by indexing an object -into {es}, read the document back by retrieving it by ID or performing a search, update +into {es}, read a document back, retrieving it by ID or performing a search, update one of the fields in a document and delete a specific document. These examples assume you have an instance of the `ElasticsearchClient` accessible via a From d79ad8f8ca928e7cec3c047cf95a5a61155c1daf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Thu, 29 Sep 2022 16:38:13 +0200 Subject: [PATCH 7/8] [DOCS] Changes line breaks. --- docs/examples.asciidoc | 71 +++++++++++++++++++++++++----------------- 1 file changed, 42 insertions(+), 29 deletions(-) diff --git a/docs/examples.asciidoc b/docs/examples.asciidoc index 498cb2d8dfb..c86a593f423 100644 --- a/docs/examples.asciidoc +++ b/docs/examples.asciidoc @@ -1,13 +1,15 @@ [[examples]] == Examples -This page helps you to understand how to perform various basic {es} CRUD operations -using the .NET client. It demonstrates how to create a document by indexing an object -into {es}, read a document back, retrieving it by ID or performing a search, update -one of the fields in a document and delete a specific document. +This page helps you to understand how to perform various basic {es} CRUD +operations using the .NET client. It demonstrates how to create a document by +indexing an object into {es}, read a document back, retrieving it by ID or +performing a search, update one of the fields in a document and delete a +specific document. -These examples assume you have an instance of the `ElasticsearchClient` accessible via a -local variable named `client` and several using directives in your C# file. +These examples assume you have an instance of the `ElasticsearchClient` +accessible via a local variable named `client` and several using directives in +your C# file. [source,csharp] ---- @@ -17,13 +19,14 @@ using Elastic.Clients.Elasticsearch.QueryDsl; var client = new ElasticsearchClient(); <1> ---- -<1> The default constructor, assumes an unsecured {es} server is running and exposed on -'http://localhost:9200'. See <> for examples of connecting to secured -servers and https://www.elastic.co/cloud[Elastic Cloud] deployments. +<1> The default constructor, assumes an unsecured {es} server is running and +exposed on 'http://localhost:9200'. See <> for examples +of connecting to secured servers and https://www.elastic.co/cloud[Elastic Cloud] +deployments. -The examples operate on data representing tweets. Tweets are modelled in the client -application using a C# class named 'Tweet' containing several properties that map to the -document structure being stored in {es}. +The examples operate on data representing tweets. Tweets are modelled in the +client application using a C# class named 'Tweet' containing several properties +that map to the document structure being stored in {es}. [source,csharp] ---- @@ -35,15 +38,18 @@ public class Tweet public string Message { get; set; } } ---- -<1> By default, the .NET client will try to find a property called `Id` on the class. When such a property is -present it will index the document into {es} using the ID specified by the value of this property. +<1> By default, the .NET client will try to find a property called `Id` on the +class. When such a property is present it will index the document into {es} +using the ID specified by the value of this property. + [discrete] [[indexing-net]] === Indexing a document -Documents can be indexed by creating an instance representing a tweet and indexing it via the client. In these -examples, we will work with an index named 'my-tweet-index'. +Documents can be indexed by creating an instance representing a tweet and +indexing it via the client. In these examples, we will work with an index named +'my-tweet-index'. [source,csharp] ---- @@ -65,7 +71,8 @@ if (response.IsValid) <3> ---- <1> Create an instance of the Tweet class with relevant properties set. <2> Prefer the async APIs, which require awaiting the response. -<3> Check the `IsValid` property on the response to confirm that the request and operation succeeded. +<3> Check the `IsValid` property on the response to confirm that the request and +operation succeeded. <4> Access the `IndexResponse` properties, such as the ID, if necessary. [discrete] @@ -78,8 +85,8 @@ var response = await client.GetAsync(1, idx => idx.Index("my-tweet-index" var tweet = response.Source; <2> ---- <1> The `GetResponse` is mapped 1-to-1 with the Elasticsearch JSON response. -<2> The original document is deserialized as an instance of the Tweet class, accessible on the response -via the `Source` property. +<2> The original document is deserialized as an instance of the Tweet class, +accessible on the response via the `Source` property. [discrete] @@ -104,13 +111,18 @@ if (response.IsValid) var tweet = response.Documents.FirstOrDefault(); <4> } ---- -<1> The generic type argument specifies the tweet class, which is used when deserialising the hits from the response. -<2> The index can be omitted if a `DefaultIndex` has been configured on `ElasticsearchClientSettings``, or a specific -index was configured when mapping this type. -<3> Execute a term query against the `user` field, searching for tweets authored by the user 'stevejgordon'. -<4> Documents matched by the query are accessible via the `Documents` collection property on the `SearchResponse`. - -You may prefer using the object initializer syntax for requests if lambdas aren't your thing. +<1> The generic type argument specifies the tweet class, which is used when +deserialising the hits from the response. +<2> The index can be omitted if a `DefaultIndex` has been configured on +`ElasticsearchClientSettings``, or a specific index was configured when mapping +this type. +<3> Execute a term query against the `user` field, searching for tweets authored +by the user 'stevejgordon'. +<4> Documents matched by the query are accessible via the `Documents` collection +property on the `SearchResponse`. + +You may prefer using the object initializer syntax for requests if lambdas +aren't your thing. [source,csharp] ---- @@ -128,15 +140,16 @@ if (response.IsValid) var tweet = response.Documents.FirstOrDefault(); } ---- -<1> Create an instance of `SearchRequest`, setting properties to control the search operation. +<1> Create an instance of `SearchRequest`, setting properties to control the +search operation. <2> Pass the request to the `SearchAsync` method on the client. [discrete] [[updating-net]] === Updating documents -Documents can be updated in several ways, including by providing a complete replacement for an -existing document ID. +Documents can be updated in several ways, including by providing a complete +replacement for an existing document ID. [source,csharp] ---- From 71dd7a03b7db658d9b3eed2da7187a91718eaf24 Mon Sep 17 00:00:00 2001 From: Steve Gordon Date: Thu, 29 Sep 2022 16:09:49 +0100 Subject: [PATCH 8/8] Refer to tweet type correctly in all locations --- docs/examples.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/examples.asciidoc b/docs/examples.asciidoc index c86a593f423..b483919c588 100644 --- a/docs/examples.asciidoc +++ b/docs/examples.asciidoc @@ -69,7 +69,7 @@ if (response.IsValid) <3> } ---- -<1> Create an instance of the Tweet class with relevant properties set. +<1> Create an instance of the `Tweet` class with relevant properties set. <2> Prefer the async APIs, which require awaiting the response. <3> Check the `IsValid` property on the response to confirm that the request and operation succeeded. @@ -111,7 +111,7 @@ if (response.IsValid) var tweet = response.Documents.FirstOrDefault(); <4> } ---- -<1> The generic type argument specifies the tweet class, which is used when +<1> The generic type argument specifies the `Tweet` class, which is used when deserialising the hits from the response. <2> The index can be omitted if a `DefaultIndex` has been configured on `ElasticsearchClientSettings``, or a specific index was configured when mapping