{"title":"数据库函数","version":"6.0","locale":"zh-hans","docname":"ref/models/database-functions","url":"/zh-hans/6.0/ref/models/database-functions/","canonical":"https://djangodocs.dev/zh-hans/6.0/ref/models/database-functions/","summary":"The classes documented below provide a way for users to use functions provided by the underlying database as annotations, aggregations, or filters in Django.…","html":"

数据库函数Link to this heading#

\n

The classes documented below provide a way for users to use functions provided\nby the underlying database as annotations, aggregations, or filters in Django.\nFunctions are also expressions, so they can be\nused and combined with other expressions like aggregate functions. See the Func documentation\nfor security considerations.

\n

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

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

我们通常不建议允许 null=True 为 CharField，因为这允许字段有两个 Coalesce，但它对下面的 Coalesce 例子很重要。

\n
\n

比较和转换函数Link to this heading#

\n
\n

CastLink to this heading#

\n
\n
\nclass Cast(expression, output_field)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

CoalesceLink to this heading#

\n
\n
\nclass Coalesce(*expressions, **extra)Link to this definition#
\n
\n\n

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

\n

使用示例：

\n
Python console
>>> # Get a screen name from least to most public\n>>> from django.db.models import Sum\n>>> from django.db.models.functions import Coalesce\n>>> Author.objects.create(name="Margaret Smith", goes_by="Maggie")\n>>> author = Author.objects.annotate(screen_name=Coalesce("alias", "goes_by", "name")).get()\n>>> print(author.screen_name)\nMaggie\n\n>>> # Prevent an aggregate Sum() from returning None\n>>> # The aggregate default argument uses Coalesce() under the hood.\n>>> aggregated = Author.objects.aggregate(\n...     combined_age=Sum("age"),\n...     combined_age_default=Sum("age", default=0),\n...     combined_age_coalesce=Coalesce(Sum("age"), 0),\n... )\n>>> print(aggregated["combined_age"])\nNone\n>>> print(aggregated["combined_age_default"])\n0\n>>> print(aggregated["combined_age_coalesce"])\n0\n
\n\n
\n
\n

CollateLink to this heading#

\n
\n
\nclass Collate(expression, collation)Link to this definition#
\n
\n\n

接受一个表达式和一个排序规则名称来进行查询。

\n

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

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

它还可以用于排序，例如在 PostgreSQL 中：

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

GreatestLink to this heading#

\n
\n
\nclass Greatest(*expressions, **extra)Link to this definition#
\n
\n\n

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

\n

使用实例：

\n
Code
class Blog(models.Model):\n    body = models.TextField()\n    modified = models.DateTimeField(auto_now=True)\n\n\nclass Comment(models.Model):\n    body = models.TextField()\n    modified = models.DateTimeField(auto_now=True)\n    blog = models.ForeignKey(Blog, on_delete=models.CASCADE)\n
\n
Python console
>>> from django.db.models.functions import Greatest\n>>> blog = Blog.objects.create(body="Greatest is the best.")\n>>> comment = Comment.objects.create(body="No, Least is better.", blog=blog)\n>>> comments = Comment.objects.annotate(last_updated=Greatest("modified", "blog__modified"))\n>>> annotated_comment = comments.get()\n
\n

annotated_comment.last_updated 将是 blog.modified 和 comment.modified 中最近的。

\n\n
\n
\n

LeastLink to this heading#

\n
\n
\nclass Least(*expressions, **extra)Link to this definition#
\n
\n\n

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

\n\n
\n
\n

NullIfLink to this heading#

\n
\n
\nclass NullIf(expression1, expression2)Link to this definition#
\n
\n\n

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

\n\n
\n
\n
\n

日期函数Link to this heading#

\n

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

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

ExtractLink to this heading#

\n
\n
\nclass Extract(expression, lookup_name=None, tzinfo=None, **extra)Link to this definition#
\n
\n\n

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

\n

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

\n

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

\n\n

如果在 Django 中使用了不同的时区，比如 Australia/Melbourne ，那么在提取值之前，日期时间会被转换为该时区。在上面的例子中，墨尔本的时区偏移是 +10:00。当这个时区被激活时，返回的值将与上述相同，除了：

\n\n\n\n

上面的每个 lookup_name 都有一个相应的 Extract 子类（下面列出的），通常应该用这个子类来代替比较啰嗦的等价物，例如，使用 ExtractYear(...) 而不是 Extract(...，lookup_name='year')。

\n

用法示例：

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

DateField 提取Link to this heading#

\n
\n
\nclass ExtractYear(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'year'
\n
\n\n
\n\n
\n
\nclass ExtractIsoYear(expression, tzinfo=None, **extra)Link to this definition#
\n

返回 ISO-8601 的周号年份。

\n
\n
\nlookup_name = 'iso_year'
\n
\n\n
\n\n
\n
\nclass ExtractMonth(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'month'
\n
\n\n
\n\n
\n
\nclass ExtractDay(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'day'
\n
\n\n
\n\n
\n
\nclass ExtractWeekDay(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'week_day'
\n
\n\n
\n\n
\n
\nclass ExtractIsoWeekDay(expression, tzinfo=None, **extra)Link to this definition#
\n

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

\n
\n
\nlookup_name = 'iso_week_day'
\n
\n\n
\n\n
\n
\nclass ExtractWeek(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'week'
\n
\n\n
\n\n
\n
\nclass ExtractQuarter(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'quarter'
\n
\n\n
\n\n

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

\n

由于 DateField 不包含时间组件，因此只能使用处理日期部分的 Extract 子类与 DateField 一起使用：

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

DateTimeField 提取Link to this heading#

\n

除以下内容外，上述 DateField 的所有提取物也可用于``DateTimeField``。

\n
\n
\nclass ExtractHour(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'hour'
\n
\n\n
\n\n
\n
\nclass ExtractMinute(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'minute'
\n
\n\n
\n\n
\n
\nclass ExtractSecond(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'second'
\n
\n\n
\n\n

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

\n

DateTimeField 例子：

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

当 USE_TZ 设置为 True 时，日期时间将以 UTC 格式存储在数据库中。如果 Django 中有不同的时区激活，那么在提取值之前，日期时间将被转换为该时区。下面的示例将日期时间转换为墨尔本时区（UTC +10:00），这将改变返回的日期、工作日和小时值：

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

显式传递时区给 Extract 函数的行为与上述相同，并优先于激活的时区：

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

NowLink to this heading#

\n
\n
\nclass NowLink to this definition#
\n
\n\n

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

\n

用法示例：

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

TruncLink to this heading#

\n
\n
\nclass Trunc(expression, kind, output_field=None, tzinfo=None, **extra)Link to this definition#
\n
\n\n

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

\n

当你只关心某事是否发生在某年、某小时或某天，而不关心确切的秒数时，那么 Trunc （及其子类）可以用来过滤或汇总你的数据。例如，你可以使用 Trunc 来计算每天的销售数量。

\n

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

\n

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

\n\n

如果在 Django 中使用了不同的时区，比如 Australia/Melbourne，那么日期时间会在被截断之前转换为新的时区。在上面的例子中，墨尔本的时区偏移是 +10:00。当这个时区被激活时，返回的值将是：

\n\n

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

\n

以上每个 kind 都有一个对应的 Trunc 子类（下面列出的），通常应该用这个子类来代替比较啰嗦的等价物，例如使用 TruncYear(...) 而不是 Trunc(...，kind='year')。

\n

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

\n

用法示例：

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

DateField 截断Link to this heading#

\n
\n
\nclass TruncYear(expression, output_field=None, tzinfo=None, **extra)Link to this definition#
\n
\n
\nkind = 'year'
\n
\n\n
\n\n
\n
\nclass TruncMonth(expression, output_field=None, tzinfo=None, **extra)Link to this definition#
\n
\n
\nkind = 'month'
\n
\n\n
\n\n
\n
\nclass TruncWeek(expression, output_field=None, tzinfo=None, **extra)Link to this definition#
\n

截断到每周一的午夜。

\n
\n
\nkind = 'week'
\n
\n\n
\n\n
\n
\nclass TruncQuarter(expression, output_field=None, tzinfo=None, **extra)Link to this definition#
\n
\n
\nkind = 'quarter'
\n
\n\n
\n\n

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

\n

由于 DateField 不包含时间组件，因此只能使用处理日期部分的 Trunc 子类与 DateField 一起使用：

\n
Python console
>>> from datetime import UTC, datetime\n>>> from django.db.models import Count\n>>> from django.db.models.functions import TruncMonth, TruncYear\n>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=UTC)\n>>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=UTC)\n>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=UTC)\n>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())\n>>> Experiment.objects.create(start_datetime=start2, start_date=start2.date())\n>>> Experiment.objects.create(start_datetime=start3, start_date=start3.date())\n>>> experiments_per_year = (\n...     Experiment.objects.annotate(year=TruncYear("start_date"))\n...     .values("year")\n...     .annotate(experiments=Count("id"))\n... )\n>>> for exp in experiments_per_year:\n...     print(exp["year"], exp["experiments"])\n...\n2014-01-01 1\n2015-01-01 2\n\n>>> import zoneinfo\n>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")\n>>> experiments_per_month = (\n...     Experiment.objects.annotate(month=TruncMonth("start_datetime", tzinfo=melb))\n...     .values("month")\n...     .annotate(experiments=Count("id"))\n... )\n>>> for exp in experiments_per_month:\n...     print(exp["month"], exp["experiments"])\n...\n2015-06-01 00:00:00+10:00 1\n2016-01-01 00:00:00+11:00 1\n2014-06-01 00:00:00+10:00 1\n
\n
\n
\n

DateTimeField 截断Link to this heading#

\n
\n
\nclass TruncDate(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'date'
\n
\n\n
\n
\noutput_field = DateField()
\n
\n\n
\n\n

TruncDate 将 expression 投射到一个日期，而不是使用内置的 SQL truncate 函数。在 DateTimeField 上，它也被注册为 __date 的转换。

\n
\n
\nclass TruncTime(expression, tzinfo=None, **extra)Link to this definition#
\n
\n
\nlookup_name = 'time'
\n
\n\n
\n
\noutput_field = TimeField()
\n
\n\n
\n\n

TruncTime 将 expression 投射到一个时间，而不是使用内置的 SQL truncate 函数。在 DateTimeField 上，它也被注册为 __time 的转换。

\n
\n
\nclass TruncDay(expression, output_field=None, tzinfo=None, **extra)Link to this definition#
\n
\n
\nkind = 'day'
\n
\n\n
\n\n
\n
\nclass TruncHour(expression, output_field=None, tzinfo=None, **extra)Link to this definition#
\n
\n
\nkind = 'hour'
\n
\n\n
\n\n
\n
\nclass TruncMinute(expression, output_field=None, tzinfo=None, **extra)Link to this definition#
\n
\n
\nkind = 'minute'
\n
\n\n
\n\n
\n
\nclass TruncSecond(expression, output_field=None, tzinfo=None, **extra)Link to this definition#
\n
\n
\nkind = 'second'
\n
\n\n
\n\n

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

\n

用法示例：

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

TimeField 截断Link to this heading#

\n
\n
\nclass TruncHour(expression, output_field=None, tzinfo=None, **extra)
\n
\n
\nkind = 'hour'
\n
\n\n
\n\n
\n
\nclass TruncMinute(expression, output_field=None, tzinfo=None, **extra)
\n
\n
\nkind = 'minute'
\n
\n\n
\n\n
\n
\nclass TruncSecond(expression, output_field=None, tzinfo=None, **extra)
\n
\n
\nkind = 'second'
\n
\n\n
\n\n

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

\n

由于 TimeField 不包含日期组件，因此只能使用处理时间部分的 Trunc 子类与 TimeField 一起使用：

\n
Python console
>>> from datetime import UTC, datetime\n>>> from django.db.models import Count, TimeField\n>>> from django.db.models.functions import TruncHour\n>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=UTC)\n>>> start2 = datetime(2014, 6, 15, 14, 40, 2, 123, tzinfo=UTC)\n>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=UTC)\n>>> Experiment.objects.create(start_datetime=start1, start_time=start1.time())\n>>> Experiment.objects.create(start_datetime=start2, start_time=start2.time())\n>>> Experiment.objects.create(start_datetime=start3, start_time=start3.time())\n>>> experiments_per_hour = (\n...     Experiment.objects.annotate(\n...         hour=TruncHour("start_datetime", output_field=TimeField()),\n...     )\n...     .values("hour")\n...     .annotate(experiments=Count("id"))\n... )\n>>> for exp in experiments_per_hour:\n...     print(exp["hour"], exp["experiments"])\n...\n14:00:00 2\n17:00:00 1\n\n>>> import zoneinfo\n>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")\n>>> experiments_per_hour = (\n...     Experiment.objects.annotate(\n...         hour=TruncHour("start_datetime", tzinfo=melb),\n...     )\n...     .values("hour")\n...     .annotate(experiments=Count("id"))\n... )\n>>> for exp in experiments_per_hour:\n...     print(exp["hour"], exp["experiments"])\n...\n2014-06-16 00:00:00+10:00 2\n2016-01-01 04:00:00+11:00 1\n
\n
\n
\n
\n
\n

JSON FunctionsLink to this heading#

\n
\n

JSONArrayLink to this heading#

\n\n
\n
\nclass JSONArray(*expressions)Link to this definition#
\n
\n\n

Accepts a list of field names or expressions and returns a JSON array\ncontaining those values.

\n

用法示例：

\n
Python console
>>> from django.db.models import F\n>>> from django.db.models.functions import JSONArray, Lower\n>>> Author.objects.create(name="Margaret Smith", alias="msmith", age=25)\n>>> author = Author.objects.annotate(\n...     json_array=JSONArray(\n...         Lower("name"),\n...         "alias",\n...         F("age") * 2,\n...     )\n... ).get()\n>>> author.json_array\n['margaret smith', 'msmith', 50]\n
\n
\n
\n

JSONObjectLink to this heading#

\n
\n
\nclass JSONObject(**fields)Link to this definition#
\n
\n\n

接受一组键值对，并返回一个包含这些键值对的 JSON 对象。

\n

用法示例：

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

数学函数Link to this heading#

\n

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

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

AbsLink to this heading#

\n
\n
\nclass Abs(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

ACosLink to this heading#

\n
\n
\nclass ACos(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

ASinLink to this heading#

\n
\n
\nclass ASin(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

ATanLink to this heading#

\n
\n
\nclass ATan(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

ATan2Link to this heading#

\n
\n
\nclass ATan2(expression1, expression2, **extra)Link to this definition#
\n
\n\n

返回 expression1 / expression2 的正切值。

\n

用法示例：

\n
Python console
>>> from django.db.models.functions import ATan2\n>>> Vector.objects.create(x=2.5, y=1.9)\n>>> vector = Vector.objects.annotate(atan2=ATan2("x", "y")).get()\n>>> vector.atan2\n0.9209258773829491\n
\n
\n
\n

CeilLink to this heading#

\n
\n
\nclass Ceil(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

CosLink to this heading#

\n
\n
\nclass Cos(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

CotLink to this heading#

\n
\n
\nclass Cot(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

DegreesLink to this heading#

\n
\n
\nclass Degrees(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

ExpLink to this heading#

\n
\n
\nclass Exp(expression, **extra)Link to this definition#
\n
\n\n

返回 e （自然对数基数）的值，将其升为一个数值字段或表达式的幂。

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

FloorLink to this heading#

\n
\n
\nclass Floor(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

LnLink to this heading#

\n
\n
\nclass Ln(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

LogLink to this heading#

\n
\n
\nclass Log(expression1, expression2, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

ModLink to this heading#

\n
\n
\nclass Mod(expression1, expression2, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

\n
Python console
>>> from django.db.models.functions import Mod\n>>> Vector.objects.create(x=5.4, y=2.3)\n>>> vector = Vector.objects.annotate(mod=Mod("x", "y")).get()\n>>> vector.mod\n0.8\n
\n
\n
\n

PiLink to this heading#

\n
\n
\nclass Pi(**extra)Link to this definition#
\n
\n\n

返回数学常数 π 的值。

\n
\n
\n

PowerLink to this heading#

\n
\n
\nclass Power(expression1, expression2, **extra)Link to this definition#
\n
\n\n

接受两个数值字段或表达式，并将第一个字段的值提高到第二个字段的幂。

\n

用法示例：

\n
Python console
>>> from django.db.models.functions import Power\n>>> Vector.objects.create(x=2, y=-2)\n>>> vector = Vector.objects.annotate(power=Power("x", "y")).get()\n>>> vector.power\n0.25\n
\n
\n
\n

RadiansLink to this heading#

\n
\n
\nclass Radians(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

RandomLink to this heading#

\n
\n
\nclass Random(**extra)Link to this definition#
\n
\n\n

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

\n
\n
\n

RoundLink to this heading#

\n
\n
\nclass Round(expression, precision=0, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

SignLink to this heading#

\n
\n
\nclass Sign(expression, **extra)Link to this definition#
\n
\n\n

返回一个数字字段或表达式的符号（-1，0，1）。

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

SinLink to this heading#

\n
\n
\nclass Sin(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

SqrtLink to this heading#

\n
\n
\nclass Sqrt(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

TanLink to this heading#

\n
\n
\nclass Tan(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

文本函数Link to this heading#

\n
\n

ChrLink to this heading#

\n
\n
\nclass Chr(expression, **extra)Link to this definition#
\n
\n\n

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

\n

和 Length 一样，它也可以在 IntegerField 上作为变换注册。默认的查询名是 chr。

\n

用法示例：

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

ConcatLink to this heading#

\n
\n
\nclass Concat(*expressions, **extra)Link to this definition#
\n
\n\n

接受至少两个文本字段或表达式的列表，并返回连接后的文本。每个参数必须是文本或字符类型。如果你想把一个 TextField() 和一个 CharField() 连接起来，那么一定要告诉 Django，output_field 应该是一个 TextField()。当连接一个 Value 时，也需要指定一个 output_field，如下面的例子。

\n

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

\n

用法示例：

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

LeftLink to this heading#

\n
\n
\nclass Left(expression, length, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

LengthLink to this heading#

\n
\n
\nclass Length(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

它也可以注册为一个转换操作。例如：

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

LowerLink to this heading#

\n
\n
\nclass Lower(expression, **extra)Link to this definition#
\n
\n\n

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

\n

它也可以像 Length 中描述的那样，作为一个变换注册。

\n

用法示例：

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

LPadLink to this heading#

\n
\n
\nclass LPad(expression, length, fill_text=Value(' '), **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

\n
Python console
>>> from django.db.models import Value\n>>> from django.db.models.functions import LPad\n>>> Author.objects.create(name="John", alias="j")\n>>> Author.objects.update(name=LPad("name", 8, Value("abc")))\n1\n>>> print(Author.objects.get(alias="j").name)\nabcaJohn\n
\n
\n
\n

LTrimLink to this heading#

\n
\n
\nclass LTrim(expression, **extra)Link to this definition#
\n
\n\n

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

\n
\n
\n

MD5Link to this heading#

\n
\n
\nclass MD5(expression, **extra)Link to this definition#
\n
\n\n

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

\n

它也可以像 Length 中描述的那样，作为一个变换注册。

\n

用法示例：

\n
Python console
>>> from django.db.models.functions import MD5\n>>> Author.objects.create(name="Margaret Smith")\n>>> author = Author.objects.annotate(name_md5=MD5("name")).get()\n>>> print(author.name_md5)\n749fb689816b2db85f5b169c2055b247\n
\n
\n
\n

OrdLink to this heading#

\n
\n
\nclass Ord(expression, **extra)Link to this definition#
\n
\n\n

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

\n

也可以像 Length 中描述的那样，把它注册为一个变换。默认的查找名称是 ord。

\n

用法示例：

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

RepeatLink to this heading#

\n
\n
\nclass Repeat(expression, number, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

\n
Python console
>>> from django.db.models.functions import Repeat\n>>> Author.objects.create(name="John", alias="j")\n>>> Author.objects.update(name=Repeat("name", 3))\n1\n>>> print(Author.objects.get(alias="j").name)\nJohnJohnJohn\n
\n
\n
\n

ReplaceLink to this heading#

\n
\n
\nclass Replace(expression, text, replacement=Value(''), **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

ReverseLink to this heading#

\n
\n
\nclass Reverse(expression, **extra)Link to this definition#
\n
\n\n

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

\n

也可以像 Length 中描述的那样，把它注册为一个变换。默认的查询名称是 reverse。

\n

用法示例：

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

RightLink to this heading#

\n
\n
\nclass Right(expression, length, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

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

RPadLink to this heading#

\n
\n
\nclass RPad(expression, length, fill_text=Value(' '), **extra)Link to this definition#
\n
\n\n

类似于 LPad，但垫在右边。

\n
\n
\n

RTrimLink to this heading#

\n
\n
\nclass RTrim(expression, **extra)Link to this definition#
\n
\n\n

类似于 Trim，但只删除尾部的空格。

\n
\n
\n

SHA1、SHA224`、SHA256`、SHA384` 和 SHA512。Link to this heading#

\n
\n
\nclass SHA1(expression, **extra)Link to this definition#
\n
\n\n
\n
\nclass SHA224(expression, **extra)Link to this definition#
\n
\n\n
\n
\nclass SHA256(expression, **extra)Link to this definition#
\n
\n\n
\n
\nclass SHA384(expression, **extra)Link to this definition#
\n
\n\n
\n
\nclass SHA512(expression, **extra)Link to this definition#
\n
\n\n

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

\n

它们也可以像 Length 中描述的那样注册为变换。

\n

用法示例：

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

StrIndexLink to this heading#

\n
\n
\nclass StrIndex(expression, substring, **extra)Link to this definition#
\n
\n\n

Returns a positive integer corresponding to the 1-indexed position of the first\noccurrence of substring inside expression, or 0 if substring is not\nfound.

\n

用法示例：

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

SubstrLink to this heading#

\n
\n
\nclass Substr(expression, pos, length=None, **extra)Link to this definition#
\n
\n\n

从字段或表达式的位置 pos 开始返回一个长度为 length 的子串。如果 length 是 None，那么将返回字符串的其余部分。

\n

用法示例：

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

TrimLink to this heading#

\n
\n
\nclass Trim(expression, **extra)Link to this definition#
\n
\n\n

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

\n

用法示例：

\n
Python console
>>> from django.db.models.functions import Trim\n>>> Author.objects.create(name="  John  ", alias="j")\n>>> Author.objects.update(name=Trim("name"))\n1\n>>> print(Author.objects.get(alias="j").name)\nJohn\n
\n
\n
\n

UpperLink to this heading#

\n
\n
\nclass Upper(expression, **extra)Link to this definition#
\n
\n\n

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

\n

它也可以像 Length 中描述的那样，作为一个变换注册。

\n

用法示例：

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

窗口函数Link to this heading#

\n

在 Window 表达式中，有很多函数可以用来计算元素的等级或某些行的 Ntile。

\n
\n

CumeDistLink to this heading#

\n
\n
\nclass CumeDist(*expressions, **extra)Link to this definition#
\n
\n\n

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

\n
\n
\n

DenseRankLink to this heading#

\n
\n
\nclass DenseRank(*expressions, **extra)Link to this definition#
\n
\n\n

相当于 Rank，但没有间隙。

\n
\n
\n

FirstValueLink to this heading#

\n
\n
\nclass FirstValue(expression, **extra)Link to this definition#
\n
\n\n

返回窗口帧第一行的值，如果没有这个值，则返回 None。

\n
\n
\n

LagLink to this heading#

\n
\n
\nclass Lag(expression, offset=1, default=None, **extra)Link to this definition#
\n
\n\n

计算 offset 的偏移值，如果没有行存在，返回 default。

\n

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

\n\n
\n
\n

LastValueLink to this heading#

\n
\n
\nclass LastValue(expression, **extra)Link to this definition#
\n
\n\n

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

\n
\n
\n

LeadLink to this heading#

\n
\n
\nclass Lead(expression, offset=1, default=None, **extra)Link to this definition#
\n
\n\n

计算给定 frame 中的前导值。offset 和 default 都是根据当前行的情况来计算的。

\n

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

\n\n
\n
\n

NthValueLink to this heading#

\n
\n
\nclass NthValue(expression, nth=1, **extra)Link to this definition#
\n
\n\n

计算相对于窗口内偏移量 nth （必须是正值）的行。如果没有行，返回 None。

\n

一些数据库可能会以不同的方式处理不存在的 nth-value，例如，对于基于字符的表达式，Oracle 会返回一个空字符串，而不是 None。在这些情况下，Django 不做任何转换。

\n
\n
\n

NtileLink to this heading#

\n
\n
\nclass Ntile(num_buckets=1, **extra)Link to this definition#
\n
\n\n

为帧子句中的每一行计算一个分区，在 1 和 num_buckets 之间尽可能均匀地分配数字。如果行没有被平均分配到若干个桶中，则一个或多个桶将被更频繁地表示。

\n
\n
\n

PercentRankLink to this heading#

\n
\n
\nclass PercentRank(*expressions, **extra)Link to this definition#
\n
\n\n

计算帧子句中行的相对排名。这个计算等同于评估：

\n
Text
(rank - 1) / (total rows - 1)\n
\n

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

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

行 #

值

排名

计算

相对排名

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

\n
\n
\n
\n

RankLink to this heading#

\n
\n
\nclass Rank(*expressions, **extra)Link to this definition#
\n
\n\n

与 RowNumber 类似，该函数对窗口中的行进行排序。计算出的排名包含有空隙。使用 DenseRank 来计算没有空隙的排名。

\n
\n
\n

RowNumberLink to this heading#

\n
\n
\nclass RowNumber(*expressions, **extra)Link to this definition#
\n
\n\n

如果没有对 窗口帧 进行分区，则根据帧子句的顺序或整个查询的顺序计算行数。

\n
\n
","rootId":"module-django.db.models.functions","toc":[{"title":"比较和转换函数","anchor":"comparison-and-conversion-functions","children":[{"title":"Cast","anchor":"cast","children":[]},{"title":"Coalesce","anchor":"coalesce","children":[]},{"title":"Collate","anchor":"collate","children":[]},{"title":"Greatest","anchor":"greatest","children":[]},{"title":"Least","anchor":"least","children":[]},{"title":"NullIf","anchor":"nullif","children":[]}]},{"title":"日期函数","anchor":"date-functions","children":[{"title":"Extract","anchor":"extract","children":[{"title":"DateField 提取","anchor":"datefield-extracts","children":[]},{"title":"DateTimeField 提取","anchor":"datetimefield-extracts","children":[]}]},{"title":"Now","anchor":"now","children":[]},{"title":"Trunc","anchor":"trunc","children":[{"title":"DateField 截断","anchor":"datefield-truncation","children":[]},{"title":"DateTimeField 截断","anchor":"datetimefield-truncation","children":[]},{"title":"TimeField 截断","anchor":"timefield-truncation","children":[]}]}]},{"title":"JSON Functions","anchor":"json-functions","children":[{"title":"JSONArray","anchor":"jsonarray","children":[]},{"title":"JSONObject","anchor":"jsonobject","children":[]}]},{"title":"数学函数","anchor":"math-functions","children":[{"title":"Abs","anchor":"abs","children":[]},{"title":"ACos","anchor":"acos","children":[]},{"title":"ASin","anchor":"asin","children":[]},{"title":"ATan","anchor":"atan","children":[]},{"title":"ATan2","anchor":"atan2","children":[]},{"title":"Ceil","anchor":"ceil","children":[]},{"title":"Cos","anchor":"cos","children":[]},{"title":"Cot","anchor":"cot","children":[]},{"title":"Degrees","anchor":"degrees","children":[]},{"title":"Exp","anchor":"exp","children":[]},{"title":"Floor","anchor":"floor","children":[]},{"title":"Ln","anchor":"ln","children":[]},{"title":"Log","anchor":"log","children":[]},{"title":"Mod","anchor":"mod","children":[]},{"title":"Pi","anchor":"pi","children":[]},{"title":"Power","anchor":"power","children":[]},{"title":"Radians","anchor":"radians","children":[]},{"title":"Random","anchor":"random","children":[]},{"title":"Round","anchor":"round","children":[]},{"title":"Sign","anchor":"sign","children":[]},{"title":"Sin","anchor":"sin","children":[]},{"title":"Sqrt","anchor":"sqrt","children":[]},{"title":"Tan","anchor":"tan","children":[]}]},{"title":"文本函数","anchor":"text-functions","children":[{"title":"Chr","anchor":"chr","children":[]},{"title":"Concat","anchor":"concat","children":[]},{"title":"Left","anchor":"left","children":[]},{"title":"Length","anchor":"length","children":[]},{"title":"Lower","anchor":"lower","children":[]},{"title":"LPad","anchor":"lpad","children":[]},{"title":"LTrim","anchor":"ltrim","children":[]},{"title":"MD5","anchor":"md5","children":[]},{"title":"Ord","anchor":"ord","children":[]},{"title":"Repeat","anchor":"repeat","children":[]},{"title":"Replace","anchor":"replace","children":[]},{"title":"Reverse","anchor":"reverse","children":[]},{"title":"Right","anchor":"right","children":[]},{"title":"RPad","anchor":"rpad","children":[]},{"title":"RTrim","anchor":"rtrim","children":[]},{"title":"SHA1、SHA224`、SHA256`、SHA384` 和 SHA512。","anchor":"sha1-sha224-sha256-sha384-and-sha512","children":[]},{"title":"StrIndex","anchor":"strindex","children":[]},{"title":"Substr","anchor":"substr","children":[]},{"title":"Trim","anchor":"trim","children":[]},{"title":"Upper","anchor":"upper","children":[]}]},{"title":"窗口函数","anchor":"window-functions","children":[{"title":"CumeDist","anchor":"cumedist","children":[]},{"title":"DenseRank","anchor":"denserank","children":[]},{"title":"FirstValue","anchor":"firstvalue","children":[]},{"title":"Lag","anchor":"lag","children":[]},{"title":"LastValue","anchor":"lastvalue","children":[]},{"title":"Lead","anchor":"lead","children":[]},{"title":"NthValue","anchor":"nthvalue","children":[]},{"title":"Ntile","anchor":"ntile","children":[]},{"title":"PercentRank","anchor":"percentrank","children":[]},{"title":"Rank","anchor":"rank","children":[]},{"title":"RowNumber","anchor":"rownumber","children":[]}]}],"breadcrumbs":[{"docname":"ref/index","title":"API 参考","url":"/zh-hans/6.0/ref/"},{"docname":"ref/models/index","title":"模型","url":"/zh-hans/6.0/ref/models/"}],"prev":{"docname":"ref/models/conditional-expressions","title":"条件表达式","url":"/zh-hans/6.0/ref/models/conditional-expressions/"},"next":{"docname":"ref/paginator","title":"分页器","url":"/zh-hans/6.0/ref/paginator/"},"formats":{"html":"/zh-hans/6.0/ref/models/database-functions/","markdown":"/zh-hans/6.0/ref/models/database-functions.md","json":"/zh-hans/6.0/ref/models/database-functions.json"},"source":"https://github.com/django/django/blob/stable/6.0.x/docs/ref/models/database-functions.txt","official":"https://docs.djangoproject.com/zh-hans/6.0/ref/models/database-functions/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0"],"inLocales":["en","sv","zh-hans","ga","fr","ja","id","it","pt-br","ko","es","el","pl"]}