Ticket #15361: 15361-2.2.diff

docs/ref/models/fields.txt

@@ -162 +162 @@
 hyphen -- that's OK. Django quotes column and table names behind the
 scenes.
 
+.. _field-db_index:
+
 ``db_index``
 ------------
 
@@ -240 +242 @@
 ``primary_key=True`` implies :attr:`null=False <Field.null>` and :attr:`unique=True <Field.unique>`.
 Only one primary key is allowed on an object.
 
+.. _field-unique:
+
 ``unique``
 ----------
 

docs/topics/db/optimization.txt

@@ -132 +132 @@
 </topics/db/sql>`. Use ``django.db.connection.queries`` to find out what Django
 is writing for you and start from there.
 
+Retrieve individual objects using a unique, indexed column
+==========================================================
+
+There are two reasons you want to use :ref:`unique <field-unique>`, 
+:ref:`indexed <field-db_index>`: columns to get individual objects. Firstly,
+the query will be quicker because of the underlying database index. Also 
+the query can run much slower if multiple objects match the lookup; having a 
+unique constraint on the column guarantees this will never happen.
+
+So using the :ref:`example Weblog models <queryset-model-example>`::
+
+  >>> entry = Entry.objects.get(id=10)
+
+will be quicker than the alternative:
+
+  >>> entry = Entry.object.get(headline="News Item Title")
+
+because ``id`` is indexed by the database and is guaranteed to be unique.
+
+Doing the following is potentially quite slow.
+
+  >>> entry = Entry.objects.get(headline__startswith="News")
+
+First of all, `headline` is not indexed, which will make the underlying
+database fetch slower.
+
+Secondly, the lookup doesn't guarantee that only one object will be returned.
+If the query matches more than one object, it will incur the penality for
+retreiving and transferring all of them from the database. This penality could
+be substantial if hundreds or thousands of records are returned. The penality
+will be compounded if the database lives on a separate server, where network
+overhead and latency also play a factor.
+
+
 Retrieve everything at once if you know you will need it
 ========================================================
 

tests/modeltests/basic/tests.py

@@ -1 +1 @@
 from datetime import datetime
 
-from django.core.exceptions import ObjectDoesNotExist
+from django.core.exceptions import ObjectDoesNotExist, MultipleObjectsReturned
 from django.db import models, DEFAULT_DB_ALIAS, connection
 from django.db.models.fields import FieldDoesNotExist
 from django.test import TestCase, skipIfDBFeature, skipUnlessDBFeature
@@ -115 +115 @@
         b = Article.objects.get(pk=a.id)
         self.assertEqual(a, b)
 
+        # Create a very similar object
+        a = Article(
+            id=None,
+            headline='Area man programs in Python',
+            pub_date=datetime(2005, 7, 28),
+        )
+        a.save()
+
+        self.assertEqual(Article.objects.count(), 2)
+
+        # Django raises an Article.MultipleObjectsReturned exception if the
+        # lookup matches more than one object
+        self.assertRaisesRegexp(
+            MultipleObjectsReturned,
+            "get\(\) returned more than one Article -- it returned 2! Lookup parameters were {'headline__startswith': 'Area'}",
+            Article.objects.get,
+            headline__startswith='Area',
+        )
+
+        self.assertRaisesRegexp(
+            MultipleObjectsReturned,
+            "get\(\) returned more than one Article -- it returned 2! Lookup parameters were {'pub_date__year': 2005}",
+            Article.objects.get,
+            pub_date__year=2005,
+        )
+
+        self.assertRaisesRegexp(
+            MultipleObjectsReturned,
+            "get\(\) returned more than one Article -- it returned 2! Lookup parameters were {'pub_date__month': 7, 'pub_date__year': 2005}",
+            Article.objects.get,
+            pub_date__year=2005,
+            pub_date__month=7,
+        )
+
     def test_object_creation(self):
         # Create an Article.
         a = Article(