sqlmodel/docs/tutorial/fastapi/limit-and-offset.md

Read Heroes with Limit and Offset with FastAPI

When a client sends a request to get all the heroes, we have been returning them all.

But if we had thousands of heroes that could consume a lot of computational resources, network bandwith, etc.

So we probably want to limit it.

Let's use the same offset and limit we learned about in the previous tutorial chapters for the API.

!!! info In many cases this is also called pagination.

Add a Limit and Offset to the Query Parameters

Let's add limit and offset to the query parameters.

By default, we will return the first results from the database, so offset will have a default value of 0.

And by default, we will return a maximum of 100 heroes, so limit will have a default value of 100.

{!./docs_src/tutorial/fastapi/limit_and_offset/tutorial001.py[ln:1-4]!}

# Code here omitted 👈

{!./docs_src/tutorial/fastapi/limit_and_offset/tutorial001.py[ln:54-58]!}

# Code below omitted 👇

👀 Full file preview

{!./docs_src/tutorial/fastapi/limit_and_offset/tutorial001.py!}

We want to allow clients to set a different offset and limit values.

But we don't want them to be able to set a limit of something like 9999, that's over 9000! 😱

So, to prevent it, we add additional validation to the limit query parameter, declaring that it has to be less than or equal to 100 with lte=100.

This way, a client can decide to take less heroes if they want, but not more.

!!! info If you need to refresh how query parameters and their validation work, check out the docs in FastAPI:

* <a href="https://fastapi.tiangolo.com/tutorial/query-params/" class="external-link" target="_blank">Query Parameters</a>
* <a href="https://fastapi.tiangolo.com/tutorial/query-params-str-validations/" class="external-link" target="_blank">Query Parameters and String Validations</a>
* <a href="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/" class="external-link" target="_blank">Path Parameters and Numeric Validations</a>

Check the Docs UI

Now we can see that the docs UI shows the new parameters to control limit and offset of our data.

Recap

You can use FastAPI's automatic data validation to get the parameters for limit and offset, and then use them with the session to control ranges of data to be sent in responses.