« 迭代器 发行说明 »
Elastic 文档 ›Elasticsearch-PHP [8.16] ›客户端辅助工具

PHP 客户端中的 ES|QL

编辑

PHP 客户端中的 ES|QL

编辑

此页面帮助您了解如何在 PHP 客户端中使用 ES|QL。

在 PHP 客户端中使用 ES|QL 的方法有两种：

  • 直接使用 Elasticsearch ES|QL API：这是最灵活的方法，但也是最复杂的方法，因为您必须处理原始形式的结果。您可以选择精确的结果格式，例如 JSON、CSV 或文本。
  • 使用 ES|QL mapTo($class) 辅助函数。此映射器负责解析原始响应并将其转换为对象数组。如果您不使用 $class 参数指定类，则映射器使用 stdClass。

如何使用 ES|QL API

编辑

ES|QL 查询 API 允许您指定结果的返回方式。您可以选择 响应格式，例如 CSV、文本或 JSON，然后使用列分隔符和区域设置等参数对其进行微调。

Elasticsearch 的默认响应是一个 JSON 表格，其中 columns 是描述数组，values 是包含值的行的数组。

这是一个示例查询和 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");
}

这是 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
        ],
        ...
    ]
}

使用此响应，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
---

以下示例将 ES|QL 结果作为 CSV 获取并进行解析

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

var_dump($result->asArray());

响应看起来像这样

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"
  }

在响应中，第一行包含列描述，其他行包含值，使用简单的 PHP 数组。

定义您自己的映射

编辑

虽然 esql()->query() API 涵盖了许多用例，但您的应用程序可能需要自定义映射。

您可以使用 mapTo() 函数将 ES|QL 结果映射到对象数组。这是一个示例

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

您还可以指定类的名称进行映射。所有值都将分配给类的属性。

这是一个返回 Book 对象数组的示例映射器

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
« 迭代器 发行说明 »