Skip to content

Commit fd8aa92

Browse files
marciwezimuel
marciw
and
ezimuel
authored
[DOCS] Add ES|QL doc structure (#1403)
* Tweak TOC * TOC title experiment * Add folder structure for helpers * Adapted the ESQL doc template for PHP * Minor edits * Revert "Minor edits" This reverts commit adfac62. * Minor edits this time without extra files :-/ --------- Co-authored-by: Enrico Zimuel <[email protected]>
1 parent 221723e commit fd8aa92

File tree

4 files changed

+240
-15
lines changed

4 files changed

+240
-15
lines changed

‎docs/helpers/esql.asciidoc

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
[[esql]]
2+
=== ES|QL in the PHP client
3+
++++
4+
<titleabbrev>ES|QL</titleabbrev>
5+
++++
6+
7+
This page helps you understand and use {ref}/esql.html[ES|QL] in the
8+
PHP client.
9+
10+
There are two ways to use ES|QL in the PHP 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 `mapTo($class)` helper. This mapper takes care of parsing the raw
17+
response and converting into an array of objects. If you don't specify the class
18+
using the `$class` parameter, the mapper uses https://www.php.net/manual/en/class.stdclass.php[stdClass].
19+
20+
[discrete]
21+
[[esql-how-to]]
22+
==== How to use the ES|QL API
23+
24+
The {es-docs}/esql-query-api.html[ES|QL query API] allows you to specify how
25+
results should be returned. You can choose a
26+
{es-docs}/esql-rest.html#esql-rest-format[response format] such as CSV, text, or
27+
JSON, then fine-tune it with parameters like column separators
28+
and locale.
29+
30+
The default response from Elasticsearch is a table in JSON, where `columns`
31+
is an array of descriptions and `values` is an array of rows containing the values.
32+
33+
[[query-script]]
34+
Here's an example query and PHP script:
35+
36+
```php
37+
$query = <<<EOD
38+
FROM books
39+
| WHERE author == "Stephen King"
40+
| SORT rating DESC
41+
| LIMIT 10
42+
EOD;
43+
44+
$result = $client->esql()->query([
45+
'body' => ['query' => $query]
46+
]);
47+
48+
foreach ($result['values'] as $value) {
49+
$i=0;
50+
foreach ($result['columns'] as $col) {
51+
printf("%s : %s\n", $col['name'], $value[$i++]);
52+
}
53+
print("---\n");
54+
}
55+
```
56+
57+
Here's the JSON response from Elasticsearch:
58+
59+
```json
60+
{
61+
"columns": [
62+
{ "name": "author", "type": "text" },
63+
{ "name": "description", "type": "text" },
64+
{ "name": "publisher", "type": "keyword" },
65+
{ "name": "rating", "type": "double" },
66+
{ "name": "title", "type": "text" },
67+
{ "name": "year", "type": "integer" }
68+
],
69+
"values": [
70+
[
71+
"Stephen King",
72+
"The author ...",
73+
"Turtleback",
74+
5.0,
75+
"How writers write",
76+
2002
77+
],
78+
[
79+
"Stephen King",
80+
"In Blockade Billy, a retired coach...",
81+
"Simon and Schuster",
82+
5.0,
83+
"Blockade",
84+
2010
85+
],
86+
[
87+
"Stephen King",
88+
"A chilling collection of twenty horror stories.",
89+
"Signet Book",
90+
4.55859375,
91+
"Night Shift (Signet)",
92+
1979
93+
],
94+
...
95+
]
96+
}
97+
```
98+
99+
Using this response, the PHP script (provided <<query-script,above>>) produces the following output:
100+
101+
```php
102+
author : Stephen King
103+
description : The author ...
104+
publisher : Turtleback
105+
rating : 5.0
106+
title : How writers write
107+
year : 2002
108+
---
109+
author : Stephen King
110+
description : In Blockade Billy, a retired coach...
111+
publisher : Simon and Schuster
112+
rating : 5.0
113+
title : Blockade
114+
year : 2010
115+
---
116+
author : Stephen King
117+
description : A chilling collection of twenty horror stories.
118+
publisher : Signet Book
119+
rating : 4.55859375
120+
title : Night Shift (Signet)
121+
year : 1979
122+
---
123+
```
124+
125+
The following example gets ES|QL results as CSV and parses them:
126+
127+
```php
128+
$result = $client->esql()->query([
129+
'format' => 'csv',
130+
'body' => ['query' => $query]
131+
]);
132+
133+
var_dump($result->asArray());
134+
```
135+
136+
The response looks something like this:
137+
138+
```json
139+
array(12) {
140+
[0]=>
141+
array(6) {
142+
[0]=>
143+
string(6) "author"
144+
[1]=>
145+
string(11) "description"
146+
[2]=>
147+
string(9) "publisher"
148+
[3]=>
149+
string(6) "rating"
150+
[4]=>
151+
string(5) "title"
152+
[5]=>
153+
string(4) "year"
154+
}
155+
[1]=>
156+
array(6) {
157+
[0]=>
158+
string(12) "Stephen King"
159+
[1]=>
160+
string(249) "The author ..."
161+
[2]=>
162+
string(18) "Turtleback"
163+
[3]=>
164+
string(3) "5.0"
165+
[4]=>
166+
string(8) "How writers write"
167+
[5]=>
168+
string(4) "2002"
169+
}
170+
```
171+
In the response, the first row contains the column descriptions and the other rows contain
172+
the values, using a plain PHP array.
173+
174+
175+
[discrete]
176+
[[esql-custom-mapping]]
177+
==== Define your own mapping
178+
179+
Although the `esql()->query()` API covers many use cases, your application
180+
might require a custom mapping.
181+
182+
You can map the ES|QL result into an array of objects, using the `mapTo()`
183+
function. Here's an example:
184+
185+
```php
186+
$result = $client->esql()->query([
187+
'body' => ['query' => $query]
188+
]);
189+
190+
$books = $result->mapTo(); // Array of stdClass
191+
foreach ($books as $book) {
192+
printf(
193+
"%s, %s, %d, Rating: %.2f\n",
194+
$book->author,
195+
$book->title,
196+
$book->year,
197+
$book->rating
198+
);
199+
}
200+
```
201+
202+
You can also specify a class name for the mapping.
203+
All the values will be assigned to the properties of the class.
204+
205+
Here's an example mapper that returns an array of `Book` objects:
206+
207+
```php
208+
class Book
209+
{
210+
public string $author;
211+
public string $title;
212+
public string $description;
213+
public int $year;
214+
public float $rating;
215+
}
216+
217+
$result = $client->esql()->query([
218+
'body' => ['query' => $query]
219+
]);
220+
$books = $result->mapTo(Book::class); // Array of Book
221+
```

‎docs/helpers/index.asciidoc

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[[client-helpers]]
2+
== Client helpers
3+
4+
The PHP client comes with the following helpers:
5+
6+
* <<iterators>>
7+
* <<esql>>
8+
9+
include::iterators.asciidoc[]
10+
include::esql.asciidoc[]

‎docs/helpers.asciidoc renamed to ‎docs/helpers/iterators.asciidoc

Lines changed: 6 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,16 @@
1-
[[client-helpers]]
2-
== Client helpers
3-
4-
The client comes with helpers to give you a more comfortable experience with
5-
some APIs.
6-
7-
8-
[discrete]
91
[[iterators]]
102
=== Iterators
113

4+
The PHP client includes helpers for iterating through results by page or by hits.
125

13-
[discrete]
146
[[search-response-iterator]]
157
==== Search response iterator
168

17-
The `SearchResponseIterator` can be used to iterate page by page in a search
9+
Use the `SearchResponseIterator` to iterate page by page in a search
1810
result using
1911
https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#paginate-search-results[pagination].
2012

21-
An example as follows:
13+
Here's an example:
2214

2315
[source,php]
2416
----
@@ -50,11 +42,11 @@ foreach($pages as $page) {
5042
[[search-hit-iterator]]
5143
==== Search hit iterator
5244

53-
The `SearchHitIterator` can be used to iterate in a `SearchResponseIterator`
45+
Use the `SearchHitIterator` to iterate in a `SearchResponseIterator`
5446
without worrying about
5547
https://www.elastic.co/guide/en/elasticsearch/reference/current/paginate-search-results.html#paginate-search-results[pagination].
5648

57-
An example as follows:
49+
Here's an example:
5850

5951
[source,php]
6052
----
@@ -81,4 +73,4 @@ foreach($hits as $hit) {
8173
// e.g. prints the document id
8274
echo $hit['_id'], PHP_EOL;
8375
}
84-
----
76+
----

‎docs/index.asciidoc

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[]
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[]
@@ -20,7 +22,7 @@ include::configuration.asciidoc[]
2022

2123
include::operations.asciidoc[]
2224

23-
include::helpers.asciidoc[]
25+
include::helpers/index.asciidoc[]
2426

2527
include::release-notes.asciidoc[]
2628

0 commit comments

Comments
 (0)