Skip to content
Laravel-Elasticsearch

Ordering and Pagination

In the Laravel-Elasticsearch integration, ordering and pagination are essential features that enable developers to manage and present data effectively. These features are designed to work seamlessly within the Laravel ecosystem, providing a familiar experience to those accustomed to Eloquent ORM

Ordering

Elasticsearch inherently ranks search results based on relevance (using internal scoring and ranking algorithms). However, it is often necessary to sort results based on specific fields. The Laravel-Elasticsearch integration provides a simple and intuitive way to sort search results using the orderBy and orderByDesc methods.

OrderBy

The orderBy method allows you to specify the field by which the results should be sorted and the direction of the sort (ascending or descending). This method is straightforward and aligns with the Laravel Eloquent’s orderBy functionality.

$products = Product::orderBy('status')->get();
 
$products = Product::orderBy('created_at', 'desc')->get();

If you have a field that is mapped as a text field with a keyword subfield, you will need to sort on the keyword subfield:

$products = Product::orderBy('name.keyword')->get();

OrderByDesc

As with Laravel’s standard eloquent, the orderByDesc method is provided to quickly sort results in descending order by a specified field, without needing to explicitly set the direction.

$products = Product::orderByDesc('created_at')->get();

Offset & Limit (skip & take)

As with Eloquent, you can use the skip and take methods in your query.

$products = Product::skip(10)->take(5)->get();

Extending ordering for Elasticsearch features

WithSort

The withSort method allows you to extend the ordering functionality to support more advanced Elasticsearch sorting features.

withSort($field, $type, $value)

Types

  • mode - Specify how Elasticsearch should handle sorting by array or multi-valued fields.
    • Options: min, max, sum, avg, median
  • missing - Specify how Elasticsearch should handle sorting when a document is missing the field being sorted.
    • Options: _first, _last, or a custom value
  • unmapped_type - By default, the search request will fail if there is no mapping associated with a field - The unmapped_type option allows you to ignore fields that have no mapping and not sort by them.
  • ignore_unmapped - Ignore documents with unmapped fields when sorting.
$products = Product::where('is_active', true)->orderBy('price_history', 'desc')->withSort('price_history', 'mode', 'avg')->get();
$products = Product::orderBy('color.keyword', 'desc')->withSort('color.keyword', 'missing', '_first')->get();
$products = Product::orderByDesc('price')->withSort('price', 'unmapped_type', 'long')->get();
$products = Product::orderByDesc('price')->withSort('price', 'ignore_unmapped', true')->get();

Pagination

Pagination works as expected in this Laravel-Elasticsearch integration.

$products = Product::where('is_active',true)
$products = $products->paginate(50)

Pagination links (Blade)

{{ $products->appends(request()->query())->links() }}

OrderBy Geo Distance

The orderByGeo method is a specialized method for sorting by geo distance. This sorting method only works with geo fields and can be used to sort results based on their distance from a specified point.

Parameter scope:

  • orderByGeo(string $column, array $pin, $direction = 'asc', $unit = 'km', $mode = null, $type = 'arc')
  • orderByGeoDesc(string $column, array $pin, $unit = 'km', $mode = null, $type = 'arc')

$pin

The point(s) from which to calculate the distance. This can be a single point or an array of points.

  • A point is an array with two values: [lon, lat] (longitude, latitude) - Order matters and Elasticsearch does not use the standard [lat, lon] format
  • For multiple points, use an array of points: [[lon1, lat1], [lon2, lat2], ...]
  • You can also specify the lat and lon keys: ['lat' => 51.50853, 'lon' => -0.12574]

$direction

  • The direction in which to sort the results. Options: asc, desc
  • asc sorts by shortest distance from the pin
  • desc sorts by longest distance from the pin

$unit

The unit to use when computing sort values. Options: m, km, mi, yd, ft

$mode

  • Used for when a field has several geo points. By default, the shortest distance is used when sorting in ascending order and the longest distance when sorting in descending order.
  • Options: min, max, sum, avg, median

$type

  • The type of distance calculation to use.
  • Options: arc, plane
  • Note: plane is faster, but inaccurate on long distances and close to the poles.
// Lat:51.50853 & Lon:-0.12574 (London)
return Product::where('is_active',true)->orderByGeo('manufacturer.location', [-0.12574, 51.50853])->get();
// OR
return Product::where('is_active',true)->orderByGeo('manufacturer.location', ['lat' => 51.50853, 'lon' => -0.12574])->get();
 
// Lat:48.85341 & Lon:2.3488 (Paris)
// Lat:51.50853 & Lon:-0.12574 (London)
return Product::where('is_active',true)->orderByGeo('manufacturer.location', [[2.3488, 48.85341], [-0.12574, 51.50853]], 'desc', 'km', 'avg', 'plane')->get();
//Or
return Product::where('is_active',true)->orderByGeo('manufacturer.location', [['lat' => 48.85341, 'lon' => 2.3488], ['lat' => 51.50853, 'lon' => -0.12574]], 'desc', 'km', 'avg', 'plane')->get();

Order By Nested

The orderByNested method allows you to order the results of a query by a nested field.

return BlogPost::where('status', 5)->orderByNested('comments.likes', 'desc', 'sum')->limit(5)->get();

Order By Random

orderByRandom(string $column, int $seed = 1)

Uses Elasticsearch’s random_score to randomise ordering

Product::where('color', 'silver')->orderByRandom('created_at', rand(1, 1000))->limit(5)->get();