Django 5.1.dev 文档

Home | Table of contents | Index | Modules

« previous | up | next »

数据库函数¶

下面介绍的类为用户提供了一种使用底层数据库提供的函数作为django中的注释、聚合或过滤器的方法。功能还包括 expressions ，因此它们可以与其他表达式（如 aggregate functions .

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

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)[源代码]¶

强制结果类型为 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)[源代码]¶

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

使用示例：

>>> # 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

警告

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

>>> 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)[源代码]¶

接受要查询的表达式和排序规则名称。

例如，要在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)[源代码]¶

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

使用实例：

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 .

警告

行为 Greatest 当一个或多个表达式 null 数据库不同：

PostgreSQL： Greatest 将返回最大的非空表达式，或 null 如果所有表达式都是 null .
sqlite、oracle和mysql：如果有任何表达式 null ， Greatest 将返回 null .

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

`JSONObject`¶

class JSONObject(**fields)[源代码]¶

获取键-值对的列表，并返回包含这些对的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)[源代码]¶

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

警告

行为 Least 当一个或多个表达式 null 数据库不同：

PostgreSQL： Least 将返回最小的非空表达式，或者 null 如果所有表达式都是 null .
sqlite、oracle和mysql：如果有任何表达式 null ， Least 将返回 null .

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

`NullIf`¶

class NullIf(expression1, expression2)[源代码]¶

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

关于甲骨文的警告

由于一个 Oracle convention ，此函数返回空字符串，而不是 None 当表达式类型为 CharField .

经过 Value(None) 到 expression1 在Oracle上是禁止的，因为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)[源代码]¶

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

需要一个 expression 代表一个 DateField ， DateTimeField ， TimeField ，或 DurationField 以及一个 lookup_name 引用的日期部分，并返回 lookup_name 作为一个 IntegerField 。Django通常使用数据库的提取函数，因此您可以使用任何 lookup_name 您的数据库支持的。一个 tzinfo 子类，通常由 zoneinfo ，可以传递以提取特定时区的值。

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

“年”：2015
“ISO年”：2015年
“四分之一”：2
“月份”：6
“天”：15
“周”：25
“周日”：2
“iso周”日：1
“小时”：23
“分钟”：30
“第二”：1

如果一个不同的时区 Australia/Melbourne 在Django中处于活动状态，然后在提取值之前将日期时间转换为时区。上述示例日期中墨尔本的时区偏移量为+10:00。此时区处于活动状态时返回的值将与上面的值相同，除了：

“天”：16
“周日”：3
“iso周”日：2
“小时”：9

week_day 价值观

这个 week_day lookup_type 计算方法与大多数数据库和Python的标准函数不同。此函数将返回 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)[源代码]¶

lookup_name = 'year'

class ExtractIsoYear(expression, tzinfo=None, **extra)[源代码]¶

返回ISO-8601周编号年份。

lookup_name = 'iso_year'

class ExtractMonth(expression, tzinfo=None, **extra)[源代码]¶

lookup_name = 'month'

class ExtractDay(expression, tzinfo=None, **extra)[源代码]¶

lookup_name = 'day'

class ExtractWeekDay(expression, tzinfo=None, **extra)[源代码]¶

lookup_name = 'week_day'

class ExtractIsoWeekDay(expression, tzinfo=None, **extra)[源代码]¶

返回ISO-8601星期一，第1天是星期一，第7天是星期天。

lookup_name = 'iso_week_day'

class ExtractWeek(expression, tzinfo=None, **extra)[源代码]¶

lookup_name = 'week'

class ExtractQuarter(expression, tzinfo=None, **extra)[源代码]¶

lookup_name = 'quarter'

它们在逻辑上等同于 Extract('date_field', lookup_name) . 每个班也是一个 Transform 注册在 DateField 和 DateTimeField 作为 __(lookup_name) ，例如 __year .

自.以来 DateField S没有时间成分，只有 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 S。

class ExtractHour(expression, tzinfo=None, **extra)[源代码]¶

lookup_name = 'hour'

class ExtractMinute(expression, tzinfo=None, **extra)[源代码]¶

lookup_name = 'minute'

class ExtractSecond(expression, tzinfo=None, **extra)[源代码]¶

lookup_name = 'second'

它们在逻辑上等同于 Extract('datetime_field', lookup_name) . 每个班也是一个 Transform 注册在 DateTimeField 作为 __(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 然后，DATETIME以UTC格式存储在数据库中。如果Django中有不同的时区处于活动状态，则在提取值之前，DateTime将被转换为该时区。下面的示例转换为墨尔本时区(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[源代码]¶

返回执行查询时数据库服务器的当前日期和时间，通常使用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上，SQL LOCALTIMESTAMP 用于避免与造型有关的问题 CURRENT_TIMESTAMP 至 DateTimeField 。

Changed in Django 5.0:

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

`Trunc`¶

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

将日期截断到重要组件。

当你只关心某一年、某一小时或某一天发生了什么事，而不是某一秒，那么 Trunc （及其子类）对于筛选或聚合数据很有用。例如，您可以使用 Trunc 计算每天的销售量。

Trunc 拿着一张单人票 expression ，代表一种 DateField ， TimeField ，或 DateTimeField 一种 kind 表示日期或时间部分的 output_field 这要么是 DateTimeField() ， TimeField() ，或 DateField() 。它返回日期时间、日期或时间，具体取决于 output_field ，其字段最高可达 kind 设置为它们的最小值。如果 output_field 被省略，则它将默认为 output_field 的 expression 。一个 tzinfo 子类，通常由 zoneinfo ，可以传递以截断特定时区中的值。

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

“年”：2015-01-01 00:00:00+00:00
“季度”：2015-04-01 00:00:00+00:00
“月”：2015-06-01 00:00:00+00:00
“周”：2015-06-15 00:00:00+00:00
“天”：2015-06-15 00:00:00+00:00
“小时”：2015-06-15 14:00:00+00:00
“分钟”：2015-06-15 14:30:00+00:00
“第二”：2015-06-15 14:30:50+00:00

如果一个不同的时区 Australia/Melbourne 在Django中处于活动状态，然后在截断值之前将日期时间转换为新时区。上述示例日期中墨尔本的时区偏移量为+10:00。此时区处于活动状态时返回的值为：

“年”：2015-01-01 00:00:00+11:00
“季度”：2015-04-01 00:00:00+10:00
“月”：2015-06-01 00:00:00+10:00
“周”：2015-06-16 00:00:00+10:00
“天”：2015-06-16 00:00:00+10:00
“小时”：2015-06-16 00:00:00+10:00
“分钟”：2015-06-16 00:30:00+10:00
“第二”：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)[源代码]¶

kind = 'year'

class TruncMonth(expression, output_field=None, tzinfo=None, **extra)[源代码]¶

kind = 'month'

class TruncWeek(expression, output_field=None, tzinfo=None, **extra)[源代码]¶

在星期一截断到午夜。

kind = 'week'

class TruncQuarter(expression, output_field=None, tzinfo=None, **extra)[源代码]¶

kind = 'quarter'

它们在逻辑上等同于 Trunc('date_field', kind) . 他们把日期的所有部分截短到 kind 它允许以较低的精度对日期进行分组或筛选。 expression 可以有一个 output_field 任一 DateField 或 DateTimeField .

自.以来 DateField S没有时间成分，只有 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)[源代码]¶

lookup_name = 'date'

output_field = DateField()

TruncDate 铸件 expression 而不是使用内置的SQL截断函数。它也注册为 DateTimeField 作为 __date .

class TruncTime(expression, tzinfo=None, **extra)[源代码]¶

lookup_name = 'time'

output_field = TimeField()

TruncTime 铸件 expression 而不是使用内置的SQL截断函数。它也注册为 DateTimeField 作为 __time .

class TruncDay(expression, output_field=None, tzinfo=None, **extra)[源代码]¶

kind = 'day'

class TruncHour(expression, output_field=None, tzinfo=None, **extra)[源代码]¶

kind = 'hour'

class TruncMinute(expression, output_field=None, tzinfo=None, **extra)[源代码]¶

kind = 'minute'

class TruncSecond(expression, output_field=None, tzinfo=None, **extra)[源代码]¶

kind = 'second'

它们在逻辑上等同于 Trunc('datetime_field', kind) . 他们把日期的所有部分截短到 kind 并且允许以较低的精度对日期时间进行分组或筛选。 expression 必须有一个 output_field 属于 DateTimeField .

使用示例：

>>> 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)[源代码]

kind = 'hour'

class TruncMinute(expression, output_field=None, tzinfo=None, **extra)[源代码]

kind = 'minute'

class TruncSecond(expression, output_field=None, tzinfo=None, **extra)[源代码]

kind = 'second'

它们在逻辑上等同于 Trunc('time_field', kind) . 他们把时间的所有部分缩短到 kind 它允许以较低的精度分组或过滤时间。 expression 可以有一个 output_field 任一 TimeField 或 DateTimeField .

自.以来 TimeField S没有日期组件，只有 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

返回数值字段或表达式的反余弦。表达式值必须在-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)[源代码]¶

返回数值字段或表达式的反正弦。表达式值必须在-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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

返回的反正切值 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

返回的值 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

返回数学常数的值 π .

`Power`¶

class Power(expression1, expression2, **extra)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

`Round`¶

class Round(expression, precision=0, **extra)[源代码]¶

将数值字段或表达式四舍五入为 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)[源代码]¶

返回数值字段或表达式的符号（-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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

接受数值字段或表达式，并将表达式的文本表示形式返回为单个字符。它与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)[源代码]¶

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

此函数永远不会有空结果。在一个空参数导致整个表达式为空的后端，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)[源代码]¶

返回第一个 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)[源代码]¶

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

使用示例：

>>> # 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)[源代码]¶

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

它也可以注册为转换，如中所述 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)[源代码]¶

返回左侧填充的给定文本字段或表达式的值 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)[源代码]¶

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

`MD5`¶

class MD5(expression, **extra)[源代码]¶

接受单个文本字段或表达式并返回字符串的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)[源代码]¶

接受单个文本字段或表达式，并返回该表达式第一个字符的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)[源代码]¶

返回给定文本字段或表达式的重复值 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)[源代码]¶

替换所有出现的 text 具有 replacement 在里面 expression . 默认替换文本为空字符串。函数的参数区分大小写。

使用示例：

>>> 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)[源代码]¶

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

它也可以注册为转换，如中所述 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)[源代码]¶

返回最后一个 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)[源代码]¶

类似 LPad 但右边有垫子。

`RTrim`¶

class RTrim(expression, **extra)[源代码]¶

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

`SHA1`, `SHA224`, `SHA256`, `SHA384`, and `SHA512`¶

class SHA1(expression, **extra)[源代码]¶

class SHA224(expression, **extra)[源代码]¶

class SHA256(expression, **extra)[源代码]¶

class SHA384(expression, **extra)[源代码]¶

class SHA512(expression, **extra)[源代码]¶

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

它们也可以注册为转换，如中所述 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 extension 必须安装。你可以使用 CryptoExtension 要安装的迁移操作。

甲骨文公司

Oracle不支持 SHA224 功能。

`StrIndex`¶

class StrIndex(string, substring, **extra)[源代码]¶

返回与第一个匹配项的索引位置1对应的正整数 substring 里面 string 或0如果 substring 找不到。

使用示例：

>>> 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中，数据库表的 collation 确定字符串比较（例如 expression 和 substring （对于此函数）区分大小写。默认情况下，比较不区分大小写。

`Substr`¶

class Substr(expression, pos, length=None, **extra)[源代码]¶

返回长度的子字符串 length 从位置开始的字段或表达式 pos . 位置是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)[源代码]¶

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

使用示例：

>>> 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)[源代码]¶

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

它也可以注册为转换，如中所述 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)[源代码]¶

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

`DenseRank`¶

class DenseRank(*expressions, **extra)[源代码]¶

相当于 Rank 但没有差距。

`FirstValue`¶

class FirstValue(expression, **extra)[源代码]¶

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

`Lag`¶

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

计算值偏移量 offset ，如果不存在行，则返回 default .

default 必须与 expression 但是，这只能由数据库验证，而不能在Python中验证。

MariaDB和 default

玛丽亚德 doesn't support 这个 default 参数。

`LastValue`¶

class LastValue(expression, **extra)[源代码]¶

可比 FirstValue ，它计算给定frame子句中的最后一个值。

`Lead`¶

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

计算给定 frame .两者都是 offset 和 default 对当前行进行计算。

default 必须与 expression 但是，这只能由数据库验证，而不能在Python中验证。

MariaDB和 default

玛丽亚德 doesn't support 这个 default 参数。

`NthValue`¶

class NthValue(expression, nth=1, **extra)[源代码]¶

计算相对于偏移量的行 nth （必须是正值）在窗口中。退换商品 None 如果不存在行。

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

`Ntile`¶

class Ntile(num_buckets=1, **extra)[源代码]¶

为frame子句中的每一行计算一个分区，在1和之间尽可能均匀地分布数字。 num_buckets . 如果行不均匀地划分为若干个存储桶，则一个或多个存储桶将更频繁地表示。

`PercentRank`¶

class PercentRank(*expressions, **extra)[源代码]¶

计算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)[源代码]¶

可比 RowNumber ，此函数对窗口中的行进行排名。计算出的列组包含间隙。使用 DenseRank 计算无间隙的秩。

`RowNumber`¶

class RowNumber(*expressions, **extra)[源代码]¶

根据frame子句的顺序或整个查询的顺序计算行数（如果没有对 window frame .

« previous | up | next »

Django 5.1.dev 文档

数据库函数¶

比较和转换函数¶

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, and SHA512¶

StrIndex¶

Substr¶

Trim¶

Upper¶

窗口功能¶

CumeDist¶

DenseRank¶

FirstValue¶

Lag¶

LastValue¶

Lead¶

NthValue¶

Ntile¶

PercentRank¶

Rank¶

RowNumber¶

Last update:

`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`, and `SHA512`¶

`StrIndex`¶

`Substr`¶

`Trim`¶

`Upper`¶

`CumeDist`¶

`DenseRank`¶

`FirstValue`¶

`Lag`¶

`LastValue`¶

`Lead`¶

`NthValue`¶

`Ntile`¶

`PercentRank`¶

`Rank`¶

`RowNumber`¶