Querying Models
This content is for v3.9. Switch to the latest version for up-to-date documentation.
Understanding how to query your models in Elasticsearch is crucial to leveraging the full potential of this package. This section covers the essentials of model querying, allowing you to fetch and interact with your data efficiently.
All
Retrieve all records for a given model:
Equivalent to get()
without clauses.
Find
As with Eloquent, you can use the find
method to retrieve a model by its primary key (_id). The method will return a single model instance or null
if no matching model is found.
Find the product with _id of IiLKG38BCOXW3U9a4zcn
and return the model collection, or null if it does not exist.
Find the product with _id of IiLKG38BCOXW3U9a4zcn
and return the model collection, or throw a ModelNotFoundException
if no result is found.
First
As with Eloquent, you can use the first
method to retrieve the first model that matches the query. The method will return a single model instance or null
if no matching model is found.
Find the first product with a status of 1 and return the model collection, or null if it does not exist.
Find the first product with a status of 1 and return the model collection, or throw a ModelNotFoundException
if no result is found.
Get
As with Eloquent, you can use the get
method to retrieve all models that match the query. The method will return a model collection or an empty collection if no matching models are found.
Find all products with a status of 1 and return the model collection, or an empty collection if it does not exist.
Where
As with Eloquent, the where
method is used to filter the query results based on the given conditions. The method accepts three parameters: the field name, an operator, and a value. The operator is optional and defaults to =
if not provided.
Find the first 10 products with a status of 1
Nested objects: Find the first 10 products with a manufacturer country of England
Find the first 10 products with a status greater than or equal to 3
Find the first 10 products with a color that is not red
See ES-specific queries for more complex queries like
Where using LIKE
Using the like
operator in your where clause works differently here than in SQL. Since Elasticsearch will match tokens, you can use a normal where
clause to search for partial matches (assuming text field with the standard analyser).
For this package, you can use the like
operator to search for partial matches within tokens. The package will automatically convert the like
operator to a wildcard query, and will search for the term in the field. For example, to search for products with a color that contains the letters bl
(blue, black, etc.), you can use the following query:
Find all products with a color that contains the letters bl
and order the results alphabetically by the color field
WhereNot
The whereNot
method is used to exclude documents that match the condition.
Find all products that do not have a status of 1, identical to where('status', '!=', 1)
AND statements
The where
method can be chained to add more conditions to the query. This will be read as AND
in the query.
Find all products that are active and have 50 or less in stock
OR Statements
The orWhere
method can be used to add an OR
condition to the query.
Find all products that are not active or have 100 or more in stock
Chaining OR/AND statements
You can chain where
and orWhere
methods to create complex queries.
Find all products that are either coffee and approved, or tea and not approved. The query reads as: Where type is coffee and is approved, or where type is tea and is not approved.
WhereIn
The whereIn
method is used to include documents that match any of the values passed in the array.
Find all products with a status of 1, 5, or 11
WhereNotIn
The whereNotIn
method is used to exclude documents that match any of the values passed in the array.
Find all products that do not have a color of red or green
WhereNull
Can be read as Where
field
does not exist
In traditional SQL databases, whereNull is commonly used to query records where a specific column’s value is NULL, indicating the absence of a value. However, in Elasticsearch, the concept of NULL applies to the absence of a field as well as the field having a value of NULL.
Therefore, in the context of the Elasticsearch implementation within Laravel, whereNull
and WhereNotNull
have been adapted to fit the common Elasticsearch requirement to query the existence or non-existence of a field as well as the null value of the field.
Find all products that do not have a color field
WhereNotNull
Can be read as Where
field
Exists
Find all products that do not have a color of red or green, and ensure that the color field exists
WhereBetween
As with Eloquent, the whereBetween
method is used to filter the query results based on the given range. The method accepts two parameters: the field name and an array containing the minimum and maximum values of the range.
Find all products with an in_stock value between 10 and 100 (including 10 and 100)
Find all products with an orders value between 1 and 20, or between 100 and 200 (including 1, 20, 100, and 200)
Grouped Queries
As with native Laravel Eloquent, where
(and alike) clauses can accept a $query
closure to group multiple queries together.
A more advanced example:
Find all products that do not have a color of lime or blue, or do not have a status of 2 and are not active, and order the results by status
Dates
Elasticsearch by default converts a date into a timestamp, and applies the strict_date_optional_time||epoch_millis
format. If you have not changed the default format for your index then acceptable values are:
- 2022-01-29
- 2022-01-29T13:05:59
- 2022-01-29T13:05:59+0:00
- 2022-01-29T12:10:30Z
- 1643500799 (timestamp)
With Carbon
You can use these values in a normal where clause, or use the built-in date clause, ie:
WhereDate()
Empty strings values
Avoid saving fields with empty strings, as Elasticsearch will treat them as a value and not as a null field. Rather, use null
or simply do not include the field when writing the document.
Good example: [object Object]
or
Bad example: [object Object]
If you need to find products without a color, the above product will not be included in the results. Further, querying for products with an empty string requires special handling since where('color', '')
will not work as expected.