diff --git a/docs/examples.asciidoc b/docs/examples.asciidoc new file mode 100644 index 00000000000..b483919c588 --- /dev/null +++ b/docs/examples.asciidoc @@ -0,0 +1,184 @@ +[[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. + +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 + +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 <1> +{ + Id = 1, + User = "stevejgordon", + PostDate = new DateTime(2009, 11, 15), + Message = "Trying out the client, so far so good?" +}; + +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]] +=== Getting a document + +[source,csharp] +---- +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 for searching. + +[source,csharp] +---- +var response = await client.SearchAsync(s => s <1> + .Index("my-tweet-index") <2> + .From(0) + .Size(10) + .Query(q => q + .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`. + +You may prefer using the object initializer syntax for requests if lambdas +aren't your thing. + +[source,csharp] +---- +var request = new SearchRequest("my-tweet-index") <1> +{ + From = 0, + Size = 10, + Query = new TermQuery("user") { Value = "stevejgordon" } +}; + +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 diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 86c5d04062f..9f16b835fb5 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -17,6 +17,8 @@ include::connecting.asciidoc[] include::configuration.asciidoc[] +include::examples.asciidoc[] + include::breaking-changes.asciidoc[] include::troubleshooting.asciidoc[]