Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #13418 -- Added notes on uniqueness requirements for natural ke…

…ys. Thanks to hunajakippo for the suggestion, and Ramiro Morales for the draft text.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13146 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 5a2324afb2f46e86b2e61b2ae983b09715d13891 1 parent e7e46d1
Russell Keith-Magee authored May 09, 2010

Showing 1 changed file with 29 additions and 6 deletions. Show diff stats Hide diff stats

  1. 35  docs/topics/serialization.txt
35  docs/topics/serialization.txt
@@ -197,6 +197,7 @@ Natural keys
197 197
 ------------
198 198
 
199 199
 .. versionadded:: 1.2
  200
+
200 201
    The ability to use natural keys when serializing/deserializing data was
201 202
    added in the 1.2 release.
202 203
 
@@ -219,13 +220,13 @@ There is also the matter of convenience. An integer id isn't always
219 220
 the most convenient way to refer to an object; sometimes, a
220 221
 more natural reference would be helpful.
221 222
 
222  
-Deserialization of natural keys
223  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
224  
-
225  
-It is for these reasons that Django provides `natural keys`. A natural
  223
+It is for these reasons that Django provides *natural keys*. A natural
226 224
 key is a tuple of values that can be used to uniquely identify an
227 225
 object instance without using the primary key value.
228 226
 
  227
+Deserialization of natural keys
  228
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  229
+
229 230
 Consider the following two models::
230 231
 
231 232
     from django.db import models
@@ -236,6 +237,9 @@ Consider the following two models::
236 237
 
237 238
         birthdate = models.DateField()
238 239
 
  240
+        class Meta:
  241
+            unique_together = (('first_name', 'last_name'),)
  242
+
239 243
     class Book(models.Model):
240 244
         name = models.CharField(max_length=100)
241 245
         author = models.ForeignKey(Person)
@@ -278,6 +282,9 @@ name::
278 282
 
279 283
         birthdate = models.DateField()
280 284
 
  285
+        class Meta:
  286
+            unique_together = (('first_name', 'last_name'),)
  287
+
281 288
 Now books can use that natural key to refer to ``Person`` objects::
282 289
 
283 290
     ...
@@ -295,6 +302,17 @@ When you try to load this serialized data, Django will use the
295 302
 ``get_by_natural_key()`` method to resolve ``["Douglas", "Adams"]``
296 303
 into the primary key of an actual ``Person`` object.
297 304
 
  305
+.. note::
  306
+
  307
+    Whatever fields you use for a natural key must be able to uniquely
  308
+    identify an object. This will usually mean that your model will
  309
+    have a uniqueness clause (either unique=True on a single field, or
  310
+    ``unique_together`` over multiple fields) for the field or fields
  311
+    in your natural key. However, uniqueness doesn't need to be
  312
+    enforced at the database level. If you are certain that a set of
  313
+    fields will be effectively unique, you can still use those fields
  314
+    as a natural key.
  315
+
298 316
 Serialization of natural keys
299 317
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
300 318
 
@@ -312,8 +330,13 @@ Firstly, you need to add another method -- this time to the model itself::
312 330
         def natural_key(self):
313 331
             return (self.first_name, self.last_name)
314 332
 
315  
-Then, when you call ``serializers.serialize()``, you provide a
316  
-``use_natural_keys=True`` argument::
  333
+        class Meta:
  334
+            unique_together = (('first_name', 'last_name'),)
  335
+
  336
+That method should always return a natural key tuple -- in this
  337
+example, ``(first name, last name)``. Then, when you call
  338
+``serializers.serialize()``, you provide a ``use_natural_keys=True``
  339
+argument::
317 340
 
318 341
     >>> serializers.serialize([book1, book2], format='json', indent=2, use_natural_keys=True)
319 342
 

0 notes on commit 5a2324a

Please sign in to comment.
Something went wrong with that request. Please try again.