Skip to content

Commit 4d8fe93

Browse files
marciwAnaethelion
marciw
and
Anaethelion
authored
[DOCS] Add ES|QL doc structure (#860)
* Add ES|QL docs structure * Fix variable; adjust TOC entry * add examples to ES|QL documentation * Small edit --------- Co-authored-by: Laurent Saint-Félix <[email protected]>
1 parent de21bec commit 4d8fe93

File tree

3 files changed

+142
-0
lines changed

3 files changed

+142
-0
lines changed

‎.doc/index.asciidoc

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

77
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
88

9+
:es-docs: https://www.elastic.co/guide/en/elasticsearch/reference/{branch}
10+
911
include::overview.asciidoc[]
1012

1113
include::getting-started.asciidoc[]

‎.doc/typedapi/esql.asciidoc

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
[[esql]]
2+
=== ES|QL in the Go client
3+
++++
4+
<titleabbrev>Using ES|QL</titleabbrev>
5+
++++
6+
7+
This page helps you understand and use {ref}/esql.html[ES|QL] in the
8+
Go client.
9+
10+
There are two ways to use ES|QL in the Go client:
11+
12+
* Use the Elasticsearch {es-docs}/esql-apis.html[ES|QL API] directly: This
13+
is the most flexible approach, but it's also the most complex because you must handle
14+
results in their raw form. You can choose the precise format of results,
15+
such as JSON, CSV, or text.
16+
* Use ES|QL mapping helpers: These mappers take care of parsing the raw
17+
response into something readily usable by the application. Helpers are
18+
available for object mapping and iterative objects.
19+
20+
21+
22+
[discrete]
23+
[[esql-how-to]]
24+
==== How to use the ES|QL API
25+
26+
The {es-docs}/esql-query-api.html[ES|QL query API] allows you to specify how
27+
results should be returned. You can choose a
28+
{es-docs}/esql-rest.html#esql-rest-format[response format] such as CSV, text, or
29+
JSON, then fine-tune it with parameters like column separators
30+
and locale.
31+
32+
The following example gets ES|QL results as CSV and parses them:
33+
34+
[source,go]
35+
------------------------------------
36+
queryAuthor := `from library
37+
| where author == "Isaac Asimov"
38+
| sort release_date desc
39+
| limit 10`
40+
41+
response, err := client.Esql.Query().
42+
Query(queryAuthor).
43+
Format("csv").
44+
Do(context.Background())
45+
if err != nil {
46+
log.Fatal(err)
47+
}
48+
49+
reader := csv.NewReader(bytes.NewReader(response))
50+
rows, err := reader.ReadAll()
51+
for _, row := range rows {
52+
fmt.Println(row)
53+
}
54+
------------------------------------
55+
56+
57+
[discrete]
58+
[[esql-consume-results]]
59+
==== Consume ES|QL results
60+
61+
The previous example showed that although the raw ES|QL API offers maximum
62+
flexibility, additional work is required in order to make use of the
63+
result data.
64+
65+
To simplify things, try working with these two main representations of ES|QL
66+
results (each with its own mapping helper):
67+
68+
* **Objects**, where each row in the results is mapped to an object from your
69+
application domain. This is similar to what ORMs (object relational mappers)
70+
commonly do.
71+
72+
[source,go]
73+
------------------------------------
74+
package main
75+
76+
import (
77+
"context"
78+
"fmt"
79+
"log"
80+
81+
"github.com/elastic/go-elasticsearch/v8"
82+
"github.com/elastic/go-elasticsearch/v8/typedapi/esql/query"
83+
)
84+
85+
type Book struct {
86+
Name string `json:"name"`
87+
Author string `json:"author"`
88+
ReleaseDate string `json:"release_date"`
89+
PageCount int `json:"page_count"`
90+
}
91+
92+
func main() {
93+
client, err := elasticsearch.NewTypedClient(elasticsearch.Config{Addresses: []string{"ELASTICSEARCH_URL"}})
94+
if err != nil {
95+
log.Fatal(err)
96+
}
97+
98+
queryAuthor := `from library
99+
| where author == "Isaac Asimov"
100+
| sort release_date desc
101+
| limit 10`
102+
103+
qry := client.Esql.Query().Query(queryAuthor)
104+
books, err := query.Helper[Book](context.Background(), qry)
105+
if err != nil {
106+
log.Fatal(err)
107+
}
108+
109+
for _, book := range books {
110+
fmt.Println(book)
111+
}
112+
}
113+
114+
------------------------------------
115+
116+
* **Iterative Objects**, where each row in the results is mapped to an object from your
117+
application domain, one at a time.
118+
119+
[source,go]
120+
------------------------------------
121+
queryAuthor := `from library
122+
| where author == "Isaac Asimov"
123+
| sort release_date desc
124+
| limit 10`
125+
126+
qry := client.Esql.Query().Query(queryAuthor)
127+
books, err := query.NewIteratorHelper[Book](context.Background(), qry)
128+
if err != nil {
129+
log.Fatal(err)
130+
}
131+
132+
for books.More() {
133+
book, err := books.Next()
134+
if err != nil {
135+
log.Fatal(err)
136+
}
137+
fmt.Println(book)
138+
}
139+
------------------------------------

‎.doc/typedapi/index.asciidoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,4 +34,5 @@ https://github.com/elastic/elasticsearch-specification[elasticsearch-specificati
3434

3535
include::conventions/index.asciidoc[]
3636
include::queries.asciidoc[]
37+
include::esql.asciidoc[]
3738
include::examples/index.asciidoc[]

0 commit comments

Comments
 (0)