Table of Contents

Class ElasticSearchCursorHelper

Namespace
Excalibur.Data.ElasticSearch
Assembly
Excalibur.Data.ElasticSearch.dll

Elasticsearch-specific cursor helpers that bridge the generic CursorEncoder with Elasticsearch Elastic.Clients.Elasticsearch.FieldValue sort values and Elastic.Clients.Elasticsearch.SearchResponse<TDocument>.

public static class ElasticSearchCursorHelper
Inheritance
ElasticSearchCursorHelper
Inherited Members

Remarks

This helper converts between the opaque Base64url cursor format (produced by CursorEncoder) and Elasticsearch's native Elastic.Clients.Elasticsearch.FieldValue type used in search_after queries.

For bidirectional cursor pagination, the cursor is always derived from the last hit in display order (after any reversal). This means:

  • Next/First: cursor from the last hit (natural order).
  • Previous/Last: items are reversed, then cursor from the last item in display order (which was the first hit from the reversed ES query).

Methods

ApplyCursorPaging<T>(SearchRequestDescriptor<T>, int, IList<FieldValue>?)

Applies cursor-based paging to an Elasticsearch search request: sets the page size with a single extra "peek" row (pageSize + 1) and applies the search_after cursor when one is supplied.

public static SearchRequestDescriptor<T> ApplyCursorPaging<T>(SearchRequestDescriptor<T> descriptor, int pageSize, IList<FieldValue>? searchAfter = null)

Parameters

descriptor SearchRequestDescriptor<T>

The search request descriptor to configure.

pageSize int

The requested page size. Must be greater than zero.

searchAfter IList<FieldValue>

The decoded cursor sort values for search_after, or null/empty for the first page. For First and Last (which navigate without a cursor), pass null.

Returns

SearchRequestDescriptor<T>

The same descriptor instance, to allow chaining.

Type Parameters

T

The document type.

Remarks

The extra peek row is what allows ToCursorResult<T>(SearchResponse<T>, int, PageNavigation) to reliably report HasMore — including the boundary case where the final page is exactly pageSize items. The peek row is never returned to callers; ToCursorResult<T>(SearchResponse<T>, int, PageNavigation) trims it. Always pair this method with ToCursorResult<T>(SearchResponse<T>, int, PageNavigation); do not set Size(pageSize) manually.

Exceptions

ArgumentNullException

Thrown when descriptor is null.

ArgumentOutOfRangeException

Thrown when pageSize is less than one.

DecodeCursor(string?)

Decodes an opaque Base64url cursor string into Elasticsearch Elastic.Clients.Elasticsearch.FieldValue sort values suitable for search_after.

public static IList<FieldValue>? DecodeCursor(string? cursor)

Parameters

cursor string

The opaque cursor string, or null for the first page.

Returns

IList<FieldValue>

A list of Elastic.Clients.Elasticsearch.FieldValue sort values to pass to SearchAfter, or null if the cursor is empty or invalid.

EncodeCursor(IReadOnlyCollection<FieldValue>)

Encodes Elasticsearch Elastic.Clients.Elasticsearch.FieldValue sort values into an opaque Base64url cursor string.

public static string EncodeCursor(IReadOnlyCollection<FieldValue> sortValues)

Parameters

sortValues IReadOnlyCollection<FieldValue>

The sort values from an Elasticsearch hit (e.g., hit.Sort).

Returns

string

A Base64url-encoded cursor string.

Exceptions

ArgumentNullException

Thrown when sortValues is null.

ArgumentException

Thrown when sortValues is empty.

ToCursorResult<T>(SearchResponse<T>, int, PageNavigation)

Builds a bidirectional CursorPagedResult<T> from an Elasticsearch search response that was issued with a single extra "peek" row (see ApplyCursorPaging<T>(SearchRequestDescriptor<T>, int, IList<FieldValue>?)).

public static CursorPagedResult<T> ToCursorResult<T>(SearchResponse<T> response, int pageSize, PageNavigation navigation)

Parameters

response SearchResponse<T>

The Elasticsearch search response.

pageSize int

The requested page size (excluding the peek row).

navigation PageNavigation

The navigation direction the query was issued for. For Previous and Last the repository must have reversed the sort order; this method restores display order and assigns the forward/backward cursors accordingly.

Returns

CursorPagedResult<T>

A cursor-paged result populated with both NextCursor (forward) and PreviousCursor (backward) so the consumer can navigate in either direction.

Type Parameters

T

The document type.

Remarks

This method assumes the query over-fetched one row (Size = pageSize + 1) via ApplyCursorPaging<T>(SearchRequestDescriptor<T>, int, IList<FieldValue>?). The presence of that extra "peek" row — not a full page — determines whether a further page exists in the direction of travel, fixing the boundary case where the final page contains exactly pageSize items. The peek row is trimmed and never returned to the caller.

Cursor assignment, in display order (the first/last item the caller sees): NextCursor is the sort values of the last displayed item (used to fetch the following page going forward), and PreviousCursor is the sort values of the first displayed item (used to fetch the preceding page via a reversed query). A cursor is null only when that direction has no further page: PreviousCursor is null on the first page, NextCursor is null on the last page.

Exceptions

ArgumentNullException

Thrown when response is null.