实现细节

Python 能够在定义函数时接受任意的 name-value(names和values均可以在运行时通过计算得到)参数. 要了解更多信息,参阅官方 Python 教程中的 关键字参数 .

OR 查询

关键字参数查询的各个条件都是 "AND" 关系. 如果你需要一个复杂的查询(举例来说,你需要一个 OR 语句), 你需要使用 Q 对象.

Q 对象是 django.core.meta.Q 的实例, 用来装载一系列关键字参数. 这些关键字参数就象指定给 get() 和 filter() 函数的关键字参数一样. 举例来说:

Q(question__startswith=‘What‘)

Q 对象可以使用 & 和 | 运算符进行组合. 当两个Q对象进行 & 或 | 运算时,会生成一个新的Q对象.举例来说语句:

Q(question__startswith=‘Who‘) | Q(question__startswith=‘What‘)

... 生成一个新的 Q 对象表示这两个 "question__startswith" 查询条件的 "OR" 关系. 等同于下面的 SQL WHERE 子句:

... WHERE question LIKE ‘Who%‘ OR question LIKE ‘What%‘

通过对多个 Q 对象的 & 和 | 运算你能得到任意复杂的查询语句. 也可以使用圆括号分组.

查询函数可以接受一个或多个 Q 对象作为参数.如果提供有多个 Q 对象参数, 它们将被 "AND" 到一起. 举例来说:

polls.get_object(
    Q(question__startswith=‘Who‘),
    Q(pub_date__exact=date(2005, 5, 2)) | Q(pub_date__exact=date(2005, 5, 6))
)

... 翻译成 SQL 就是这样:

SELECT * from polls WHERE question LIKE ‘Who%‘
    AND (pub_date = ‘2005-05-02‘ OR pub_date = ‘2005-05-06‘)

如果需要,查询函数可以混合使用 Q 对象参数和关键字参数. 所有提供给查询函数的参数(不管是关键字参数还是Q对象)都被 "AND" 到一起. 如果提供了 Q 对象作为参数,它就必须在其它关键字参数(如果有的话)的前面. 举例来说:

polls.get_object(
    Q(pub_date__exact=date(2005, 5, 2)) | Q(pub_date__exact=date(2005, 5, 6)),
    question__startswith=‘Who‘)

... 这是一个合法的查询, 等价于前一个例子,不过:

# INVALID QUERY
polls.get_object(
    question__startswith=‘Who‘,
    Q(pub_date__exact=date(2005, 5, 2)) | Q(pub_date__exact=date(2005, 5, 6)))

... 这个查询则不符合我们的规则,会引发异常.

Q 对象也可以以 complex 关键字参数的形式使用. 举例来说:

polls.get_object(
    complex=Q(question__startswith=‘Who‘) &
        (Q(pub_date__exact=date(2005, 5, 2)) |
         Q(pub_date__exact=date(2005, 5, 6))
    )
)

参阅 OR 查询示例 以阅读更多实例.

get(**kwargs)

以下文描述的 "字段查询" 格式返回匹配查找参数的对象.如果没有找到符合给定参数的对象,会引发一个模块级的 DoesNotExist 异常. 如果找到不止一个对象,引发AssertionError 异常.

count()

返回结果集的行数.``count()`` 永远不会引发异常.

根据你使用的数据库引擎 (比如 PostgreSQL vs. MySQL), 它可能返回一个长整数而不是普通整数.

in_bulk(id_list)

接受一个 ID 列表作为参数, 返回一个字典(每个ID映射一个具有给定ID的对象实例). 也接受可选的关键字查询参数(参数格式在下面 "字段查询" 小节有描述),这里有一个例子,使用上面定义的 Poll model.

>>> Poll.objects.in_bulk([1])
{1: What‘s up?}
>>> Poll.objects.in_bulk([1, 2])
{1: What‘s up?, 2: What‘s your name?}
>>> Poll.objects.in_bulk([])
{}

latest(field_name=None)

根据 model 的 ‘get_latest_by‘ 选项或可选的字段名参数返回最新的对象. 例子:

>>> Poll.objects.latest()
What‘s up?
>>> Poll.objects.latest(‘expire_date‘)
What‘s your name?

One-to-one relations

one-to-one 关系中的每个对象拥有一个 get_relatedobjectname() 方法. 举例来说:

class Place(meta.Model):
    # ...

class Restaurant(meta.Model):
    # ...
    the_place = meta.OneToOneField(places.Place)

在上面的例子里, 每个 Place 会自动拥有一个 get_restaurant() 方法, 且每个 Restaurant 会自动拥有一个 get_the_place() 方法.

Many-to-one relations

在 many-to-one 关系中, 关联对象(Many)会自动拥有一个 get_relatedobject() 方法. 被关联的对象(one)会自动拥有 get_relatedobject(),get_relatedobject_list(), 和 get_relatedobject_count() 方法 (功能与模块级的 get_object(), filter(), 和 get_count() 相同).

在上面的民意测试例子里, 一个 Poll 对象 p 自动拥有下列方法:

p.get_choice()
p.get_choice_list()
p.get_choice_count()

Choice 对象 c 则自动拥有下面的方法:

c.get_poll()

Many-to-many 关系

Many-to-many 关系类似`Many-to-one relations`_, 它生成同样的方法集.例外的是关联对象的 get_relatedobject_list() 方法返回一个实例的列表而不是一个仅一个实例.因此,若 Poll 和 Choice 是 many-to-many 关系, choice.get_poll_list() 将返回一个列表.

order_by(*fields)

根据 model 中提供 ordering tuple, 结果集会被自动排序. 不过, 排序也可以通过 order_by 方法显式的进行:

Poll.objects.filter(pub_date__year=2005,
    pub_date__month=1).order_by(‘-pub_date‘, ‘question‘)

结果集将按降序排列 pub_date, 然后按升序排列 question."-pub_date" 中的负号表示降序(递减).要取随机序,使用"?", 象下面这样:

Poll.objects.order_by=(‘?‘)

要按另一个表中的字段排序, 添加另一个表的名字和一个句点,象下面这样:

Choice.objects.order_by=(‘Poll.pub_date‘, ‘choice‘)

无法指定排序是否大小写敏感, 不管你的数据库后端如何排序, Django都会以大小写敏感的方式重新排序结果集.. (这样是不是会降低效率? 不能关掉这个特性么?)

distinct()

默认的, 一个结果集不会自动除去重复的行. 尤其当你进行跨关系查询时, 很容易出现重复的行.

distinct() 返回一个除去了重复行的新的结果集,它等价于 SELECT DISTINCT SQL 语句.

values(*fields)

类似 filter(), 不过它返回一个字典的列表而不是 model 实例对象的列表.

它接受一个可选参数: fields, 这是一个字段名列表或tuple.如果你没有指定 fields, 每个字段都会返回.否则就只返回你指定的字段名和值.这里有一个例子,使用上面定义的 Poll model

>>> from datetime import datetime
>>> p1 = Poll(slug=‘whatsup‘, question="What‘s up?",
...     pub_date=datetime(2005, 2, 20), expire_date=datetime(2005, 3, 20))
>>> p1.save()
>>> p2 = Poll(slug=‘name‘, question="What‘s your name?",
...     pub_date=datetime(2005, 3, 20), expire_date=datetime(2005, 4, 20))
>>> p2.save()
>>> Poll.objects.all()
[What‘s up?, What‘s your name?]
>>> Poll.objects.values()
[{‘id‘: 1, ‘slug‘: ‘whatsup‘, ‘question‘: "What‘s up?", ‘pub_date‘: datetime.datetime(2005, 2, 20), ‘expire_date‘: datetime.datetime(2005, 3, 20)},
 {‘id‘: 2, ‘slug‘: ‘name‘, ‘question‘: "What‘s your name?", ‘pub_date‘: datetime.datetime(2005, 3, 20), ‘expire_date‘: datetime.datetime(2005, 4, 20)}]
>>> Poll.objects.values(fields=[‘id‘, ‘slug‘])
[{‘id‘: 1, ‘slug‘: ‘whatsup‘}, {‘id‘: 2, ‘slug‘: ‘name‘}]

当你知道你要取得哪些字段的值时并且你不需要那些 model实例对象的功能时,使用 values() 函数.它具有上佳的效率..

dates(field, kind, order=‘ASC‘)

每个管理器拥有一个 dates() 方法, 它返回一个 datetime.datetime 对象的列表, 表示经过给定的过滤器(由 kind 参数定义)过滤后的所有可用的 dates .

field 是 model 模块中的一个 DateField 或 DateTimeField 属性名.

kind 是 "year", "month" 或 "day" 中的一个. 结果列表中的每个 datetime.datetime 对象被截短为给定的 type 形式.

• "year" 返回一个该字段的不重复的年的列表.
• "month" 返回一个该字段的不重复的年/月的列表.
• "day" 返回一个该字段的不重复的年/月/日的列表.

order 只能是 "ASC" 或 "DESC", 默认值是 ‘ASC‘. 它指定如何排序结果.

这里有一个例子, 使用上面定义的 Poll model

>>> from datetime import datetime
>>> p1 = Poll(slug=‘whatsup‘, question="What‘s up?",
...     pub_date=datetime(2005, 2, 20), expire_date=datetime(2005, 3, 20))
>>> p1.save()
>>> p2 = Poll(slug=‘name‘, question="What‘s your name?",
...     pub_date=datetime(2005, 3, 20), expire_date=datetime(2005, 4, 20))
>>> p2.save()
>>> Poll.objects.dates(‘pub_date‘, ‘year‘)
[datetime.datetime(2005, 1, 1)]
>>> Poll.objects.dates(‘pub_date‘, ‘month‘)
[datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)]
>>> Poll.objects.dates(‘pub_date‘, ‘day‘)
[datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)]
>>> Poll.objects.dates(‘pub_date‘, ‘day‘, order=‘DESC‘)
[datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]
>>> Poll.objects.filter(question__contains=‘name‘).dates(‘pub_date‘, ‘day‘)
[datetime.datetime(2005, 3, 20)]

select_related()

关系是数据库的根本, select_related() 方法"追踪" 所有的关系对象, 并将它们预先存放到一个简单的缓存中.这样当需要调用一个具有一对多关系的对象时就不必再次访问数据库.要做到这一点, 只需对一个结果集使用 select_related() 方法.这可能导致(某些时候相当)大的(有可能是不必要的)查询, 但这却意味着后续的关系使用会快很多.(俺的建议:对一个频繁变化的多用户数据库,不要使用该参数)

举例来说, 上面的 Poll 和 Choice models 中, 如果你这样做:

c = Choice.objects.select_related().get(id=5)

那么后面的 c.poll() 将不用访问数据库.

注意这个 select_related 方法会尽可能远的追踪外键. 如果你有下面的 models:

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

class Choice(models.Model):
    # ...
    poll = models.ForeignKey(Poll)

class SingleVote(meta.Model):
    # ...
    choice = models.ForeignKey(Choice)

那么调用 SingleVotes.objects.select_related().get(id=4) 会缓存相关的 choice 和 相关的 poll:

>>> sv = SingleVotes.objects.select_related().get(id=4)
>>> c = sv.choice        # Doesn‘t hit the database.
>>> p = c.poll           # Doesn‘t hit the database.

>>> sv = SingleVotes.objects.get(id=4)
>>> c = sv.choice        # Hits the database.
>>> p = c.poll           # Hits the database.

extra(params, select, where, tables)

有时候, Django 提供的查询语法不太够用. 为了满足这些边缘需求, Django 提供了 extra() 结果集修改器 - 一种提供额外查询参数的机制.

要注意这些额外的方式对不同的数据库引擎可能存在移植性问题.(因为你在显式的书写SQL语句),除非万不得已,尽量避免这样做:

params

下面描述的所有 额外-SQL 参数都必须是标准 Python 字符串格式(数据库引擎会自动用引号将它引起).``params`` 参数可以包含任意多个的SQL参数.

select

select 关键字参数允许你选择特定的字段. 它是一个字典(属性名与 SQL 语句的映射). 举例来说:

    Poll.objects.extra(
        select={
            ‘choice_count‘: ‘SELECT COUNT(*) FROM choices WHERE poll_id = polls.id‘
        }
    )

每个返回的 ``Poll`` 对象会有一个额外的属性: ``choice_count``, 一个关联`` Choice`` 对象的整数. 注意大多数数据库引擎需要用括号将子查询括起来. Django 的 ``select`` 子句则不需要这个括号.

where / tables

如果你需要传递一个额外的 WHERE 子句 -- 比方进行一个非显式的连接--你可以使用 where 关键字参数. 如果你需要在查询中连接其它的表,你可以传递它们的名字给 tables 参数.

where 和 tables 都接受一个字符串列表作为它们的值.所有的 where 参数都被 "AND" 到其它的查询条件中.

举例来说:

    Poll.objects.filter(
        question__startswith=‘Who‘).extra(where=[‘id IN (3, 4, 5, 20)‘])

...翻译成 SQL 语句就是::

    SELECT * FROM polls_polls WHERE question LIKE ‘Who%‘ AND id IN (3, 4, 5, 20);

get_FOO_display()

如果一个字段有 choices 选项集事, 这个对象将有一个 get_FOO_display() 方法.这里 FOO 是该字段的名字. 这个方法返回一个 "human-readable" 的字段值. 举例来说, 下面的model中:

GENDER_CHOICES = (
    (‘M‘, ‘Male‘),
    (‘F‘, ‘Female‘),
)
class Person:
    name = models.CharField(maxlength=20)
    gender = models.CharField(maxlength=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) 和 get_previous_by_FOO(**kwargs)

不存在 null=True 的每个 DateField 和 DateTimeField 自动拥有 get_next_by_FOO() 和 get_previous_by_FOO() 方法, 此处的 FOO 是字段的名字. 它们分别返回该字段的上一个对象和下一个对象. 如果上一对象或下一对象不存在,则抛出 *DoesNotExist 异常.

这两个方法均接受可选关键字参数, 这些参数应该遵循上文中 "Field 查询" 中提到的格式.

注意如果遇到相同值的对象, 这些方法会使用 ID 字段进行检查. 这保证了没有一条记录会被跳过或重复记数.参阅 lookup API sample model_ ,那里有一个完整的例子.

get_FOO_filename()

对一个 FileField 对象来说, 它自动拥有一个 get_FOO_filename() 方法. 这里 FOO 是字段名,它根据你的 MEDIA_ROOT 设置返回一个完整的路径名称.

注意 ImageField 技术上是 FileField 的一个子类, 因此每个有 ImageField 的 model 自动拥有此方法.

get_FOO_url()

含有 FileField 字段的每个对象自动拥有一个 get_FOO_url() 方法,这里的 FOO 是字段的名字. 该方法根据你的 MEDIA_URL 设置返回该文件的完整 URL ,如果MEDIA_URL 设置为空, 该方法返回一个空的字符串.

get_FOO_size()

含有 FileField 字段的每个对象自动拥有一个 get_FOO_filename() 方法, 这里的 FOO 是字段的名字. 该方法返回文件的长度(字节数).(在后台, Django 使用os.path.getsize.)

save_FOO_file(filename, raw_contents)

含有 FileField 字段的每个对象自动拥有一个 get_FOO_filename() 方法, 这里的 FOO 是字段的名字. 该方法使用给定的文件名将文件保存到文件系统.. 如果同目录下已经有同名文件存在,Django 会在文件名后添加一个下划线(扩展名之前)直到文件名有效为止(也就是如果加了下划线还重名,就再加....直到没有重名为止).

get_FOO_height() 和 get_FOO_width()

含有 ImageField 字段的每个对象自动拥有 get_FOO_height() 和 get_FOO_width() 方法, 这里的 FOO 是字段的名字. 它们返回相应的图片高度和宽度(整数,以像素计).