Elasticsearch-PHP 文档操作指南：索引、查询、更新与删除

前言

Elasticsearch-PHP 是 Elasticsearch 官方提供的 PHP 客户端库，它允许开发者通过 PHP 代码与 Elasticsearch 集群进行交互。本文将深入讲解如何使用 Elasticsearch-PHP 进行文档的 CRUD（创建、读取、更新、删除）操作，帮助 PHP 开发者高效地使用 Elasticsearch。

文档索引操作

单文档索引

在 Elasticsearch 中，索引文档是最基本的操作。文档以 JSON 格式存储，这与 PHP 的关联数组天然兼容，因为关联数组可以轻松转换为 JSON。

指定文档 ID 索引

$params = [
    'index' => 'my_index',  // 指定索引名称
    'id'    => 'my_id',     // 指定文档 ID
    'body'  => ['testField' => 'abc']  // 文档内容
];

$response = $client->index($params);  // 执行索引操作

这种方式会将文档索引到 my_index/_doc/my_id 路径下。

自动生成文档 ID 索引

如果不指定 ID，Elasticsearch 会自动生成一个唯一 ID：

$params = [
    'index' => 'my_index',
    'body'  => ['testField' => 'abc']
];

$response = $client->index($params);

此时文档会被索引到 my_index/_doc/<自动生成的ID>。

附加参数设置

索引时可以设置多种参数，如路由值、时间戳等：

$params = [
    'index'     => 'my_index',
    'id'        => 'my_id',
    'routing'   => 'company_xyz',  // 路由值
    'timestamp' => strtotime("-1d"),  // 时间戳设置为前一天
    'body'      => ['testField' => 'abc']
];

$response = $client->index($params);

批量索引

对于大量文档，使用批量索引能显著提高效率。批量 API 需要 JSON 格式的动作/元数据对，在 PHP 中可以通过构建数组来实现。

基础批量索引

$params = ['body' => []];

for($i = 0; $i < 100; $i++) {
    // 添加索引动作
    $params['body'][] = [
        'index' => [
            '_index' => 'my_index'
        ]
    ];
    
    // 添加文档内容
    $params['body'][] = [
        'my_field'     => 'my_value',
        'second_field' => 'some more values'
    ];
}

$responses = $client->bulk($params);

分批批量索引

对于海量数据，建议分批处理以避免内存问题：

$params = ['body' => []];

for ($i = 1; $i <= 1234567; $i++) {
    $params['body'][] = [
        'index' => [
            '_index' => 'my_index',
            '_id'    => $i
        ]
    ];

    $params['body'][] = [
        'my_field'     => 'my_value',
        'second_field' => 'some more values'
    ];

    // 每1000个文档发送一次批量请求
    if ($i % 1000 == 0) {
        $responses = $client->bulk($params);
        $params = ['body' => []];  // 重置参数
        unset($responses);  // 释放内存
    }
}

// 发送最后一批
if (!empty($params['body'])) {
    $responses = $client->bulk($params);
}

文档查询操作

Elasticsearch 提供实时 GET 操作，文档一旦被索引并收到确认，就可以立即从任何分片检索到。

$params = [
    'index' => 'my_index',
    'id'    => 'my_id'
];

$response = $client->get($params);  // 获取指定文档

文档更新操作

部分更新

可以只更新文档的部分字段，而不是替换整个文档：

$params = [
    'index' => 'my_index',
    'id'    => 'my_id',
    'body'  => [
        'doc' => [  // 指定要更新的字段
            'new_field' => 'abc'
        ]
    ]
];

$response = $client->update($params);

脚本更新

使用脚本可以实现更复杂的更新逻辑，如计数器递增：

$params = [
    'index' => 'my_index',
    'id'    => 'my_id',
    'body'  => [
        'script' => 'ctx._source.counter += count',  // 更新脚本
        'params' => [
            'count' => 4  // 脚本参数
        ]
    ]
];

$response = $client->update($params);

Upsert 操作

Upsert 是"更新或插入"操作，当文档不存在时执行插入：

$params = [
    'index' => 'my_index',
    'id'    => 'my_id',
    'body'  => [
        'script' => [
            'source' => 'ctx._source.counter += params.count',
            'params' => ['count' => 4],
        ],
        'upsert' => [  // 文档不存在时的默认值
            'counter' => 1
        ],
    ]
];

$response = $client->update($params);

文档删除操作

删除文档非常简单，只需指定索引和文档 ID：

$params = [
    'index' => 'my_index',
    'id'    => 'my_id'
];

$response = $client->delete($params);  // 删除指定文档

最佳实践建议

1. 批量操作：对于大量文档，始终使用批量操作而非单文档操作
2. 分批处理：超大数据集应分批处理以避免内存溢出
3. 合理使用 Upsert：需要"存在即更新，不存在即插入"的场景使用 Upsert
4. 脚本更新：复杂更新逻辑考虑使用脚本而非多次请求
5. 错误处理：所有操作都应添加适当的错误处理逻辑

通过掌握这些核心操作，您已经能够使用 Elasticsearch-PHP 完成大多数文档操作需求。在实际应用中，根据具体场景选择最适合的操作方式，可以显著提高系统性能和开发效率。