5 |
5 |
6 |
7 | [](https://github.com/mrahhal/MR.EntityFrameworkCore.KeysetPagination/actions/workflows/ci.yml)
8 | [](https://www.nuget.org/packages/MR.EntityFrameworkCore.KeysetPagination)
9 | [](LICENSE.txt)
10 |
11 | Keyset pagination for EF Core (Entity Framework Core). Also known as seek pagination or cursor pagination.
12 |
13 | Learn about why the standard offset based pagination (`Take().Skip()`) is bad in many common cases [here](http://use-the-index-luke.com/no-offset).
14 |
15 | Check the [benchmarks](#benchmarks) section below for a quick look at the different performance characteristics between offset and keyset.
16 |
17 | > [!NOTE]
18 | > If you're using ASP.NET Core, you can use [MR.AspNetCore.Pagination](https://github.com/mrahhal/MR.AspNetCore.Pagination) which wraps this package and offers an easier to consume keyset pagination behavior with additional features for ASP.NET Core. This is a lower level library that implements keyset pagination for EF Core.
19 |
20 | ## Usage
21 |
22 | `KeysetPaginate` is an extension method on `IQueryable
44 |
45 | The columns and their configured order are used to order the data, and then the direction decides if we're getting the data before or after the reference row.
46 |
47 | > [!WARNING]
48 | > You'll want to reverse the result whenever you use `KeysetPaginationDirection.Backward` to get the proper order of the data, since walking `Backward` gives results in the opposite order to the configured columns order. There's a helper method on `KeysetContext` for this, shown in a snippet later.
49 |
50 | `KeysetPaginate` returns a context object which you can use to get secondary info and get the data result.
51 |
52 | It can be called without direction and reference, in which case this is equivalent to querying the first page:
53 |
54 | ```cs
55 | KeysetPaginate(
56 | b => b.Ascending(entity => entity.Id)
57 | )
58 | ```
59 |
60 | Configuring a composite keyset is easy as well. Just add all the columns you want:
61 |
62 | ```cs
63 | KeysetPaginate(
64 | b => b.Ascending(entity => entity.Id).Ascending(entity => entity.Score),
65 | ...
66 | )
67 | ```
68 |
69 | You can also mix ASC/DESC columns. `KeysetPaginate` knows how to handle that:
70 |
71 | ```cs
72 | KeysetPaginate(
73 | b => b.Ascending(entity => entity.Id).Descending(entity => entity.Score),
74 | ...
75 | )
76 | ```
77 |
78 | > [!IMPORTANT]
79 | > Make sure to read the "Deterministic keysets" and "Indexing" sections for important notes about configuring keysets.
80 |
81 | ## Common patterns
82 |
83 | Here are the 4 most common patterns of using `KeysetPaginate`.
84 |
85 | #### First page
86 |
87 | Not specifying direction and reference gives you the first page of data.
88 |
89 | ```cs
90 | KeysetPaginate(
91 | b => ...
92 | )
93 | ```
94 |
95 | This is equivalent to the following:
96 |
97 | ```cs
98 | KeysetPaginate(
99 | b => ...,
100 | KeysetPaginationDirection.Forward,
101 | null
102 | )
103 | ```
104 |
105 | #### Last page
106 |
107 | We get the last page by specifying a `Backward` direction.
108 |
109 | ```cs
110 | KeysetPaginate(
111 | b => ...,
112 | KeysetPaginationDirection.Backward
113 | )
114 | ```
115 |
116 | #### Previous page
117 |
118 | You get previous/next pages by providing a direction and a reference. In this case, the reference should be the first item of the current page, and the direction is `Backward`:
119 |
120 | ```cs
121 | KeysetPaginate(
122 | b => ...,
123 | KeysetPaginationDirection.Backward,
124 | reference
125 | )
126 | ```
127 |
128 | #### Next page
129 |
130 | You get previous/next pages by providing a direction and a reference. In this case, the reference should be the last item of the current page, and the direction is `Forward`:
131 |
132 | ```cs
133 | KeysetPaginate(
134 | b => ...,
135 | KeysetPaginationDirection.Forward,
136 | reference
137 | )
138 | ```
139 |
140 | ## Prebuilt keyset query definition
141 |
142 | Although all the examples here build the keyset directly inside the `KeysetPaginate` call for brevity, the recommended way of doing this is to prebuild the keyset query definition. Prebuilding will allow reusing of internal caches, leading to more performance and less allocations.
143 |
144 | To prebuild, all you need to do is move the keyset building code out of the `KeysetPaginate` call and into a long lived instance (such as a static field).
145 |
146 | ```cs
147 | // In the ctor or someplace similar, set this to a static field for example.
148 | _usersKeysetQuery = KeysetQuery.Build
334 |
335 | Notice that when querying the first page, offset pagination does just as well as keyset. Offset pagination starts falling behind remarkably the further away the page you want to read is. Do consider this when choosing what method you want to use.
336 |
337 | To that point, the keyset bars (green) are barely visible in the MidPage and LastPage graphs. This shows a major advantage of keyset pagination over offset pagination, that is the stable performance characteristic over large amounts of data even when querying _further away_ pages.
338 |
339 |
342 |
343 | Check the [benchmarks](benchmarks) folder for the source code.
344 |
345 | Check this [blog post](https://github.com/mrahhal/blog/blob/main/posts/2023-05-14-offset-vs-keyset-pagination/post.md) for a more detailed look into the benchmarks.
346 |
347 | ## Caveats
348 |
349 | Check [this document](docs/caveats.md) on a few caveats to keep in mind when working with keyset pagination.
350 |
351 | ## Samples
352 |
353 | Check the [samples](samples) folder for project samples.
354 |
355 | - [Basic](samples/Basic): This is a quick example of a page that has First/Previous/Next/Last links (using razor pages).
356 |
357 | ## Talks
358 |
359 | [.NET Standup session](https://www.youtube.com/watch?v=DIKH-q-gJNU) where we discuss pagination and showcase this package.
360 |
361 | [](https://www.youtube.com/watch?v=DIKH-q-gJNU)
362 |
--------------------------------------------------------------------------------
/benchmarks/.editorconfig:
--------------------------------------------------------------------------------
1 | [*.cs]
2 | # CA1050: Declare types in namespaces
3 | dotnet_diagnostic.CA1050.severity = none
4 |
--------------------------------------------------------------------------------
/benchmarks/.gitignore:
--------------------------------------------------------------------------------
1 | BenchmarkDotNet.Artifacts/
2 |
--------------------------------------------------------------------------------
/benchmarks/Benchmarks/BenchmarksBase.cs:
--------------------------------------------------------------------------------
1 | using BenchmarkDotNet.Attributes;
2 | using Dapper;
3 | using Microsoft.EntityFrameworkCore;
4 | using Microsoft.Extensions.DependencyInjection;
5 | using MR.EntityFrameworkCore.KeysetPagination;
6 |
7 | public abstract class BenchmarksBase
8 | {
9 | protected ServiceProvider _provider = default!;
10 | protected User _midPageReference = default!;
11 | protected User _lastPageReference = default!;
12 |
13 | protected Func