Skip to content

Commit f5e1661

Browse files
stevejgordonszabosteve
stevejgordon
and
szabosteve
authored
[DOCS] Adds Examples section to .NET docs (#6418) (#6691)
* [DOCS] Adds Examples section to .NET docs. * [DOCS] Fixe index file. * [DOCS] Fixes index file. * [DOCS] Further changes. * Expand documentation and add missing examples * Use consistant wording when referring to 'a' document. * [DOCS] Changes line breaks. * Refer to tweet type correctly in all locations Co-authored-by: Steve Gordon <sgordon@hotmail.co.uk> (cherry picked from commit a945680) Co-authored-by: István Zoltán Szabó <szabosteve@gmail.com>
1 parent 1a955fa commit f5e1661

File tree

2 files changed

+186
-0
lines changed

2 files changed

+186
-0
lines changed

‎docs/examples.asciidoc

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
[[examples]]
2+
== Examples
3+
4+
This page helps you to understand how to perform various basic {es} CRUD
5+
operations using the .NET client. It demonstrates how to create a document by
6+
indexing an object into {es}, read a document back, retrieving it by ID or
7+
performing a search, update one of the fields in a document and delete a
8+
specific document.
9+
10+
These examples assume you have an instance of the `ElasticsearchClient`
11+
accessible via a local variable named `client` and several using directives in
12+
your C# file.
13+
14+
[source,csharp]
15+
----
16+
using System;
17+
using Elastic.Clients.Elasticsearch;
18+
using Elastic.Clients.Elasticsearch.QueryDsl;
19+
20+
var client = new ElasticsearchClient(); <1>
21+
----
22+
<1> The default constructor, assumes an unsecured {es} server is running and
23+
exposed on 'http://localhost:9200'. See <<connecting, connecting>> for examples
24+
of connecting to secured servers and https://www.elastic.co/cloud[Elastic Cloud]
25+
deployments.
26+
27+
The examples operate on data representing tweets. Tweets are modelled in the
28+
client application using a C# class named 'Tweet' containing several properties
29+
that map to the document structure being stored in {es}.
30+
31+
[source,csharp]
32+
----
33+
public class Tweet
34+
{
35+
public int Id { get; set; } <1>
36+
public string User { get; set; }
37+
public DateTime PostDate { get; set; }
38+
public string Message { get; set; }
39+
}
40+
----
41+
<1> By default, the .NET client will try to find a property called `Id` on the
42+
class. When such a property is present it will index the document into {es}
43+
using the ID specified by the value of this property.
44+
45+
46+
[discrete]
47+
[[indexing-net]]
48+
=== Indexing a document
49+
50+
Documents can be indexed by creating an instance representing a tweet and
51+
indexing it via the client. In these examples, we will work with an index named
52+
'my-tweet-index'.
53+
54+
[source,csharp]
55+
----
56+
var tweet = new Tweet <1>
57+
{
58+
Id = 1,
59+
User = "stevejgordon",
60+
PostDate = new DateTime(2009, 11, 15),
61+
Message = "Trying out the client, so far so good?"
62+
};
63+
64+
var response = await client.IndexAsync(tweet, request => request.Index("my-tweet-index")); <2>
65+
66+
if (response.IsValid) <3>
67+
{
68+
Console.WriteLine($"Index document with ID {response.Id} succeeded."); <4>
69+
}
70+
71+
----
72+
<1> Create an instance of the `Tweet` class with relevant properties set.
73+
<2> Prefer the async APIs, which require awaiting the response.
74+
<3> Check the `IsValid` property on the response to confirm that the request and
75+
operation succeeded.
76+
<4> Access the `IndexResponse` properties, such as the ID, if necessary.
77+
78+
[discrete]
79+
[[getting-net]]
80+
=== Getting a document
81+
82+
[source,csharp]
83+
----
84+
var response = await client.GetAsync<Tweet>(1, idx => idx.Index("my-tweet-index")); <1>
85+
var tweet = response.Source; <2>
86+
----
87+
<1> The `GetResponse` is mapped 1-to-1 with the Elasticsearch JSON response.
88+
<2> The original document is deserialized as an instance of the Tweet class,
89+
accessible on the response via the `Source` property.
90+
91+
92+
[discrete]
93+
[[searching-net]]
94+
=== Searching for documents
95+
96+
The client exposes a fluent interface and a powerful query DSL for searching.
97+
98+
[source,csharp]
99+
----
100+
var response = await client.SearchAsync<Tweet>(s => s <1>
101+
.Index("my-tweet-index") <2>
102+
.From(0)
103+
.Size(10)
104+
.Query(q => q
105+
.Term(t => t.User, "stevejgordon") <3>
106+
)
107+
);
108+
109+
if (response.IsValid)
110+
{
111+
var tweet = response.Documents.FirstOrDefault(); <4>
112+
}
113+
----
114+
<1> The generic type argument specifies the `Tweet` class, which is used when
115+
deserialising the hits from the response.
116+
<2> The index can be omitted if a `DefaultIndex` has been configured on
117+
`ElasticsearchClientSettings``, or a specific index was configured when mapping
118+
this type.
119+
<3> Execute a term query against the `user` field, searching for tweets authored
120+
by the user 'stevejgordon'.
121+
<4> Documents matched by the query are accessible via the `Documents` collection
122+
property on the `SearchResponse`.
123+
124+
You may prefer using the object initializer syntax for requests if lambdas
125+
aren't your thing.
126+
127+
[source,csharp]
128+
----
129+
var request = new SearchRequest("my-tweet-index") <1>
130+
{
131+
From = 0,
132+
Size = 10,
133+
Query = new TermQuery("user") { Value = "stevejgordon" }
134+
};
135+
136+
var response = await client.SearchAsync<Tweet>(request); <2>
137+
138+
if (response.IsValid)
139+
{
140+
var tweet = response.Documents.FirstOrDefault();
141+
}
142+
----
143+
<1> Create an instance of `SearchRequest`, setting properties to control the
144+
search operation.
145+
<2> Pass the request to the `SearchAsync` method on the client.
146+
147+
[discrete]
148+
[[updating-net]]
149+
=== Updating documents
150+
151+
Documents can be updated in several ways, including by providing a complete
152+
replacement for an existing document ID.
153+
154+
[source,csharp]
155+
----
156+
tweet.Message = "This is a new message"; <1>
157+
158+
var response = await client.UpdateAsync<Tweet, object>("my-tweet-index", 1, u => u
159+
.Doc(tweet)); <2>
160+
161+
if (response.IsValid)
162+
{
163+
Console.WriteLine("Update document succeeded.");
164+
}
165+
----
166+
<1> Update a property on the existing tweet instance.
167+
<2> Send the updated tweet object in the update request.
168+
169+
170+
[discrete]
171+
[[deleting-net]]
172+
=== Deleting documents
173+
174+
Documents can be deleted by providing the ID of the document to remove.
175+
176+
[source,csharp]
177+
----
178+
var response = await client.DeleteAsync("my-tweet-index", 1);
179+
180+
if (response.IsValid)
181+
{
182+
Console.WriteLine("Delete document succeeded.");
183+
}
184+
----

‎docs/index.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ include::connecting.asciidoc[]
1717

1818
include::configuration.asciidoc[]
1919

20+
include::examples.asciidoc[]
21+
2022
include::breaking-changes.asciidoc[]
2123

2224
include::troubleshooting.asciidoc[]

0 commit comments

Comments
 (0)