Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

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

Closed
wants to merge 1 commit into from

3 participants

mrmagooey Tim Graham Igor Polynets
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 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
Igor Polynets

Seems useful and well formated to me.

Tim Graham
Owner

Made a few tweaks and merged, thanks!

Tim Graham timgraham closed this September 08, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Showing 1 unique commit by 1 author.

Aug 26, 2012
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
This page is out of date. Refresh to see the latest.

Showing 1 changed file with 40 additions and 8 deletions. Show diff stats Hide diff stats

  1. 48  docs/ref/models/querysets.txt
48  docs/ref/models/querysets.txt
@@ -27,10 +27,14 @@ You can evaluate a ``QuerySet`` in the following ways:
27 27
 * **Iteration.** A ``QuerySet`` is iterable, and it executes its database
28 28
   query the first time you iterate over it. For example, this will print
29 29
   the headline of all entries in the database::
30  
-
  30
+  
31 31
       for e in Entry.objects.all():
32 32
           print(e.headline)
33 33
 
  34
+  Note: *Don't* use this if all you want to do is determine if at least one
  35
+  result exists, and don't need the actual objects. It's more efficient to
  36
+  use :meth:`exists() <QuerySet.exists>` (see below).
  37
+
34 38
 * **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can
35 39
   be sliced, using Python's array-slicing syntax. Slicing an unevaluated
36 40
   ``QuerySet`` usually returns another unevaluated ``QuerySet``, but Django
@@ -1523,13 +1527,41 @@ exists
1523 1527
 
1524 1528
 Returns ``True`` if the :class:`.QuerySet` contains any results, and ``False``
1525 1529
 if not. This tries to perform the query in the simplest and fastest way
1526  
-possible, but it *does* execute nearly the same query. This means that calling
1527  
-:meth:`.QuerySet.exists` is faster than ``bool(some_query_set)``, but not by
1528  
-a large degree. If ``some_query_set`` has not yet been evaluated, but you know
1529  
-that it will be at some point, then using ``some_query_set.exists()`` will do
1530  
-more overall work (one query for the existence check plus an extra one to later
1531  
-retrieve the results) than simply using ``bool(some_query_set)``, which
1532  
-retrieves the results and then checks if any were returned.
  1530
+possible, but it *does* execute nearly the same query as a normal :class:`.QuerySet` query.
  1531
+
  1532
+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.
  1533
+
  1534
+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::
  1535
+
  1536
+   known_entry_id = 123
  1537
+   if some_query_set.filter(pk=known_entry_id).exists():
  1538
+       print ("Entry contained in queryset")
  1539
+
  1540
+Which will be faster than::
  1541
+
  1542
+   if e in some_query_set:
  1543
+       print("Entry contained in QuerySet")
  1544
+
  1545
+And to find whether a returned queryset contains any items::
  1546
+
  1547
+   if some_query_set.exists():
  1548
+       print("There is at least one Entry with the headline Test")
  1549
+
  1550
+Which will be faster than::
  1551
+
  1552
+   if some_query_set:
  1553
+       print("There is at least one Entry with the headline Test")
  1554
+
  1555
+...but not by a large degree (hence needing a large queryset for
  1556
+efficiency gains).
  1557
+
  1558
+Additionally, if a ``some_query_set`` has not yet been evaluated, but you know that
  1559
+it will be at some point, then using ``some_query_set.exists()`` 
  1560
+will do more overall work (one query for the existence check plus 
  1561
+an extra one to later retrieve the results) than simply using
  1562
+``bool(some_query_set)``, which retrieves the results and then
  1563
+checks if any were returned.
  1564
+
1533 1565
 
1534 1566
 update
1535 1567
 ~~~~~~
Commit_comment_tip

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.