babenkoivan/elastic-scout-driver-plus

Extension for Elastic Scout Driver

v3.2.3 2022-01-22 17:58 UTC

README

logo.gif

68747470733a2f2f706f7365722e707567782e6f72672f626162656e6b6f6976616e2f656c61737469632d73636f75742d6472697665722d706c75732f762f737461626c65 68747470733a2f2f706f7365722e707567782e6f72672f626162656e6b6f6976616e2f656c61737469632d73636f75742d6472697665722d706c75732f646f776e6c6f616473 68747470733a2f2f706f7365722e707567782e6f72672f626162656e6b6f6976616e2f656c61737469632d73636f75742d6472697665722d706c75732f6c6963656e7365 badge.svg badge.svg badge.svg 68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f6e6174652d70617970616c2d626c7565

🎅🏻 Ho ho ho! Christmas is coming! Please consider supporting and starring the project! ⭐️

Support the project!

Extension for Elastic Scout Driver.

Contents

Features

Elastic Scout Driver Plus supports:

Compatibility

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

  • PHP 7.3-8.0
  • Elasticsearch 7.x
  • Laravel 6.x-8.x
  • Laravel Scout 7.x-9.x
  • Elastic Scout Driver 2.x

Installation

The library can be installed via Composer:

composer require babenkoivan/elastic-scout-driver-plus

Note that this library doesn't work without Elastic Scout Driver. If it's not installed yet, please follow the installation steps described here. If you already use Elastic Scout Driver, I recommend you to update it before installing Elastic Scout Driver Plus:

composer update babenkoivan/elastic-scout-driver

After installing the libraries, you need to add ElasticScoutDriverPlus\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 Elastic Scout Driver Plus.

If you want to use Elastic Scout Driver Plus with Lumen framework refer to this guide.

Usage

Query

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 ElasticScoutDriverPlus\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 ElasticScoutDriverPlus\Support\Query factory creates a query builder for the respective type. Available methods are listed below:

Search Parameters

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:

Search Results

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.

Custom Routing

If you want to use a custom shard routing for your model, override the shardRouting method:

class Book extends Model
{
    use ElasticScoutDriverPlus\Searchable;
    
    public function shardRouting()
    {
        return $this->user->id;
    }
}

Custom routing is automatically applied to all index and delete operations.

Eager Loading Relations

Sometimes you need to index your model with related data:

class Book extends Model
{
    use ElasticScoutDriverPlus\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 ElasticScoutDriverPlus\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.