A cursor marks the last result you read, so the next request can continue after it.
dotnet add package RecursiveAI.OneIndex --prereleaseRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using OneIndex; using var index = SearchIndex.InMemory<Item>(); index.Upsert([new() { Id = "a" }, new() { Id = "b" }]); index.Commit(); var query = index.Search() .OrderBy(x => x.Id).Take(1); var first = query.Execute(); var next = query .SearchAfter(first.NextCursor!).Execute(); Console.WriteLine(next[0].Document.Id); public class Item { [SearchId] public string Id { get; set; } = ""; }
bUnzip the example, then dotnet run.
The full program
The download indexes four synthetic items. Two share the same rank; sorting by ID after rank makes their relative order explicit. This example uses OneIndex 0.4.0-preview.2, a preview release.
using OneIndex; using OneIndex.Search; using var index = SearchIndex.InMemory<Item>(); index.Upsert([ new() { Id = "c", Rank = 2 }, new() { Id = "b", Rank = 1 }, new() { Id = "a", Rank = 1 }, new() { Id = "d", Rank = 3 } ]); index.Commit(); SortCursor? cursor = null; int pageNumber = 0; while (true) { var query = index.Search().OrderBy(x => x.Rank) .ThenBy(x => x.Id).Take(2); if (cursor is not null) query = query.SearchAfter(cursor); var page = query.Execute(); if (page.Count == 0) break; Console.WriteLine($"Page {++pageNumber}: " + string.Join(", ", page.Select(h => h.Document.Id))); cursor = page.NextCursor; if (cursor is null) break; } public class Item { [SearchId] public string Id { get; set; } = ""; [Sortable] public int Rank { get; set; } }
dotnet run prints:
Page 1: a, b Page 2: c, d
Combining Skip with SearchAfter throws InvalidOperationException; reusing a cursor with a different sort throws ArgumentException.
Variations
To carry the cursor between requests, replace the cursor declaration and paging loop in the full program with this token round-trip. Keep its using OneIndex.Search; line, model and indexed items:
var first = index.Search().OrderBy(x => x.Rank) .ThenBy(x => x.Id).Take(2).Execute(); string token = first.NextCursor!.ToToken(); if (!SortCursor.TryParse(token, out var parsed)) throw new ArgumentException("Invalid cursor"); var next = index.Search().OrderBy(x => x.Rank) .ThenBy(x => x.Id).SearchAfter(parsed!).Take(2).Execute(); Console.WriteLine(string.Join(", ", next.Select(h => h.Document.Id)));
c, dRelated recipes
Full-text search · Faceted search
The short answer
Order the query, call Take, execute it, and feed the returned NextCursor to SearchAfter on the next request. Keep the query and sort the same throughout the walk. Use a [SearchId] property so the final tie-break identifies a document rather than its internal position. The download sorts by rank and then ID and reads all four documents in two pages.
What is cursor-based pagination?
A cursor records the last returned hit’s sort values and identifier. The next search keeps only matches strictly after that position in the same total order. It does not mean “skip this many rows.” In OneIndex, TotalHits still counts all query matches, not just those after the cursor. Stop when a request returns no hits; the program also stops if no cursor is returned.
The sort must settle ties. Here the first two items both have rank 1, and ThenBy(x => x.Id) orders them as a, b. OneIndex also applies an identifier tie-break at the end of its total order. Making the secondary key explicit helps a caller understand why results with equal primary values appear in that order. For keyword columns, the order is UTF-8 byte order, not a language-aware collation.
The token variation uses ToToken and SortCursor.TryParse so an HTTP client can send a URL-safe string back rather than a C# object. Reject malformed input when parsing fails. A valid token is not permission to access documents: apply the same application filters to every request. The sort checksum checks sort compatibility; it does not establish that a request has the same search text or access filters as the previous request.
What is the difference between cursor and offset pagination?
Offset pagination uses Skip and Take and fits a UI that asks for numbered pages. OneIndex’s result window requires their sum to be at most 10,000. Search-after instead moves forward from an existing cursor, so the client needs a prior page’s position rather than an arbitrary page number. Don’t combine the two styles in one request.
A field-sort search visits every matching document and retains the requested page in a heap. Using a cursor does not turn it into a database index seek or avoid inspecting the matches. It does avoid retaining an ever-growing skipped prefix. Choose a cursor for a sequential “load more” interaction; choose an offset when the user needs a page number within the result window. The sorting documentation defines both behaviors.
What are the drawbacks of cursor pagination?
A cursor is not a frozen view of the collection. With stable identifiers, a document that remains unchanged throughout a walk appears exactly once, even if other documents change. But changing a document’s sort values can move it across the cursor, making it appear again or not appear at all. Sorting by relevance adds another dependency: scores depend on the collection, so unrelated index updates can affect the order.
Without an identifier field, a low-level cursor uses the global document ID and is valid only within one snapshot, because merges can renumber documents. With identifiers, the cursor does not depend on the original commit. This distinction matters more than simply keeping a token well formed. For a consistent export, control updates or use an appropriate fixed snapshot rather than treating an ordinary multi-request walk as a transaction.