diff --git a/docs/helpers/esql.asciidoc b/docs/helpers/esql.asciidoc index 3e20d583d..48d8f22ad 100644 --- a/docs/helpers/esql.asciidoc +++ b/docs/helpers/esql.asciidoc @@ -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]] @@ -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 = <<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 \ No newline at end of file +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 +``` \ No newline at end of file