Pagination

Overview

Break down large result sets into smaller, manageable pages to improve performance. Add pagination parameters to your query alongside your search criteria.

Syntax

{
  "query": {
    // search query
  },
  "page": <number>,
  "size": <number>
}

Parameters

Examples

Basic pagination

Retrieve the second page with 20 results per page:

{
  "page": 2,
  "size": 20
}

Pagination with search query

{
  "query": {
    "text": {
      "query": "football",
      "path": "heroMedia.title"
    }
  },
  "page": 1,
  "size": 10
}

Best practices

• Use reasonable page sizes (10-100) to balance performance and usability
• Avoid very large page sizes (500+) as they can impact performance
• Consider total result count when implementing pagination UI
• Deep pagination (page 1000+) may be slower - consider alternative approaches like cursor-based pagination for very large datasets

Sorting

Overview

Sort results by one or more fields. By default, results are sorted by relevance score (descending) when a search query is present.

Syntax

{
  "sort": [
    {
      "field": "<field-name>",
      "order": "asc" | "desc"
    }
  ]
}

Parameters

Examples

Single field sort

Sort by publish date (most recent first):

{
  "query": {
    "text": {
      "query": "championship",
      "path": "heroMedia.title"
    }
  },
  "sort": [
    {
      "field": "publishDate",
      "order": "desc"
    }
  ]
}

Multi-field sort

Sort by pinned status first, then by publish date:

{
  "query": {
    "in": {
      "path": "tags",
      "values": ["breaking-news", "featured"]
    }
  },
  "sort": [
    {
      "field": "pinned",
      "order": "desc"
    },
    {
      "field": "publishDate",
      "order": "desc"
    }
  ]
}

When using multiple sort fields, they are evaluated in order. In this example, all pinned articles appear first, and within each group (pinned/not pinned), articles are sorted by publish date.

Sort by relevance score

To explicitly sort by search relevance score:

{
  "query": {
    "text": {
      "query": "tournament final",
      "path": ["heroMedia.title", "content.text"]
    }
  },
  "sort": [
    {
      "field": "_score",
      "order": "desc"
    }
  ]
}

Sort without search query

Retrieve all articles sorted by publish date:

{
  "sort": [
    {
      "field": "publishDate",
      "order": "desc"
    }
  ]
}

Sortable Fields

Special fields

• _score - Relevance score (only meaningful with search queries)

Field Type Restrictions

Sortable field types:

• Keyword fields
• Date fields
• Numeric fields
• Boolean fields

NOT sortable:

• Analysed text fields (e.g., heroMedia.title, content.text, heroMedia.summary)
• Nested object fields (e.g., categories, linkedIds)

Notes

• When no sort is specified and a search query is present, results are automatically sorted by relevance score (_score) in descending order
• When no sort is specified and no search query is present, results may appear in an arbitrary order
• Sorting by multiple fields is evaluated in order - the first sort field takes precedence
• Sorting by _score without a search query may produce unexpected results (all documents have the same score)
• Combining custom sorting with score functions may produce unexpected results - the explicit sort order will take precedence over score-based ordering
• Sort performance varies by field type - keyword and numeric fields are generally faster than date fields

Common Patterns

Latest articles

{
  "sort": [
    {
      "field": "publishDate",
      "order": "desc"
    }
  ]
}

Featured content first

{
  "sort": [
    {
      "field": "pinned",
      "order": "desc"
    },
    {
      "field": "publishDate",
      "order": "desc"
    }
  ]
}

Alphabetical by slug

{
  "sort": [
    {
      "field": "slug",
      "order": "asc"
    }
  ]
}

Most relevant with date decay

It is not recommended to combine relevance scoring with explicit sorting, such as:

{
  "query": {
    "text": {
      "query": "championship",
      "path": "heroMedia.title"
    }
  },
  "sort": [
    {
      "field": "_score",
      "order": "desc"
    },
    {
      "field": "publishDate",
      "order": "desc"
    }
  ]
}

_score sorting takes precedence over publishDate, which may lead to unexpected ordering where older but more relevant articles appear before newer ones.

Rather than combining _score sorting with date fields, use a score function like gauss to incorporate recency into the relevance score itself:

{
  "query": {
    "text": {
      "query": "championship",
      "path": "heroMedia.title",
      "score": {
        "function": {
          "gauss": {
            "field": "publishDate",
            "origin": "now",
            "scale": "30d",
            "decay": 0.5
          }
        }
      }
    }
  },
  "sort": [
    {
      "field": "_score",
      "order": "desc"
    }
  ]
}