Legacy Query Interface
**********************

Warning:

  The query interface is considered legacy in SQLAlchemy. Prefer using
  "session.execute(select(...))" instead.

Flask-SQLAlchemy adds a "query" object to each model. This can be used
to query instances of a given model. "User.query" is a shortcut for
"db.session.query(User)".

   # get the user with id 5
   user = User.query.get(5)

   # get a user by username
   user = User.query.filter_by(username=username).one()


Queries for Views
=================

If you write a Flask view function it's often useful to return a "404
Not Found" error for missing entries. Flask-SQLAlchemy provides some
extra query methods.

* "Query.get_or_404()" will raise a 404 if the row with the given id
  doesn't exist, otherwise it will return the instance.

* "Query.first_or_404()" will raise a 404 if the query does not return
  any results, otherwise it will return the first result.

* "Query.one_or_404()" will raise a 404 if the query does not return
  exactly one result, otherwise it will return the result.

   @app.route("/user/<username>")
   def show_user(username):
       user = User.query.filter_by(username=username).one_or_404()
       return render_template("show_user.html", user=user)

You can add a custom message to the 404 error:

      user = User.query.filter_by(username=username).one_or_404(
          description=f"No user named '{username}'."
      )


Pagination
==========

If you have a lot of results, you may only want to show a certain
number at a time, allowing the user to click next and previous links
to see pages of data.

Call "paginate()" on a query to get a "Pagination" object. See Paging
Query Results for more information about the pagination object.

During a request, this will take "page" and "per_page" arguments from
the query string "request.args". Pass "max_per_page" to prevent users
from requesting too many results on a single page. If not given, the
default values will be page 1 with 20 items per page.

   page = User.query.order_by(User.join_date).paginate()
   return render_template("user/list.html", page=page)
