QuerySets¶
QuerySets are a way to contruct queries for a particular resource, while minimising requests sent to the API. They function similarly to Django’s QuerySets, so if you’re comfortable with these you should be right at home with TastyTopping’s QuerySets (differences will be highlighted as you go).
Like Django’s QuerySets, these will be evaluated only when needed - a term that has a slightly different meaning here - in the following cases:
- Iteration. A QuerySet is iterable, and it executes its database query the first time you iterate over it.
- Slicing / Indexing. Unlike with Django’s, TastyTopping’s QuerySets are always evaluated when slicing or indexing.
- list(). Same warnings apply as with Django’s QuerySets - using
list()
will iterate over the whole QuerySet and load it into memory. - bool(). Testing a QuerySet in a boolean context, such as using
bool()
,or
,and
or anif
statement, will cause the query to be executed.
Creation¶
To create a QuerySet
, it’s usually easiest to
use one of the methods from Resource
which
returns a QuerySet for that Resource:
all()
- return a QuerySet matching all objects of a particular Resource.filter()
- return a QuerySet matching objects filtered by the given keyword args. The filters used are the same as those passed to tastypie.none()
- return an EmptyQuerySet. It contains shortcuts to avoid hitting the API where necessary.
Usage¶
To demonstrate using QuerySets, we’re going to use the same API as in the Getting Started section:
from tastytopping import ResourceFactory
factory = ResourceFactory('http://127.0.0.1:8000/api/v1/')
We’ve even already used a QuerySet as part of the tutorial:
existing_user = factory.user.all().first()
which is simple enough - it will get the first user (using the default ordering). Using this existing user, we can query the API to see how many blog entries this user has made:
blog_entries = factory.entry.filter(user=existing_user)
num_blog_entries = blog_entries.count()
To update the published date on all of these blog entries to the current date in a single call:
from datetime import datetime
blog_entries.update(pub_date=datetime.now())
To delete all blog entries from before 2012:
factory.entry.filter(pub_date__lt=datetime(2012)).delete()
There’s a more convenient way to order the resources too; to order the blog entries by reverse date:
factory.entry.all().order_by('-pub_date')
or to get the latest blog entry:
factory.entry.all().latest('pub_date')
There are some optimizations possible with QuerySets:
To view all available methods, take a look at the API Documentation.