Skip to content

Commit afd6f98

Browse files
ezimuelezimuel
committed
Adapted the ESQL doc template for PHP
1 parent b0abb7b commit afd6f98

File tree

1 file changed

+186
-44
lines changed

1 file changed

+186
-44
lines changed

‎docs/helpers/esql.asciidoc

Lines changed: 186 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,10 @@ There are two ways to use ES|QL in the PHP client:
1313
is the most flexible approach, but it's also the most complex because you must handle
1414
results in their raw form. You can choose the precise format of results,
1515
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. Several mappers are
18-
available for different use cases, such as object mapping, cursor
19-
traversal of results, and dataframes. You can also define your own mapper for specific
20-
use cases.
21-
22-
16+
* Use ES|QL `mapTo($class)` helper. This mapper take 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 mapping will use the https://www.php.net/manual/en/class.stdclass.php[stdClass]
19+
of PHP.
2320

2421
[discrete]
2522
[[esql-how-to]]
@@ -31,49 +28,194 @@ results should be returned. You can choose a
3128
JSON, then fine-tune it with parameters like column separators
3229
and locale.
3330

34-
// Add any PHP-specific usage notes
31+
The default response from Elasticsearch is a table in JSON specified using `columns`
32+
as array of descriptions and `values` as array of rows with the values.
33+
34+
An example is as follows:
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+
Given the following 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+
The output of the revious PHP script is as follows:
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+
```
35124

36125
The following example gets ES|QL results as CSV and parses them:
37126

38-
// Code example to be written
39-
40-
41-
[discrete]
42-
[[esql-consume-results]]
43-
==== Consume ES|QL results
44-
45-
The previous example showed that although the raw ES|QL API offers maximum
46-
flexibility, additional work is required in order to make use of the
47-
result data.
48-
49-
To simplify things, try working with these three main representations of ES|QL
50-
results (each with its own mapping helper):
51-
52-
* **Objects**, where each row in the results is mapped to an object from your
53-
application domain. This is similar to what ORMs (object relational mappers)
54-
commonly do.
55-
* **Cursors**, where you scan the results row by row and access the data using
56-
column names. This is similar to database access libraries.
57-
* **Dataframes**, where results are organized in a column-oriented structure that
58-
allows efficient processing of column data.
59-
60-
// Code examples to be written for each of them, depending on availability in the language
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 will look something as follows:
137+
138+
```
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+
where the first row is the column descriptions and the other rows contain
172+
the values, using a plain PHP array.
61173

62174

63175
[discrete]
64176
[[esql-custom-mapping]]
65177
==== Define your own mapping
66178

67-
Although the mappers provided by the PHP client cover many use cases, your
68-
application might require a custom mapping.
69-
You can write your own mapper and use it in a similar way as the
70-
built-in ones.
71-
72-
Note that mappers are meant to provide a more usable representation of ES|QL
73-
results—not to process the result data. Data processing should be based on
74-
the output of a result mapper.
75-
76-
Here's an example mapper that returns a simple column-oriented
77-
representation of the data:
78-
79-
// Code example to be written
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 object, using the `mapTo()`
183+
function, as follows:
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 the class name to be used 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+
```

0 commit comments

Comments
 (0)