README

Extension for OpenSearch Scout Driver.

Contents

• Features
• Compatibility
• Installation
• Usage
  • Query
  • Search parameters
  • Search results
  • Custom routing
  • Eager loading relations
  • Multiple connections

Features

OpenSearch Scout Driver Plus supports:

• Aggregations
• Custom routing
• Highlighting
• Multiple connections
• Search across multiple indices
• Search after
• Source filtering
• Suggesters

Compatibility

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

Installation

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.

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 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

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:

• aggregate
• boostIndex
• collapse
• from
• highlight
• join
• load
• minScore
• postFilter
• size
• sort
• refineModels
• rescore
• refineModels
• source
• suggest
• trackScores
• trackTotalHits
• when
• explain

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 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.

Eager Loading Relations

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.

Multiple Connections

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';
    }
}