/elastic-scout-driver-plus

Extension for Elastic Scout Driver

Primary LanguagePHPMIT LicenseMIT

Extension for Elastic Scout Driver.

Contents

Compatibility

The current version of Elastic Scout Driver Plus has been tested with the following configuration:

  • PHP 7.2-7.4
  • Elasticsearch 7.0-7.6
  • Laravel 6.x-7.x
  • Laravel Scout 7.x-8.x
  • Elastic Scout Driver 1.x

Installation

The library can be installed via Composer:

composer require babenkoivan/elastic-scout-driver-plus

Note, that the library doesn't work without Elastic Scout Driver. If it's not installed yet, please follow the installation steps described here.

Usage

Elastic Scout Driver Plus doesn't replace or modify default search method provided by Laravel Scout. Instead, it introduces a list of advanced query builders, which allow you to make complex search requests.

To get started with the builders you need to add CustomSearch trait to your model:

class MyModel
{
    use \ElasticScoutDriverPlus\CustomSearch;
}

Bool Search

Use boolSearch method to make a bool request:

MyModel::boolSearch()
    // must clause 
    ->must('match', ['title' => 'incredible'])
    ->mustRaw(['match' => ['title' => 'incredible']])
    // must not clause
    ->mustNot('match', ['title' => 'incredible'])
    ->mustNotRaw(['match' => ['title' => 'incredible']])
    // should clause
    ->should('match', ['title' => 'incredible'])
    ->shouldRaw(['match' => ['title' => 'incredible']])
    ->minimumShouldMatch(1)
    // filter clause
    ->filter('term', ['year' => 2020])
    ->filterRaw(['term' => ['year' => 2020]])
    // soft deletes
    ->onlyTrashed()
    ->withTrashed()
    // sorting
    ->sort('year', 'asc')
    ->sortRaw([['year' => 'asc']])
    // highlighting
    ->highlight('title', ['number_of_fragments' => 3])
    ->highlightRaw(['fields' => ['title' => ['number_of_fragments' => 3]]])
    // pagination
    ->from(0)
    ->size(20)
    // suggest
    ->suggest('title_suggest', ['text' => 'incrediple', 'term' => ['field' => 'title']])
    ->suggestRaw(['title_suggest' => ['text' => 'incrediple', 'term' => ['field' => 'title']]])
    // source filtering
    ->source(['title', 'description'])
    ->sourceRaw(false)
    // field collapsing
    ->collapse('user')
    ->collapseRaw(['field' => 'user'])
    // aggregations
    ->aggregate('max_price', ['max' => ['field' => 'price']])
    ->aggregateRaw(['max_price' => ['max' => ['field' => 'price']]])
    // execute request and return array result
    ->raw()
    // execute request and return SearchResult instance (see below for more details)
    ->execute();

Raw Search

Use rawSearch method to make a custom search request:

MyModel::rawSearch()
    // raw query
    ->query(['match' => ['title' => 'incredible']])
    // sorting
    ->sort('year', 'asc')
    ->sortRaw([['year' => 'asc']])
    // highlighting
    ->highlight('title', ['number_of_fragments' => 3])
    ->highlightRaw(['fields' => ['title' => ['number_of_fragments' => 3]]])
    // pagination
    ->from(0)
    ->size(20)
    // suggest
    ->suggest('title_suggest', ['text' => 'incrediple', 'term' => ['field' => 'title']])
    ->suggestRaw(['title_suggest' => ['text' => 'incrediple', 'term' => ['field' => 'title']]])
    // source filtering
    ->source(['title', 'description'])
    ->sourceRaw(false)
    // field collapsing
    ->collapse('user')
    ->collapseRaw(['field' => 'user'])
    // aggregations
    ->aggregate('max_price', ['max' => ['field' => 'price']])
    ->aggregateRaw(['max_price' => ['max' => ['field' => 'price']]])
    // execute request and return array result
    ->raw()
    // execute request and return SearchResult instance (see below for more details)
    ->execute();

Search Result

Whenever you preform a search request, SearchResult instance is returned:

$searchResult = MyModel::boolSearch()
    ->must('match_all')
    ->execute();

With SearchResult you can quickly get access to collection of models, documents, highlights, suggestions and aggregations:

$searchResult->models();
$searchResult->documents();    
$searchResult->highlights();
$searchResult->suggestions();
$searchResult->aggregations();

And of course the total amount of matches:

$searchResult->total();

You can also retrieve a collection of matches, which group related model, document and highlight:

$matches = $searchResult->matches();
$firstMatch = $matches->first();

// model
$model = $firstMatch->model();

// document
$document = $firstMatch->document();
$documentId = $document->getId();
$documentContent = $document->getContent();

// highlight
$highlight = $firstMatch->highlight();
$highlightedSnippets = $highlight->getSnippets('title');
$rawHighlight = $highlight->getRaw();

Note, that models are lazy loaded, which means, that they will be fetched from the database with a single query and only when it's needed.