From b2f72fc0405e966a5c4dbce23e84a43d80db3614 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Fri, 24 Jul 2009 13:38:36 +0000 Subject: Fixed #11527 -- Added unit tests and documentation for the use of F() expressions in single object updates. Thanks to Zachary Voase for the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11322 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/instances.txt | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index c6509ece3d..7a0606dafe 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -188,6 +188,46 @@ almost always do the right thing and trying to override that will lead to errors that are difficult to track down. This feature is for advanced use only. +Updating attributes based on existing fields +-------------------------------------------- + +Sometimes you'll need to perform a simple arithmetic task on a field, such +as incrementing or decrementing the current value. The obvious way to +achieve this is to do something like:: + + >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') + >>> product.number_sold += 1 + >>> product.save() + +If the old ``number_sold`` value retrieved from the database was 10, then +the value of 11 will be written back to the database. + +This can be optimized slightly by expressing the update relative to the +original field value, rather than as an explicit assignment of a new value. +Django provides :ref:`F() expressions ` as a way of +performing this kind of relative update. Using ``F()`` expressions, the +previous example would be expressed as:: + + >>> from django.db.models import F + >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') + >>> product.number_sold = F('number_sold') + 1 + >>> product.save() + +This approach doesn't use the initial value from the database. Instead, it +makes the database do the update based on whatever value is current at the +time that the save() is executed. + +Once the object has been saved, you must reload the object in order to access +the actual value that was applied to the updated field:: + + >>> product = Products.objects.get(pk=product.pk) + >>> print product.number_sold + 42 + +For more details, see the documentation on :ref:`F() expressions +` and their :ref:`use in update queries +`. + Deleting objects ================ @@ -196,7 +236,7 @@ Deleting objects Issues a SQL ``DELETE`` for the object. This only deletes the object in the database; the Python instance will still be around, and will still have data in its fields. - + For more details, including how to delete objects in bulk, see :ref:`topics-db-queries-delete`. -- cgit v1.3