Cross Fields Search Queries

Cross fields search queries tap into Elasticsearch’s text analysis features, allowing for sophisticated searches across text fields.

---

Multi-match query

These methods enable full-text search across all (or some) fields and integrate seamlessly with standard Eloquent methods like get(), first(), aggregate(), and paginate().

Note

• search{Method} → across all fields/full-text queries
• where{Method} → single-field queries

MyModel::searchTerm('XYZ')->get();

{
    "index": "my_models",
    "body": {
        "query": {
            "multi_match": {
                "query": "XYZ",
                "type": "best_fields"
            }
        },
        "size": 1000
    }
}

DSL

---

Search Term

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

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"
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "bool": {
                            "must": [
                                {
                                    "multi_match": {
                                        "query": "Lean",
                                        "type": "best_fields"
                                    }
                                },
                                {
                                    "multi_match": {
                                        "query": "Startup",
                                        "type": "best_fields"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        "size": 1000
    }
}

DSL

---

Search Term Most

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

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"
                ]
            }
        },
        "size": 1000
    }
}

DSL

---

Search Term Cross

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

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",
                "operator": "and",
                "type": "cross_fields",
                "fields": [
                    "first_name",
                    "last_name"
                ]
            }
        },
        "size": 1000
    }
}

DSL

---

Search Phrase

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

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

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"
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "bool": {
                            "must": [
                                {
                                    "multi_match": {
                                        "query": "United Kingdom",
                                        "type": "phrase"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        "size": 1000
    }
}

DSL

---

Search Phrase Prefix

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

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"
            }
        },
        "size": 1000
    }
}

DSL

---

Search Bool Prefix

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

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": "products",
    "body": {
        "query": {
            "multi_match": {
                "query": "loves espressos and te",
                "type": "bool_prefix"
            }
        },
        "size": 1000
    }
}

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": "products",
    "body": {
        "query": {
            "multi_match": {
                "query": "John",
                "type": "best_fields",
                "fields": [
                    "name^3",
                    "description^2",
                    "friends.name"
                ]
            }
        },
        "size": 1000
    }
}

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

use PDPhilip\Elasticsearch\Query\Options\SearchOptions;

Product::searchTerm('espreso tme', function (SearchOptions $options) {
    $options->type('most_fields');
    $options->searchFuzzy();
    $options->analyzer('my_custom_analyzer');
    $options->boost(2);
    $options->operator('OR');
    $options->minimumShouldMatch(2);
    $options->autoGenerateSynonymsPhraseQuery(true);
    $options->fuzzyTranspositions(true);
    $options->fuzzyRewrite('constant_score');
    $options->lenient(true);
    $options->zeroTermsQuery('all');
    $options->constantScore(true);
})->get();

{
    "index": "products",
    "body": {
        "query": {
            "constant_score": {
                "filter": {
                    "multi_match": {
                        "query": "espreso tme",
                        "type": "best_fields",
                        "fuzziness": "AUTO",
                        "analyzer": "my_custom_analyzer",
                        "boost": 2,
                        "operator": "OR",
                        "minimum_should_match": 2,
                        "auto_generate_synonyms_phrase_query": true,
                        "fuzzy_transpositions": true,
                        "fuzzy_rewrite": "constant_score",
                        "lenient": true,
                        "zero_terms_query": "all"
                    }
                }
            }
        },
        "size": 1000
    }
}

DSL

---

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::searchTerm('espresso')->highlight()->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.

{
    "index": "products",
    "body": {
        "query": {
            "multi_match": {
                "query": "and",
                "type": "best_fields"
            }
        },
        "highlight": {
            "pre_tags": "<em>",
            "post_tags": "</em>"
        },
        "size": 1000
    }
}

DSL

You can filter the fields to highlight:

$highlights = [];
$products = Product::searchTerm('espresso')->highlight(['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.

{
    "index": "products",
    "body": {
        "query": {
            "multi_match": {
                "query": "espresso",
                "type": "best_fields"
            }
        },
        "highlight": {
            "fields": [
                {
                    "description": {}
                }
            ],
            "pre_tags": "<strong>",
            "post_tags": "</strong>"
        },
        "size": 1000
    }
}

DSL

$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')->highlight($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.

{
    "index": "products",
    "body": {
        "query": {
            "multi_match": {
                "query": "espresso",
                "type": "best_fields"
            }
        },
        "highlight": {
            "fields": [
                {
                    "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>"
                        ]
                    }
                }
            ],
            "pre_tags": "<em>",
            "post_tags": "</em>"
        },
        "size": 1000
    }
}

DSL

Global options can be set for all fields:

$options = [
    'number_of_fragments' => 3,
    'fragment_size' => 150,
];
$highlights = [];
$products = Product::searchTerm('espresso')->highlight([],'<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.

{
    "index": "products",
    "body": {
        "query": {
            "multi_match": {
                "query": "espresso",
                "type": "best_fields"
            }
        },
        "highlight": {
            "number_of_fragments": 3,
            "fragment_size": 150,
            "pre_tags": "<em>",
            "post_tags": "</em>"
        },
        "size": 1000
    }
}

DSL

$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