Elasticsearch Specific Queries

Elasticsearch offers a rich set of query capabilities, including geospatial queries and regex-based searches, which go beyond the traditional query types found in SQL databases. The Laravel-Elasticsearch integration provides a seamless interface to leverage these powerful features directly within your Laravel models.

---

Where Match NEW

This method allows you to query for matches within a field. This is useful when you need to search for a specific value within a text field.

Person::whereMatch('description', 'John Smith')->get();

{
    "index": "people",
    "body": {
        "query": {
            "match": {
                "description": {
                    "query": "John Smith",
                    "operator": "and"
                }
            }
        },
        "size": 1000
    }
}

DSL

Where Match options

use PDPhilip\Elasticsearch\Query\Options\MatchOptions;

Person::whereMatch('description', 'Jhn Smth', function (MatchOptions $options) {
    $options->operator('or');
    $options->analyzer('my_custom_analyzer');
    $options->asFuzzy();
})->get();

{
    "index": "products",
    "body": {
        "query": {
            "match": {
                "description": {
                    "query": "Jhn Smth",
                    "operator": "or",
                    "analyzer": "my_custom_analyzer",
                    "fuzziness": "AUTO"
                }
            }
        },
        "size": 1000
    }
}

DSL

---

Where Term

This method allows you to query for exact case-sensitive matches within a field. This is useful when you need to find a specific value.

Make sure the field is mapped as a keyword or uses .keyword subfield. Otherwise, term queries will fail.

Person::whereTerm('name', 'John Smith')->get();
//Or
Person::whereExact('name', 'John Smith')->get(); //Alias

This will only return the documents where the name field is exactly ‘John Smith’. ‘john smith’ or ‘John’ will not be returned.

{
    "index": "people",
    "body": {
        "query": {
            "term": {
                "name.keyword": {
                    "value": "John Smith"
                }
            }
        },
        "size": 1000
    }
}

DSL

Where Term options

use PDPhilip\Elasticsearch\Query\Options\TermOptions;

Person::whereTerm('name', 'John Smith',function (TermOptions $options) {
    $options->asCaseInsensitive();
})->get();

{
    "index": "people",
    "body": {
        "query": {
            "term": {
                "name.keyword": {
                    "value": "John Smith",
                    "case_insensitive": true
                }
            }
        },
        "size": 1000
    }
}

DSL

---

Where Prefix

This method allows you to query for exact case-sensitive values that start with the given value within a field.

Make sure the field is mapped as a keyword or uses .keyword subfield. Otherwise, term queries will fail.

Person::wherePrefix('name', 'John Sm')->get();
//Or
Person::whereStartsWith('name', 'John Sm')->get(); //Alias

{
    "index": "people",
    "body": {
        "query": {
            "prefix": {
                "name.keyword": {
                    "value": "John Sm"
                }
            }
        },
        "size": 1000
    }
}

DSL

Where Phrase

This method allows you to query for exact phrases within a field. This is useful when you need to search for a specific sequence of words within a text field.

Under the hood, this method uses the match_phrase query from Elasticsearch’s Query DSL.

Person::wherePhrase('description', 'loves espressos')->get();

This will only return the documents where the description field contains the exact phrase ‘loves espressos’. Individual tokens like ‘loves’ or ‘espressos’ will not be returned in isolation.

{
    "index": "people",
    "body": {
        "query": {
            "match_phrase": {
                "description": {
                    "query": "loves espressos"
                }
            }
        },
        "size": 1000
    }
}

DSL

Where Phrase Options

use PDPhilip\Elasticsearch\Query\Options\PhraseOptions;

Person::wherePhrase('description', 'loves espressos',function (PhraseOptions $options) {
    $options->analyzer('english');
    $options->slop(1);
})->get();

This will only return the documents where the description field contains the exact phrase ‘loves espressos’. Individual tokens like ‘loves’ or ‘espressos’ will not be returned in isolation.

{
    "index": "people",
    "body": {
        "query": {
            "match_phrase": {
                "description": {
                    "query": "loves espressos",
                    "analyzer": "english",
                    "slop": 1
                }
            }
        },
        "size": 1000
    }
}

DSL

---

Where Phrase Prefix

Similar to wherePhrasePrefix, this method allows you to query for exact phrases where the last word starts with a particular prefix.

Under the hood, this method uses the match_phrase_prefix query from Elasticsearch’s Query DSL.

Person::wherePhrasePrefix('description', 'loves es')->get();

This will only return the documents where the description field contains the phrase ‘loves es…’. Ex: ‘loves espresso’, ‘loves essays’ and ‘loves eskimos’ etc

{
    "index": "people",
    "body": {
        "query": {
            "match_phrase_prefix": {
                "description": {
                    "query": "loves es"
                }
            }
        },
        "size": 1000
    }
}

DSL

Where Phrase Prefix Options

use PDPhilip\Elasticsearch\Query\Options\PhrasePrefixOptions;

Person::wherePhrasePrefix('description', 'loves es',function (PhrasePrefixOptions $options) {
    $options->analyzer('my_custom_analyzer');
    $options->maxExpansions(75);
    $options->slop(1);
})->get();

{
    "index": "people",
    "body": {
        "query": {
            "match_phrase_prefix": {
                "description": {
                    "query": "loves es",
                    "analyzer": "my_custom_analyzer",
                    "max_expansions": 75,
                    "slop": 1
                }
            }
        },
        "size": 1000
    }
}

DSL

---

Where Regex

The WhereRegex method allows you to query for documents based on a regular expression pattern within a field.

$regex1 = Product::whereRegex('color', 'bl(ue)?(ack)?')->get();
$regex2 = Product::whereRegex('color', 'bl...*')->get();

The first example will return documents where the color field matches the pattern ‘bl(ue)?(ack)?’, which means it can be ‘blue’ or ‘black’. The second example will return documents where the color field matches the pattern ‘bl…*’, which means it starts with ‘bl’ and has at least three more characters. Both should return Blue or Black from the colors field.

{
    "index": "products",
    "body": {
        "query": {
            "regexp": {
                "color.keyword": {
                    "value": "bl(ue)?(ack)?"
                }
            }
        },
        "size": 1000
    }
}
{
    "index": "products",
    "body": {
        "query": {
            "regexp": {
                "color.keyword": {
                    "value": "bl...*"
                }
            }
        },
        "size": 1000
    }
}

DSL

Where Regex Options

use PDPhilip\Elasticsearch\Query\Options\RegexOptions;

Product::whereRegex('color', 'bl(ue)?(ack)?', function (RegexOptions $options) {
    $options->flags('ALL');
    $options->caseInsensitive(true);
    $options->maxDeterminizedStates(20000);
})->get();

{
    "index": "products",
    "body": {
        "query": {
            "regexp": {
                "color.keyword": {
                    "value": "bl(ue)?(ack)?",
                    "flags": "ALL",
                    "case_insensitive": true,
                    "max_determinized_states": 20000
                }
            }
        },
        "size": 1000
    }
}

DSL

---

Where Fuzzy NEW

The whereFuzzy method allows you to query for documents based on a fuzzy search within a field. This is useful when you need to search for approximate matches to a given value.

whereFuzzy is a term-level query.

Product::whereFuzzy('description', 'qick brwn fx')->get();

{
    "index": "products",
    "body": {
        "query": {
            "fuzzy": {
                "description": {
                    "value": "qick brwn fx"
                }
            }
        },
        "size": 1000
    }
}

DSL

Where Fuzzy Options

use PDPhilip\Elasticsearch\Query\Options\FuzzyOptions;

Product::whereFuzzy('description', 'qick brwn fx',function (FuzzyOptions $options) {
    $options->fuzziness('AUTO');
    $options->maxExpansions(50);
    $s>prefixLength(0);
    $options->transpositions(true);
    $options->rewrite('constant_score_blended');
})->get();

{
    "index": "products",
    "body": {
        "query": {
            "fuzzy": {
                "description": {
                    "value": "qick brwn fx",
                    "fuzziness": "AUTO",
                    "max_expansions": 50,
                    "prefix_length": 0,
                    "transpositions": true,
                    "rewrite": "constant_score_blended"
                }
            }
        },
        "size": 1000
    }
}

DSL

Where Geo Distance

The whereGeoDistance method filters results based on their proximity to a given point, specified by latitude and longitude, within a certain radius.

Method Signature

/**
 * Filter results based on a geo-point field within a defined box on a map.
 *
 * @param string $field
 * @param string $distance [numeric value + distance unit (e.g., km, mi)]
 * @param array $point [latitude, longitude]
 * @param string $distanceType arc|plane
 * @param string $validationMethod STRICT|IGNORE_MALFORMED|COERCE
 * @return $this
*/
whereGeoDistance($column, string $distance, array $location, $distanceType = 'arc', $validationMethod = 'STRICT')
orWhereGeoDistance($column, string $distance, array $location, $distanceType = 'arc', $validationMethod = 'STRICT')
whereNotGeoDistance($column, string $distance, array $location, $distanceType = 'arc', $validationMethod = 'STRICT')
orWhereNotGeoDistance($column, string $distance, array $location, $distanceType = 'arc', $validationMethod = 'STRICT')

// Specify the central point and radius
$point = [
    'lat' => 51.509865,
    'lon' => -0.118092,
]; //or:
$point = [51.509865, -0.118092]; // [latitude, longitude]
$distance = '20km';

// Retrieve UserLogs with Status 7 where 'agent.geo' is within 20km of center of London
UserLog::where('status', 7)->whereGeoDistance('agent.geo', $distance, $point)->get();

{
    "index": "user_logs",
    "body": {
        "query": {
            "bool": {
                "must": [
                    {
                        "term": {
                            "status": {
                                "value": 7
                            }
                        }
                    },
                    {
                        "geo_distance": {
                            "agent.geo": [
                                51.509865,
                                -0.118092
                            ],
                            "distance": "20km"
                        }
                    }
                ]
            }
        },
        "size": 1000
    }
}

DSL

The $distance parameter is a string combining a numeric value and a distance unit (e.g., km for kilometers, mi for miles). Refer to the Elasticsearch documentation on distance units for more information.

---

Where Geo Box

The whereGeoBox method allows you to retrieve documents based on geospatial data, specifically targeting documents where a geo-point field falls within a defined “box” on a map. This is particularly useful for applications requiring location-based filtering, such as finding all events within a specific geographical area.

Method Signature

/**
 * Filter results based on a geo-point field within a defined box on a map.
 *
 * @param string $field
 * @param array $topLeft [latitude, longitude]
 * @param array $bottomRight [latitude, longitude]
 * @param string $validationMethod STRICT|IGNORE_MALFORMED|COERCE
 * @return $this
*/
whereGeoBox(string $field, array $topLeft, array $bottomRight, $validationMethod = 'STRICT')
orWhereGeoBox(string $field, array $topLeft, array $bottomRight, $validationMethod = 'STRICT')
whereNotGeoBox(string $field, array $topLeft, array $bottomRight, $validationMethod = 'STRICT')
orWhereNotGeoBox(string $field, array $topLeft, array $bottomRight, $validationMethod = 'STRICT')

// Define the top-left and bottom-right coordinates of the box
$topLeft = [-10, 10]; // [latitude, longitude]
$bottomRight = [10, -10]; // [latitude, longitude]

// Retrieve UserLogs where 'agent.geo' falls within the defined box
UserLog::where('status', 7)->whereGeoBox('agent.geo', $topLeft, $bottomRight)->get();

{
    "index": "user_logs",
    "body": {
        "query": {
            "bool": {
                "must": [
                    {
                        "term": {
                            "status": {
                                "value": 7
                            }
                        }
                    },
                    {
                        "geo_bounding_box": {
                            "agent.geo": {
                                "top_left": [
                                    -180,
                                    90
                                ],
                                "bottom_right": [
                                    180,
                                    -90
                                ]
                            }
                        }
                    }
                ]
            }
        },
        "size": 1000
    }
}

DSL

Note

The field must be of type geo_point for both whereGeoDistance and whereGeoBox methods otherwise your shards will fail, make sure to set the geo field in your migration, ex:

Schema::create('user_logs',function (IndexBlueprint $index){
    $index->geoPoint('agent.geo');
});

For more details, see Migrations

---

Where Script NEW

Filter documents based on custom scripts.

$script = "doc['orders'].size() > 0 && doc['orders'].value >= 29";
$options = ['params' => ['value' => 29]];
Product::whereScript($script, $options)->get();

{
    "index": "products",
    "body": {
        "query": {
            "script": {
                "script": {
                    "source": "doc['orders'].size() > 0 && doc['orders'].value >= 29",
                    "params": {
                        "value": 29
                    }
                }
            }
        },
        "size": 1000
    }
}

DSL

Where Timestamp

This method allows you to query for timestamps on a known field and will sanitize the input to ensure it is a valid timestamp for both seconds and milliseconds.

Product::whereTimestamp('last_viewed', '<=', 1713911889521)->get();

This will only return the documents where the last_viewed field is less than or equal to the timestamp 1713911889521 ms.

{
    "index": "products",
    "body": {
        "query": {
            "range": {
                "last_viewed": {
                    "lte": 1713911889521
                }
            }
        },
        "size": 1000
    }
}

DSL

---

RAW DSL Queries

For scenarios where you need the utmost flexibility and control over your Elasticsearch queries, the Laravel-Elasticsearch integration provides the capability to directly use Elasticsearch’s Query DSL (Domain Specific Language). The results will still be returned as collections of Eloquent models.

$bodyParams = [
  'query' => [
    'match' => [
      'color' => 'silver',
    ],
  ],
];

Product::rawSearch($bodyParams, $optionsParams = []); //Will search within the products index

Product::rawDsl($dsl); //Will use the given $dsl as is and return the raw response from Elasticsearch

The DSL example above uses the match query to search for products with the color ‘silver’

Explain

---

RAW Aggregation Queries

Similar to raw search queries, you can also execute raw aggregation queries using Elasticsearch’s Aggregation DSL. This allows you to perform complex aggregations on your data and retrieve the results in a structured format.

$body = [
    'aggs' => [
        'price_ranges' => [
            'range' => [
                'field'  => 'price',
                'ranges' => [
                    ['to' => 100],
                    ['from' => 100, 'to' => 500],
                    ['from' => 500, 'to' => 1000],
                    ['from' => 1000],
                ],

            ],
            'aggs'  => [
                'sales_over_time' => [
                    'date_histogram' => [
                        'field'          => 'datetime',
                        'fixed_interval' => '1d',
                    ],

                ],
            ],
        ],
    ],
];
return Product::rawAggregation($body);

The aggregation example above uses the range aggregation to group products into price ranges and the date_histogram aggregation to group sales over time within each price range.

Explain

---

To DSL

This method returns the parsed DSL query from the query builder. This can be useful when you need to inspect the raw query being generated by the query builder.

$query = Product::where('price', '>', 100)->toDsl();

This will return the raw DSL query generated by the query builder instance.

Explain

Note

toDsl() and the inherited toSQL() are the same method. You can use them interchangeably.

---