### Install Project Dependencies

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/CONTRIBUTING.md

Run this command to install all necessary project dependencies using Composer.

```bash
composer install
```

--------------------------------

### Install Elastic Scout Driver Plus via Composer

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/README.md

Use Composer to install the library. Ensure Elastic Scout Driver is also installed and updated.

```bash
composer require babenkoivan/elastic-scout-driver-plus
```

```bash
composer update babenkoivan/elastic-scout-driver
```

--------------------------------

### Install Elastic Scout Driver Plus with Composer

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/wiki/Lumen-Installation

Use Composer to require the package. This command fetches and installs the necessary files for the driver.

```bash
composer require babenkoivan/elastic-scout-driver-plus
```

--------------------------------

### from

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

Defines the starting document offset for the search query.

```APIDOC
## from

### Description
`from` defines the starting document offset.

### Method
`from(int $value)
execute()
`

### Parameters
#### from(int $value)
- **value** (int) - The starting document offset.

### Request Example
```php
$searchResult = Book::searchQuery($query)
    ->from(5)
    ->execute();
```

### Response
#### Success Response
The `execute()` method returns a search result object starting from the specified offset.
```

--------------------------------

### Starting a Search with `Model::searchQuery()`

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Initiate a search using `Model::searchQuery()`, which returns a `SearchParametersBuilder`. Chain search parameters and then execute the query.

```php
use Elastic\ScoutDriverPlus\Support\Query;

$builder = Book::searchQuery(
    Query::match()->field('title')->query('Laravel')
);

// Chain parameters, then execute
$searchResult = $builder
    ->size(5)
    ->from(0)
    ->sort('price', 'asc')
    ->execute();

// Raw Elasticsearch response array
$raw = Book::searchQuery($query)->raw();
```

--------------------------------

### Set Starting Document Offset

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

Use the `from` method to specify the starting document offset for a search query, controlling which page of results is returned.

```php
$searchResult = Book::searchQuery($query)
    ->from(5)
    ->execute();
```

--------------------------------

### Initiate a Search Query

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/README.md

Start a search request by calling `searchQuery` on your model with a defined query. This returns a builder instance for chaining further search parameters.

```php
$builder = Book::searchQuery($query);
```

--------------------------------

### Build a Terms Query with Boost

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/term-queries.md

This example shows how to increase or decrease the relevance score for a terms query. Apply boost after defining the field and values.

```php
$query = Query::terms()
    ->field('tags')
    ->values(['available', 'new'])
    ->boost(2);

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

--------------------------------

### Build a Boolean Query

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/compound-queries.md

Use `Query::bool()` to construct a boolean query. This example demonstrates a basic must clause.

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

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

--------------------------------

### Access Specific Suggestions

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

Suggestions are returned as a collection. Use the `get` method with the suggestion name to retrieve a specific set of suggested terms.

```php
$titleSuggestions = $suggestions->get('title_suggest');
```

--------------------------------

### Multi-Match Query Example

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Use `multiMatch` to search for a query across multiple fields. Options include specifying the type of match, tie-breaker, fuzziness, and operator.

```php
use Elastic\ScoutDriverPlus\Support\Query;

$query = Query::multiMatch()
    ->fields(['title', 'description'])
    ->query('My book')
    ->type('best_fields')
    ->tieBreaker(0.3)
    ->fuzziness('AUTO')
    ->operator('OR')
    ->minimumShouldMatch(1)
    ->boost(2);

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

--------------------------------

### Match Query Example

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Construct a `match` query to find documents with a text, number, date, or boolean value in a specific field. Various options like analyzer, fuzziness, and boost are available.

```php
use Elastic\ScoutDriverPlus\Support\Query;

$query = Query::match()
    ->field('title')
    ->query('My book')
    ->analyzer('english')
    ->fuzziness('AUTO')
    ->fuzzyTranspositions(true)
    ->prefixLength(0)
    ->maxExpansions(50)
    ->operator('OR')
    ->minimumShouldMatch(1)
    ->boost(1.5)
    ->zeroTermsQuery('none');

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

--------------------------------

### Match Phrase Query Example

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Employ `matchPhrase` to find documents containing an exact phrase. Control the analyzer, slop (edit distance), and zero-term query behavior.

```php
use Elastic\ScoutDriverPlus\Support\Query;

$query = Query::matchPhrase()
    ->field('title')
    ->query('My book')
    ->analyzer('english')
    ->slop(1)
    ->zeroTermsQuery('none');

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

--------------------------------

### Match Phrase Prefix Query Example

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Utilize `matchPhrasePrefix` for matching documents with an exact phrase where the last term is treated as a prefix. Configure analyzer, max expansions, slop, and zero-term query.

```php
use Elastic\ScoutDriverPlus\Support\Query;

$query = Query::matchPhrasePrefix()
    ->field('title')
    ->query('My boo')
    ->analyzer('english')
    ->maxExpansions(50)
    ->slop(0)
    ->zeroTermsQuery('none');

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

--------------------------------

### Include Score Explanation

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Enable score explanation with `explain(true)` to get detailed information about how the relevance score was computed for each hit. This is useful for debugging and understanding search results.

```php
$searchResult = Book::searchQuery($query)
    ->explain(true)
    ->execute();

$explanation = $searchResult->hits()->first()->explanation();
$value       = $explanation->value();
$description = $explanation->description();
$details     = $explanation->details();
```

--------------------------------

### Execute Search Query and Get SearchResult

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Run a search query and retrieve a SearchResult object for typed access to response components. This is the primary method for retrieving search results.

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

// All hits (raw Elasticsearch hit objects)
$hits = $searchResult->hits();
$hit  = $hits->first();

$indexName   = $hit->indexName();
$score       = $hit->score();
$model       = $hit->model();       // Eloquent model (lazy loaded)
$document    = $hit->document();    // Elasticsearch document
$highlight   = $hit->highlight();
$innerHits   = $hit->innerHits();
$explanation = $hit->explanation();
$raw         = $hit->raw();

// Document fields
$doc     = $searchResult->documents()->first();
$id      = $doc->id();
$content = $doc->content();

// Convenience collections
$models      = $searchResult->models();      // Collection of Eloquent models
$documents   = $searchResult->documents();   // Collection of documents
$highlights  = $searchResult->highlights();  // Collection of highlights
$aggregations = $searchResult->aggregations();
$total       = $searchResult->total();       // int: total matching documents

// Highlight snippets
$snippets = $searchResult->highlights()->first()->snippets('title');
```

--------------------------------

### Get Similar Terms with suggest

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

Use the `suggest` method to retrieve similar terms based on provided text. Ensure the suggester is configured in your Elasticsearch index.

```php
$searchResult = Book::searchQuery(Query::matchNone())
    ->suggest('title_suggest', ['text' => 'book', 'term' => ['field' => 'title']])
    ->execute();
```

--------------------------------

### Prefix Query

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Matches documents whose field contains terms starting with a specific prefix. Supports case-insensitive matching and rewrite strategies.

```php
$query = Query::prefix()
    ->field('title')
    ->value('boo')
    ->caseInsensitive(true)
    ->rewrite('constant_score');

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

--------------------------------

### Get Similar Terms with suggestRaw

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

The `suggestRaw` method provides a way to pass raw suggestion definitions to Elasticsearch. This is an alternative to the `suggest` method.

```php
$searchResult = Book::searchQuery(Query::matchNone())
    ->suggestRaw(['title_suggest' => ['text' => 'book', 'term' => ['field' => 'title']]])
    ->execute();
```

--------------------------------

### Range Query Basic Example

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/term-queries.md

Build a basic range query to find documents with terms within a specified range on a given field. The `gt()` method sets a 'greater than' condition.

```php
$query = Query::range()
    ->field('price')
    ->gt(100);

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

--------------------------------

### Specify Node/Shard Preference for Search

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Control which nodes and shards are used for executing a search query using the `preference()` method. For example, `_local` prioritizes local shards.

```php
$searchResult = Book::searchQuery($query)
    ->preference('_local')
    ->execute();
```

--------------------------------

### Execute Search and Get SearchResult Instance

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/search-results.md

Execute a search query and obtain a SearchResult object for structured access to Elasticsearch data. This object provides access to aggregations, documents, highlights, hits, models, suggestions, and total counts.

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

```

--------------------------------

### Suggesters

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Gets similar-looking terms based on provided text, useful for auto-completion or spell correction. Use `suggest()` for basic suggestions and `suggestRaw()` for advanced configurations. Suggestions are retrieved via `$searchResult->suggestions()`.

```php
$searchResult = Book::searchQuery(Query::matchNone())
    ->suggest('title_suggest', ['text' => 'boko', 'term' => ['field' => 'title']])
    ->execute();

$suggestions    = $searchResult->suggestions();
$titleSuggest   = $suggestions->get('title_suggest');
$firstSuggestion = $titleSuggest->first();

$text    = $firstSuggestion->text();    // 'boko'
$options = $firstSuggestion->options(); // [['text' => 'book', 'score' => 0.75, ...]]
$models  = $firstSuggestion->models();  // related Eloquent models (completion suggester)
```

--------------------------------

### Run Test Suite

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/CONTRIBUTING.md

Execute this command to set up the environment and run the project's test suite.

```bash
make up wait test
```

--------------------------------

### Accessing Documents

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/search-results.md

Get a collection of matching documents from the `SearchResult` object. Each document contains an ID and its content.

```APIDOC
### Documents

`documents` returns a collection of matching documents:

```php
$documents = $searchResult->documents();
```

Every document has an id and content:

```php
$document = $documents->first();

$id = $document->id();
$content = $document->content();
```
```

--------------------------------

### Set Geo-Distance Validation Method

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/geo-queries.md

Use `validationMethod()` to define how latitude and longitude are validated. Example: 'IGNORE_MALFORMED'.

```php
use Elastic\ScoutDriverPlus\Support\Query;

$query = Query::geoDistance()
    ->field('location')
    ->distance('200km')
    ->lat(40)
    ->lon(-70)
    ->validationMethod('IGNORE_MALFORMED');

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

--------------------------------

### Deep Pagination with Point-in-Time and Search After

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Implement deep pagination using a point-in-time snapshot for stability and `searchAfter` for cursor-based navigation. Ensure to open and close the point-in-time resource.

```php
$pit = Book::openPointInTime('1m');

$firstPage = Book::searchQuery($query)
    ->sort('_shard_doc', 'asc')
    ->pointInTime($pit, '5m')
    ->size(10)
    ->execute();

$lastSort = $firstPage->hits()->last()->sort();

$secondPage = Book::searchQuery($query)
    ->sort('_shard_doc', 'asc')
    ->pointInTime($pit, '5m')
    ->searchAfter($lastSort)
    ->size(10)
    ->execute();

Book::closePointInTime($pit);
```

--------------------------------

### Get Total Number of Matching Documents

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/search-results.md

Retrieve the total count of documents that match the search query from the SearchResult object.

```php
$total = $searchResult->total();

```

--------------------------------

### Retrieve Matching Documents

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/search-results.md

Get a collection of matching documents from the SearchResult. Each document object provides access to its ID and content.

```php
$documents = $searchResult->documents();
$document = $documents->first();

$id = $document->id();
$content = $document->content();

```

--------------------------------

### Match All / None Query

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Use `matchAll` to retrieve all documents or `matchNone` to retrieve no documents. Useful for scenarios involving suggesters.

```php
$allResults  = Book::searchQuery(Query::matchAll())->execute();
$noneResults = Book::searchQuery(Query::matchNone())->execute();
```

--------------------------------

### Get Raw Elasticsearch Response

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/search-results.md

Use this method to retrieve the raw response directly from Elasticsearch without any additional decoration.

```php
$raw = Book::searchQuery($query)->raw();

```

--------------------------------

### pointInTime() and searchAfter()

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Enables deep pagination using a point-in-time snapshot for stable cursor-based pagination. This is more efficient for large datasets than traditional offset-based pagination.

```APIDOC
## pointInTime() and searchAfter()

### Description
Uses a point-in-time snapshot for stable cursor-based pagination.

### Method
```php
// Open a point in time
$pit = Book::openPointInTime('1m');

// First page
$firstPage = Book::searchQuery($query)
    ->sort('_shard_doc', 'asc')
    ->pointInTime($pit, '5m')
    ->size(10)
    ->execute();

// Get sort values from the last hit of the first page
$lastSort = $firstPage->hits()->last()->sort();

// Second page using searchAfter
$secondPage = Book::searchQuery($query)
    ->sort('_shard_doc', 'asc')
    ->pointInTime($pit, '5m')
    ->searchAfter($lastSort)
    ->size(10)
    ->execute();

// Close the point in time
Book::closePointInTime($pit);
```
```

--------------------------------

### Prefix Query Options

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/term-queries.md

Demonstrates various options for configuring a prefix query, including case-insensitivity, field specification, rewrite strategies, and the search value.

```APIDOC
## Prefix Query Options

This section covers the configuration options available for the prefix query.

### caseInsensitive

Allows ASCII case-insensitive matching for the prefix query.

```php
$query = Query::prefix()
    ->field('title')
    ->value('boo')
    ->caseInsensitive(true);

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

### field

Specifies the field to perform the prefix search on.

```php
$query = Query::prefix()
    ->field('title')
    ->value('boo');

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

### rewrite

Defines how the query should be rewritten. Common values include 'constant_score'.

```php
$query = Query::prefix()
    ->field('title')
    ->value('boo')
    ->rewrite('constant_score');

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

### value

Sets the beginning characters of terms to find within the specified field.

```php
$query = Query::prefix()
    ->field('title')
    ->value('boo');

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

--------------------------------

### suggest

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

This method can be used to get similar looking terms based on the provided text. It utilizes Elasticsearch's suggesters functionality.

```APIDOC
## suggest

### Description
This method allows you to retrieve similar-looking terms based on a provided text input, leveraging Elasticsearch's suggesters.

### Method
`suggest(string $name, array $parameters)`

### Endpoint
N/A (SDK Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
$searchResult = Book::searchQuery(Query::matchNone())
    ->suggest('title_suggest', ['text' => 'book', 'term' => ['field' => 'title']])
    ->execute();

$searchResult = Book::searchQuery(Query::matchNone())
    ->suggestRaw(['title_suggest' => ['text' => 'book', 'term' => ['field' => 'title']]])
    ->execute();
```

### Response
#### Success Response (200)
An object containing search results, which can be further processed to extract suggestions.

#### Response Example
```php
// To retrieve suggestions from the search result:
$suggestions = $searchResult->suggestions();

// To get specific suggestions by name:
$titleSuggestions = $suggestions->get('title_suggest');

// Accessing individual suggestion details:
$firstSuggestion = $titleSuggestions->first();
$text = $firstSuggestion->text();
$offset = $firstSuggestion->offset();
$length = $firstSuggestion->length();
$options = $firstSuggestion->options();
$models = $firstSuggestion->models();
$raw = $firstSuggestion->raw();
```
```

--------------------------------

### Define a Query using Query Builder or Raw Array

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/README.md

Use the `Query` factory to build search queries with a fluent interface or define them as raw arrays. This is the first step before initiating a search.

```php
use Elastic\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'
        ] 
    ]
];
```

--------------------------------

### explain

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

Includes detailed information about score computation for every hit when set to true.

```APIDOC
## explain

### Description
When set to `true` every hit includes detailed information about score computation.

### Method
`explain(bool $value)
execute()
`

### Parameters
#### explain(bool $value)
- **value** (bool) - Set to `true` to enable score explanation.

### Request Example
```php
$searchResult = Book::searchQuery($query)
    ->explain(true)
    ->execute();
```

### Response
#### Success Response
The `execute()` method returns a search result object where each hit contains explanation details.

#### Response Example
```php
$hits = $searchResult->hits();
$explanation = $hits->first()->explanation();

$value = $explanation->value();
$description = $explanation->description();
$details = $explanation->details();
$raw = $explanation->raw();
```
```

--------------------------------

### Build Match All Query

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/full-text-queries.md

Use `Query::matchAll()` to create a query that matches all documents in the index. This is useful for retrieving all records.

```php
$query = Query::matchAll();

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

--------------------------------

### when

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

This method will execute the given callback when the first argument given to the method evaluates to true. It's useful for conditionally applying query modifications.

```APIDOC
## when

### Description
Conditionally applies query modifications. The provided callback is executed only if the initial condition evaluates to `true`.

### Method
`when(mixed $condition, callable $callback, ?callable $elseCallback = null)`

### Endpoint
N/A (SDK Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
// Example without an else callback
$searchResult = Book::searchQuery($query)
    ->when($orderBy, function ($builder, $orderBy) {
        return $builder->sort($orderBy, 'asc');
    })
    ->execute();

// Example with an else callback
$searchResult = Book::searchQuery($query)
    ->when($orderBy, function ($builder, $orderBy) {
        return $builder->sort($orderBy, 'asc');
    }, function ($builder) {
         return $builder->sort('price', 'asc');
     })
    ->execute();
```

### Response
#### Success Response (200)
An object containing search results, with query modifications applied conditionally.

#### Response Example
```php
// The search result object
$searchResult
```
```

--------------------------------

### Accessing Suggestions

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/search-results.md

Get a collection of suggestions keyed by suggestion name from the `SearchResult` object. Each suggestion includes text, offset, length, and options.

```APIDOC
### Suggestions

This method returns a collection of suggestions keyed by suggestion name:

```php
$suggestions = $searchResult->suggestions();
$titleSuggestions = $suggestions->get('title_suggest');
```

Each suggestion includes a suggestion text, an offset, a length and an arbitrary number of options:

```php
$firstSuggestion = $titleSuggestions->first();

$text = $firstSuggestion->text();
$offset = $firstSuggestion->offset();
$length = $firstSuggestion->length();
$options = $firstSuggestion->options();
```

You can also resolve the related models when [the completion suggester](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html#completion-suggester) is used:

```php
$models = $firstSuggestion->models();
```
```

--------------------------------

### Access Highlights from Search Results

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/search-results.md

Retrieve highlights from a SearchResult object. Use the `snippets` method to get highlighted text for a specific field.

```php
$highlights = $searchResult->highlights();
$highlight = $highlights->first();
$snippets = $highlight->snippets('title');

```

--------------------------------

### Accessing Hits

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/search-results.md

Get a collection of hits from the `SearchResult` object. Each hit provides details like index name, score, model, document, and highlight.

```APIDOC
### Hits

You can retrieve a collection of hits:

```php
$hits = $searchResult->hits();
```

Each hit provides access to the related index name, the score, the model, the document, the highlight and more:

```php
$hit = $hits->first();

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

Furthermore, you can get a raw representation of the respective hit:

```php
$raw = $hit->raw();
```
```

--------------------------------

### Match Phrase Query Options

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/full-text-queries.md

Configuration options for building a match_phrase query.

```APIDOC
## Match Phrase Query Options

This section details the available methods for configuring a `match_phrase` query.

### `analyzer`

`analyzer` is used to convert the `query` text into tokens.

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

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

### `field`

Use `field` to specify the field you wish to search.

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

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

### `query`

Use `query` to set the text you wish to find in the provided `field`.

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

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

### `slop`

Use `slop` to define the maximum number of positions allowed between matching tokens.

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

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

### `zeroTermsQuery`

You can define what to return in case `analyzer` removes all tokens with `zeroTermsQuery`.

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

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

--------------------------------

### Define GeoJSON Shape Query

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/geo-queries.md

Use `shape` to define a GeoJSON representation of a shape for geo-spatial filtering. This example constructs a query for an 'envelope' shape.

```php
$query = Query::geoShape()
    ->field('location')
    ->shape('envelope', [[13.0, 53.0], [14.0, 52.0]])
    ->relation('within');

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

--------------------------------

### Match None Query

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/full-text-queries.md

Builds a query that matches no documents. This can be useful for excluding all results or as a starting point for building queries that explicitly include specific documents.

```APIDOC
## Match None

You can use `Elastic\ScoutDriverPlus\Support\Query::matchNone()` to build a query that
[matches no documents](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-all-query.html#query-dsl-match-none-query):

```php
$query = Query::matchNone();

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

```
```

--------------------------------

### Enable Score Explanation

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

Set `explain(true)` to include detailed score computation information with each hit. The `explanation()` method on a hit object provides access to the score value, description, and details. The raw explanation can also be retrieved.

```php
$searchResult = Book::searchQuery($query)
    ->explain(true)
    ->execute();

$hits = $searchResult->hits();
$explanation = $hits->first()->explanation();

// every explanation includes a value, a description and details
// it is also possible to get its raw representation
$value = $explanation->value();
$description = $explanation->description();
$details = $explanation->details();
$raw = $explanation->raw();
```

--------------------------------

### Perform Static Code Analysis

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/CONTRIBUTING.md

It is recommended to run static code analysis before submitting a Pull Request to catch potential issues.

```bash
make static-analysis
```

--------------------------------

### join

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

Enables multi-index search, allowing queries across multiple indices and optionally boosting results from specific indices.

```APIDOC
## join

### Description
This method enables multi-index search.

### Method
`join(string $modelClass, int $boost = 1)
execute()
`

### Parameters
#### join(string $modelClass, int $boost = 1)
- **modelClass** (string) - The class name of the model to join with.
- **boost** (int, optional) - The boost value for results from this index. Defaults to 1.

### Request Example
```php
$query = Query::bool()
    ->should(Query::match()->field('name')->query('John'))
    ->should(Query::match()->field('title')->query('The Book'))
    ->minimumShouldMatch(1);

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

$searchResult = Author::searchQuery($query)
    ->join(Book::class, 2)
    ->execute();
```

### Response
#### Success Response
The `execute()` method returns a search result object containing models from all joined indices.
```

--------------------------------

### join()

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Enables searching across multiple Eloquent model indices simultaneously. Results from different indices can be boosted.

```APIDOC
## join()

### Description
Searches across multiple Eloquent model indices simultaneously.

### Method
```php
->join(string $modelClass, float $boost)
```

### Parameters
- **modelClass** (string) - The class name of the model to join.
- **boost** (float) - The boost factor to apply to results from this index.

### Request Example
```php
$query = Query::bool()
    ->should(Query::match()->field('name')->query('John'))
    ->should(Query::match()->field('title')->query('The Book'))
    ->minimumShouldMatch(1);

$searchResult = Author::searchQuery($query)
    ->join(Book::class, 2.0)  // boost Book results by factor 2
    ->load(['books'], Author::class)
    ->load(['author'], Book::class)
    ->execute();

// Models are a mix of Author and Book instances
$models = $searchResult->models();
```
```

--------------------------------

### Build a Regexp Query with Flags

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/term-queries.md

Apply optional operators to the regular expression for more advanced matching. Use the `flags` method to specify these operators.

```php
$query = Query::regexp()
    ->field('title')
    ->value('b.*k')
    ->flags('ALL');

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

--------------------------------

### Boolean Query Minimum Should Match

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/compound-queries.md

Specify the minimum number of `should` queries that must match using `minimumShouldMatch`.

```php
$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();
```

--------------------------------

### Query::matchAll() / Query::matchNone()

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Matches all documents or no documents. Useful for scenarios involving suggesters.

```APIDOC
## `Query::matchAll()` / `Query::matchNone()` — Match all / none

Matches all documents or no documents (useful with suggesters).

```php
$allResults  = Book::searchQuery(Query::matchAll())->execute();
$noneResults = Book::searchQuery(Query::matchNone())->execute();
```
```

--------------------------------

### Build a Wildcard Query with Boost

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/term-queries.md

Adjust the relevance scores for a wildcard query using the boost method. This is applied after setting the field and value.

```php
$query = Elastic\ScoutDriverPlus\Support\Query::wildcard()
    ->field('title')
    ->value('bo*k')
    ->boost(2);

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

--------------------------------

### execute() — Run and get SearchResult

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Executes a search query and returns a SearchResult object, which provides typed accessors for all Elasticsearch response components, including hits, documents, highlights, aggregations, and total count.

```APIDOC
## execute()

### Description
Returns a `SearchResult` decorator with typed accessors for all Elasticsearch response components.

### Method
`execute()`

### Parameters
None

### Request Example
```php
$searchResult = Book::searchQuery($query)->execute();
```

### Response
#### Success Response (SearchResult)
- `hits()`: Returns a collection of raw Elasticsearch hit objects.
- `documents()`: Returns a collection of document objects.
- `models()`: Returns a collection of Eloquent models (lazy loaded).
- `highlights()`: Returns a collection of highlight objects.
- `aggregations()`: Returns aggregation results.
- `total()`: Returns the total number of matching documents.

### Response Example
```php
// Accessing hits
$hits = $searchResult->hits();
$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();

// Accessing document fields
$doc = $searchResult->documents()->first();
$id = $doc->id();
$content = $doc->content();

// Accessing convenience collections
$models = $searchResult->models();
$documents = $searchResult->documents();
$highlights = $searchResult->highlights();
$aggregations = $searchResult->aggregations();
$total = $searchResult->total();

// Accessing highlight snippets
$snippets = $searchResult->highlights()->first()->snippets('title');
```
```

--------------------------------

### Highlighting

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Returns highlighted snippet fragments for matched fields. Use `highlight()` for basic highlighting and `highlightRaw()` for advanced configurations. Snippets for a specific field can be retrieved using `$hit->highlight()->snippets('field_name')`.

```php
$searchResult = Book::searchQuery($query)
    ->highlightRaw(['fields' => ['title' => ['number_of_fragments' => 3]]])
    ->execute();

$hits = $searchResult->hits();
$snippets = $hits->first()->highlight()->snippets('title');
// => ['My <em>book</em> about Laravel']

$allHighlights = $searchResult->highlights();
```

--------------------------------

### Build a Term Query with Case Insensitivity

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/term-queries.md

Enable ASCII case-insensitive matching for term queries. This allows matching terms regardless of their casing.

```php
$query = Query::term()
    ->field('price')
    ->value(300)
    ->caseInsensitive(true);

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

--------------------------------

### Retrieve Hits from Search Results

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/search-results.md

Get a collection of hits from the SearchResult. Each hit object provides detailed information including index name, score, model, document, highlights, inner hits, and explanation. A raw representation of the hit is also available.

```php
$hits = $searchResult->hits();
$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();

```

--------------------------------

### Conditional Query Building with `when()` and `unless()`

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Conditionally apply builder methods based on runtime values using `when()` and `unless()`. This allows for dynamic query construction.

```php
$searchResult = Book::searchQuery($query)
    ->when($orderBy, function ($builder, $orderBy) {
        return $builder->sort($orderBy, 'asc');
    }, function ($builder) {
        return $builder->sort('price', 'asc'); // default
    })
    ->unless($maxResults === null, function ($builder, $max) {
        return $builder->size($max);
    })
    ->execute();
```

--------------------------------

### Configure Match Phrase Prefix Query Zero Terms Query

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/full-text-queries.md

Specify `zeroTermsQuery` to define the behavior when the `analyzer` removes all tokens from the query text. Options typically include 'none' or 'all'.

```php
$query = Query::matchPhrasePrefix()
    ->field('title')
    ->query('My boo')
    ->zeroTermsQuery('none');

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

--------------------------------

### Perform Multi-Index Search with Join

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

The `join` method allows searching across multiple indices. Results from different indices are returned in a single collection. You can optionally boost results from a specific index by providing a second argument.

```php
$query = Query::bool()
    ->should(Query::match()->field('name')->query('John'))
    ->should(Query::match()->field('title')->query('The Book'))
    ->minimumShouldMatch(1);

$searchResult = Author::searchQuery($query)
    ->join(Book::class)
    ->execute();
```

```php
// every model is either Author or Book
$models = $searchResult->models();
```

```php
$searchResult = Author::searchQuery($query)
    ->join(Book::class, 2)
    ->execute();
```

--------------------------------

### Control Total Hits Tracking with trackTotalHits

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

Use `trackTotalHits` to control how the total number of hits is tracked. Pass `true` to enable tracking.

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

--------------------------------

### Build a Fuzzy Query

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/term-queries.md

Use `Query::fuzzy()` to match documents with terms similar to the search term. Configure fuzziness, maximum expansions, prefix length, rewrite strategy, and transpositions for fine-grained control.

```php
$query = Query::fuzzy()
    ->field('title')
    ->value('boko');

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

```php
$query = Query::fuzzy()
    ->field('title')
    ->value('boko')
    ->fuzziness('AUTO');

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

```php
$query = Query::fuzzy()
    ->field('title')
    ->value('boko')
    ->maxExpansions(50);

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

```php
$query = Query::fuzzy()
    ->field('title')
    ->value('boko')
    ->prefixLength(0);

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

```php
$query = Query::fuzzy()
    ->field('title')
    ->value('boko')
    ->rewrite('constant_score');

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

```php
$query = Query::fuzzy()
    ->field('title')
    ->value('boko')
    ->transpositions(true);

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

```php
$query = Query::fuzzy()
    ->field('title')
    ->value('boko');

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

--------------------------------

### Eloquent Model Configuration

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Configure your Eloquent model to use the `Searchable` trait and define methods for data transformation, eager loading, shard routing, and connection.

```php
use Elastic\ScoutDriverPlus\Searchable;
use Illuminate\Database\Eloquent\Model;

class Book extends Model
{
    use Searchable;

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

    // Eager-load relations during bulk indexing
    public function searchableWith(): array
    {
        return ['author'];
    }

    // Custom shard routing (optional)
    public function searchableRouting(): int
    {
        return $this->user_id;
    }

    // Named Elasticsearch connection (optional)
    public function searchableConnection(): ?string
    {
        return 'books';
    }
}
```

--------------------------------

### Range Query Configuration

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/term-queries.md

Explains how to build and configure range queries for searching documents with terms within a specified range.

```APIDOC
## Range Query

Builds a query to match documents containing terms within a provided range.

### General Usage

```php
$query = Query::range()
    ->field('price')
    ->gt(100);

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

### Available Methods

* [boost](#range-boost)
* [field](#range-field)
* [format](#range-format)
* [gt](#range-gt)
* [gte](#range-gte)
* [lt](#range-lt)
* [lte](#range-lte)
* [relation](#range-relation)
* [timeZone](#range-time-zone)

### boost

Decreases or increases the relevance scores of a query.

```php
$query = Query::range()
    ->field('price')
    ->gt(100)
    ->boost(2);

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

### field

Specifies the field to perform the range search on.

```php
$query = Query::range()
    ->field('price')
    ->gt(100);

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

### format

Converts date values in the query.

```php
$query = Query::range()
    ->field('updated_at')
    ->gt('2020-10-18')
    ->format('yyyy-MM-dd');

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

### gt (Greater Than)

Defines a greater than range.

```php
$query = Query::range()
    ->field('price')
    ->gt(100);

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

### gte (Greater Than or Equal To)

Defines a greater than or equal to range.

```php
$query = Query::range()
    ->field('price')
    ->gte(100);

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

### lt (Less Than)

Defines a less than range.

```php
$query = Query::range()
    ->field('price')
    ->lt(100);

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

### lte (Less Than or Equal To)

Defines a less than or equal to range.

```php
$query = Query::range()
    ->field('price')
    ->lte(100);

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

### relation

Specifies how the range query matches values for range fields. Example: 'INTERSECTS'.

```php
$query = Query::range()
    ->field('price')
    ->gt(50)
    ->lt(100)
    ->relation('INTERSECTS');

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

--------------------------------

### Access Suggestion Details

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/available-methods.md

Each suggestion object provides methods to access its text, offset, length, options, related models, and raw representation.

```php
$firstSuggestion = $titleSuggestions->first();

// the suggestion text
$text = $firstSuggestion->text();
// the start offset and the length of the suggested text
$offset = $firstSuggestion->offset();
$length = $firstSuggestion->length();
// an arbitrary number of options
$options = $firstSuggestion->options();
// related models (only some suggesters support this feature)
$models = $firstSuggestion->models();
// an array representation of the suggestion
$raw = $firstSuggestion->raw();
```

--------------------------------

### Build a Term Query with Boost

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/term-queries.md

Adjust the relevance score of a term query using the `boost` method. Higher boost values increase the relevance of matching documents.

```php
$query = Query::term()
    ->field('price')
    ->value(300)
    ->boost(2);

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

--------------------------------

### Define Runtime Fields with Painless Script

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Use `runtimeMappings` to define fields that are evaluated at query time using a Painless script. Specify the field type, script source, and parameters.

```php
$searchResult = Book::searchQuery()
    ->runtimeMappings('final_price', 'double', [
        'lang'   => 'painless',
        'source' => 'emit(doc[params.field].value * params.multiplier)',
        'params' => ['field' => 'price', 'multiplier' => 2],
    ])
    ->fields(['final_price'])
    ->execute();

$value = $searchResult->hits()->first()->raw()['fields']['final_price'];
```

--------------------------------

### Match Query with Boost

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/full-text-queries.md

Adjust the relevance scoring of `match` query results using the `boost` parameter. Higher values increase the score, making matching documents more relevant.

```php
$query = Query::match()
    ->field('title')
    ->query('My book')
    ->boost(2);

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

--------------------------------

### MultiMatch: Auto Generate Synonyms Phrase Query

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/full-text-queries.md

Set to true to automatically create match phrase queries for multi-term synonyms.

```php
$query = Query::multiMatch()
    ->fields(['title', 'description'])
    ->query('My book')
    ->autoGenerateSynonymsPhraseQuery(true);

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

--------------------------------

### Match All Query

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/full-text-queries.md

Builds a query that matches all documents in the index. Useful for retrieving all records or as a base for more complex queries.

```APIDOC
## Match All

You can use `Elastic\ScoutDriverPlus\Support\Query::matchAll()` to build a query that
[matches all documents](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-all-query.html#query-dsl-match-all-query):

```php
$query = Query::matchAll();

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

--------------------------------

### Build an Ids Query

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/blob/master/docs/term-queries.md

Use `Query::ids()` to match documents based on their specific IDs. Provide an array of IDs to search for.

```php
$query = Query::ids()->values(['1', '2', '3']);

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

--------------------------------

### Register Container Bindings in Lumen

Source: https://github.com/babenkoivan/elastic-scout-driver-plus/wiki/Lumen-Installation

Register the package's service provider and extend the Scout engine in Lumen's bootstrap/app.php file. This ensures the driver is correctly integrated into the application's service container.

```php
foreach ((new ElasticScoutDriverPlus\ServiceProvider($app))->bindings as $abstract => $concrete) {
    $app->bind($abstract, $concrete);
}

$app->extend(ElasticScoutDriver\Engine::class, function (Laravel\Scout\Engines\Engine $engine) use ($app) {
    return $app->make(ElasticScoutDriverPlus\Engine::class, compact('engine'));
});
```

--------------------------------

### suggest() / suggestRaw()

Source: https://context7.com/babenkoivan/elastic-scout-driver-plus/llms.txt

Provides search suggestions based on provided text and a field. It helps users correct typos or find related terms.

```APIDOC
## suggest() / suggestRaw()

### Description
Gets similar-looking terms based on provided text.

### Method
```php
->suggest(string $name, array $options)
```

### Parameters
- **name** (string) - The name for the suggestion query.
- **options** (array) - An array of suggestion options, including 'text' and 'term' (field and settings).

### Request Example
```php
$searchResult = Book::searchQuery(Query::matchNone())
    ->suggest('title_suggest', ['text' => 'boko', 'term' => ['field' => 'title']])
    ->execute();

$suggestions    = $searchResult->suggestions();
$titleSuggest   = $suggestions->get('title_suggest');
$firstSuggestion = $titleSuggest->first();

$text    = $firstSuggestion->text();    // 'boko'
$options = $firstSuggestion->options(); // [['text' => 'book', 'score' => 0.75, ...]]
$models  = $firstSuggestion->models();  // related Eloquent models (completion suggester)
```
```