README

Elastic Adapter是官方PHP Elasticsearch客户端的适配器。它旨在简化基本的索引和文档操作。

内容

• 兼容性
• 安装
• 配置
• 索引管理
• 文档管理
• 时间点管理

兼容性

Elastic Adapter当前版本已与以下配置进行测试：

• PHP 8.2
• Elasticsearch 8.x
• Laravel 11.x

如果你的项目使用较旧的Laravel（或PHP）版本，请检查包的先前主要版本。

安装

该库可以通过Composer安装

composer require babenkoivan/elastic-adapter

配置

Elastic Adapter使用babenkoivan/elastic-client作为依赖项。要更改客户端设置，您需要首先发布配置文件

php artisan vendor:publish --provider="Elastic\Client\ServiceProvider"

在新建的config/elastic.client.php文件中，您可以定义默认连接名称，并使用配置哈希描述多个连接。请参阅elastic-client文档获取更多详细信息。

索引管理

\Elastic\Adapter\Indices\IndexManager用于操作索引。

创建

创建索引，可以是默认设置和映射，

$index = new \Elastic\Adapter\Indices\Index('my_index');

$indexManager->create($index);

或者根据您的需求进行配置

$mapping = (new \Elastic\Adapter\Indices\Mapping())
    ->text('title', [
        'boost' => 2,
    ])
    ->keyword('tag', [
        'null_value' => 'NULL'
    ])
    ->geoPoint('location')
    ->dynamic(true)
    ->dynamicTemplate('no_doc_values', [
        'match_mapping_type' => '*',
        'mapping' => [
            'type' => '{dynamic_type}',
            'doc_values' => false,
        ],
    ]);

$settings = (new \Elastic\Adapter\Indices\Settings())
    ->index([
        'number_of_replicas' => 2,
        'refresh_interval' => -1
    ]);

$index = new \Elastic\Adapter\Indices\Index('my_index', $mapping, $settings);

$indexManager->create($index);

或者，您可以使用原始输入创建索引

$mapping = [
    'properties' => [
        'title' => [
            'type' => 'text'
        ]   
    ]
];

$settings = [
    'number_of_replicas' => 2
];

$indexManager->createRaw('my_index', $mapping, $settings);

删除

删除索引

$indexManager->drop('my_index');

放置映射

使用构建器更新索引映射，

$mapping = (new \Elastic\Adapter\Indices\Mapping())
    ->text('title', [
        'boost' => 2,
    ])
    ->keyword('tag', [
        'null_value' => 'NULL'
    ])
    ->geoPoint('location');

$indexManager->putMapping('my_index', $mapping);

或使用原始输入

$mapping = [
    'properties' => [
        'title' => [
            'type' => 'text'
        ]   
    ]
];

$indexManager->putMappingRaw('my_index', $mapping);

放置设置

使用构建器更新索引设置，

$settings = (new \Elastic\Adapter\Indices\Settings())
    ->analysis([
        'analyzer' => [
            'content' => [
                'type' => 'custom',
                'tokenizer' => 'whitespace'    
            ]
        ]
    ]);

$indexManager->putSettings('my_index', $settings);

或使用原始输入

$settings = [
    'number_of_replicas' => 2
];

$indexManager->putSettingsRaw('my_index', $settings);

存在

检查索引是否存在

$indexManager->exists('my_index');

打开

打开索引

$indexManager->open('my_index');

关闭

关闭索引

$indexManager->close('my_index');

放置别名

创建别名

$alias = new \Elastic\Adapter\Indices\Alias('my_alias', true, [
    'term' => [
        'user_id' => 12,
    ],
]);

$indexManager->putAlias('my_index', $alias);

与原始输入相同

$settings = [
    'is_write_index' => true,
    'filter' => [
        'term' => [
            'user_id' => 12,
        ],
    ],
];

$indexManager->putAliasRaw('my_index', 'my_alias', $settings);

获取别名

获取索引别名

$indexManager->getAliases('my_index');

删除别名

删除别名

$indexManager->deleteAlias('my_index', 'my_alias');

连接

切换Elasticsearch连接

$indexManager->connection('my_connection');

文档管理

\Elastic\Adapter\Documents\DocumentManager用于管理和搜索文档。

索引

将文档添加到索引

$documents = collect([
    new \Elastic\Adapter\Documents\Document('1', ['title' => 'foo']),
    new \Elastic\Adapter\Documents\Document('2', ['title' => 'bar']),
]);

$documentManager->index('my_index', $documents);

您还可以立即刷新索引

$documentManager->index('my_index', $documents, true);

最后，您可以设置自定义路由

$routing = (new \Elastic\Adapter\Documents\Routing())
    ->add('1', 'value1')
    ->add('2', 'value2');

$documentManager->index('my_index', $documents, false, $routing);

删除

从索引中删除文档

$documentIds = ['1', '2'];

$documentManager->delete('my_index', $documentIds);

如果您想立即刷新索引，请将第三个参数传递为true

$documentManager->delete('my_index', $documentIds, true);

您还可以设置自定义路由

$routing = (new \Elastic\Adapter\Documents\Routing())
    ->add('1', 'value1')
    ->add('2', 'value2');

$documentManager->delete('my_index', $documentIds, false, $routing);

最后，您可以使用查询删除文档

$documentManager->deleteByQuery('my_index', ['match_all' => new \stdClass()]);

搜索

在索引中搜索文档

// configure search parameters
$searchParameters = new \Elastic\Adapter\Search\SearchParameters();

// specify indices to search in
$searchParameters->indices(['my_index1', 'my_index2']);

// define the query
$searchParameters->query([
    'match' => [
        'message' => 'test'
    ]
]);

// configure highlighting
$searchParameters->highlight([
    'fields' => [
        'message' => [
            'type' => 'plain',
            'fragment_size' => 15,
            'number_of_fragments' => 3,
            'fragmenter' => 'simple'
        ]
    ]
]);

// add suggestions
$searchParameters->suggest([
    'message_suggest' => [
        'text' => 'test',
        'term' => [
            'field' => 'message'
        ]
    ]
]);

// enable source filtering
$searchParameters->source(['message', 'post_date']);

// collapse fields
$searchParameters->collapse([
    'field' => 'user'
]);

// aggregate data
$searchParameters->aggregations([
    'max_likes' => [
        'max' => [
            'field' => 'likes'
        ]
    ]
]);

// sort documents
$searchParameters->sort([
    ['post_date' => ['order' => 'asc']],
    '_score'
]);

// rescore documents
$searchParameters->rescore([
    'window_size' => 50,
    'query' => [
        'rescore_query' => [
            'match_phrase' => [
                'message' => [
                    'query' => 'the quick brown',
                    'slop' => 2,
                ],
            ],
        ],
        'query_weight' => 0.7,
        'rescore_query_weight' => 1.2,
    ]
]);

// add a post filter
$searchParameters->postFilter([
    'term' => [
        'cover' => 'hard'
    ]
]);

// track total hits
$searchParameters->trackTotalHits(true);

// track scores
$searchParameters->trackScores(true);

// script fields
$searchParameters->scriptFields([
    'my_doubled_field' => [
        'script' => [
            'lang' => 'painless',
            'source' => 'doc[params.field] * params.multiplier',
            'params' => [
                'field' => 'my_field',
                'multiplier' => 2,
            ],
        ],
    ],
]);

// boost indices
$searchParameters->indicesBoost([
    ['my-alias' => 1.4],
    ['my-index' => 1.3],
]);

// define the search type
$searchParameters->searchType('query_then_fetch');

// set the preference
$searchParameters->preference('_local');

// use pagination
$searchParameters->from(0)->size(20);

// search after
$searchParameters->pointInTime([
    'id' => '46ToAwMDaWR5BXV1',
    'keep_alive' => '1m',
]);

$searchParameters->searchAfter([
    '2021-05-20T05:30:04.832Z',
    4294967298,
]);

// use custom routing
$searchParameters->routing(['user1', 'user2']);

// enable explanation
$searchParameters->explain(true);

// set maximum number of documents to collect for each shard
$searchParameters->terminateAfter(10);

// enable caching
$searchParameters->requestCache(true);

// perform the search and get the result
$searchResult = $documentManager->search($searchParameters);

// get the total number of matching documents
$total = $searchResult->total(); 

// get the corresponding hits
$hits = $searchResult->hits();

// every hit provides access to the related index name, the score, the document, the highlight and more
// in addition, you can get a raw representation of the hit
foreach ($hits as $hit) {
    $indexName = $hit->indexName();
    $score = $hit->score();
    $document = $hit->document();
    $highlight = $hit->highlight();
    $innerHits = $hit->innerHits();
    $innerHitsTotal = $hit->innerHitsTotal();
    $raw = $hit->raw();
    
    // get an explanation 
    $explanation = $searchResult->explanation();
    
    // every explanation includes a value, a description and details
    // it is also possible to get its raw representation
    $value = $explanation->value();
    $description = $explanation->description();
    $details = $explanation->details();
    $raw = $explanation->raw();
}

// get suggestions
$suggestions = $searchResult->suggestions();

// get aggregations
$aggregations = $searchResult->aggregations();

连接

切换Elasticsearch连接

$documentManager->connection('my_connection');

时间点管理

\Elastic\Adapter\Search\PointInTimeManager用于控制时间点。

打开

打开时间点

$pointInTimeId = $pointInTimeManager->open('my_index', '1m');

关闭

关闭时间点

$pointInTimeManager->close($pointInTimeId);

连接

切换Elasticsearch连接

$pointInTimeManager->connection('my_connection');