HomeDev guideAPI Reference
Dev guideUser GuidesLegal TermsNuGetDev CommunityOptimizely AcademySubmit a ticketLog In
Dev guide

OrderBy

Describes the OrderBy parameter, part of the GraphQL API used for the Optimizely querying service, when retrieving content in Optimizely solutions.

The orderBy parameter enables the ordering (sorting) of the result list. You can order by:

  • Relevance – Scores with _ranking using RELEVANCE, which uses BM25 for best matching and sorted in descending order (most relevant at the top). If you only sort by RELEVANCE and the scores are the same, then the index order is used as a secondary sort.
  • Boost Only – Scores with _ranking using BOOST_ONLY. Sort by only using the query clauses with a boost. Other clauses only match but do not affect the scores. This is useful to take full control over the ranking using only boosts. Non-boosted clauses are ordered by index order, but you can override this with secondary (and more) sorting criteria like lexicographical sorting of a field in ascending direction.
  • Index order – Sort by index order using DOC, the order in which the items are synchronized with _ranking. You should use it in combination with cursor.
  • Field values – Sorted in DESC (descending) or ASC (ascending) order.

The orderBy can have one or more sorting criteria. If there is a tie-breaker, the next sorting criteria is used, and so on. If there are null values, these are ranked after the non-null values.

If you have multi-valued (list) fields, then Optimizely Graph sorts by the highest value in the list when in DESC order and by the lowest value in the list when in ASC order. For string values, the lexicographic order determines the highest and lowest value, such as B is higher than A.

📘

Note

Field values are limited to 1024 characters. Fields with values that exceed the maximum length should be made searchable instead and should not be used for sorting.

Limit results by score

You can limit the results by relevance score (_score) using the _minimumScore as input argument in the orderBy. This is needed to implement specific ranking rules to control the results retrieved by Graph using the BOOST_ONLY or SEMANTIC ranking. For example, the _minimumScore makes it possible to present multiple views of the search results with the same query, where adding the _minimumScore can show top relevant results on a landing page, and show more but lower scored results when clicking through. When the _minimumScore is added, Graph will always add relevance ranking on top of other ranking criteria, even when _ranking is not specified. See this example query:

{
  BiographyPage(
    orderBy: { Name: ASC, _minimumScore: 1.01 }
    where: { _fulltext: { match: "a" } }
  ) {
    total
    items {
      _score
      Name
      Die
      _fulltext
    }
  }
}

Examples

To sort by relevance, and when the scores are the same, then by a field called created in descending order (newest in top):

orderBy: { 
    _ranking: RELEVANCE 
    created: DESC 
}

You can order nested fields like this:

{
  BiographyPage(
    orderBy: {
      _ranking: RELEVANCE
      ContentLink: {
        GuidValue: ASC
      }
    }) {
    items {
      ContentLink {
        GuidValue
      }
    }
  }
}

As explained above, when you have a field like MetaKeywords that is multi-valued (list of strings), this query sorts the items by the lowest value of the field in each item because the sort direction is ASC.

{
  BiographyPage(
    orderBy: {
      MetaKeywords: ASC
    }) {
    items {
      MetaKeywords
    }
  }
}

Do custom ranking logic with boosting, but only select the top ranked results with at least score of 15:

{
  BiographyPage(
    orderBy: { _minimumScore: 16 }
    where: { _fulltext: { match: "a", boost: 15 } }
  ) {
  total
  items {
    Name
    _score
  }
}
}