# Pagination and sorting

This document explains how to control the number of results and the order in which they appear using pagination and sorting as part of the Content Advanced Search query structure.

# 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

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

## Parameters

| Parameter | Type   | Description                             | Default | Minimum | Maximum |
| --------- | ------ | --------------------------------------- | ------- | ------- | ------- |
| `page`    | number | The page number to retrieve (1-indexed) | `1`     | `1`     | N/A     |
| `size`    | number | Number of results per page              | `20`    | `1`     | `200`   |

## Examples

### Basic pagination

Retrieve the second page with 20 results per page:

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

### Pagination with search query

```json
{
  "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

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

## Parameters

| Parameter | Type   | Description                                          | Required? |
| --------- | ------ | ---------------------------------------------------- | --------- |
| `field`   | string | The field name to sort by                            | Yes       |
| `order`   | string | Sort order: `asc` (ascending) or `desc` (descending) | Yes       |

## Examples

### Single field sort

Sort by publish date (most recent first):

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

### Multi-field sort

Sort by pinned status first, then by publish date:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

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

### Featured content first

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

### Alphabetical by slug

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

### Most relevant with date decay

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

```json
{
  "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:

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