{"title":"データベース関数","version":"6.0","locale":"ja","docname":"ref/models/database-functions","url":"/ja/6.0/ref/models/database-functions/","canonical":"https://djangodocs.dev/ja/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

通常、CharField に null=True を許可することはお勧めしません。なぜなら、これはフィールドに2つの "空の値 "を持たせてしまうからです。

\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

少なくとも2つのフィールド名または式のリストを受け取り、最初のNULLでない値を返します（空文字列はNULL値とはみなされないことに注意してください）。各引数は同じような型でなければならないので、テキストと数値が混在するとデータベースエラーになります。

\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

クエリに使用する式と照合順序名 (collation name) を指定します。

\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

少なくとも2つのフィールド名または式のリストを受け取り、最大値を返します。各引数は同じような型でなければならないので、テキストと数値が混在するとデータベースエラーになります。

\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

少なくとも2つのフィールド名または式のリストを受け取り、最小の値を返します。各引数は同じような型でなければならないので、テキストと数値が混在するとデータベースエラーになります。

\n\n
\n
\n

NullIfLink to this heading#

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

2つの式を受け取り、等しい場合は 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 を使うことができます。通常 zoneinfo によって提供される tzinfo サブクラスを渡すと、特定のタイムゾーンの値を抽出できます。

\n

datetime 2015-06-15 23:30:01.000321+00:00 が渡されると、組み込みの lookup_name は下記の値を返します：

\n\n

Australia/Melbourne のような異なるタイムゾーンが Django で有効な場合、 datetime は値を抽出する前にそのタイムゾーンに変換されます。上の例の日付のメルボルンのタイムゾーンオフセットは +10:00 です。このタイムゾーンが有効な場合に返される値は、以下を除けば上と同じです：

\n\n\n\n

各 lookup_name には、冗長な等価表現の代わりに通常使用すべき Extract サブクラス（下記）があります。たとえば Extract(..., lookup_name='year') の代わりに ExtractYear(...) が使えます。

\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 からの抽出 (extract)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) と等価です。各クラスは DateField と DateTimeField に __(lookup_name) として登録された Transform でもあります。たとえば __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 からの抽出 (extract)Link to this heading#

\n

以下に加え、上記の DateField のすべての抽出操作 (extract) は 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) と等価です。各クラスは DateTimeField に __(lookup_name) として登録された Transform でもあります。たとえば、 __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 の場合、 datetime は UTC でデータベースに保存されます。異なるタイムゾーンが Django で有効な場合、 datetime はそのタイムゾーンに変換されてから値が抽出されます。以下の例では、メルボルンのタイムゾーン (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

クエリが実行された時のデータベースサーバの現在の日時を返します。通常は CURRENT_TIMESTAMP という SQL を使用します。

\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 、そして (DateTimeField(), TimeField(), または DateField() のいずれかである) output_field を受け取ります。これは output_field に応じて日時、日付、または時刻を返し、kind 単位未満のフィールドをその最小値に設定します。output_field が省略された場合、デフォルトで expression の output_field になります。特定のタイムゾーンで値を切り捨てるために、通常 zoneinfo によって提供される tzinfo サブクラスを渡すことができます。

\n

datetime 2015-06-15 14:30:50.000321+00:00 が渡された場合、組み込みの kind は以下の値を返します：

\n\n

Australia/Melbourne のような異なるタイムゾーンが Django で有効な場合、 datetime は切り捨てられる前に新しいタイムゾーンに変換されます。上の例の日付のメルボルンのタイムゾーンオフセットは +10:00 です。このタイムゾーンが有効な場合に返される値は以下のようになります：

\n\n

この年はサマータイムに移行したため、+11:00のオフセットがあります。

\n

各 kind には、冗長な等価表現の代わりに通常使用すべき Trunc サブクラス（下記）があります。たとえば Trunc(..., kind='year') の代わりに TruncYear(...) が使えます。

\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

その週の月曜日の午前0時に切り捨てます。

\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 には DateField または DateTimeField の output_field を指定できます。

\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 は、組み込みの SQL の切り捨て関数を使わずに、 expression を日付にキャストします。また、 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 は、組み込み SQL の切り捨て関数を使わずに、 expression を時刻にキャストします。また、 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 単位未満の日時のすべての部分を切り捨て、大ざっぱな datetime のグループ化やフィルタリングができます。 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 関数Link to this heading#

\n
\n

JSONArrayLink to this heading#

\n\n
\n
\nclass JSONArray(*expressions)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 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

2つの数値フィールドまたは式を受け取り、最初の値を底とする2番目の値の対数を返します。

\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

2つの数値フィールドまたは式を受け取り、1つ目を2つ目で割った余りを返します（モジュロ演算）。

\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

2つの数値フィールドまたは式を受け取り、1番目の値を2番目の値のべき乗にした値を返します。

\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

数値フィールドまたは式を受け取り、その式のテキスト表現を1文字として返します。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

少なくとも2つのテキストフィールドまたは式のリストを受け取り、連結したテキストを返します。各引数は text 型か char 型でなければなりません。もし TextField() と CharField() を連結したい場合は、必ず Django に output_field が TextField() であることを伝えてください。以下の例のように Value を連結する場合にも output_field を指定する必要があります。

\n

この関数は決して null を返しません。null 引数があると式全体が null になるようなバックエンドでは、 Django は各 null 部分を最初に空文字列に変換にします。

\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

単一のテキストフィールドまたは式を受け取り、その値が持つ文字数を返します。式が null の場合は、長さも null になります。

\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() 関数と似たような動作をしますが、式が1文字より長くても例外を発生させません。

\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 内で text を replacement で置き換えます。デフォルトの置換テキストは空文字列です。関数の引数は大文字小文字を区別します。

\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, SHA512Link 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 の部分文字列を返します。位置は1から始まるインデックスであるため、位置は0より大きくなければなりません。もし 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

与えられた フレーム の先頭の値を計算します。 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

データベースによっては、存在しない n 番目の値の扱いが異なる場合があります。例えば、 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 までの間で可能な限り均等に番号を割り振ります。行がいくつかのバケットに均等に分割されない場合、1つ以上のバケットがより頻繁に表されます。

\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

行 No.

値

順位

計算

相対順位

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 からの抽出 (extract)","anchor":"datefield-extracts","children":[]},{"title":"DateTimeField からの抽出 (extract)","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 関数","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":"/ja/6.0/ref/"},{"docname":"ref/models/index","title":"モデル","url":"/ja/6.0/ref/models/"}],"prev":{"docname":"ref/models/conditional-expressions","title":"条件式","url":"/ja/6.0/ref/models/conditional-expressions/"},"next":{"docname":"ref/paginator","title":"ページ分割 (Paginator)","url":"/ja/6.0/ref/paginator/"},"formats":{"html":"/ja/6.0/ref/models/database-functions/","markdown":"/ja/6.0/ref/models/database-functions.md","json":"/ja/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/ja/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","1.11","1.10","1.9"],"inLocales":["en","sv","zh-hans","ga","fr","ja","id","it","pt-br","ko","es","el","pl"]}