Python without ifs and buts - an ORM layer for Python objects, inspired by Django
The result of a reobject query is a QuerySet.
Returns a new QuerySet
containing objects that match the given lookup
parameters.
The lookup parameters should be specified as **kwargs
and must conform to a
specific format which bears close resemblance with the Django ORM.
It also possible to construct complex Q
objects and pass them to the
filter()
as *args
.
Multiple parameters (*args
or **kwargs
) are joined together with a logical
AND
.
For example, some ways to filter all objects in queryset
where
0 <= value < 1
are shown below.
>>> # Multiple keyword-only query
>>> queryset.filter(value__gte=0, value__lt=1)
>>> # Chained keyword-only query
>>> queryset.filter(value__gte=0).filter(value__lt=1)
>>> # Mixed query containing Q object and kwargs
>>> queryset.filter(Q(value__gte=0), value__lt=1)
>>> # Arg-only query with a single Q object: Q & Q => Q
>>> queryset.filter(Q(value__gte=0) & Q(value__lt=1))
Returns the object matching the given lookup parameters.
The lookup parameter syntax is same as that in filter()
.
get()
raises MultipleObjectsReturned
if more than one object was found.
get()
raises a DoesNotExist
exception if an object wasn’t found for the given parameters.
Example:
>>> queryset.get(nom='Doe', prenom='John')
Returns the same queryset on which it is operated on. It is an identity method.
Returns a new QuerySet
containing objects that do not match the given
lookup parameters.
The format of lookup parameters is the same as that of filter()
. Multiple
parameters are joined via AND
, and the whole thing is enclosed in a NOT
.
For example, some ways to exclude all objects in queryset
where
0 <= value < 1
are shown below.
>>> # Multiple keyword-only query
>>> queryset.exclude(value__gte=0, value__lt=1)
>>> # Arg-only query with a single Q object: Q & Q => Q
>>> queryset.exclude(Q(value__gte=0) & Q(value__lt=1))
>>> # Applying De Morgan's
>>> queryset.filter(~Q(value__gte=0) | ~Q(value__lt=1)))
Returns an integer representing the number of objects in the QuerySet
. Same
as performing a len()
on the QuerySet
.
>>> # Number of entries whose headline contains 'Lennon'
>>> Entry.objects.filter(headline__contains='Lennon').count()
7
Removes all objects in the QuerySet
, and returns the number of objects
deleted and a dictionary with the number of deletions per object type.
Note: Deleting an object only untracks it from reobject store, and doesn't actually garbage collect it.
>>> # Delete entries whose headline contains 'Lennon'
>>> Entry.objects.filter(headline__contains='Lennon').delete()
(7, {'Entry': 7})
Returns the latest object in the queryset, by date, using the fieldname
.
By default, the created
field is used as fieldname
.
>>> # Most recently updated entry whose headline is 'Lennon'
>>> Entry.objects.filter(headline='Lennon').latest('updated')
Works otherwise like latest()
except the direction is changed.
Returns the last object matched by the queryset, or None
if there is no matching object.
Works like last()
, but returns the first object in the queryset.
Reverses the order in which a queryset’s elements are returned.
Returns a random object matched by the queryset, or None
if there is no matching object.
Returns instance of an EmptyQuerySet
.
Returns a QuerySet
ordered by fields
. Ascending order is implied by default.
Example:
>>> Character.objects.all()
[Character(first_name='Ned', last_name='Stark'),
Character(first_name='Catelyn', last_name='Stark'),
Character(first_name='Robert', last_name='Baratheron')]
>>> Character.objects.filter().order_by('last_name', 'first_name')
[Character(first_name='Robert', last_name='Baratheron'),
Character(first_name='Catelyn', last_name='Stark'),
Character(first_name='Ned', last_name='Stark')]
Note: To indicate descending order, prepend the ordering
field with a negative sign, like -age
. Ordering by descending
order is only supported for integer fields.
Returns a new QuerySet
with all objects with duplicate fields removed.
For a distinct()
call without arguments, each field in each object
is compared when determining which objects are distinct. For a distinct()
call with specified field names, only the specified field names are compared.
Note: Performing distinct()
gives you the
first object for each duplicate entry. It is therefore important to make
sure that the queryset on which distinct()
is applied, has
been ordered using order_by()
. If you don't specify an order,
you'll get some arbitrary row.
Example: applying distinct()
by last_name
on the queryset defined in the
example of order_by()
.
>>> queryset.distinct('last_name')
[Character(first_name='Robert', last_name='Baratheron'),
Character(first_name='Catelyn', last_name='Stark')]
Applies a callable
function on each item in the QuerySet
and yields
a generator map
object containing the result.
Example:
>>> queryset
[Character(first_name='robert', last_name='baratheron'),
Character(first_name='catelyn', last_name='stark')]
>>> list(queryset.map(lambda x: x.first_name.upper()))
['ROBERT', 'CATELYN']
Returns a QuerySet
that returns dictionaries, rather than model instances.
Each of those dictionaries represents an object, with the keys corresponding
to the attribute names of model objects.
If no field is specified, the dictionaries will contain all the attributes.
Example:
>>> Book.objects.filter(price__lt=50).values('title')
[{'title': 'The Go Programming Language'}, ...]
Same as values()
, but returns tuples instead of dictionaries.
For one-tuple values, passing the flat
parameter will flatten them and return
single values.
Example:
>>> Character.objects.filter().values_list('first_name', flat=True)
['Robert', 'Catelyn', 'Ned']
Field lookup parameters are specified as keyword arguments to the QuerySet
methods filter()
, exclude()
and get()
.
By default, when no lookup type is provided the lookup type is assumed to be
exact
.
Exact match.
Examples:
>>> Entry.objects.get(id__exact=14)
>>> Entry.objects.get(id__exact=None)
Case-insensitive exact match.
Examples:
>>> Character.objects.get(first_name__iexact='NeD')
Character(first_name='Ned', last_name='Stark')
Case-sensitive containment test.
Examples:
>>> Character.objects.filter(first_name__contains='Cate')
Character(first_name='Catelyn', last_name='Stark')
>>> # Also works for non-string iterables
>>> SomeModel.objects.filter(list_attr__contains='item')
SomeModel(list_attr=['item', 'another item', ...])
Case-insensitive containment test.
Examples:
>>> Character.objects.filter(first_name__icontains='cAtE')
Character(first_name='Catelyn', last_name='Stark')
>>> # Also works for non-string iterables
>>> SomeModel.objects.filter(list_attr__icontains='item')
SomeModel(list_attr=['ITEM', ...])
In a given list.
Examples:
>>> Character.objects.filter(last_name__in='Starks')
[Character(first_name='Ned', last_name='Stark'),
Character(first_name='Catelyn', last_name='Stark')]
>>> # Also works for non-string iterables
>>> Character.objects.filter(last_name__in=['Stark', 'Baratheon'])
[Character(first_name='Ned', last_name='Stark'),
Character(first_name='Catelyn', last_name='Stark'),
Character(first_name='Robert', last_name='Baratheron')]
Case-insensitive lookup in a given list.
Examples:
>>> Character.objects.filter(last_name__iin='starks')
[Character(first_name='Ned', last_name='Stark'),
Character(first_name='Catelyn', last_name='Stark')]
>>> # Also works for non-string iterables
>>> Character.objects.filter(last_name__iin=['stark', 'baratheon'])
[Character(first_name='Ned', last_name='Stark'),
Character(first_name='Catelyn', last_name='Stark'),
Character(first_name='Robert', last_name='Baratheron')]
Greater than.
Greater than or equal to.
Less than.
Less than or equal to.
Case-sensitive starts-with.
Case-insensitive starts-with.
Case-sensitive ends-with.
Case-insensitive ends-with.
Checks if the value is equal to Python NoneType
.