OrderBy

5 min

The orderBy argument controls the order of items in an Optimizely Graph result list so you can surface the most relevant matches first, apply custom ranking through boosts, or paginate consistently with a cursor. Use it to align the result order with the experience you build on top of the query (for example, ranking landing-page results by relevance, while listing taxonomy values alphabetically). Order by one of the following:

Relevance – Scores with _ranking using RELEVANCE, which uses BM25 for best matching and sorts in descending order (most relevant at the top). When you only sort by RELEVANCE and the scores are the same, the index order acts as a secondary sort.

Boost only – Scores with _ranking using BOOST_ONLY. Sort using only the query clauses with a boost. Other clauses match but do not affect the scores. This option lets you take full control over the ranking using only boostsboosts. Non-boosted clauses are ordered by index order, but you can override this with secondary sorting criteria, such as 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. 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. When there is a tie-breaker, Optimizely Graph uses the next sorting criterion, and so on. Optimizely Graph ranks null values after non-null values.

When you have multi-valued (list) fields, 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 (for example, B is higher than A).

📘 Note Field values are limited to 1,024 characters. Make fields with values that exceed the maximum length searchable instead, and do not use them for sorting.

Limit results by score

Use _minimumScore to drop results that fall below a relevance threshold so the response contains only the matches your experience treats as good enough. This is useful when the same query feeds several views: a strict threshold on a landing page surfaces only top matches, while a relaxed threshold on a follow-up view exposes weaker matches.

Limit the results by relevance score (_score) using _minimumScore as an input argument in orderBy. Use this to implement specific ranking rules that control the results retrieved by Optimizely Graph using the BOOST_ONLY or SEMANTIC ranking. For example, _minimumScore lets you present multiple views of the search results with the same query. Adding _minimumScore can show top relevant results on a landing page and show more lower-scored results when readers click through. When you add _minimumScore, Optimizely Graph always adds relevance ranking on top of other ranking criteria, even when _ranking is not specified. See the following example query:

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

Examples

The following examples show common orderBy patterns: combining relevance with a secondary field sort, sorting on nested fields, sorting on multi-valued fields, and applying a _minimumScore threshold with custom boosting. Use them as starting points for your own queries.

The following query sorts by relevance, and when the scores are the same, then by a field called created in descending order (newest on top):

orderBy: { 
    _ranking: RELEVANCE 
    created: DESC 
}

The following query orders nested fields:

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

As explained in the previous section, when you have a field like MetaKeywords that is multi-valued (a list of strings), the following 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
    }
  }
}

The following query uses custom ranking logic with boosting, but selects only the top-ranked results with a score of at least 15:

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