Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Fixed #17156 -- Added documentation examples for exists(). #306

Closed
wants to merge 1 commit into from

3 participants

@mrmagooey

Added two examples for exists() in the queryset reference documentation,
also added an additional callout to exists() in the "When Querysets are
evaluated" section for the first list element (i.e. for x in queryset).

@mrmagooey mrmagooey Fixed #17156 -- Added documentation examples for exists().
Added two examples for exists() in the queryset reference documentation,
also added an additional callout to exists() in the "When Querysets are
evaluated" section for the first list element (i.e. for x in queryset).
fc3d37c
@polinom

Seems useful and well formated to me.

@timgraham
Owner

Made a few tweaks and merged, thanks!

@timgraham timgraham closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Aug 26, 2012
  1. @mrmagooey

    Fixed #17156 -- Added documentation examples for exists().

    mrmagooey authored
    Added two examples for exists() in the queryset reference documentation,
    also added an additional callout to exists() in the "When Querysets are
    evaluated" section for the first list element (i.e. for x in queryset).
This page is out of date. Refresh to see the latest.
Showing with 40 additions and 8 deletions.
  1. +40 −8 docs/ref/models/querysets.txt
View
48 docs/ref/models/querysets.txt
@@ -27,10 +27,14 @@ You can evaluate a ``QuerySet`` in the following ways:
* **Iteration.** A ``QuerySet`` is iterable, and it executes its database
query the first time you iterate over it. For example, this will print
the headline of all entries in the database::
-
+
for e in Entry.objects.all():
print(e.headline)
+ Note: *Don't* use this if all you want to do is determine if at least one
+ result exists, and don't need the actual objects. It's more efficient to
+ use :meth:`exists() <QuerySet.exists>` (see below).
+
* **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can
be sliced, using Python's array-slicing syntax. Slicing an unevaluated
``QuerySet`` usually returns another unevaluated ``QuerySet``, but Django
@@ -1523,13 +1527,41 @@ exists
Returns ``True`` if the :class:`.QuerySet` contains any results, and ``False``
if not. This tries to perform the query in the simplest and fastest way
-possible, but it *does* execute nearly the same query. This means that calling
-:meth:`.QuerySet.exists` is faster than ``bool(some_query_set)``, but not by
-a large degree. If ``some_query_set`` has not yet been evaluated, but you know
-that it will be at some point, then using ``some_query_set.exists()`` will do
-more overall work (one query for the existence check plus an extra one to later
-retrieve the results) than simply using ``bool(some_query_set)``, which
-retrieves the results and then checks if any were returned.
+possible, but it *does* execute nearly the same query as a normal :class:`.QuerySet` query.
+
+The usage of :meth:`.QuerySet.exists` is useful for searches relating to both object membership and to the existence of specific :class:`.QuerySet`\s, particularly in the context of large :class:`.QuerySet`\s.
+
+The most efficient method of finding whether a model with a known unique characteristic (e.g. ``primary_key``) is a member of a :class:`.QuerySet`, is::
+
+ known_entry_id = 123
+ if some_query_set.filter(pk=known_entry_id).exists():
+ print ("Entry contained in queryset")
+
+Which will be faster than::
+
+ if e in some_query_set:
+ print("Entry contained in QuerySet")
+
+And to find whether a returned queryset contains any items::
+
+ if some_query_set.exists():
+ print("There is at least one Entry with the headline Test")
+
+Which will be faster than::
+
+ if some_query_set:
+ print("There is at least one Entry with the headline Test")
+
+...but not by a large degree (hence needing a large queryset for
+efficiency gains).
+
+Additionally, if a ``some_query_set`` has not yet been evaluated, but you know that
+it will be at some point, then using ``some_query_set.exists()``
+will do more overall work (one query for the existence check plus
+an extra one to later retrieve the results) than simply using
+``bool(some_query_set)``, which retrieves the results and then
+checks if any were returned.
+
update
~~~~~~
Something went wrong with that request. Please try again.