De objetos ES|QL para PHP

A partir da versão 8.13.0 do elasticsearch-php, você pode executar consultas ES|QL e mapear o resultado para um objeto PHP da classe padrão (stdClass) ou de uma classe personalizada.

ES|QL

ES|QL é uma nova linguagem de consulta do Elasticsearch introduzida na versão 8.11.0. Neste momento, está disponível em versão de pré-visualização técnica. Ele oferece uma maneira poderosa de filtrar, transformar e analisar dados armazenados no Elasticsearch.

Ele utiliza "pipes" (|) para manipular e transformar dados passo a passo. Essa abordagem permite aos usuários compor uma série de operações, onde o resultado de uma operação se torna a entrada para a próxima, possibilitando transformações e análises de dados complexas.

Por exemplo, a seguinte consulta retorna os 3 primeiros documentos (linhas) do índice sample_data :

FROM sample_data
| LIMIT 3

Caso de uso: recursos ES|QL no cliente PHP oficial

Para ilustrar os recursos do ES|QL desenvolvidos no cliente PHP oficial, armazenamos no Elasticsearch um arquivo CSV com 81.828 livros (54,4 MB) contendo as seguintes informações:

Title;Descrition;Author;Year;Publisher;Ratings

Extraímos esta lista do conjunto de dados público de avaliações de livros da Amazon.

Criamos um índice books com os seguintes mapeamentos do Elasticsearch:

'mappings' : {
    'properties': {
        'title': {
            'type': 'text'
        },
        'description': {
            'type': 'text'
        },
        'author': {
            'type': 'text'
        },
        'year': {
            'type': 'short'
        },
        'publisher': {
            'type': 'keyword'
        },
        'rating': {
            'type': 'half_float'
        }
    }
}

O valor rating é a média das classificações das avaliações extraídas do arquivo Books_rating.csv de 2,9 GB.

Aqui você encontra o script PHP que usamos para importar todos os livros em massa para o Elasticsearch. A operação em lote levou 7 segundos e consumiu 28 MB de RAM usando o PHP 8.2.17. Com o mapeamento proposto, o tamanho do índice no Elasticsearch é de aproximadamente 62 MB.

Mapear resultados ES|QL para um objeto PHP ou classe personalizada

Podemos executar uma consulta ES|QL em PHP usando o endpoint esql()->query() . O resultado desta consulta é uma estrutura de dados em forma de tabela. Isso é expresso em JSON usando os campos columns e values . No campo columns temos a definição name e type .

Aqui está um exemplo de consulta ES|QL para recuperar os 10 melhores livros escritos por Stephen King, ordenados pela classificação das avaliações dos usuários:

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

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

O resultado JSON do Elasticsearch tem a seguinte aparência:

{
    "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
        ],
        ...
    ]
}

Neste exemplo, temos 6 propriedades (autor, descrição, editora, classificação, título, ano) relacionadas a um livro e 10 resultados, todos livros de Stephen King.

Uma lista de todos os tipos suportados em ES|QL é apresentada aqui.

O objeto de resposta $result pode ser acessado como uma matriz, uma string ou como um objeto (veja aqui para mais informações).

Utilizando a interface de objeto, podemos acessar os valores por meio de propriedades e índices. Por exemplo, $result->values[0][4] retorna o título (4) do primeiro livro (0) da lista, $result->values[1][3] retorna a pontuação de classificação (3) do segundo livro (1), etc. Lembre-se, o índice de um array em PHP começa em zero.

Essa interface pode ser suficiente para alguns casos de uso, mas na maioria das vezes preferimos obter um array de objetos como resultado.

Para mapear o resultado em uma matriz de objetos, podemos usar o novo recurso mapTo() do elasticsearch-php.

Essa função está disponível diretamente no objeto de resposta do Elasticsearch. Isso significa que você pode acessá-lo da seguinte forma:

$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
    );
}

Se você tiver uma classe Book personalizada, poderá mapear o resultado usando-a, da seguinte forma:

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

$books = $result->mapTo(Book::class); // Array of Book

Se sua classe tiver outras propriedades além das incluídas no resultado ES|QL, isso também funcionará. A função mapTo() usará apenas as propriedades retornadas como colunas do resultado ES|QL.

Você pode baixar todos os exemplos relatados neste artigo aqui.