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
descriptorSearchRequestDescriptor<T>The search request descriptor to configure.
pageSizeintThe requested page size. Must be greater than zero.
searchAfterIList<FieldValue>The decoded cursor sort values for
search_after, ornull/empty for the first page. For First and Last (which navigate without a cursor), passnull.
Returns
- SearchRequestDescriptor<T>
The same
descriptorinstance, to allow chaining.
Type Parameters
TThe 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
descriptorisnull.- ArgumentOutOfRangeException
Thrown when
pageSizeis 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
cursorstringThe opaque cursor string, or
nullfor the first page.
Returns
- IList<FieldValue>
A list of Elastic.Clients.Elasticsearch.FieldValue sort values to pass to
SearchAfter, ornullif 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
sortValuesIReadOnlyCollection<FieldValue>The sort values from an Elasticsearch hit (e.g.,
hit.Sort).
Returns
- string
A Base64url-encoded cursor string.
Exceptions
- ArgumentNullException
Thrown when
sortValuesisnull.- ArgumentException
Thrown when
sortValuesis 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
responseSearchResponse<T>The Elasticsearch search response.
pageSizeintThe requested page size (excluding the peek row).
navigationPageNavigationThe 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
TThe 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
responseisnull.