Skip to content

Commit

Permalink
Adapted the ESQL doc template for PHP
Browse files Browse the repository at this point in the history
  • Loading branch information
@ezimuel
ezimuel committed May 29, 2024
1 parent b0abb7b commit afd6f98
Showing 1 changed file with 186 additions and 44 deletions.
230 changes: 186 additions & 44 deletions docs/helpers/esql.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,10 @@ There are two ways to use ES|QL in the PHP client:
is the most flexible approach, but it's also the most complex because you must handle
results in their raw form. You can choose the precise format of results,
such as JSON, CSV, or text.
* Use ES|QL mapping helpers: These mappers take care of parsing the raw
response into something readily usable by the application. Several mappers are
available for different use cases, such as object mapping, cursor
traversal of results, and dataframes. You can also define your own mapper for specific
use cases.


* Use ES|QL `mapTo($class)` helper. This mapper take care of parsing the raw
response and converting into an array of objects. If you don't specify the class
using the `$class` parameter the mapping will use the https://www.php.net/manual/en/class.stdclass.php[stdClass]
of PHP.

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

// Add any PHP-specific usage notes
The default response from Elasticsearch is a table in JSON specified using `columns`
as array of descriptions and `values` as array of rows with the values.

An example is as follows:

```php
$query = <<<EOD
FROM books
| WHERE author == "Stephen King"
| SORT rating DESC
| LIMIT 10
EOD;

$result = $client->esql()->query([
'body' => ['query' => $query]
]);

foreach ($result['values'] as $value) {
$i=0;
foreach ($result['columns'] as $col) {
printf("%s : %s\n", $col['name'], $value[$i++]);
}
print("---\n");
}
```

Given the following JSON response from Elasticsearch:

```json
{
"columns": [
{ "name": "author", "type": "text" },
{ "name": "description", "type": "text" },
{ "name": "publisher", "type": "keyword" },
{ "name": "rating", "type": "double" },
{ "name": "title", "type": "text" },
{ "name": "year", "type": "integer" }
],
"values": [
[
"Stephen King",
"The author ...",
"Turtleback",
5.0,
"How writers write",
2002
],
[
"Stephen King",
"In Blockade Billy, a retired coach...",
"Simon and Schuster",
5.0,
"Blockade",
2010
],
[
"Stephen King",
"A chilling collection of twenty horror stories.",
"Signet Book",
4.55859375,
"Night Shift (Signet)",
1979
],
...
]
}
```

The output of the revious PHP script is as follows:

```php
author : Stephen King
description : The author ...
publisher : Turtleback
rating : 5.0
title : How writers write
year : 2002
---
author : Stephen King
description : In Blockade Billy, a retired coach...
publisher : Simon and Schuster
rating : 5.0
title : Blockade
year : 2010
---
author : Stephen King
description : A chilling collection of twenty horror stories.
publisher : Signet Book
rating : 4.55859375
title : Night Shift (Signet)
year : 1979
---
```

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

// Code example to be written


[discrete]
[[esql-consume-results]]
==== Consume ES|QL results

The previous example showed that although the raw ES|QL API offers maximum
flexibility, additional work is required in order to make use of the
result data.

To simplify things, try working with these three main representations of ES|QL
results (each with its own mapping helper):

* **Objects**, where each row in the results is mapped to an object from your
application domain. This is similar to what ORMs (object relational mappers)
commonly do.
* **Cursors**, where you scan the results row by row and access the data using
column names. This is similar to database access libraries.
* **Dataframes**, where results are organized in a column-oriented structure that
allows efficient processing of column data.

// Code examples to be written for each of them, depending on availability in the language
```php
$result = $client->esql()->query([
'format' => 'csv',
'body' => ['query' => $query]
]);

var_dump($result->asArray());
```

The response will look something as follows:

```
array(12) {
[0]=>
array(6) {
[0]=>
string(6) "author"
[1]=>
string(11) "description"
[2]=>
string(9) "publisher"
[3]=>
string(6) "rating"
[4]=>
string(5) "title"
[5]=>
string(4) "year"
}
[1]=>
array(6) {
[0]=>
string(12) "Stephen King"
[1]=>
string(249) "The author ..."
[2]=>
string(18) "Turtleback"
[3]=>
string(3) "5.0"
[4]=>
string(8) "How writers write"
[5]=>
string(4) "2002"
}
```
where the first row is the column descriptions and the other rows contain
the values, using a plain PHP array.


[discrete]
[[esql-custom-mapping]]
==== Define your own mapping

Although the mappers provided by the PHP client cover many use cases, your
application might require a custom mapping.
You can write your own mapper and use it in a similar way as the
built-in ones.

Note that mappers are meant to provide a more usable representation of ES|QL
results—not to process the result data. Data processing should be based on
the output of a result mapper.

Here's an example mapper that returns a simple column-oriented
representation of the data:

// Code example to be written
Although the `esql()->query()` API covers many use cases, your application
might require a custom mapping.

You can map the ES|QL result into an array of object, using the `mapTo()`
function, as follows:

```php
$result = $client->esql()->query([
'body' => ['query' => $query]
]);

$books = $result->mapTo(); // Array of stdClass
foreach ($books as $book) {
printf(
"%s, %s, %d, Rating: %.2f\n",
$book->author,
$book->title,
$book->year,
$book->rating
);
}
```

You can also specify the class name to be used for the mapping.
All the values will be assigned to the properties of the class.

Here's an example mapper that returns an array of `Book` objects.

```php
class Book
{
public string $author;
public string $title;
public string $description;
public int $year;
public float $rating;
}

$result = $client->esql()->query([
'body' => ['query' => $query]
]);
$books = $result->mapTo(Book::class); // Array of Book
```

0 comments on commit afd6f98

Please sign in to comment.