Class PaginatedCursor<T, TResult, TOptions, TCursor>

Namespace

DataStax.AstraDB.DataApi.Core.Enumeration

Assembly

DataStax.AstraDB.DataApi.dll

A fluent API cursor for a generic, formally paginated, find-like operation, be it a regular find or a find-and-rerank query. Cursors allow to run multiple-results queries, enumerating the results, and applying filters, projections, and other modifiers to the search.

This cursor extends AbstractCursor<T> to provide pagination management and the handling of those options that are common to all find-like operations, such as projecting or filtering.

Both synchronous and asynchronous iteration patterns are supported.

Use the fluent methods to refine your query, then iterate using foreach, LINQ, or manual cursor navigation.

public abstract class PaginatedCursor<T, TResult, TOptions, TCursor> : AbstractCursor<TResult>, IDisposable, IEnumerable<TResult>, IEnumerable, IAsyncEnumerable<TResult> where T : class where TResult : class where TOptions : BasePaginatedFindOptions<T, TOptions> where TCursor : PaginatedCursor<T, TResult, TOptions, TCursor>

Type Parameters

T

The type representing the record or row being queried.

TResult

The type to deserialize the results to (e.g., when using projections).

TOptions

The type for the find options suitable to the query being executed.

TCursor

The concrete cursor type for fluent method chaining.

Inheritance

object

AbstractCursor<TResult>

PaginatedCursor<T, TResult, TOptions, TCursor>

Implements

IDisposable

IEnumerable<TResult>

IEnumerable

IAsyncEnumerable<TResult>

Derived

FindAndRerankCursor<T, TResult, TSort, TCursor>

FindCursor<T, TResult, TSort, TCursor>

Inherited Members

AbstractCursor<TResult>.State

AbstractCursor<TResult>.Buffered()

AbstractCursor<TResult>.Consumed

AbstractCursor<TResult>.ConsumeBuffer(int)

AbstractCursor<TResult>.HasNext()

AbstractCursor<TResult>.HasNextAsync(CancellationToken)

AbstractCursor<TResult>.MoveNext()

AbstractCursor<TResult>.MoveNextAsync(CancellationToken)

AbstractCursor<TResult>.GetAsyncEnumerator(CancellationToken)

AbstractCursor<TResult>.GetEnumerator()

AbstractCursor<TResult>.MoveNextAsync(CancellationToken, bool, bool)

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Properties

_buffer

Gets the internal buffer containing the current page of results.

protected override List<TResult> _buffer { get; }

Property Value

List<TResult>

Methods

Clone()

Creates a new cursor instance with the same configuration.

public abstract TCursor Clone()

Returns

TCursor

A new cursor instance.

CloneWith(Filter<T>, TOptions)

Creates a new cursor instance with updated filter and options.

protected abstract TCursor CloneWith(Filter<T> filter, TOptions options)

Parameters

filter Filter<T>

The filter to apply.

options TOptions

The find options to use.

Returns

TCursor

A new cursor instance.

Dispose()

Releases all resources used by the cursor and clears the current page.

public override void Dispose()

FetchMoreAsync(CancellationToken, bool)

Fetches the next page of results from the underlying data source.

protected override Task<bool> FetchMoreAsync(CancellationToken cancellationToken, bool runSynchronously)

Parameters

cancellationToken CancellationToken

A cancellation token to cancel the operation.

runSynchronously bool

Whether to run the operation synchronously.

Returns

Task<bool>

True if more pages are available, false otherwise.

FetchNextPage()

Synchronously fetches the next complete page of results from the server.

public FindPage<TResult> FetchNextPage()

Returns

FindPage<TResult>

The next page of results.

Exceptions

CursorException

Thrown when the cursor is closed or the current buffer is not empty.

FetchNextPageAsync(CancellationToken)

Asynchronously fetches the next complete page of results from the server.

public Task<FindPage<TResult>> FetchNextPageAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

An optional cancellation token to cancel the operation.

Returns

Task<FindPage<TResult>>

The next page of results.

Exceptions

CursorException

Thrown when the cursor is closed or the current buffer is not empty.

Filter(Filter<T>)

Specifies a filter to apply to the query.

public TCursor Filter(Filter<T> filter)

Parameters

filter Filter<T>

The filter to apply.

Returns

TCursor

A new cursor instance with the updated filter.

Examples

// When targeting a collection (analogous syntax for tables):
var filter = Builders<MyRecord>.CollectionFilter.Eq(d => d.Status, "active");
var cursor = collection.Find().Filter(filter);

GetSortVector()

Synchronously retrieves the sort vector used for the query.

public float[] GetSortVector()

Returns

float[]

The sort vector, or null if not available.

Remarks

The cursor must have been started (at least one record fetched) and IncludeSortVector(bool) must be enabled. The asynchronous version GetSortVectorAsync(CancellationToken) is recommended to avoid potential deadlocks.

GetSortVectorAsync(CancellationToken)

Asynchronously retrieves the sort vector used for the query.

public Task<float[]> GetSortVectorAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

An optional cancellation token to cancel the operation.

Returns

Task<float[]>

The sort vector, or null if not available.

Remarks

The cursor must have been started (at least one record fetched) and IncludeSortVector(bool) must be enabled. If the cursor hasn't been started yet, this method will automatically fetch the first page to retrieve the sort vector.

IncludeSortVector(bool)

Specifies whether to include the sort vector in the results.

public TCursor IncludeSortVector(bool include = true)

Parameters

include bool

Whether to include the sort vector. Defaults to true.

Returns

TCursor

A new cursor instance with the updated setting.

Examples

var cursor = collection.Find()
    .Sort(Builders<MyRecord>.CollectionSort.Vectorize("search query"))
    .IncludeSortVector();

await foreach (var doc in cursor)
{
    // Process records
}

var sortVector = await cursor.GetSortVectorAsync();

Remarks

When enabled, you can retrieve the sort vector using GetSortVector() or GetSortVectorAsync(CancellationToken). This is useful for vector similarity searches where you want to access the vector used for sorting.

InitialPageState(string)

Sets the initial page state used to resume pagination from a previous find operation.

public TCursor InitialPageState(string initialPageState)

Parameters

initialPageState string

The page state to resume from, or null to start from the beginning.

Returns

TCursor

A new cursor instance with the updated initial page state.

Limit(int)

Specifies the maximum number of records to return.

public TCursor Limit(int limit)

Parameters

limit int

The maximum number of records to return.

Returns

TCursor

A new cursor instance with the updated limit.

Project(IProjectionBuilder)

Specifies a projection to apply to the results.

public TCursor Project(IProjectionBuilder projection)

Parameters

projection IProjectionBuilder

The projection to apply.

Returns

TCursor

A new cursor instance with the updated projection.

Examples

var projection = Builders<MyRecord>.Projection.Include(d => d.Name).Include(d => d.Email);
var cursor = collection.Find().Project(projection);

Rewind()

Resets the cursor to its initial state, clearing the current page.

public override void Rewind()