Cross Fields Search Queries

The Laravel-Elasticsearch integration introduces an intuitive and powerful approach to full-text search, extending the familiar Eloquent syntax with Elasticsearch’s rich querying capabilities. This section outlines how to construct and execute search queries that span across all or selected fields within an index, leveraging various search techniques such as term queries, boosting, fuzzy searches, and regex.

---

Multi-match query

These query methods can be used for full-text search across multiple fields in your model. They work alongside the standard where()->get() methods, allowing you to search across all and execute the standard Eloquent queries. IE: get(), first(), aggregate(), paginate()

Note

• Cross field clauses start with search{Method}
• Single field clauses start with where{Method}

$results = MyModel::searchTerm('XYZ')->get();

{
    "index": "my_models",
    "body": {
        "query": {
            "multi_match": {
                "query": "XYZ",
                "type": "best_fields",
                "fields": [
                    "*"
                ]
            }
        },
        "_source": [
            "*"
        ]
    }
}

DSL

---

searchTerm()

• searchTerm($term, $fields = ['*'], $options = [])
• orSearchTerm($term, $fields = ['*'], $options = [])
• Type: best_fields

$results = Book::searchTerm('Eric')->orSearchTerm('Lean')->searchTerm('Startup')->get();

Search for books that contain ‘Eric’ or (‘Lean’ and ‘Startup’)

{
    "index": "books",
    "body": {
        "query": {
            "bool": {
                "should": [
                    {
                        "bool": {
                            "must": [
                                {
                                    "multi_match": {
                                        "query": "Eric",
                                        "type": "best_fields",
                                        "fields": [
                                            "*"
                                        ]
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "bool": {
                            "must": [
                                {
                                    "multi_match": {
                                        "query": "Lean",
                                        "type": "best_fields",
                                        "fields": [
                                            "*"
                                        ]
                                    }
                                },
                                {
                                    "multi_match": {
                                        "query": "Startup",
                                        "type": "best_fields",
                                        "fields": [
                                            "*"
                                        ]
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        "_source": [
            "*"
        ]
    }
}

DSL

---

searchTermMost()

• searchTermMost($term, $fields = ['*'], $options = [])
• orSearchTermMost($term, $fields = ['*'], $options = [])
• Type: most_fields

$results = Book::searchTermMost('quick brown fox', [ "title", "title.original", "title.shingles" ])->get();

Search for books that contain ‘quick brown fox’ in the ‘title’, ‘title.original’, or ‘title.shingles’ fields

{
    "index": "books",
    "body": {
        "query": {
            "multi_match": {
                "query": "quick brown fox",
                "type": "most_fields",
                "fields": [
                    "title",
                    "title.original",
                    "title.shingles"
                ]
            }
        },
        "_source": [
            "*"
        ]
    }
}

DSL

---

searchTermCross()

• searchTermCross($term, $fields = ['*'], $options = [])
• orSearchTermCross($term, $fields = ['*'], $options = [])
• Type: cross_fields

$results = Person::searchTermCross('Will Smith', [ 'first_name','last_name'],['operator' => 'and'])->get();

Search for people with the first name ‘Will’ and the last name ‘Smith’

{
    "index": "people",
    "body": {
        "query": {
            "multi_match": {
                "query": "Will Smith",
                "type": "cross_fields",
                "fields": [
                    "first_name",
                    "last_name"
                ],
                "operator": "and"
            }
        },
        "_source": [
            "*"
        ]
    }
}

DSL

---

searchPhrase()

• searchPhrase($phrase, $fields = ['*'], $options = [])
• orSearchPhrase($phrase, $fields = ['*'], $options = [])
• Type: phrase

Product::searchPhrase('United States')->orSearchPhrase('United Kingdom')->sum('orders');

Search for products that contain either ‘United States’ or ‘United Kingdom’ in any field, then sum the ‘orders’ field.

{
    "index": "products",
    "body": {
        "query": {
            "bool": {
                "should": [
                    {
                        "bool": {
                            "must": [
                                {
                                    "multi_match": {
                                        "query": "United States",
                                        "type": "phrase",
                                        "fields": [
                                            "*"
                                        ]
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "bool": {
                            "must": [
                                {
                                    "multi_match": {
                                        "query": "United Kingdom",
                                        "type": "phrase",
                                        "fields": [
                                            "*"
                                        ]
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        "_source": [
            "*"
        ]
    }
}

DSL

---

searchPhrasePrefix()

• searchPhrasePrefix($phrase, $fields = ['*'], $options = [])
• orSearchPhrasePrefix($phrase, $fields = ['*'], $options = [])
• Type: phrase_prefix

$results = Person::searchPhrasePrefix('loves espressos and te')->get();

Search for people who have the phrase ‘loves espressos and’ with a prefix of ‘ru’ in the next word in any field. Ex:

• ‘loves espressos and tea’
• ‘loves espressos and tennis’
• ‘loves espressos and tequila’

{
    "index": "people",
    "body": {
        "query": {
            "multi_match": {
                "query": "loves espressos and te",
                "type": "phrase_prefix",
                "fields": [
                    "*"
                ]
            }
        },
        "_source": [
            "*"
        ]
    }
}

DSL

---

searchBoolPrefix()

• searchBoolPrefix($phrase, $fields = ['*'], $options = [])
• orSearchBoolPrefix($phrase, $fields = ['*'], $options = [])
• Type: bool_prefix
• Scoring behaves like most_fields, but using a match_bool_prefix query instead of a match query.

$results = Person::searchBoolPrefix('loves espressos and te')->get();

Search for people who have the phrase ‘loves espressos and’ with a prefix of ‘ru’ in the next word in any field. Ex:

• ‘loves espressos and tea’
• ‘loves espressos and tennis’
• ‘loves espressos and tequila’

{
    "index": "people",
    "body": {
        "query": {
            "multi_match": {
                "query": "loves espressos and te",
                "type": "bool_prefix",
                "fields": [
                    "*"
                ]
            }
        },
        "_source": [
            "*"
        ]
    }
}

DSL

---

Parameter: $fields

By default, all fields will be searched through; you can specify which to search through as well as optionally boost certain fields using a caret ^:

People:searchTerm('John',['name^3','description^2','friends.name'])->get();

Search for people with the name ‘John’ in the name field, description field, and friends.name field. The name field is boosted by 3, and the description field is boosted by 2, which will affect the relevance score used for sorting.

{
    "index": "people",
    "body": {
        "query": {
            "multi_match": {
                "query": "John",
                "type": "best_fields",
                "fields": [
                    "name^3",
                    "description^2",
                    "friends.name"
                ]
            }
        },
        "_source": [
            "*"
        ]
    }
}

DSL

---

Parameter: $options

Allows you to set any options for the multi_match clause to use, ex:

• analyzer
• boost
• operator
• minimum_should_match
• fuzziness
• lenient
• prefix_length
• max_expansions
• fuzzy_rewrite
• zero_terms_query

---

withHighlights()

Highlighting allows you to display search results with the matched terms highlighted:

withHighlights($fields = [], $preTag = '<em>', $postTag = '</em>', $globalOptions = [])

The highlighted results are stored in the model’s metadata and can be accessed via a built-in model attribute using:

• $model->searchHighlights: returns on object with the found highlights for each field.
• $model->searchHighlightsAsArray: returns an associative array with the found highlights for each field.

The values of the highlights are always in an array, even if there is only one fragment.

Note

In $model->searchHighlights only the top level fields are the object keys (as is with normal model attributes). Ex: $model->searchHighlights->manufacturer['location']['country'] The array in $model->searchHighlightsAsArray is a flat associative array with the field names (in dot notation) as keys. Ex: $model->searchHighlights[manufacturer.location.country]

$highlights = [];
$products = Product::searchTerm('espresso')->withHighlights()->get();
foreach ($products as $product) {
    $highlights[$product->_id] = $product->searchHighlights;
}

Search for products containing ‘espresso’ in any field. All hits on espresso will be stored in the highlights metadata as an array under the field where the hit occurred.

Explain

You can filter the fields to highlight:

$highlights = [];
$products = Product::searchTerm('espresso')->withHighlights(['description'],'<strong>','</strong>')->get();
foreach ($products as $product) {
    $highlights[$product->_id] = $product->searchHighlights->description ?? [];
}

Search for products containing ‘espresso’ in any field. Only hits on espresso in the description field will highlighted and wrapped in strong tags. All results will be returned.

Explain

$highlightFields = [
    'name' => [
        'pre_tags'  => ['<span class="text-primary-500">'],
        'post_tags' => ['</span>'],
    ],
    'description' => [
        'pre_tags'  => ['<span class="text-secondary-500">'],
        'post_tags' => ['</span>'],
    ],
    'manufacturer.name' => [
        'pre_tags'  => ['<span class="text-sky-500">'],
        'post_tags' => ['</span>'],
    ],
];
$highlights = [];
$products = Product::searchTerm('espresso')->withHighlights($highlightFields)->get();
foreach ($products as $product) {
    $highlights[$product->_id]['name'] = $product->searchHighlights->name ?? [];
    $highlights[$product->_id]['description'] = $product->searchHighlights->description ?? [];
    $highlights[$product->_id]['manufacturer'] = $product->searchHighlights->manufacturer['name'] ?? [];
}

Search for products containing ‘espresso’ in any field. Hits on espresso in the name field will be highlighted with a primary color, hits in the description field will be highlighted with a secondary color, and any hits in the manufacturer.name field will be highlighted with a sky color.

Explain

Global options can be set for all fields:

$options = [
    'number_of_fragments' => 3,
    'fragment_size' => 150,
];
$highlights = [];
$products = Product::searchTerm('espresso')->withHighlights([],'<em>','</em>',$options)->get();
foreach ($products as $product) {
    $highlights[$product->_id] = $product->searchHighlights;
}

Search for products containing ‘espresso’ in any field. A maximum of 3 fragments will be returned for each field, with each fragment being a maximum of 150 characters long.

Explain

$model->withHighlights->field

This built in attribute will get all the model’s data, parse any user defined mutators, then overwrite any fields that have highlighted data. This is useful when you want to display the highlighted data in a view.

Note

This is not an instance of the model, so you cannot call any model methods on it (like save, update, etc). This is intentional to avoid accidentally saving the highlighted data to the database.

Note

For multiple fragments, the values are concatenated with .....

@foreach ($products as $product)
    <tr>
        <td>{!! $product->withHighlights->name !!}</td>
        <td>{!! $product->withHighlights->description !!}</td>
    </tr>
@endforeach

searchFor()

• searchFor($termOrPhrase, $fields = ['*'], $options = [])
• Convenience method that will either use searchTerm or searchPhrase depending on the word count of $value

Helper: asFuzzy()

• Will mark the previous clause as fuzzy

Product::searchTerm('remarkble')->asFuzzy()->searchTerm('excellnt')->withHighlights()->get();

Search for products containing ‘remarkable’ with fuzzy matching, but not ‘excellent’ since is was not followed by asFuzzy()

DSL

Helper: setMinShouldMatch()

• will set the option {"minimum_should_match": $value} to the previous clause only

Helper: setBoost()

• will set the option {"boost": $value} to the previous clause only

---

(DEPRECATED) Legacy Search Query

Caution

The legacy search query methods are still available for backwards compatibility. We recommend using the new Multi Match Query methods for new projects as these will be completely removed in V5+

Unlike the traditional where()->get() method which operates on specific fields, the search method is designed to perform a full-text search across multiple fields, offering a broader search scope.

$results = MyModel::term('XYZ')->search();

Note

The search query can only execute on the search() method, and not on get(), first(), paginate(), etc.

---

Term Search: term()

To search for a single term across all fields in an index:

$results = Book::term('Eric')->search();

Search for ‘Eric’ across all fields

Explain

---

Multiple Terms

Combining terms with logical operators (AND/OR):

$results = Book::term('Eric')->orTerm('Lean')->andTerm('Startup')->search();

Search for books that contain ‘Eric’ or both ‘Lean’ and ‘Startup’

Explain

---

Phrase Search: phrase()

A phrase is a sequence of words that must appear in the same order as the search query. This is useful for finding exact matches or specific sequences of words.

To search for a phrase across all fields in an index:

$results = Book::phrase('Lean Startup')->search();

Search for the phrase ‘Lean Startup’ across all fields

Explain

---

Multiple Phrases

Combining phrases with logical operators (AND/OR):

orPhrase($phrase): Searches for documents containing either the original phrase or the specified phrase.

$results = Book::phrase('United States')->orPhrase('United Kingdom')->search();

Search for books that contain either ‘United States’ or ‘United Kingdom’, phrases like ‘United Emirates’ will not be included.

Explain

andPhrase($phrase): Searches for documents containing both the original phrase and the specified phrase.

$results = Book::phrase('Lean Startup')->andPhrase('Eric Ries')->search();

Search for books that contain both ‘Lean Startup’ and ‘Eric Ries’

Explain

---

Boosting Terms

Boosting enhances the relevance score of certain terms:

$results = Book::term('Eric', 2)->orTerm('Lean Startup')->search();

‘Eric’ is boosted, making it more significant in the search results. The term Lean AND Startup are searched for independently (Not the phrase ‘Lean Startup’).

Explain

---

Searching Selected Fields

Limiting the search to specific fields:

$results = Book::term('Eric')->fields(['title', 'author', 'description'])->search();

Search only within the ‘title’, ‘author’, and ‘description’ fields

Explain

---

Minimum Should Match

Configures the minimum amount of terms that are required to match

$results = Book::term('Eric')->orTerm('Lean')->orTerm('Startup')->field('title')->field('author')->minShouldMatch(2)->search();

Requires at least 2 of the 3 terms to match in the specified fields

Explain

---

Minimum Score

Sets a minimum relevance score for results:

$results = Book::term('Eric')->field('title', 3)->field('author', 2)->field('description')->minScore(2.1)->search();

Only includes results with a score higher than 2.1

Explain

---

Combining Search with Eloquent Queries

Search queries can be blended with standard Eloquent queries:

$results = Book::term('David')->field('title', 3)->field('author', 2)->field('description')->minScore(2.1)->where('is_active', true)->search();

Combines a full-text search with a filter on the ‘is_active’ field

Explain

---

Fuzzy Searches

Fuzzy searches allow for matching terms that are similar to the search term:

$results = Book::fuzzyTerm('quikc')->orFuzzyTerm('brwn')->andFuzzyTerm('foks')->search();

Performs a fuzzy search to account for minor typos or variations

Explain

---

Regular Expressions

Leverage Elasticsearch’s support for regex in your searches:

// Uses regex patterns to match documents
$results = Book::regEx('joh?n(ath[oa]n)')->andRegEx('doey*')->search();

---

Highlighting

Highlighting allows you to display search results with the matched terms highlighted:

highlight($fields = [], $preTag = '<em>', $postTag = '</em>', $globalOptions = [])

The highlighted results are stored in the model’s metadata and can be accessed via a built-in model attribute using:

• $model->searchHighlights: returns on object with the found highlights for each field.
• $model->searchHighlightsAsArray: returns an associative array with the found highlights for each field.

The values of the highlights are always in an array, even if there is only one fragment.

Note

In $model->searchHighlights only the top level fields are the object keys (as is with normal model attributes). Ex: $model->searchHighlights->manufacturer['location']['country'] The array in $model->searchHighlightsAsArray is a flat associative array with the field names (in dot notation) as keys. Ex: $model->searchHighlights[manufacturer.location.country]

$highlights = [];
$products = Product::term('espresso')->highlight()->search();
foreach ($products as $product) {
    $highlights[$product->_id] = $product->searchHighlights;
}

Search for products containing ‘espresso’ in any field. All hits on espresso will be stored in the highlights metadata as an array under the field where the hit occurred.

Explain

You can filter the fields to highlight:

$highlights = [];
$products = Product::term('espresso')->highlight(['description'],'<strong>','</strong>')->search();
foreach ($products as $product) {
    $highlights[$product->_id] = $product->searchHighlights->description ?? [];
}

Search for products containing ‘espresso’ in any field. Only hits on espresso in the description field will highlighted and wrapped in strong tags. All results will be returned.

Explain

$highlightFields = [
    'name' => [
        'pre_tags'  => ['<span class="text-primary-500">'],
        'post_tags' => ['</span>'],
    ],
    'description' => [
        'pre_tags'  => ['<span class="text-secondary-500">'],
        'post_tags' => ['</span>'],
    ],
    'manufacturer.name' => [
        'pre_tags'  => ['<span class="text-sky-500">'],
        'post_tags' => ['</span>'],
    ],
];
$highlights = [];
$products = Product::term('espresso')->highlight($highlightFields)->search();
foreach ($products as $product) {
    $highlights[$product->_id]['name'] = $product->searchHighlights->name ?? [];
    $highlights[$product->_id]['description'] = $product->searchHighlights->description ?? [];
    $highlights[$product->_id]['manufacturer'] = $product->searchHighlights->manufacturer['name'] ?? [];
}

Search for products containing ‘espresso’ in any field. Hits on espresso in the name field will be highlighted with a primary color, hits in the description field will be highlighted with a secondary color, and any hits in the manufacturer.name field will be highlighted with a sky color.

Explain

Global options can be set for all fields:

$options = [
    'number_of_fragments' => 3,
    'fragment_size' => 150,
];
$highlights = [];
$products = Product::term('espresso')->highlight([],'<em>','</em>',$options)->search();
foreach ($products as $product) {
    $highlights[$product->_id] = $product->searchHighlights;
}

Search for products containing ‘espresso’ in any field. A maximum of 3 fragments will be returned for each field, with each fragment being a maximum of 150 characters long.

Explain

$model->withHighlights->field

This built in attribute will get all the model’s data, parse any user defined mutators, then overwrite any fields that have highlighted data. This is useful when you want to display the highlighted data in a view.

Note

This is not an instance of the model, so you cannot call any model methods on it (like save, update, etc). This is intentional to avoid accidentally saving the highlighted data to the database.

Note

For multiple fragments, the values are concatenated with .....

@foreach ($products as $product)
    <tr>
        <td>{!! $product->withHighlights->name !!}</td>
        <td>{!! $product->withHighlights->description !!}</td>
    </tr>
@endforeach

---