获取帮助

en
es
fr
id
it
ja
ko
pl
pt-br
zh-hans
语言: en

1.8
1.10
1.11
2.0
2.1
2.2
3.0
3.1
3.2
4.0
4.1
4.2
5.0
dev
文档版本: 5.1

数据库函数¶

下面记录的类为用户提供了一种方法，可以使用底层数据库提供的函数作为 Django 中的注释、聚合或过滤器。函数也是表达式，因此可以像聚合函数一样使用和组合其他表达式。

我们将在每个函数的示例中使用以下模型

class Author(models.Model):
    name = models.CharField(max_length=50)
    age = models.PositiveIntegerField(null=True, blank=True)
    alias = models.CharField(max_length=50, null=True, blank=True)
    goes_by = models.CharField(max_length=50, null=True, blank=True)

我们通常不建议允许 null=True 用于 CharField，因为这允许字段有两个“空值”，但对于下面的 Coalesce 示例很重要。

比较和转换函数¶

`Cast`¶

class Cast(expression, output_field)[source]¶

强制 expression 的结果类型为 output_field 中的类型。

用法示例

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Cast
>>> Author.objects.create(age=25, name="Margaret Smith")
>>> author = Author.objects.annotate(
...     age_as_float=Cast("age", output_field=FloatField()),
... ).get()
>>> print(author.age_as_float)
25.0

`Coalesce`¶

class Coalesce(*expressions, **extra)[source]¶

接受至少两个字段名或表达式的列表，并返回第一个非空值（请注意，空字符串不被视为空值）。每个参数必须具有类似的类型，因此混合文本和数字会导致数据库错误。

用法示例

>>> # Get a screen name from least to most public
>>> from django.db.models import Sum
>>> from django.db.models.functions import Coalesce
>>> Author.objects.create(name="Margaret Smith", goes_by="Maggie")
>>> author = Author.objects.annotate(screen_name=Coalesce("alias", "goes_by", "name")).get()
>>> print(author.screen_name)
Maggie

>>> # Prevent an aggregate Sum() from returning None
>>> # The aggregate default argument uses Coalesce() under the hood.
>>> aggregated = Author.objects.aggregate(
...     combined_age=Sum("age"),
...     combined_age_default=Sum("age", default=0),
...     combined_age_coalesce=Coalesce(Sum("age"), 0),
... )
>>> print(aggregated["combined_age"])
None
>>> print(aggregated["combined_age_default"])
0
>>> print(aggregated["combined_age_coalesce"])
0

警告

传递给 MySQL 上 Coalesce 的 Python 值可能会转换为不正确的类型，除非显式转换为正确的数据库类型

>>> from django.db.models import DateTimeField
>>> from django.db.models.functions import Cast, Coalesce
>>> from django.utils import timezone
>>> now = timezone.now()
>>> Coalesce("updated", Cast(now, DateTimeField()))

`Collate`¶

class Collate(expression, collation)[source]¶

获取表达式和排序规则名称以进行查询。

例如，要在 SQLite 中进行不区分大小写的过滤

>>> Author.objects.filter(name=Collate(Value("john"), "nocase"))
<QuerySet [<Author: John>, <Author: john>]>

它还可以在排序时使用，例如使用 PostgreSQL

>>> Author.objects.order_by(Collate("name", "et-x-icu"))
<QuerySet [<Author: Ursula>, <Author: Veronika>, <Author: Ülle>]>

`Greatest`¶

class Greatest(*expressions, **extra)[source]¶

接受至少两个字段名或表达式的列表，并返回最大值。每个参数必须具有类似的类型，因此混合文本和数字会导致数据库错误。

用法示例

class Blog(models.Model):
    body = models.TextField()
    modified = models.DateTimeField(auto_now=True)


class Comment(models.Model):
    body = models.TextField()
    modified = models.DateTimeField(auto_now=True)
    blog = models.ForeignKey(Blog, on_delete=models.CASCADE)

>>> from django.db.models.functions import Greatest
>>> blog = Blog.objects.create(body="Greatest is the best.")
>>> comment = Comment.objects.create(body="No, Least is better.", blog=blog)
>>> comments = Comment.objects.annotate(last_updated=Greatest("modified", "blog__modified"))
>>> annotated_comment = comments.get()

annotated_comment.last_updated 将是 blog.modified 和 comment.modified 中最新的一个。

警告

当一个或多个表达式可能为 null 时，Greatest 的行为在不同的数据库之间有所不同

PostgreSQL：Greatest 将返回最大的非空表达式，如果所有表达式都为 null，则返回 null。
SQLite、Oracle 和 MySQL：如果任何表达式为 null，则 Greatest 将返回 null。

如果知道要提供的合理最小值作为默认值，则可以使用 Coalesce 模拟 PostgreSQL 的行为。

`JSONObject`¶

class JSONObject(**fields)[source]¶

获取键值对列表，并返回包含这些对的 JSON 对象。

用法示例

>>> from django.db.models import F
>>> from django.db.models.functions import JSONObject, Lower
>>> Author.objects.create(name="Margaret Smith", alias="msmith", age=25)
>>> author = Author.objects.annotate(
...     json_object=JSONObject(
...         name=Lower("name"),
...         alias="alias",
...         age=F("age") * 2,
...     )
... ).get()
>>> author.json_object
{'name': 'margaret smith', 'alias': 'msmith', 'age': 50}

`Least`¶

class Least(*expressions, **extra)[source]¶

接受至少两个字段名或表达式的列表，并返回最小值。每个参数必须具有类似的类型，因此混合文本和数字会导致数据库错误。

警告

当一个或多个表达式可能为 null 时，Least 的行为在不同的数据库之间有所不同

PostgreSQL：Least 将返回最小的非空表达式，如果所有表达式都为 null，则返回 null。
SQLite、Oracle 和 MySQL：如果任何表达式为 null，则 Least 将返回 null。

如果知道要提供的合理最大值作为默认值，则可以使用 Coalesce 模拟 PostgreSQL 的行为。

`NullIf`¶

class NullIf(expression1, expression2)[source]¶

接受两个表达式，如果它们相等则返回 None，否则返回 expression1。

Oracle 上的注意事项

由于Oracle 约定，当表达式类型为CharField时，此函数返回空字符串而不是 None。

在 Oracle 上禁止将 Value(None) 传递给 expression1，因为 Oracle 不接受 NULL 作为第一个参数。

日期函数¶

我们将在每个函数的示例中使用以下模型

class Experiment(models.Model):
    start_datetime = models.DateTimeField()
    start_date = models.DateField(null=True, blank=True)
    start_time = models.TimeField(null=True, blank=True)
    end_datetime = models.DateTimeField(null=True, blank=True)
    end_date = models.DateField(null=True, blank=True)
    end_time = models.TimeField(null=True, blank=True)

`Extract`¶

class Extract(expression, lookup_name=None, tzinfo=None, **extra)[source]¶

将日期的组成部分提取为数字。

获取表示 DateField、DateTimeField、TimeField 或 DurationField 的 expression 和 lookup_name，并返回由 lookup_name 引用的日期部分作为 IntegerField。Django 通常使用数据库的 extract 函数，因此您可以使用数据库支持的任何 lookup_name。可以传递 tzinfo 子类（通常由zoneinfo 提供）以在特定时区中提取值。

给定日期时间 2015-06-15 23:30:01.000321+00:00，内置的 lookup_name 返回

“year”: 2015
“iso_year”: 2015
“quarter”: 2
“month”: 6
“日”: 15
“周”: 25
“星期”: 2
“ISO星期”: 1
“小时”: 23
“分钟”: 30
“秒”: 1

如果 Django 中启用了不同的时区，例如 Australia/Melbourne，则在提取值之前会将日期时间转换为该时区。在上述示例日期中，墨尔本的时区偏移量为 +10:00。当此时区处于活动状态时返回的值将与上述相同，但以下除外：

“日”: 16
“星期”: 3
“ISO星期”: 2
“小时”: 9

week_day 值

与大多数数据库和 Python 的标准函数不同，week_day 的 lookup_type 计算方式有所不同。此函数将返回 1 表示星期日，2 表示星期一，依此类推，直到 7 表示星期六。

Python 中等效的计算方式为

>>> from datetime import datetime
>>> dt = datetime(2015, 6, 15)
>>> (dt.isoweekday() % 7) + 1
2

week 值

week 的 lookup_type 基于 ISO-8601 进行计算，即一周从星期一开始。一年的第一周是包含该年第一个星期四的那一周，即第一周的大部分日期（四天或更多）都在该年中。返回的值范围为 1 到 52 或 53。

上面每个 lookup_name 都对应一个 Extract 子类（如下所示），通常应该使用它而不是更冗长的等效项，例如，使用 ExtractYear(...) 而不是 Extract(..., lookup_name='year')。

用法示例

>>> from datetime import datetime
>>> from django.db.models.functions import Extract
>>> start = datetime(2015, 6, 15)
>>> end = datetime(2015, 7, 2)
>>> Experiment.objects.create(
...     start_datetime=start, start_date=start.date(), end_datetime=end, end_date=end.date()
... )
>>> # Add the experiment start year as a field in the QuerySet.
>>> experiment = Experiment.objects.annotate(
...     start_year=Extract("start_datetime", "year")
... ).get()
>>> experiment.start_year
2015
>>> # How many experiments completed in the same year in which they started?
>>> Experiment.objects.filter(start_datetime__year=Extract("end_datetime", "year")).count()
1

`DateField` 提取¶

class ExtractYear(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'year'

class ExtractIsoYear(expression, tzinfo=None, **extra)[source]¶

返回 ISO-8601 周编号年份。

lookup_name = 'iso_year'

class ExtractMonth(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'month'

class ExtractDay(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'day'

class ExtractWeekDay(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'week_day'

class ExtractIsoWeekDay(expression, tzinfo=None, **extra)[source]¶

返回 ISO-8601 星期，其中星期一为 1，星期日为 7。

lookup_name = 'iso_week_day'

class ExtractWeek(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'week'

class ExtractQuarter(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'quarter'

这些在逻辑上等效于 Extract('date_field', lookup_name)。每个类也是一个在 DateField 和 DateTimeField 上注册的 Transform，作为 __(lookup_name)，例如 __year。

由于 DateField 没有时间部分，因此只有处理日期部分的 Extract 子类才能与 DateField 一起使用。

>>> from datetime import datetime, timezone
>>> from django.db.models.functions import (
...     ExtractDay,
...     ExtractMonth,
...     ExtractQuarter,
...     ExtractWeek,
...     ExtractIsoWeekDay,
...     ExtractWeekDay,
...     ExtractIsoYear,
...     ExtractYear,
... )
>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=timezone.utc)
>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.utc)
>>> Experiment.objects.create(
...     start_datetime=start_2015,
...     start_date=start_2015.date(),
...     end_datetime=end_2015,
...     end_date=end_2015.date(),
... )
>>> Experiment.objects.annotate(
...     year=ExtractYear("start_date"),
...     isoyear=ExtractIsoYear("start_date"),
...     quarter=ExtractQuarter("start_date"),
...     month=ExtractMonth("start_date"),
...     week=ExtractWeek("start_date"),
...     day=ExtractDay("start_date"),
...     weekday=ExtractWeekDay("start_date"),
...     isoweekday=ExtractIsoWeekDay("start_date"),
... ).values(
...     "year",
...     "isoyear",
...     "quarter",
...     "month",
...     "week",
...     "day",
...     "weekday",
...     "isoweekday",
... ).get(
...     end_date__year=ExtractYear("start_date")
... )
{'year': 2015, 'isoyear': 2015, 'quarter': 2, 'month': 6, 'week': 25,
 'day': 15, 'weekday': 2, 'isoweekday': 1}

`DateTimeField` 提取¶

除了以下内容外，上面列出的所有 DateField 的提取也可以用于 DateTimeField。

class ExtractHour(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'hour'

class ExtractMinute(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'minute'

class ExtractSecond(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'second'

这些在逻辑上等效于 Extract('datetime_field', lookup_name)。每个类也是一个在 DateTimeField 上注册的 Transform，作为 __(lookup_name)，例如 __minute。

DateTimeField 示例

>>> from datetime import datetime, timezone
>>> from django.db.models.functions import (
...     ExtractDay,
...     ExtractHour,
...     ExtractMinute,
...     ExtractMonth,
...     ExtractQuarter,
...     ExtractSecond,
...     ExtractWeek,
...     ExtractIsoWeekDay,
...     ExtractWeekDay,
...     ExtractIsoYear,
...     ExtractYear,
... )
>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=timezone.utc)
>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.utc)
>>> Experiment.objects.create(
...     start_datetime=start_2015,
...     start_date=start_2015.date(),
...     end_datetime=end_2015,
...     end_date=end_2015.date(),
... )
>>> Experiment.objects.annotate(
...     year=ExtractYear("start_datetime"),
...     isoyear=ExtractIsoYear("start_datetime"),
...     quarter=ExtractQuarter("start_datetime"),
...     month=ExtractMonth("start_datetime"),
...     week=ExtractWeek("start_datetime"),
...     day=ExtractDay("start_datetime"),
...     weekday=ExtractWeekDay("start_datetime"),
...     isoweekday=ExtractIsoWeekDay("start_datetime"),
...     hour=ExtractHour("start_datetime"),
...     minute=ExtractMinute("start_datetime"),
...     second=ExtractSecond("start_datetime"),
... ).values(
...     "year",
...     "isoyear",
...     "month",
...     "week",
...     "day",
...     "weekday",
...     "isoweekday",
...     "hour",
...     "minute",
...     "second",
... ).get(
...     end_datetime__year=ExtractYear("start_datetime")
... )
{'year': 2015, 'isoyear': 2015, 'quarter': 2, 'month': 6, 'week': 25,
 'day': 15, 'weekday': 2, 'isoweekday': 1, 'hour': 23, 'minute': 30,
 'second': 1}

当 USE_TZ 为 True 时，日期时间以 UTC 存储在数据库中。如果 Django 中启用了不同的时区，则在提取值之前，日期时间将转换为该时区。以下示例转换为墨尔本时区 (UTC +10:00)，这会更改返回的日期、星期几和小时值。

>>> from django.utils import timezone
>>> import zoneinfo
>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")  # UTC+10:00
>>> with timezone.override(melb):
...     Experiment.objects.annotate(
...         day=ExtractDay("start_datetime"),
...         weekday=ExtractWeekDay("start_datetime"),
...         isoweekday=ExtractIsoWeekDay("start_datetime"),
...         hour=ExtractHour("start_datetime"),
...     ).values("day", "weekday", "isoweekday", "hour").get(
...         end_datetime__year=ExtractYear("start_datetime"),
...     )
...
{'day': 16, 'weekday': 3, 'isoweekday': 2, 'hour': 9}

显式地将时区传递给 Extract 函数的行为方式相同，并且优先于活动时区。

>>> import zoneinfo
>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")
>>> Experiment.objects.annotate(
...     day=ExtractDay("start_datetime", tzinfo=melb),
...     weekday=ExtractWeekDay("start_datetime", tzinfo=melb),
...     isoweekday=ExtractIsoWeekDay("start_datetime", tzinfo=melb),
...     hour=ExtractHour("start_datetime", tzinfo=melb),
... ).values("day", "weekday", "isoweekday", "hour").get(
...     end_datetime__year=ExtractYear("start_datetime"),
... )
{'day': 16, 'weekday': 3, 'isoweekday': 2, 'hour': 9}

`Now`¶

class Now[source]¶

在执行查询时返回数据库服务器的当前日期和时间，通常使用 SQL CURRENT_TIMESTAMP。

用法示例

>>> from django.db.models.functions import Now
>>> Article.objects.filter(published__lte=Now())
<QuerySet [<Article: How to Django>]>

PostgreSQL 注意事项

在 PostgreSQL 上，SQL CURRENT_TIMESTAMP 返回当前事务开始的时间。因此，为了跨数据库兼容性，Now() 使用 STATEMENT_TIMESTAMP 代替。如果您需要事务时间戳，请使用 django.contrib.postgres.functions.TransactionNow。

Oracle

在 Oracle 上，SQL LOCALTIMESTAMP 用于避免将 CURRENT_TIMESTAMP 转换为 DateTimeField 时出现的问题。

Django 5.0 中的更改

在较旧的版本中，在 Oracle 上使用 SQL CURRENT_TIMESTAMP 而不是 LOCALTIMESTAMP。

`Trunc`¶

class Trunc(expression, kind, output_field=None, tzinfo=None, **extra)[source]¶

将日期截断到一个重要的组成部分。

当您只关心某件事是否发生在特定年份、小时或日期，而不是确切的秒数时，则 Trunc（及其子类）可用于过滤或聚合您的数据。例如，您可以使用 Trunc 计算每天的销售额。

Trunc 获取单个 expression，表示 DateField、TimeField 或 DateTimeField，一个表示日期或时间部分的 kind，以及一个 output_field，它可以是 DateTimeField()、TimeField() 或 DateField()。它根据 output_field 返回日期时间、日期或时间，其中字段最多设置为 kind 的最小值。如果省略 output_field，它将默认为 expression 的 output_field。可以传递 tzinfo 子类（通常由 zoneinfo 提供）以在特定时区截断值。

给定日期时间 2015-06-15 14:30:50.000321+00:00，内置的 kind 返回

“year”: 2015-01-01 00:00:00+00:00
“quarter”: 2015-04-01 00:00:00+00:00
“month”: 2015-06-01 00:00:00+00:00
“week”: 2015-06-15 00:00:00+00:00
“day”: 2015-06-15 00:00:00+00:00
“hour”: 2015-06-15 14:00:00+00:00
“minute”: 2015-06-15 14:30:00+00:00
“second”: 2015-06-15 14:30:50+00:00

如果 Django 中启用了像 Australia/Melbourne 这样的不同时区，则在截断值之前，日期时间将转换为新时区。在上面示例日期中，墨尔本的时区偏移量为 +10:00。当此时区处于活动状态时返回的值将为

“year”: 2015-01-01 00:00:00+11:00
“quarter”: 2015-04-01 00:00:00+10:00
“month”: 2015-06-01 00:00:00+10:00
“week”: 2015-06-16 00:00:00+10:00
“day”: 2015-06-16 00:00:00+10:00
“hour”: 2015-06-16 00:00:00+10:00
“minute”: 2015-06-16 00:30:00+10:00
“second”: 2015-06-16 00:30:50+10:00

年份的偏移量为 +11:00，因为结果过渡到夏令时。

上面每个 kind 都有一个对应的 Trunc 子类（列在下面），通常应该使用它而不是更冗长的等效项，例如，使用 TruncYear(...) 而不是 Trunc(..., kind='year')。

子类都定义为转换，但它们未注册到任何字段，因为查找名称已被 Extract 子类保留。

用法示例

>>> from datetime import datetime
>>> from django.db.models import Count, DateTimeField
>>> from django.db.models.functions import Trunc
>>> Experiment.objects.create(start_datetime=datetime(2015, 6, 15, 14, 30, 50, 321))
>>> Experiment.objects.create(start_datetime=datetime(2015, 6, 15, 14, 40, 2, 123))
>>> Experiment.objects.create(start_datetime=datetime(2015, 12, 25, 10, 5, 27, 999))
>>> experiments_per_day = (
...     Experiment.objects.annotate(
...         start_day=Trunc("start_datetime", "day", output_field=DateTimeField())
...     )
...     .values("start_day")
...     .annotate(experiments=Count("id"))
... )
>>> for exp in experiments_per_day:
...     print(exp["start_day"], exp["experiments"])
...
2015-06-15 00:00:00 2
2015-12-25 00:00:00 1
>>> experiments = Experiment.objects.annotate(
...     start_day=Trunc("start_datetime", "day", output_field=DateTimeField())
... ).filter(start_day=datetime(2015, 6, 15))
>>> for exp in experiments:
...     print(exp.start_datetime)
...
2015-06-15 14:30:50.000321
2015-06-15 14:40:02.000123

`DateField` 截断¶

class TruncYear(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'year'

class TruncMonth(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'month'

class TruncWeek(expression, output_field=None, tzinfo=None, **extra)[source]¶

截断到星期一的午夜。

kind = 'week'

class TruncQuarter(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'quarter'

这些在逻辑上等效于 Trunc('date_field', kind)。它们将日期的所有部分截断到 kind，这允许使用较低的精度对日期进行分组或过滤。 expression 可以具有 DateField 或 DateTimeField 的 output_field。

由于DateField没有时间部分，因此只有处理日期部分的Trunc子类才能与DateField一起使用。

>>> from datetime import datetime, timezone
>>> from django.db.models import Count
>>> from django.db.models.functions import TruncMonth, TruncYear
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)
>>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)
>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.utc)
>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())
>>> Experiment.objects.create(start_datetime=start2, start_date=start2.date())
>>> Experiment.objects.create(start_datetime=start3, start_date=start3.date())
>>> experiments_per_year = (
...     Experiment.objects.annotate(year=TruncYear("start_date"))
...     .values("year")
...     .annotate(experiments=Count("id"))
... )
>>> for exp in experiments_per_year:
...     print(exp["year"], exp["experiments"])
...
2014-01-01 1
2015-01-01 2

>>> import zoneinfo
>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")
>>> experiments_per_month = (
...     Experiment.objects.annotate(month=TruncMonth("start_datetime", tzinfo=melb))
...     .values("month")
...     .annotate(experiments=Count("id"))
... )
>>> for exp in experiments_per_month:
...     print(exp["month"], exp["experiments"])
...
2015-06-01 00:00:00+10:00 1
2016-01-01 00:00:00+11:00 1
2014-06-01 00:00:00+10:00 1

`DateTimeField` 截断¶

class TruncDate(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'date'

output_field = DateField()

TruncDate 将expression转换为日期，而不是使用内置的SQL截断函数。它也作为__date在DateTimeField上注册为转换。

class TruncTime(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'time'

output_field = TimeField()

TruncTime 将expression转换为时间，而不是使用内置的SQL截断函数。它也作为__time在DateTimeField上注册为转换。

class TruncDay(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'day'

class TruncHour(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'hour'

class TruncMinute(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'minute'

class TruncSecond(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'second'

这些在逻辑上等效于Trunc('datetime_field', kind)。它们将日期的所有部分截断到kind，并允许以较低的精度对日期时间进行分组或过滤。expression必须具有DateTimeField的output_field。

用法示例

>>> from datetime import date, datetime, timezone
>>> from django.db.models import Count
>>> from django.db.models.functions import (
...     TruncDate,
...     TruncDay,
...     TruncHour,
...     TruncMinute,
...     TruncSecond,
... )
>>> import zoneinfo
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)
>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())
>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")
>>> Experiment.objects.annotate(
...     date=TruncDate("start_datetime"),
...     day=TruncDay("start_datetime", tzinfo=melb),
...     hour=TruncHour("start_datetime", tzinfo=melb),
...     minute=TruncMinute("start_datetime"),
...     second=TruncSecond("start_datetime"),
... ).values("date", "day", "hour", "minute", "second").get()
{'date': datetime.date(2014, 6, 15),
 'day': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=zoneinfo.ZoneInfo('Australia/Melbourne')),
 'hour': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=zoneinfo.ZoneInfo('Australia/Melbourne')),
 'minute': 'minute': datetime.datetime(2014, 6, 15, 14, 30, tzinfo=timezone.utc),
 'second': datetime.datetime(2014, 6, 15, 14, 30, 50, tzinfo=timezone.utc)
}

`TimeField` 截断¶

class TruncHour(expression, output_field=None, tzinfo=None, **extra)[source]

kind = 'hour'

class TruncMinute(expression, output_field=None, tzinfo=None, **extra)[source]

kind = 'minute'

class TruncSecond(expression, output_field=None, tzinfo=None, **extra)[source]

kind = 'second'

这些在逻辑上等效于Trunc('time_field', kind)。它们将时间的所有部分截断到kind，这允许以较低的精度对时间进行分组或过滤。expression可以具有TimeField或DateTimeField的output_field。

由于TimeField没有日期部分，因此只有处理时间部分的Trunc子类才能与TimeField一起使用。

>>> from datetime import datetime, timezone
>>> from django.db.models import Count, TimeField
>>> from django.db.models.functions import TruncHour
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)
>>> start2 = datetime(2014, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)
>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.utc)
>>> Experiment.objects.create(start_datetime=start1, start_time=start1.time())
>>> Experiment.objects.create(start_datetime=start2, start_time=start2.time())
>>> Experiment.objects.create(start_datetime=start3, start_time=start3.time())
>>> experiments_per_hour = (
...     Experiment.objects.annotate(
...         hour=TruncHour("start_datetime", output_field=TimeField()),
...     )
...     .values("hour")
...     .annotate(experiments=Count("id"))
... )
>>> for exp in experiments_per_hour:
...     print(exp["hour"], exp["experiments"])
...
14:00:00 2
17:00:00 1

>>> import zoneinfo
>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")
>>> experiments_per_hour = (
...     Experiment.objects.annotate(
...         hour=TruncHour("start_datetime", tzinfo=melb),
...     )
...     .values("hour")
...     .annotate(experiments=Count("id"))
... )
>>> for exp in experiments_per_hour:
...     print(exp["hour"], exp["experiments"])
...
2014-06-16 00:00:00+10:00 2
2016-01-01 04:00:00+11:00 1

数学函数¶

我们将在数学函数示例中使用以下模型

class Vector(models.Model):
    x = models.FloatField()
    y = models.FloatField()

`Abs`¶

class Abs(expression, **extra)[source]¶

返回数字字段或表达式的绝对值。

用法示例

>>> from django.db.models.functions import Abs
>>> Vector.objects.create(x=-0.5, y=1.1)
>>> vector = Vector.objects.annotate(x_abs=Abs("x"), y_abs=Abs("y")).get()
>>> vector.x_abs, vector.y_abs
(0.5, 1.1)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Abs
>>> FloatField.register_lookup(Abs)
>>> # Get vectors inside the unit cube
>>> vectors = Vector.objects.filter(x__abs__lt=1, y__abs__lt=1)

`ACos`¶

class ACos(expression, **extra)[source]¶

返回数字字段或表达式的反余弦值。表达式值必须在 -1 到 1 的范围内。

用法示例

>>> from django.db.models.functions import ACos
>>> Vector.objects.create(x=0.5, y=-0.9)
>>> vector = Vector.objects.annotate(x_acos=ACos("x"), y_acos=ACos("y")).get()
>>> vector.x_acos, vector.y_acos
(1.0471975511965979, 2.6905658417935308)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import ACos
>>> FloatField.register_lookup(ACos)
>>> # Get vectors whose arccosine is less than 1
>>> vectors = Vector.objects.filter(x__acos__lt=1, y__acos__lt=1)

`ASin`¶

class ASin(expression, **extra)[source]¶

返回数值字段或表达式的反正弦值。表达式值必须在 -1 到 1 的范围内。

用法示例

>>> from django.db.models.functions import ASin
>>> Vector.objects.create(x=0, y=1)
>>> vector = Vector.objects.annotate(x_asin=ASin("x"), y_asin=ASin("y")).get()
>>> vector.x_asin, vector.y_asin
(0.0, 1.5707963267948966)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import ASin
>>> FloatField.register_lookup(ASin)
>>> # Get vectors whose arcsine is less than 1
>>> vectors = Vector.objects.filter(x__asin__lt=1, y__asin__lt=1)

`ATan`¶

class ATan(expression, **extra)[source]¶

返回数值字段或表达式的反正切值。

用法示例

>>> from django.db.models.functions import ATan
>>> Vector.objects.create(x=3.12, y=6.987)
>>> vector = Vector.objects.annotate(x_atan=ATan("x"), y_atan=ATan("y")).get()
>>> vector.x_atan, vector.y_atan
(1.2606282660069106, 1.428638798133829)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import ATan
>>> FloatField.register_lookup(ATan)
>>> # Get vectors whose arctangent is less than 2
>>> vectors = Vector.objects.filter(x__atan__lt=2, y__atan__lt=2)

`ATan2`¶

class ATan2(expression1, expression2, **extra)[source]¶

返回 expression1 / expression2 的反正切值。

用法示例

>>> from django.db.models.functions import ATan2
>>> Vector.objects.create(x=2.5, y=1.9)
>>> vector = Vector.objects.annotate(atan2=ATan2("x", "y")).get()
>>> vector.atan2
0.9209258773829491

`Ceil`¶

class Ceil(expression, **extra)[source]¶

返回大于或等于数值字段或表达式的最小整数。

用法示例

>>> from django.db.models.functions import Ceil
>>> Vector.objects.create(x=3.12, y=7.0)
>>> vector = Vector.objects.annotate(x_ceil=Ceil("x"), y_ceil=Ceil("y")).get()
>>> vector.x_ceil, vector.y_ceil
(4.0, 7.0)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Ceil
>>> FloatField.register_lookup(Ceil)
>>> # Get vectors whose ceil is less than 10
>>> vectors = Vector.objects.filter(x__ceil__lt=10, y__ceil__lt=10)

`Cos`¶

class Cos(expression, **extra)[source]¶

返回数值字段或表达式的余弦值。

用法示例

>>> from django.db.models.functions import Cos
>>> Vector.objects.create(x=-8.0, y=3.1415926)
>>> vector = Vector.objects.annotate(x_cos=Cos("x"), y_cos=Cos("y")).get()
>>> vector.x_cos, vector.y_cos
(-0.14550003380861354, -0.9999999999999986)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Cos
>>> FloatField.register_lookup(Cos)
>>> # Get vectors whose cosine is less than 0.5
>>> vectors = Vector.objects.filter(x__cos__lt=0.5, y__cos__lt=0.5)

`Cot`¶

class Cot(expression, **extra)[source]¶

返回数值字段或表达式的余切值。

用法示例

>>> from django.db.models.functions import Cot
>>> Vector.objects.create(x=12.0, y=1.0)
>>> vector = Vector.objects.annotate(x_cot=Cot("x"), y_cot=Cot("y")).get()
>>> vector.x_cot, vector.y_cot
(-1.5726734063976826, 0.642092615934331)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Cot
>>> FloatField.register_lookup(Cot)
>>> # Get vectors whose cotangent is less than 1
>>> vectors = Vector.objects.filter(x__cot__lt=1, y__cot__lt=1)

`Degrees`¶

class Degrees(expression, **extra)[source]¶

将数值字段或表达式从弧度转换为度。

用法示例

>>> from django.db.models.functions import Degrees
>>> Vector.objects.create(x=-1.57, y=3.14)
>>> vector = Vector.objects.annotate(x_d=Degrees("x"), y_d=Degrees("y")).get()
>>> vector.x_d, vector.y_d
(-89.95437383553924, 179.9087476710785)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Degrees
>>> FloatField.register_lookup(Degrees)
>>> # Get vectors whose degrees are less than 360
>>> vectors = Vector.objects.filter(x__degrees__lt=360, y__degrees__lt=360)

`Exp`¶

class Exp(expression, **extra)[source]¶

返回 e（自然对数底数）的数值字段或表达式次幂的值。

用法示例

>>> from django.db.models.functions import Exp
>>> Vector.objects.create(x=5.4, y=-2.0)
>>> vector = Vector.objects.annotate(x_exp=Exp("x"), y_exp=Exp("y")).get()
>>> vector.x_exp, vector.y_exp
(221.40641620418717, 0.1353352832366127)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Exp
>>> FloatField.register_lookup(Exp)
>>> # Get vectors whose exp() is greater than 10
>>> vectors = Vector.objects.filter(x__exp__gt=10, y__exp__gt=10)

`Floor`¶

class Floor(expression, **extra)[source]¶

返回不大于数值字段或表达式的最大整数。

用法示例

>>> from django.db.models.functions import Floor
>>> Vector.objects.create(x=5.4, y=-2.3)
>>> vector = Vector.objects.annotate(x_floor=Floor("x"), y_floor=Floor("y")).get()
>>> vector.x_floor, vector.y_floor
(5.0, -3.0)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Floor
>>> FloatField.register_lookup(Floor)
>>> # Get vectors whose floor() is greater than 10
>>> vectors = Vector.objects.filter(x__floor__gt=10, y__floor__gt=10)

`Ln`¶

class Ln(expression, **extra)[source]¶

返回数值字段或表达式的自然对数。

用法示例

>>> from django.db.models.functions import Ln
>>> Vector.objects.create(x=5.4, y=233.0)
>>> vector = Vector.objects.annotate(x_ln=Ln("x"), y_ln=Ln("y")).get()
>>> vector.x_ln, vector.y_ln
(1.6863989535702288, 5.4510384535657)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Ln
>>> FloatField.register_lookup(Ln)
>>> # Get vectors whose value greater than e
>>> vectors = Vector.objects.filter(x__ln__gt=1, y__ln__gt=1)

`Log`¶

class Log(expression1, expression2, **extra)[source]¶

接受两个数值字段或表达式，并返回第二个以第一个为底的对数。

用法示例

>>> from django.db.models.functions import Log
>>> Vector.objects.create(x=2.0, y=4.0)
>>> vector = Vector.objects.annotate(log=Log("x", "y")).get()
>>> vector.log
2.0

`Mod`¶

class Mod(expression1, expression2, **extra)[source]¶

接受两个数值字段或表达式，并返回第一个除以第二个的余数（取模运算）。

用法示例

>>> from django.db.models.functions import Mod
>>> Vector.objects.create(x=5.4, y=2.3)
>>> vector = Vector.objects.annotate(mod=Mod("x", "y")).get()
>>> vector.mod
0.8

`Pi`¶

class Pi(**extra)[source]¶

返回数学常数 π 的值。

`Power`¶

class Power(expression1, expression2, **extra)[source]¶

接受两个数值字段或表达式，并返回第一个的第二个次幂的值。

用法示例

>>> from django.db.models.functions import Power
>>> Vector.objects.create(x=2, y=-2)
>>> vector = Vector.objects.annotate(power=Power("x", "y")).get()
>>> vector.power
0.25

`Radians`¶

class Radians(expression, **extra)[source]¶

将数值字段或表达式从度转换为弧度。

用法示例

>>> from django.db.models.functions import Radians
>>> Vector.objects.create(x=-90, y=180)
>>> vector = Vector.objects.annotate(x_r=Radians("x"), y_r=Radians("y")).get()
>>> vector.x_r, vector.y_r
(-1.5707963267948966, 3.141592653589793)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Radians
>>> FloatField.register_lookup(Radians)
>>> # Get vectors whose radians are less than 1
>>> vectors = Vector.objects.filter(x__radians__lt=1, y__radians__lt=1)

`Random`¶

class Random(**extra)[source]¶

返回范围在 0.0 ≤ x < 1.0 内的随机值。

`Round`¶

class Round(expression, precision=0, **extra)[source]¶

将数值字段或表达式舍入到precision（必须是整数）个小数位。默认情况下，它会舍入到最接近的整数。一半值是向上舍入还是向下舍入取决于数据库。

用法示例

>>> from django.db.models.functions import Round
>>> Vector.objects.create(x=5.4, y=-2.37)
>>> vector = Vector.objects.annotate(x_r=Round("x"), y_r=Round("y", precision=1)).get()
>>> vector.x_r, vector.y_r
(5.0, -2.4)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Round
>>> FloatField.register_lookup(Round)
>>> # Get vectors whose round() is less than 20
>>> vectors = Vector.objects.filter(x__round__lt=20, y__round__lt=20)

`Sign`¶

class Sign(expression, **extra)[source]¶

返回数值字段或表达式的符号（-1、0、1）。

用法示例

>>> from django.db.models.functions import Sign
>>> Vector.objects.create(x=5.4, y=-2.3)
>>> vector = Vector.objects.annotate(x_sign=Sign("x"), y_sign=Sign("y")).get()
>>> vector.x_sign, vector.y_sign
(1, -1)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Sign
>>> FloatField.register_lookup(Sign)
>>> # Get vectors whose signs of components are less than 0.
>>> vectors = Vector.objects.filter(x__sign__lt=0, y__sign__lt=0)

`Sin`¶

class Sin(expression, **extra)[source]¶

返回数值字段或表达式的正弦值。

用法示例

>>> from django.db.models.functions import Sin
>>> Vector.objects.create(x=5.4, y=-2.3)
>>> vector = Vector.objects.annotate(x_sin=Sin("x"), y_sin=Sin("y")).get()
>>> vector.x_sin, vector.y_sin
(-0.7727644875559871, -0.7457052121767203)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Sin
>>> FloatField.register_lookup(Sin)
>>> # Get vectors whose sin() is less than 0
>>> vectors = Vector.objects.filter(x__sin__lt=0, y__sin__lt=0)

`Sqrt`¶

class Sqrt(expression, **extra)[source]¶

返回非负数值字段或表达式的平方根。

用法示例

>>> from django.db.models.functions import Sqrt
>>> Vector.objects.create(x=4.0, y=12.0)
>>> vector = Vector.objects.annotate(x_sqrt=Sqrt("x"), y_sqrt=Sqrt("y")).get()
>>> vector.x_sqrt, vector.y_sqrt
(2.0, 3.46410)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Sqrt
>>> FloatField.register_lookup(Sqrt)
>>> # Get vectors whose sqrt() is less than 5
>>> vectors = Vector.objects.filter(x__sqrt__lt=5, y__sqrt__lt=5)

`Tan`¶

class Tan(expression, **extra)[source]¶

返回数值字段或表达式的正切值。

用法示例

>>> from django.db.models.functions import Tan
>>> Vector.objects.create(x=0, y=12)
>>> vector = Vector.objects.annotate(x_tan=Tan("x"), y_tan=Tan("y")).get()
>>> vector.x_tan, vector.y_tan
(0.0, -0.6358599286615808)

它也可以注册为转换。例如

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Tan
>>> FloatField.register_lookup(Tan)
>>> # Get vectors whose tangent is less than 0
>>> vectors = Vector.objects.filter(x__tan__lt=0, y__tan__lt=0)

文本函数¶

`Chr`¶

class Chr(expression, **extra)[source]¶

接受一个数值字段或表达式，并将其文本表示形式作为单个字符返回。它的作用与 Python 的 chr() 函数相同。

与 Length 一样，它可以注册为 IntegerField 的转换。默认查找名称为 chr。

用法示例

>>> from django.db.models.functions import Chr
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.filter(name__startswith=Chr(ord("M"))).get()
>>> print(author.name)
Margaret Smith

`Concat`¶

class Concat(*expressions, **extra)[source]¶

接受至少两个文本字段或表达式的列表，并返回连接后的文本。每个参数必须是文本或字符类型。如果要将 TextField() 与 CharField() 连接，则务必告诉 Django output_field 应为 TextField()。在连接 Value 时，也需要指定 output_field，如下例所示。

此函数的结果永远不会为空。在空参数会导致整个表达式为空的后端，Django 将确保每个空部分首先转换为空字符串。

用法示例

>>> # Get the display name as "name (goes_by)"
>>> from django.db.models import CharField, Value as V
>>> from django.db.models.functions import Concat
>>> Author.objects.create(name="Margaret Smith", goes_by="Maggie")
>>> author = Author.objects.annotate(
...     screen_name=Concat("name", V(" ("), "goes_by", V(")"), output_field=CharField())
... ).get()
>>> print(author.screen_name)
Margaret Smith (Maggie)

`Left`¶

class Left(expression, length, **extra)[source]¶

返回给定文本字段或表达式的前 length 个字符。

用法示例

>>> from django.db.models.functions import Left
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(first_initial=Left("name", 1)).get()
>>> print(author.first_initial)
M

`Length`¶

class Length(expression, **extra)[source]¶

接受单个文本字段或表达式，并返回该值具有的字符数。如果表达式为空，则长度也将为空。

用法示例

>>> # Get the length of the name and goes_by fields
>>> from django.db.models.functions import Length
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(
...     name_length=Length("name"), goes_by_length=Length("goes_by")
... ).get()
>>> print(author.name_length, author.goes_by_length)
(14, None)

它也可以注册为转换。例如

>>> from django.db.models import CharField
>>> from django.db.models.functions import Length
>>> CharField.register_lookup(Length)
>>> # Get authors whose name is longer than 7 characters
>>> authors = Author.objects.filter(name__length__gt=7)

`Lower`¶

class Lower(expression, **extra)[source]¶

接受单个文本字段或表达式，并返回其小写表示形式。

它也可以注册为转换，如 Length 中所述。

用法示例

>>> from django.db.models.functions import Lower
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(name_lower=Lower("name")).get()
>>> print(author.name_lower)
margaret smith

`LPad`¶

class LPad(expression, length, fill_text=Value(' '), **extra)[source]¶

返回给定文本字段或表达式的值，该值在左侧填充 fill_text，以便结果值为 length 个字符长。默认的 fill_text 是空格。

用法示例

>>> from django.db.models import Value
>>> from django.db.models.functions import LPad
>>> Author.objects.create(name="John", alias="j")
>>> Author.objects.update(name=LPad("name", 8, Value("abc")))
1
>>> print(Author.objects.get(alias="j").name)
abcaJohn

`LTrim`¶

class LTrim(expression, **extra)[source]¶

类似于 Trim，但仅删除前导空格。

`MD5`¶

class MD5(expression, **extra)[source]¶

接受单个文本字段或表达式，并返回该字符串的 MD5 哈希值。

它也可以注册为转换，如 Length 中所述。

用法示例

>>> from django.db.models.functions import MD5
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(name_md5=MD5("name")).get()
>>> print(author.name_md5)
749fb689816b2db85f5b169c2055b247

`Ord`¶

class Ord(expression, **extra)[source]¶

接受单个文本字段或表达式，并返回该表达式第一个字符的 Unicode 代码点值。它的工作原理类似于 Python 的 ord() 函数，但如果表达式长度超过一个字符，则不会引发异常。

它还可以注册为转换，如 Length 中所述。默认查找名称为 ord。

用法示例

>>> from django.db.models.functions import Ord
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(name_code_point=Ord("name")).get()
>>> print(author.name_code_point)
77

`Repeat`¶

class Repeat(expression, number, **extra)[source]¶

返回给定文本字段或表达式重复 number 次的值。

用法示例

>>> from django.db.models.functions import Repeat
>>> Author.objects.create(name="John", alias="j")
>>> Author.objects.update(name=Repeat("name", 3))
1
>>> print(Author.objects.get(alias="j").name)
JohnJohnJohn

`Replace`¶

class Replace(expression, text, replacement=Value(''), **extra)[source]¶

在 expression 中将所有 text 出现的实例替换为 replacement。默认替换文本为空字符串。函数的参数区分大小写。

用法示例

>>> from django.db.models import Value
>>> from django.db.models.functions import Replace
>>> Author.objects.create(name="Margaret Johnson")
>>> Author.objects.create(name="Margaret Smith")
>>> Author.objects.update(name=Replace("name", Value("Margaret"), Value("Margareth")))
2
>>> Author.objects.values("name")
<QuerySet [{'name': 'Margareth Johnson'}, {'name': 'Margareth Smith'}]>

`Reverse`¶

class Reverse(expression, **extra)[source]¶

接受单个文本字段或表达式，并以相反的顺序返回该表达式的字符。

它还可以注册为转换，如 Length 中所述。默认查找名称为 reverse。

用法示例

>>> from django.db.models.functions import Reverse
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(backward=Reverse("name")).get()
>>> print(author.backward)
htimS teragraM

`Right`¶

class Right(expression, length, **extra)[source]¶

返回给定文本字段或表达式的最后 length 个字符。

用法示例

>>> from django.db.models.functions import Right
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(last_letter=Right("name", 1)).get()
>>> print(author.last_letter)
h

`RPad`¶

class RPad(expression, length, fill_text=Value(' '), **extra)[source]¶

类似于 LPad，但在右侧填充。

`RTrim`¶

class RTrim(expression, **extra)[source]¶

类似于 Trim，但仅删除尾随空格。

`SHA1`、`SHA224`、`SHA256`、`SHA384` 和 `SHA512`¶

class SHA1(expression, **extra)[source]¶

class SHA224(expression, **extra)[source]¶

class SHA256(expression, **extra)[source]¶

class SHA384(expression, **extra)[source]¶

class SHA512(expression, **extra)[source]¶

接受单个文本字段或表达式，并返回字符串的特定哈希值。

它们还可以注册为转换，如 Length 中所述。

用法示例

>>> from django.db.models.functions import SHA1
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(name_sha1=SHA1("name")).get()
>>> print(author.name_sha1)
b87efd8a6c991c390be5a68e8a7945a7851c7e5c

PostgreSQL

必须安装 pgcrypto 扩展。您可以使用 CryptoExtension 迁移操作来安装它。

Oracle

Oracle 不支持 SHA224 函数。

`StrIndex`¶

class StrIndex(string, substring, **extra)[source]¶

返回在string中第一次出现substring的1索引位置对应的正整数，如果未找到substring，则返回0。

用法示例

>>> from django.db.models import Value as V
>>> from django.db.models.functions import StrIndex
>>> Author.objects.create(name="Margaret Smith")
>>> Author.objects.create(name="Smith, Margaret")
>>> Author.objects.create(name="Margaret Jackson")
>>> Author.objects.filter(name="Margaret Jackson").annotate(
...     smith_index=StrIndex("name", V("Smith"))
... ).get().smith_index
0
>>> authors = Author.objects.annotate(smith_index=StrIndex("name", V("Smith"))).filter(
...     smith_index__gt=0
... )
<QuerySet [<Author: Margaret Smith>, <Author: Smith, Margaret>]>

警告

在MySQL中，数据库表的校对规则决定字符串比较（例如此函数的expression和substring）是否区分大小写。默认情况下，比较不区分大小写。

`Substr`¶

class Substr(expression, pos, length=None, **extra)[source]¶

返回字段或表达式从位置pos开始长度为length的子字符串。位置为1索引，因此位置必须大于0。如果length为None，则返回字符串的其余部分。

用法示例

>>> # Set the alias to the first 5 characters of the name as lowercase
>>> from django.db.models.functions import Lower, Substr
>>> Author.objects.create(name="Margaret Smith")
>>> Author.objects.update(alias=Lower(Substr("name", 1, 5)))
1
>>> print(Author.objects.get(name="Margaret Smith").alias)
marga

`Trim`¶

class Trim(expression, **extra)[source]¶

返回给定文本字段或表达式的值，并删除前导和尾随空格。

用法示例

>>> from django.db.models.functions import Trim
>>> Author.objects.create(name="  John  ", alias="j")
>>> Author.objects.update(name=Trim("name"))
1
>>> print(Author.objects.get(alias="j").name)
John

`Upper`¶

class Upper(expression, **extra)[source]¶

接受单个文本字段或表达式，并返回其大写表示形式。

它也可以注册为转换，如 Length 中所述。

用法示例

>>> from django.db.models.functions import Upper
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(name_upper=Upper("name")).get()
>>> print(author.name_upper)
MARGARET SMITH

窗口函数¶

有一些函数可以在Window表达式中使用，用于计算元素的排名或某些行的Ntile。

`CumeDist`¶

class CumeDist(*expressions, **extra)[source]¶

计算窗口或分区内值的累积分布。累积分布定义为在当前行之前或与当前行同级的行数除以框架中总行数。

`DenseRank`¶

class DenseRank(*expressions, **extra)[source]¶

等同于Rank，但没有间隙。

`FirstValue`¶

class FirstValue(expression, **extra)[source]¶

返回在窗口框架的第一行计算的值，如果不存在这样的值，则返回None。

`Lag`¶

class Lag(expression, offset=1, default=None, **extra)[source]¶

计算偏移量为offset的值，如果不存在该行，则返回default。

default必须与expression具有相同的类型，但是，这仅由数据库验证，而不是在Python中验证。

MariaDB 和 default

MariaDB 不支持default参数。

`LastValue`¶

class LastValue(expression, **extra)[source]¶

与FirstValue类似，它计算给定框架中的最后一个值。

`Lead`¶

class Lead(expression, offset=1, default=None, **extra)[source]¶

计算给定框架中的前导值。offset和default都相对于当前行进行评估。

default必须与expression具有相同的类型，但是，这仅由数据库验证，而不是在Python中验证。

MariaDB 和 default

MariaDB 不支持default参数。

`NthValue`¶

class NthValue(expression, nth=1, **extra)[source]¶

计算窗口内相对于偏移量nth（必须为正值）的行。如果不存在该行，则返回None。

某些数据库可能以不同的方式处理不存在的第n个值。例如，对于基于字符的表达式，Oracle 返回空字符串而不是None。Django 在这些情况下不执行任何转换。

`Ntile`¶

class Ntile(num_buckets=1, **extra)[source]¶

为 frame 子句中的每一行计算一个分区，并在 1 到 num_buckets 之间尽可能均匀地分配数字。如果行不能被桶数整除，则一个或多个桶将被更频繁地表示。

`PercentRank`¶

class PercentRank(*expressions, **extra)[source]¶

计算 frame 子句中行的相对排名。此计算等效于评估

(rank - 1) / (total rows - 1)

下表解释了行相对排名的计算方法

行号	值	排名	计算方法	相对排名
1	15	1	(1-1)/(7-1)	0.0000
2	20	2	(2-1)/(7-1)	0.1666
3	20	2	(2-1)/(7-1)	0.1666
4	20	2	(2-1)/(7-1)	0.1666
5	30	5	(5-1)/(7-1)	0.6666
6	30	5	(5-1)/(7-1)	0.6666
7	40	7	(7-1)/(7-1)	1.0000

`Rank`¶

class Rank(*expressions, **extra)[source]¶

与 RowNumber 相似，此函数对窗口中的行进行排名。计算出的排名包含间隙。使用 DenseRank 计算无间隙的排名。

`RowNumber`¶

class RowNumber(*expressions, **extra)[source]¶

根据 frame 子句的排序或整个查询的排序（如果窗口框架没有分区）计算行号。

条件表达式

分页器

返回顶部

文档

数据库函数¶

比较和转换函数¶

Cast¶

Coalesce¶

Collate¶

Greatest¶

JSONObject¶

Least¶

NullIf¶

日期函数¶

Extract¶

DateField 提取¶

DateTimeField 提取¶

Now¶

Trunc¶

DateField 截断¶

DateTimeField 截断¶

TimeField 截断¶

数学函数¶

Abs¶

ACos¶

ASin¶

ATan¶

ATan2¶

Ceil¶

Cos¶

Cot¶

Degrees¶

Exp¶

Floor¶

Ln¶

Log¶

Mod¶

Pi¶

Power¶

Radians¶

Random¶

Round¶

Sign¶

Sin¶

Sqrt¶

Tan¶

文本函数¶

Chr¶

Concat¶

Left¶

Length¶

Lower¶

LPad¶

LTrim¶

MD5¶

Ord¶

Repeat¶

Replace¶

Reverse¶

Right¶

RPad¶

RTrim¶

SHA1、SHA224、SHA256、SHA384 和 SHA512¶

StrIndex¶

Substr¶

Trim¶

Upper¶

窗口函数¶

CumeDist¶

DenseRank¶

FirstValue¶

Lag¶

LastValue¶

Lead¶

NthValue¶

Ntile¶

PercentRank¶

Rank¶

RowNumber¶

其他信息

支持 Django！

目录

浏览

`Cast`¶

`Coalesce`¶

`Collate`¶

`Greatest`¶

`JSONObject`¶

`Least`¶

`NullIf`¶

`Extract`¶

`DateField` 提取¶

`DateTimeField` 提取¶

`Now`¶

`Trunc`¶

`DateField` 截断¶

`DateTimeField` 截断¶

`TimeField` 截断¶

`Abs`¶

`ACos`¶

`ASin`¶

`ATan`¶

`ATan2`¶

`Ceil`¶

`Cos`¶

`Cot`¶

`Degrees`¶

`Exp`¶

`Floor`¶

`Ln`¶

`Log`¶

`Mod`¶

`Pi`¶

`Power`¶

`Radians`¶

`Random`¶

`Round`¶

`Sign`¶

`Sin`¶

`Sqrt`¶

`Tan`¶

`Chr`¶

`Concat`¶

`Left`¶

`Length`¶

`Lower`¶

`LPad`¶

`LTrim`¶

`MD5`¶

`Ord`¶

`Repeat`¶

`Replace`¶

`Reverse`¶

`Right`¶

`RPad`¶

`RTrim`¶

`SHA1`、`SHA224`、`SHA256`、`SHA384` 和 `SHA512`¶

`StrIndex`¶

`Substr`¶

`Trim`¶

`Upper`¶

`CumeDist`¶

`DenseRank`¶

`FirstValue`¶

`Lag`¶

`LastValue`¶

`Lead`¶

`NthValue`¶

`Ntile`¶

`PercentRank`¶

`Rank`¶

`RowNumber`¶