Skip to content

Commit 116dfec

Browse files
github-actions[bot]szabosteveAnaethelion
authored
[DOCS] Adds getting started content based on the template (#686) (#687)
* [DOCS] Adds getting started content based on the template. * [DOCS] Fixes image extension. * [DOCS] Adds support for two APIs in the getting started. * add code examples to the mix --------- Co-authored-by: István Zoltán Szabó <szabosteve@gmail.com> Co-authored-by: Laurent Saint-Félix <laurent.saintfelix@elastic.co>
1 parent 743b167 commit 116dfec

File tree

6 files changed

+246
-9
lines changed

6 files changed

+246
-9
lines changed

‎.doc/getting-started.asciidoc

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
[[getting-started-go]]
2+
== Getting started
3+
4+
This page guides you through the installation process of the Go client, shows
5+
you how to instantiate the client, and how to perform basic Elasticsearch
6+
operations with it. You can use the client with either a low-level API or a
7+
fully typed API. This getting started shows you examples of both APIs.
8+
9+
[discrete]
10+
=== Requirements
11+
12+
Go version 1.13+
13+
14+
[discrete]
15+
=== Installation
16+
17+
To install the latest version of the client, run the following command:
18+
19+
[source,shell]
20+
--------------------------
21+
go get github.com/elastic/go-elasticsearch/v8@latest
22+
--------------------------
23+
24+
Refer to the <<installation>> page to learn more.
25+
26+
27+
[discrete]
28+
=== Connecting
29+
30+
You can connect to the Elastic Cloud using an API key and the Elasticsearch
31+
endpoint for the low level API:
32+
33+
[source,go]
34+
----
35+
client, err := elasticsearch.NewClient(elasticsearch.Config{
36+
CloudID: "<CloudID>",
37+
APIKey: "<ApiKey>",
38+
})
39+
----
40+
41+
This is the same for the fully-typed API:
42+
43+
[source,go]
44+
----
45+
typedClient, err := elasticsearch.NewTypedClient(elasticsearch.Config{
46+
CloudID: "<CloudID>",
47+
APIKey: "<ApiKey>",
48+
})
49+
----
50+
51+
52+
Your Elasticsearch endpoint can be found on the **My deployment** page of your
53+
deployment:
54+
55+
image::images/es-endpoint.jpg[alt="Finding Elasticsearch endpoint",align="center"]
56+
57+
You can generate an API key on the **Management** page under Security.
58+
59+
image::images/create-api-key.png[alt="Create API key",align="center"]
60+
61+
For other connection options, refer to the <<connecting>> section.
62+
63+
64+
[discrete]
65+
=== Operations
66+
67+
Time to use Elasticsearch! This section walks you through the basic, and most
68+
important, operations of Elasticsearch. For more operations and more advanced
69+
examples, refer to the <<examples>> page.
70+
71+
72+
[discrete]
73+
==== Creating an index
74+
75+
This is how you create the `my_index` index with the low level API:
76+
77+
[source,go]
78+
----
79+
client.Indices.Create("my_index")
80+
----
81+
82+
This is how you create the `my_index` index with the fully-typed API:
83+
84+
[source,go]
85+
----
86+
typedClient.Indices.Create("my_index").Do(context.TODO())
87+
----
88+
89+
90+
[discrete]
91+
==== Indexing documents
92+
93+
This is a simple way of indexing a document by using the low-level API:
94+
95+
[source,go]
96+
----
97+
document := struct {
98+
Name string `json:"name"`
99+
}{
100+
"go-elasticsearch",
101+
}
102+
data, _ := json.Marshal(document)
103+
client.Index("my_index", bytes.NewReader(data))
104+
----
105+
106+
The same operation by using the fully-typed API:
107+
108+
[source,go]
109+
----
110+
document := struct {
111+
Name string `json:"name"`
112+
}{
113+
"go-elasticsearch",
114+
}
115+
typedClient.Index("my_index").
116+
Id("1").
117+
Request(document).
118+
Do(context.TODO())
119+
----
120+
121+
[discrete]
122+
==== Getting documents
123+
124+
You can get documents by using the following code with the low-level API:
125+
126+
[source,go]
127+
----
128+
client.Get("my_index", "id")
129+
----
130+
131+
This is how you can get documents by using the fully-typed API:
132+
133+
[source,go]
134+
----
135+
typedClient.Get("my_index", "id").Do(context.TODO())
136+
----
137+
138+
139+
[discrete]
140+
==== Searching documents
141+
142+
This is how you can create a single match query with the low-level API:
143+
144+
[source,go]
145+
----
146+
query := `{ query: { match_all: {} } }`
147+
client.Search(
148+
client.Search.WithIndex("my_index"),
149+
client.Search.WithBody(strings.NewReader(query)),
150+
)
151+
----
152+
153+
You can perform a single match query with the fully-typed API, too:
154+
155+
[source,go]
156+
----
157+
typedClient.Search().
158+
Index("my_index").
159+
Request(&search.Request{
160+
Query: &types.Query{MatchAll: &types.MatchAllQuery{}},
161+
}).
162+
Do(context.TODO())
163+
----
164+
165+
166+
[discrete]
167+
==== Updating documents
168+
169+
This is how you can update a document, for example to add a new field, by using
170+
the low-level API:
171+
172+
[source,go]
173+
----
174+
client.Update("my_index", "id", strings.NewReader(`{doc: { language: "Go" }}`))
175+
----
176+
177+
And this is how you can update a document with the fully-typed API:
178+
179+
[source,go]
180+
----
181+
typedClient.Update("my_index", "id").
182+
Request(&update.Request{
183+
Doc: json.RawMessage(`{ language: "Go" }`),
184+
}).Do(context.TODO())
185+
----
186+
187+
188+
[discrete]
189+
==== Deleting documents
190+
191+
Low-level API:
192+
193+
[source,go]
194+
----
195+
client.Delete("my_index", "id")
196+
----
197+
198+
Fully-typed API:
199+
200+
[source,go]
201+
----
202+
typedClient.Delete("my_index", "id").Do(context.TODO())
203+
----
204+
205+
206+
[discrete]
207+
==== Deleting an index
208+
209+
Low-level API:
210+
211+
[source,go]
212+
----
213+
client.Indices.Delete([]string{"my_index"})
214+
----
215+
216+
Fully-typed API:
217+
218+
[source,go]
219+
----
220+
typedClient.Indices.Delete("my_index").Do(context.TODO())
221+
----
222+
223+
224+
[discrete]
225+
== Further reading
226+
227+
* Learn more about the <<typedapi>>, a strongly typed Golang API
228+
for {es}.

‎.doc/images/create-api-key.png

78.7 KB
Loading

‎.doc/images/es-endpoint.jpg

361 KB
Loading

‎.doc/index.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
88

99
include::overview.asciidoc[]
1010

11+
include::getting-started.asciidoc[]
12+
1113
include::installation.asciidoc[]
1214

1315
include::connecting.asciidoc[]

‎.doc/typedapi.asciidoc

Whitespace-only changes.

‎.doc/typedapi/index.asciidoc

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,26 @@
11
[[typedapi]]
22
== Typed API
33

4-
The goal for this API is to provide a strongly typed, fluent-like Golang API for {es}.
4+
The goal for this API is to provide a strongly typed Golang API for
5+
{es}.
56

6-
This was designed with structures and the Golang runtime in mind, following as closely as possible the API and its objects.
7+
This was designed with structures and the Golang runtime in mind, following as
8+
closely as possible the API and its objects.
9+
10+
The first version focuses on the requests and does not yet include NDJSON
11+
endpoints such as `bulk` or `msearch`. These will be added later on along with
12+
typed responses and error handling.
713

8-
The first version focuses on the requests and does not yet include NDJSON endpoints such as `bulk` or `msearch`.
9-
These will be added later on along with typed responses and error handling.
1014

1115
[getting-started]
12-
=== Getting started
16+
=== Getting started with the API
1317

14-
The new typed client can be obtained from the `elasticsearch` package using the `NewTypedClient` function.
15-
This new API takes the same arguments as the previous one and uses the same transport underneath.
18+
The new typed client can be obtained from the `elasticsearch` package using the
19+
`NewTypedClient` function. This new API takes the same arguments as the previous
20+
one and uses the same transport underneath.
1621

17-
Connection to an {es} cluster is identical to the existing client, only the API changes:
22+
Connection to an {es} cluster is identical to the existing client, only the API
23+
changes:
1824

1925
[source,go]
2026
-----
@@ -23,7 +29,8 @@ client, err := elasticsearch.NewTypedClient(elasticsearch.Config{
2329
})
2430
-----
2531

26-
The code is generated from the https://github.com/elastic/elasticsearch-specification[elasticsearch-specification].
32+
The code is generated from the
33+
https://github.com/elastic/elasticsearch-specification[elasticsearch-specification].
2734

2835
include::conventions/index.asciidoc[]
2936
include::queries.asciidoc[]

0 commit comments

Comments
 (0)