Skip to content

Sort

Sorting helps you order the results in the API response. Here are the details on how to use sorting in Gainly API.

Most API requests that return multiple results accept the sort parameter. This parameter accepts an array of JSON objects specifying the sorting criteria for the results.

You can sort the results using one or more of the supported fields.

Set the order parameter to:

  • asc - Sort in ascending order
  • desc - Sort in descending order

Single criterion

"sort": [
  {
      "metadata.price": {     // field to sort by
          "order": "asc"      // order of sorting
      }
  }
]

Results will be sorted in ascending order of metadata.price.

Multiple criteria

You can specify multiple sorting criteria:

"sort": [
    {
        "metadata.price": {
            "order": "asc"
        }
    },
    {
        "metadata.released_on": {
            "order": "desc"
        }
    }
]

Results will be sorted in ascending order of metadata.price. If there are multiple results with the same value for metadata.price, those will then be sorted in descending order of metadata.released_on.

Supported fields for sorting

You can use the following fields for sorting:

  • metadata subfields of supported field types. Specify using dot notation, for example:
    • metadata.price
    • metadata.sale.sale_end_date
  • created_at
  • updated_at
  • _score
    • Refers to the relevance score assigned by the search engine to each result.
    • This can be used to sort only in the Search Documents endpoint.

Supported metadata field types

You can use the following metadata field types in your sorting criteria:

  • date
  • float
  • integer
  • keyword
  • boolean
  • Arrays of the field types listed above.

In addition, you can also use geo_point fields to sort by geo distance.

Using "mode" for array fields

When sorting by an array field, use the mode parameter to specify what array value to use for sorting.

1
2
3
4
5
6
7
8
"sort": [
  {
      "metadata.sizes": {
          "order": "desc",
          "mode": "max"
      }
  }
]
Array field types mode values
float, integer avg, max, median, min, sum
keyword max, min

Missing values

Use the missing parameter to specify how to handle missing values. The allowed values are:

  • _last - List documents with missing value last. This is the default.
  • _first - List documents with missing value first.
1
2
3
4
5
6
7
8
"sort": [
  {
      "created_at": {
          "order": "asc",
          "missing": "_first"
      }
  }
]

Results will be sorted in ascending order of created_at, and results with a missing value for created_at will be listed first.

Sort by geo-distance

If you have a geo_point field in your metadata, you can filter by geo-distance.

To ensure that these filtered results are sorted by distance from the specified point, use the sort parameter as shown below:

"sort": [
  {
    "_geo_distance": {
      "metadata.store_location_geo_point": {  // geo-point field in your documents
        "lat": 45.77,   // latitude of the specified point
        "lon": -110.91  // longitude of the specified point
      },
      "order": "asc",   // nearest first
      "unit": "mi"      // unit in which distance of each result will be returned
    }
  }
]

sort_value parameter of each document in the API response will contain the distance (in the unit specified in the unit parameter shown above) from the specified point:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "id": "doc-bd7696ed-a5af-4957-aa07-aad58510648d",
  "title": "My Store Location #10",
  "metadata": {
      "store_location_geo_point": {
          "lon": -111.04,
          "lat": 45.67
      }
  },
  "tenant_id": "tenant223",
  "language": "en",
  "sort_value": [
      9.3308485146159
  ],
  "created_at": "2024-09-19T06:15:32.973074Z",
  "updated_at": "2024-09-19T06:15:32.973079Z"
}

Supported values for the unit parameter (default is m):

  • mi (miles)
  • nmi (nautical miles)
  • km (kilometers)
  • m (meters)

When sorting using a geo_point field with multiple geo-points (array of geo-points), the mode parameter supports the following values:

  • avg, max, median, min

Common Pitfalls

  • Field names and types:
    • Always use dot notation for metadata fields (e.g., metadata.price not just price)
    • Ensure fields used for sorting are of supported types in your metadata schema
    • Text fields must be of type keyword to be sortable
  • Array fields:
    • Always specify a mode when sorting on array fields
    • Choose the appropriate mode for your use case (e.g., max vs avg for numeric arrays)
    • Be aware that avg, median, and sum modes are only available for numeric arrays
  • Geo-distance sorting:
    • Must specify both lat and lon values
    • The field being sorted must be of type geo_point
    • Consider the performance impact of geo-distance sorting on large datasets
  • Multiple sort criteria:
    • Order matters - subsequent criteria only apply to documents with equal values for previous criteria
    • Mixing different field types in sort criteria may lead to unexpected results
    • Using _score in sort criteria only works with search endpoints
  • Performance considerations:
    • Sorting on computed values (like geo-distance) is slower than sorting on stored fields
    • Complex sorting with multiple criteria may impact query performance
    • Consider using pagination when sorting large result sets
  • Missing values:
    • Default behavior places documents with missing values last
    • Be explicit about missing value handling using the missing parameter if you need different behavior
    • Consider the impact of missing values when using multiple sort criteria