Update docs on default pagination behavior.#2226
Update docs on default pagination behavior.#2226zachdaniel merged 3 commits intoash-project:mainfrom
Conversation
| - Force offset: `page: [limit: 10, offset: 0]` | ||
| - Force keyset: `page: [limit: 10, after: cursor]` | ||
|
|
||
| > **Note**: This configuration is automatically set to `:keyset` when using `mix igniter.install ash` |
There was a problem hiding this comment.
All of these are set to the "new behavior" by the installer, which is stated above
The ash installer automatically sets all of these.
So I think we can remove this section.
| If an action supports both offset and keyset pagination (e.g. default read actions), offset pagination is used by default when page options only contain `limit`. However, the records will have the keyset in the metadata, so keyset pagination can be performed on next pages. | ||
| > #### ⚠️ Configuration Warning | ||
| > | ||
| > Never set `config :ash, :default_page_type, nil` as this will cause a runtime crash. |
There was a problem hiding this comment.
This warning is a bit specific. I'd suggest trimming down these docs a bit WRT the configuration and instead just link to the backwards compatbility config guide. No need to explain both options here. In this case this reads more like a "feature" rather than a backwards compatibility tool.
|
|
||
| ```elixir | ||
| # Check your config/config.exs | ||
| config :ash, :default_page_type, :keyset # or :offset |
There was a problem hiding this comment.
What I'm getting at is that for backwards compatible configurations, we shouldn't call this out as a configuration that we want people to set. So at most, there can be a note that a backwards compatibility configuration exists. We don't want to model this as something that the user might set as a "feature". These configuarations will be removed in future versions of Ash and only the new behavior will be available. So we really shouldn't explain it here except at most saying something like "note that this behavior is subject to a backwards compatibility configuration: "
There was a problem hiding this comment.
Ok, so keyset will be the default in the future without it being explicitly being stated in the config, is that what you're saying?
I get that in general in terms of performance characteristics, keyset is preferred over offset, but this basically just explains to the user that unless if you have a config for this setting, currently Ash will default to using offset pagination, which is the current behavior?
The main premise for the PR was to clarify that when you run a query with page: [limit: 10] with the default setup, why do I get either an offset or keyset result.
There was a problem hiding this comment.
For new users, when they generate an app, it defaults to keyset and we don't ever want them to change it back, so we don't want to explain really how or why they might want to at all.
|
🚀 Thank you for your contribution! 🚀 |
2 participants
Adds some more details on default behavior regarding pagination, and the current default config setup.