当您�存的时候�生了什么?

当您�存一个对象的时候, Django执行下�的步骤:

�出一个预存信�。 它�出一个将�存储一个对象的通知。你�以注册一个监�程�，在信��出的时候就会被调用。到本书出版时，这些信��在开�中并且没有文档化，请查看在线文档�获得最新的消�。

预处�数�. 对于对象的�个字段，将根�需�进行自动的数�修改。

大部分字段并�预处�，它们会��它们原�的样�。预处�仅仅用在那些有特殊性质的字段，比如文件字段。

为数�库准备数�。 �一个字段先�把当�值转化�数�库中�以�存的数�的类型。

大多数字段的数��需�预先准备。简�的数�类型，比如整型和字符串等python对象�以直接写进数�库。然而，更��的数�类型需��一些修改。比如， DateFields 使用python的 datetime 对象�存储数�。数�库并�能存储 datetime 对象，所以该字段�存入数�库先�把值转化为符�ISO标准的日期字符串。

�数�库中�入数�。 �过预处�准备好的数�然�会组��一�SQL语���入数�库。

�出存毕信�。 与预存信�类似，存毕信�在对象�功�存之��出。�样，这些信�也还没有文档化。

自增主键

为了方便，�个数�库模型都会添加一个自增主键字段，� id 。除�你在�个字段属性中显�的指定 primary_key=True （��附录B中题为AutoField的章节）。

如果你的数�库模型中包括 AutoField ，这个自增�的值将会在你第一次调用 save() 时作为对象的一个属性计算得出并�存起�。

>>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b2.id     # Returns None, because b doesn't have an ID yet.
None

>>> b2.save()
>>> b2.id     # Returns the ID of your new object.
14

在调用 save() 方法之�没有办法知�ID的值，因为这个值是数�库计算出�的，�是Django。

如果你想在一个新数�存储时，定义其 AutoField 字段值，而��赖于数�库自动分�，明确赋值��。

>>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b3.id
3
>>> b3.save()
>>> b3.id
3

如果你手动指定自增主键的值，�确�这个主键在数�库中�存在�如果你显�地指定主键�创建新对象，而这个主键在数�库中已�存在的�，Django会认为你�更改已�存在的那�记录，而�是创建一个新的。

以��的 'Cheddar Talk' blog为例，下�的例�会覆盖数�库中已�存在的记录：

>>> b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.')
>>> b4.save()  # Overrides the previous blog with ID=3!

如果你确信�会产生主键冲�的�，当需��存大�对象的时候，明确指定自增主键的值是�常有用的。

级�过滤器

细化过的 QuerySet 本身就是一个 QuerySet ，所以�以进一步细化，比如：

>>> qs = Entry.objects.filter(headline__startswith='What')
>>> qs = qs..exclude(pub_date__gte=datetime.datetime.now())
>>> qs = qs.filter(pub_date__gte=datetime.datetime(2005, 1, 1))

这样，我们把最�过的数�库中所有内容的一个 QuerySet �过添加一个过滤器�一个��过滤器和�外一个过滤器，得到一个最终的 QuerySet ，最终结果中包�了所有标题以“What�开头的2005年至今的出版的�目。

这里需�指出的一点是，创建一个 QuerySet 并�会牵涉到任何数�库动作。事实上，上�的三行并�会产生 任何的 数�库调用。就是说你�以连接任�多个过滤器，��你�把这个 QuerySet 用于赋值的�，Django是�会执行查询的。

你�以用下�的方法�计算 QuerySet 的值：

迭代 ： QuerySet 是�以迭代的，它会在迭代结�的时候执行数�库查询。例如，下�的这个 QuerySet 在for循环迭代完毕之�，是�会被赋值的：

qs = Entry.objects.filter(pub_date__year=2006)
qs = qs.filter(headline__icontains="bill")
for e in qs:
    print e.headline

它会打�2006年所有包�bill的标题，但�会触�一次数�库访问。

打� ：对 QuerySet 使用 repr() 方法时，它是会被赋值的。这是为了方便Python的交互解释器，这样在交互环境中使用API时就会立刻看到结果。

切片 ： 在接下�的“��查询集�一节中就会解释这一点， QuerySet 是�以用Python的数组切片的语法�切片的。通常切片过的 QuerySet 会返回�外一个（尚未赋值的） QuerySet ，但是如果在切片时使用步长�数的�，Django会执行数�库查询的。

转化�列表 ：对 QuerySet 调用 list() 方法的�，就�以对它强制赋值，比如：

>>> entry_list = list(Entry.objects.all())

但是，需�警告的是这样�会导致很大的内存负载，因为Django会把列表的�一个元素加载到内存。相比之下，对 QuerySet 进行迭代会利用数�库�加载数�，并且在需�的时候�会把对象实例化。

过滤过的查询集是独一无二的

你�次细化一个 QuerySet 都会得到一个崭新的 QuerySet ，��会与之�的 QuerySet 有任何的瓜葛。�次的细化都会创建一个�自的截然��的 QuerySet ，�以用�存储�使用和�用。

q1 = Entry.objects.filter(headline__startswith="What")
q2 = q1.exclude(pub_date__gte=datetime.now())
q3 = q1.filter(pub_date__gte=datetime.now())

这三个 QuerySet 是无关的。第一个基础查询集包�了所有标题以What开始的�目。第二个查询集是第一个的�集，�是过滤掉了 pub_date 比当�时间大的记录。第三个查询集也是第一个的�集，��留 pub_date 比当�时间大的记录。�始的 QuerySet （ q1 ）是��细化过程的影�。

��查询集

�以用Python的数�切片的语法��定 QuerySet 的结果数�，这和SQL中的 LIMIT 和 OFFSET 语�是一样的。

比如，这�返回�五个�目（ LIMIT 5 ）：

>>> Entry.objects.all()[:5]

这�返回第六到第�个�目（ OFFSET 5 LIMIT 5 ）：

>>> Entry.objects.all()[5:10]

一般地，对 QuerySet 进行切片会返回一个新的 QuerySet ，但并�执行查询。如果你在Python切片语法中使用步长�数的�，就会出现特例。例如，�返回��个对象中的��数对象的列表时，实际上会执行查询：

>>> Entry.objects.all()[:10:2]

�得到 �个 对象而�是一个列表时（例如 SELECT foo FROM bar LIMIT 1 ），�以�用切片而是使用下标。例如，这样就会返回数�库中对标题进行字�排��的第一个 Entry ：

>>> Entry.objects.order_by('headline')[0]

刚�这�和下�的大致相当：

>>> Entry.objects.order_by('headline')[0:1].get()

但是�记�，如果没有符��件的记录的�，第一�用法会导致 IndexError ，而第二�用法会导致 DoesNotExist 。

返回新的 QuerySets 的 查询方法

Django�供了一系列的 QuerySet 细化方法，既�以修改 QuerySet 返回的结果的类型，��以修改对应的SQL查询的执行方法。这就是这一节我们�讨论的内容。其中有一些细化方法会接收字段查询�数，我们��会详细讨论。

>> Entry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline')

>>> Entry.objects.order_by('?')

# This list contains a Blog object.
>>> Blog.objects.filter(name__startswith='Beatles')
[Beatles Blog]

# This list contains a dictionary.
>>> Blog.objects.filter(name__startswith='Beatles').values()
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]

>>> Blog.objects.values()
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}],
>>> Blog.objects.values('id', 'name')
[{'id': 1, 'name': 'Beatles Blog'}]

>>> Entry.objects.dates('pub_date', 'year')
[datetime.datetime(2005, 1, 1)]

>>> Entry.objects.dates('pub_date', 'month')
[datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)]

>>> Entry.objects.dates('pub_date', 'day')
[datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)]

>>> Entry.objects.dates('pub_date', 'day', order='DESC')
[datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]

>>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
[datetime.datetime(2005, 3, 20)]

# Hits the database.
>>> e = Entry.objects.get(id=5)

# Hits the database again to get the related Blog object.
>>> b = e.blog

# Hits the database.
>>> e = Entry.objects.select_related().get(id=5)

# Doesn't hit the database, because e.blog has been prepopulated
# in the previous query.
>>> b = e.blog

class City(models.Model):
    # ...

class Person(models.Model):
    # ...
    hometown = models.ForeignKey(City)

class Book(models.Model):
    # ...
    author = models.ForeignKey(Person)

>>> b = Book.objects.select_related().get(id=4)
>>> p = b.author         # Doesn't hit the database.
>>> c = p.hometown       # Doesn't hit the database.

>>> b = Book.objects.get(id=4) # No select_related() in this example.
>>> p = b.author         # Hits the database.
>>> c = p.hometown       # Hits the database.

>>> Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})

>>> subq = 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'
>>> Blog.objects.extra(select={'entry_count': subq})

>>> Entry.objects.extra(where=['id IN (3, 4, 5, 20)'])

>>> Entry.objects.extra(where=['headline=%s'], params=['Lennon'])

Entry.objects.extra(where=["headline='%s'" % name])

Entry.objects.extra(where=['headline=%s'], params=[name])

QuerySet Methods That Do Not Return QuerySets

The following QuerySet methods evaluate the QuerySet and return something otherthan a QuerySet a single object, value, and so forth.

>>> Entry.objects.get(id='foo') # raises Entry.DoesNotExist

>>> from django.core.exceptions import ObjectDoesNotExist
>>> try:
...     e = Entry.objects.get(id=3)
...     b = Blog.objects.get(id=1)
... except ObjectDoesNotExist:
...     print "Either the entry or blog doesn't exist."

>>> p = Person(first_name="Bruce", last_name="Springsteen")
>>> p.save()

>>> p = Person.objects.create(first_name="Bruce", last_name="Springsteen")

try:
    obj = Person.objects.get(first_name='John', last_name='Lennon')
except Person.DoesNotExist:
    obj = Person(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9))
    obj.save()

obj, created = Person.objects.get_or_create(
    first_name = 'John',
    last_name  = 'Lennon',
    defaults   = {'birthday': date(1940, 10, 9)}
)

defaults = kwargs.pop('defaults', {})
params = dict([(k, v) for k, v in kwargs.items() if '__' not in k])
params.update(defaults)
obj = self.model(**params)
obj.save()

Foo.objects.get_or_create(
    defaults__exact = 'bar',
    defaults={'defaults': 'baz'}
)

# Returns the total number of entries in the database.
>>> Entry.objects.count()
4

# Returns the number of entries whose headline contains 'Lennon'
>>> Entry.objects.filter(headline__contains='Lennon').count()
1

>>> Blog.objects.in_bulk([1])
{1: Beatles Blog}
>>> Blog.objects.in_bulk([1, 2])
{1: Beatles Blog, 2: Cheddar Talk}
>>> Blog.objects.in_bulk([])
{}

>>> Entry.objects.latest('pub_date')

exact

Performs an exact match:

>>> Entry.objects.get(headline__exact="Man bites dog")

This matches any object with the exact headline Man bites dog.

If you dont provide a lookup type that is, if your keyword argument doesnt contain a double underscore the lookup type is assumed to be exact .

例如，下�两个语�是等效的：

>>> Blog.objects.get(id__exact=14) # Explicit form
>>> Blog.objects.get(id=14) # __exact is implied

This is for convenience, because exact lookups are the common case.

iexact

字符串比较（大�写无关）

>>> Blog.objects.get(name__iexact='beatles blog')

This will match 'Beatles Blog' , 'beatles blog' , 'BeAtLes BLoG' , and so forth.

contains

执行严格区分大�写的内容包�检测：

Entry.objects.get(headline__contains='Lennon')

这将会匹é…�标题为``’Today Lennon honored’`` 的，而ä¸�匹é…� ``‘today lennon honored’``。

SQLite�支�严格区分大�写的 LIKE 语�，所以在使用SQLite时``contains``的作用和``icontains``一样。

除了LIKE语�中的百分�和下划线

使用相当于``LIKE``的SQL查找语�(iexact , contains , icontains, startswith, istartswith, endswith, 和``iendswith``)时，会自动的排除``LIKE``语�中使用的两个特殊符�：百分��下划线。（在一�``LIKE``语�中，百分�是多个字符的通�符，下划线是�个字符的通�符）

这�味�使用的直观性，所以�会产生���的。例如，查找所有�有一个百分�的项，�需�想用其他字符一样用一个百分�：

Entry.objects.filter(headline__contains='%')

Django 为你处�了这一引用。产生的SQL如下：

SELECT ... WHERE headline LIKE '%\%%';

The same goes for underscores. Both percentage signs and underscores are handled for you transparently.

icontains

执行一个忽略大�写的内容包�检测：

>>> Entry.objects.get(headline__icontains='Lennon')

与``contains``��, icontains 会 匹� 'today lennon honored' 。

gt, gte, lt, and lte

这些�大于，大于或等于，�于，�于或等于:

>>> Entry.objects.filter(id__gt=4)
>>> Entry.objects.filter(id__lt=15)
>>> Entry.objects.filter(id__gte=0)

这些查询分别返回 ID 大于 4，ID �于 15，以� ID 大于等于 0 的对象。

Youll usually use these on numeric fields. Be careful with character fields since character order isnt always what youd expect (i.e., the string 4 sorts after the string 10).

in

筛选出包�在给定列表中的数�：

Entry.objects.filter(id__in=[1, 3, 4])

这会返回所有ID为1，3，或4的�目。

startswith

区分大�写的开头匹�：

>>> Entry.objects.filter(headline__startswith='Will')

这将返回标题Will he run?和Willbur named judge，但是�会返回Who is Will? 和will found in crypt.

istartswith

Performs a case-insensitive starts-with:

>>> Entry.objects.filter(headline__istartswith='will')

This will return the headlines Will he run?, Willbur named judge, and will found in crypt, but not Who is Will?

endswith and iendswith

区分大�写和忽略大�写的末尾匹�。

>>> Entry.objects.filter(headline__endswith='cats')
>>> Entry.objects.filter(headline__iendswith='cats')

range

Performs an inclusive range check:

>>> start_date = datetime.date(2005, 1, 1)
>>> end_date = datetime.date(2005, 3, 31)
>>> Entry.objects.filter(pub_date__range=(start_date, end_date))

You can use range anywhere you can use BETWEEN in SQL for dates, numbers, and even characters.

year, month, and day

对date/datetime类型严格匹�年�月或日：

# Year lookup
>>>Entry.objects.filter(pub_date__year=2005)

# Month lookup -- takes integers
>>> Entry.objects.filter(pub_date__month=12)

# Day lookup
>>> Entry.objects.filter(pub_date__day=3)

# Combination: return all entries on Christmas of any year
>>> Entry.objects.filter(pub_date__month=12, pub_date_day=25)

isnull

使用``True``或``False``，则分别相当于SQL语�中的``IS NULL``和``IS NOT NULL``:

>>> Entry.objects.filter(pub_date__isnull=True)

__isnull=True vs. __exact=None

__isnull=True``和``__exact=None``有一个很主�的区别。因为SQL规定无值就等于``NULL ，所以``__exact=None``会 总是 返回一个空的结果。``__isnull``则�决于该阈是�当�有值 ``NULL``而�进行比较。

search

A Boolean full-text search that takes advantage of full-text indexing. This is like contains but is significantly faster due to full-text indexing.

Note this is available only in MySQL and requires direct manipulation of the database to add the full-text index.

The pk Lookup Shortcut

For convenience, Django provides a pk lookup type, which stands for primary_key.

In the example Blog model, the primary key is the id field, so these three statements are equivalent:

>>> Blog.objects.get(id__exact=14) # Explicit form
>>> Blog.objects.get(id=14) # __exact is implied
>>> Blog.objects.get(pk=14) # pk implies id__exact

The use of pk isnt limited to __exact queries any query term can be combined with pk to perform a query on the primary key of a model:

# Get blogs entries  with id 1, 4, and 7
>>> Blog.objects.filter(pk__in=[1,4,7])

# Get all blog entries with id > 14
>>> Blog.objects.filter(pk__gt=14)

pk lookups also work across joins. For example, these three statements are equivalent:

>>> Entry.objects.filter(blog__id__exact=3) # Explicit form
>>> Entry.objects.filter(blog__id=3) # __exact is implied
>>> Entry.objects.filter(blog__pk=3) # __pk implies __id__exact

多对多关系

在多对多关系的两端，都�以通过相应的API�访问�外的一端。 API的工作方�跟�一节所�述的��一对多关系差�多。

唯一的��在于属性的命�：定义了``ManyToManyField``的model的实例使用属性�称本身，�外一端的model的实例则使用model�称的�写加上``_set``�活得关�的对象集（就跟��一对多关系一样）

用例��说明一下大家会更容易�解：

e = Entry.objects.get(id=3)
e.authors.all() # Returns all Author objects for this Entry.
e.authors.count()
e.authors.filter(name__contains='John')

a = Author.objects.get(id=5)
a.entry_set.all() # Returns all Entry objects for this Author.

Like ForeignKey , ManyToManyField can specify related_name . In the preceding example, if the ManyToManyField in Entry had specified related_name='entries' , then each Author instance would have an entries attribute instead of entry_set .

How Are the Backward Relationships Possible?

Other object-relational mappers require you to define relationships on both sides. The Django developers believe this is a violation of the DRY (Dont Repeat Yourself) principle, so Django requires you to define the relationship on only one end. But how is this possible, given that a model class doesnt know which other model classes are related to it until those other model classes are loaded?

The answer lies in the INSTALLED_APPS setting. The first time any model is loaded, Django iterates over every model in INSTALLED_APPS and creates the backward relationships in memory as needed. Essentially, one of the functions of INSTALLED_APPS is to tell Django the entire model domain.

通过关�对象查询

包�关�对象的�索和包�普通字段的�索�循相�的规则。当指定一个值去查询时，你�以使用那个对象的一个实例，也�以使用它的主键值。

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

get_FOO_display()

For every field that has choices set, the object will have a get_FOO_display() method, where FOO is the name of the field. This method returns the human-readable value of the field. For example, in the following model:

GENDER_CHOICES = (
    ('M', 'Male'),
    ('F', 'Female'),
)
class Person(models.Model):
    name = models.CharField(max_length=20)
    gender = models.CharField(max_length=1, choices=GENDER_CHOICES)

�一个 Person 实例都将有一个 get_gender_display() 方法：

>>> p = Person(name='John', gender='M')
>>> p.save()
>>> p.gender
'M'
>>> p.get_gender_display()
'Male'

get_next_by_FOO(**kwargs) and get_previous_by_FOO(**kwargs)

对于任何ä¸�å…�许空值的DateFieldå’ŒDateTimeField字段，将会有”get_next_by_FOO()”å’Œ”get_previous_by_FOO()”这两个方法。FOO表示字段å��。这两个方法将根æ�®ç»™å®šçš„日期字段返回其å‰�一个ã€�å�Žä¸€ä¸ªå¯¹è±¡ï¼Œé€‚当的时候会抛出”DoesNotExist”的异常。

两�方法都接��选的关键��数，这些�数应该�循 “域查询�一节中的格�。

Note that in the case of identical date values, these methods will use the ID as a fallback check. This guarantees that no records are skipped or duplicated. For a full example, see the lookup API samples at http://www.djangoproject.com/documentation/0.96/models/lookup/.

get_FOO_filename()

For every FileField , the object will have a get_FOO_filename() method, where FOO is the name of the field. This returns the full filesystem path to the file, according to your MEDIA_ROOT setting.

注�到 ``ImageField``从技术上是 ``FileField``的�类，所以�个有``ImageField``的模型都有这个方法。

get_FOO_url()

For every FileField , the object will have a get_FOO_url() method, where FOO is the name of the field. This returns the full URL to the file, according to your MEDIA_URL setting. If the value is blank, this method returns an empty string.

get_FOO_size()

For every FileField , the object will have a get_FOO_size() method, where FOO is the name of the field. This returns the size of the file, in bytes. (Behind the scenes, it uses os.path.getsize .)

save_FOO_file(filename, raw_contents)

For every FileField , the object will have a save_FOO_file() method, where FOO is the name of the field. This saves the given file to the filesystem, using the given file name. If a file with the given file name already exists, Django adds an underscore to the end of the file name (but before the extension) until the file name is available.

get_FOO_height() and get_FOO_width()

For every ImageField , the object will have get_FOO_height() and get_FOO_width() methods, where FOO is the name of the field. This returns the height (or width) of the image, as an integer, in pixels.

get_object_or_404()

One common idiom to use get() and raise Http404 if the object doesnt exist. This idiom is captured by get_object_or_404() . This function takes a Django model as its first argument and an arbitrary number of keyword arguments, which it passes to the default managers get() function. It raises Http404 if the object doesnt exist, for example:

# Get the Entry with a primary key of 3
e = get_object_or_404(Entry, pk=3)

When you provide a model to this shortcut function, the default manager is used to execute the underlying get() query. If you dont want to use the default manager, or if you want to search a list of related objects, you can provide get_object_or_404() with a Manager object instead:

# Get the author of blog instance e with a name of 'Fred'
a = get_object_or_404(e.authors, name='Fred')

# Use a custom manager 'recent_entries' in the search for an
# entry with a primary key of 3
e = get_object_or_404(Entry.recent_entries, pk=3)

get_list_or_404()

get_list_or_404 行为与 get_object_or_404() 相�，但是它用 filter() �代了 get() 。如果列表为空，它将引� Http404 。