Extension for OpenSearch Scout Driver.
OpenSearch Scout Driver Plus supports:
- Aggregations
- Custom routing
- Highlighting
- Multiple connections
- Search across multiple indices
- Search after
- Source filtering
- Suggesters
The current version of OpenSearch Scout Driver Plus has been tested with the following configuration:
- PHP 7.4-8.2
- OpenSearch 2.x
- Laravel 7.x-10.x
- Laravel Scout 7.x-10.x
The library can be installed via Composer:
composer require friendsofcat/opensearch-scout-driver-plus
Note that this library doesn't work without OpenSearch Scout Driver. If it's not installed yet, please follow the installation steps described here. If you already use OpenSearch Scout Driver, I recommend you to update it before installing OpenSearch Scout Driver Plus:
composer update friendsofcat/opensearch-scout-driver
After installing the libraries, you need to add OpenSearch\ScoutDriverPlus\Searchable
trait to your models. In case
some models already use the standard Laravel\Scout\Searchable
trait, you should replace it with the one provided by
OpenSearch Scout Driver Plus.
If you want to use OpenSearch Scout Driver Plus with Lumen framework refer to this guide.
Before you begin searching a model, you should define a query. You can either use a query builder or describe the query with an array:
use OpenSearch\ScoutDriverPlus\Support\Query;
// using a query builder
$query = Query::match()
->field('title')
->query('My book')
->fuzziness('AUTO');
// using a raw query
$query = [
'match' => [
'title' => [
'query' => 'My book',
'fuzziness' => 'AUTO'
]
]
];
Each method of OpenSearch\ScoutDriverPlus\Support\Query
factory creates a query builder for the respective type.
Available methods are listed below:
- bool
- exists
- fuzzy
- geoDistance
- ids
- matchAll
- matchNone
- matchPhrasePrefix
- matchPhrase
- match
- multiMatch
- nested
- prefix
- range
- regexp
- term
- terms
- wildcard
When the query is defined, you can begin new search with searchQuery
method:
$builder = Book::searchQuery($query);
You can then chain other parameters to make your search request more precise:
$builder = Book::searchQuery($query)
->size(2)
->sort('price', 'asc');
The builder supports various search parameters and provides a number of useful helpers:
- aggregate
- boostIndex
- collapse
- from
- highlight
- join
- load
- minScore
- postFilter
- size
- sort
- refineModels
- rescore
- refineModels
- source
- suggest
- trackScores
- trackTotalHits
- when
- explain
You can retrieve search results by chaining the execute
method onto the builder:
$searchResult = Book::searchQuery($query)->execute();
$searchResult
provides easy access to matching hits, models, documents, etc.:
$hits = $searchResult->hits();
$models = $searchResult->models();
$documents = $searchResult->documents();
$highlights = $searchResult->highlights();
You can get more familiar with the $searchResult
object and learn how to paginate the search results on this page.
If you want to use a custom shard routing
for your model, override the searchableRouting
method:
class Book extends Model
{
use OpenSearch\ScoutDriverPlus\Searchable;
public function searchableRouting()
{
return $this->user->id;
}
}
Custom routing is automatically applied to all index and delete operations.
Sometimes you need to index your model with related data:
class Book extends Model
{
use OpenSearch\ScoutDriverPlus\Searchable;
public function toSearchableArray()
{
return [
'title' => $this->title,
'price' => $this->price,
'author' => $this->author->only(['name', 'phone_number']),
];
}
}
You can improve the performance of bulk operations by overriding the searchableWith
method:
class Book extends Model
{
use OpenSearch\ScoutDriverPlus\Searchable;
public function toSearchableArray()
{
return [
'title' => $this->title,
'price' => $this->price,
'author' => $this->author->only(['name', 'phone_number']),
];
}
public function searchableWith()
{
return ['author'];
}
}
In case you are looking for a way to preload relations for models matching a search query, check the builder's
load
method documentation.
You can configure multiple connections to OpenSearch in the client's configuration file.
If you want to change a connection used by a model, you need to override the searchableConnection
method:
class Book extends Model
{
use OpenSearch\ScoutDriverPlus\Searchable;
public function searchableConnection(): ?string
{
return 'books';
}
}