API

API

Empty

To create an empty queryset:

MyModel.objects.none()

LIMIT

Limiting QuerySets

For example, this returns the first 5 objects (LIMIT 5):

Entry.objects.all()[:5]

order_by

To order by more than one field:

qs = Option.objects.filter(option_group__site=site)
qs.order_by('option_group__name', 'name')

values

Return a dictionary, rather than model-instance objects e.g:

>>> Blog.objects.filter(name__startswith='Beatles').values()
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]

…or to return specific fields:

>>> Blog.objects.values('id', 'name')
[{'id': 1, 'name': 'Beatles Blog'}]

values_list

This is similar to values except that instead of returning dictionaries, it returns tuples. Each tuple contains the value from the respective field passed into the values_list() call - so the first item is the first field, etc. For example:

>>> Entry.objects.values_list('id', 'headline')
[(1, u'First entry'), ...]

If you only pass in a single field, you can also pass in the flat parameter. If True, this will mean the returned results are single values, rather than one-tuples e.g:

>>> Entry.objects.values_list('id').order_by('id')
[(1,), (2,), (3,), ...]

>>> Entry.objects.values_list('id', flat=True).order_by('id')
[1, 2, 3, ...]

Note: It is an error to pass in flat when there is more than one field.

If you don’t pass any values to values_list(), it will return all the fields in the model, in the order they were declared.

Filter

See Field Lookups…

Multi-Conditions

rows = Delivery.objects.filter(name='sam', age=47)

Lazy Evaluation

>>> q = Entry.objects.filter(headline__startswith="What")
>>> q = q.filter(pub_date__lte=datetime.now())
>>> q = q.exclude(body_text__icontains="food")
>>> print q

Though this looks like three database hits, in fact it hits the database only once, at the last line (print q). In general, the results of a QuerySet aren’t fetched from the database until you “ask” for them.

Sample

python manage.py shell
>>> from books.models import Publisher
>>>
>>> p = Publisher(name = 'Apress', address = '2855 Telegraph Ave.', website = 'http://www.apress.com/')
>>> p.save()
>>> p = Publisher(name = "O'Reilly", address = 'Farnham, Surrey', website = 'http://www.oreilly.com/')
>>> p.save()

>>> Publisher.objects.all()
[<Publisher: Apress 2855 Telegraph Ave.>, <Publisher: O'Reilly Farnham, Surrey>]

>>> Publisher.objects.filter(name='Apress')
[<Publisher: Apress 2855 Telegraph Ave.>]

>>> Publisher.objects.get(name='Apress')
<Publisher: Apress 2855 Telegraph Ave.>

>>> Publisher.objects.order_by("-name")
[<Publisher: O'Reilly Farnham, Surrey>, <Publisher: Apress 2855 Telegraph Ave.>]

>>> Publisher.objects.all()[1]
<Publisher: O'Reilly Farnham, Surrey>

>>> p = Publisher.objects.get(name="Apress")
>>> p.delete()
>>> Publisher.objects.all()
[<Publisher: O'Reilly Farnham, Surrey>]

>>> from django.contrib.auth.models import User
>>> User.objects.filter(last_name__icontains='kimber')
[<User: patrick>]