Refs #2217 -- Updated DB API docs to discuss filtering using objects rather than IDs. Second attempt - forgot to save before commit last time.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@3302 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 10 insertions, 4 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 64f3438014..ce6bb0ab3b 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -1555,11 +1555,17 @@ of ``INSTALLED_APPS`` is to tell Django the entire model domain.
 Queries over related objects
 ----------------------------
 
-When specifying a query over a related object, you have the option of 
-
-    b = Blog.objects.get(id=5)
-    e1 = Entry.objects.filter()
+Queries involving related objects follow the same rules as queries involving
+normal value fields. When specifying the the value for a query to match, you 
+may use either an object instance itself, or the primary key value for the 
+object.
 
+For example, if you have a Blog object ``b`` with ``id=5``, the following
+three queries would be identical::
+     
+    Entry.objects.filter(blog=b) # Query using object instance
+    Entry.objects.filter(blog=b.id) # Query using id from instance
+    Entry.objects.filter(blog=5) # Query using id directly
 
 Deleting objects
 ================