Elastic Scout Driver Plus

You can construct complex Elasticsearch boolean queries using the Elastic\ScoutDriverPlus\Support\Query::bool() method. This method allows you to compose multiple query clauses (like must, filter, should, etc.) to refine your search results. Once the query is built, you can execute it using the model's searchQuery($query)->execute() method.

$query = Query::bool()->must(
    Query::match()
        ->field('title')
        ->query('The Book')
);

$searchResult = Book::searchQuery($query)->execute();

Install the library via Composer.

Prerequisites: This library requires Elastic Scout Driver to function. It is recommended to update your existing babenkoivan/elastic-scout-driver installation before proceeding.

Steps:

1. Install the package:

   composer require babenkoivan/elastic-scout-driver-plus

2. Update the base driver (if already installed):

   composer update babenkoivan/elastic-scout-driver

3. Update your models: Replace the standard Laravel\Scout\Searchable trait with Elastic\ScoutDriverPlus\Searchable in all models you wish to index using this driver.

Once a query is defined, use the searchQuery method on your model to initiate a search builder. You can then chain parameters like size(), sort(), or highlight() to refine the request before calling execute() to retrieve the results.

Example Workflow:

1. Define the query.
2. Call Model::searchQuery($query).
3. Chain parameters (e.g., size, sort).
4. Call execute() to get the SearchResult object.

// 1. Define query
$query = Query::match()->field('title')->query('My book');

// 2. Build and refine search
$builder = Book::searchQuery($query)
    ->size(2)
    ->sort('price', 'asc');

// 3. Execute
$searchResult = $builder->execute();

The SearchParametersBuilder is used to fluently construct complex Elasticsearch queries. It allows you to define query logic, sorting, pagination, aggregations, and more before executing the search against your models. You typically start by obtaining a builder instance from a searchable model and then chain methods to configure the search parameters.

// Assuming $model is a searchable Eloquent model
$results = $model->search()
    ->query(['match' => ['title' => 'search term']])
    ->sort('created_at', 'desc')
    ->size(20)
    ->execute();

The searchQuery() method accepts both the fluent Query builder and raw Elasticsearch query arrays for nested structures.

// Using the Query builder
$query = Query::nested()
    ->path('author')
    ->query(Query::match()->field('author.name')->query('Steven'));

// Using a raw query array
$query = [
    'nested' => [
        'path' => 'author',
        'query' => [
            'match' => [
               'author.name' => 'Steven'
            ]
        ]
    ]
];

$searchResult = Book::searchQuery($query)->execute();

The hits() method returns a collection of hits. Each hit object provides metadata about the match and links to the underlying data. You can also retrieve the raw representation of a specific hit.

$hit = $hits->first();

$indexName = $hit->indexName();
$score = $hit->score();
$model = $hit->model();
$document = $hit->document();
$highlight = $hit->highlight();
$innerHits = $hit->innerHits();
$explanation = $hit->explanation();

$raw = $hit->raw();

The filter clause requires documents to match the specified criteria, but unlike must, it does not contribute to the relevance score. You can pass either a Query builder instance or a raw array to the filter() method.

If you need to pass a raw array directly and replace any existing filter clauses, use filterRaw().

// Using the builder
$filter = Query::term()
    ->field('published')
    ->value('2020-06-07');

$query = Query::bool()->filter($filter);

// Using a raw array
$filter = [
    'term' => [
        'published' => '2020-06-07'
    ]
];
$query = Query::bool()->filter($filter);

// Using filterRaw (replaces existing filter clause)
$query = Query::bool()->filterRaw([
    'term' => [
        'published' => '2020-06-07'
    ]
]);

$searchResult = Book::searchQuery($query)->execute();

Use Elastic\ScoutDriverPlus\Support\Query::matchPhrase() to match documents that contain the exact provided phrase.

Available methods:

• field(string $field): Specify the field to search.
• query(string $query): Set the text to find.
• analyzer(string $analyzer): Specify the analyzer to convert query text into tokens.
• slop(int $slop): Define the maximum number of positions allowed between matching tokens.
• zeroTermsQuery(string $zeroTermsQuery): Define what to return if the analyzer removes all tokens.

$query = Query::matchPhrase()
    ->field('title')
    ->query('My book');

$searchResult = Book::searchQuery($query)->execute();

When indexing models, you can include related data in the toSearchableArray() method. To prevent N+1 query issues during bulk indexing, override the searchableWith() method to specify which relations should be eager-loaded.

class Book extends Model
{
    use Elastic\ScoutDriverPlus\Searchable;

    public function toSearchableArray()
    {
        return [
            'title' => $this->title,
            'price' => $this->price,
            'author' => $this->author->only(['name', 'phone_number']),
        ];
    }

    public function searchableWith()
    {
        return ['author'];
    }
}

The trackTotalHits() method allows you to control how the total number of hits is tracked in the search response.

$searchResult = Book::searchQuery($query)
    ->trackTotalHits(true)
    ->execute();

The minimumShouldMatch method allows you to specify the number of should queries a document must match to be included in the results.

$query = Query::bool()
    ->should(Query::term()->field('published')->value('2018-04-23'))
    ->should(Query::term()->field('published')->value('2020-03-07'))
    ->minimumShouldMatch(1);

$searchResult = Book::searchQuery($query)->execute();