{"title":"データベース関数","version":"5.2","locale":"ja","docname":"ref/models/database-functions","url":"/ja/5.2/ref/models/database-functions/","canonical":"https://djangodocs.dev/ja/5.2/ref/models/database-functions/","summary":"以下で説明するクラスは、基盤となるデータベースが提供する関数を、ユーザが Django のアノテーション、集計、フィルタとして使う方法を提供します。関数は 式 (expression) でもあるので、 集計関数 のように他の式と組み合わせて使うこともできます。 各関数の例では、以下のモデルを使用します： Code Copy…","html":"

データベース関数Link to this heading#

\n

以下で説明するクラスは、基盤となるデータベースが提供する関数を、ユーザが Django のアノテーション、集計、フィルタとして使う方法を提供します。関数は 式 (expression) でもあるので、 集計関数 のように他の式と組み合わせて使うこともできます。

\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 datetime, timezone\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=timezone.utc)\n>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.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 datetime, timezone\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=timezone.utc)\n>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.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 datetime, timezone\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=timezone.utc)\n>>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)\n>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.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 date, datetime, timezone\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=timezone.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=timezone.utc),\n 'second': datetime.datetime(2014, 6, 15, 14, 30, 50, tzinfo=timezone.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 datetime, timezone\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=timezone.utc)\n>>> start2 = datetime(2014, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)\n>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.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(string, substring, **extra)Link to this definition#
\n
\n\n

substring が string 内で最初に出現する1から始まる位置に対応する正の整数を返します。もし substring が見つからない場合は0を返します。

\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/5.2/ref/"},{"docname":"ref/models/index","title":"モデル","url":"/ja/5.2/ref/models/"}],"prev":{"docname":"ref/models/conditional-expressions","title":"条件式","url":"/ja/5.2/ref/models/conditional-expressions/"},"next":{"docname":"ref/paginator","title":"ページ分割 (Paginator)","url":"/ja/5.2/ref/paginator/"},"formats":{"html":"/ja/5.2/ref/models/database-functions/","markdown":"/ja/5.2/ref/models/database-functions.md","json":"/ja/5.2/ref/models/database-functions.json"},"source":"https://github.com/django/django/blob/stable/5.2.x/docs/ref/models/database-functions.txt","official":"https://docs.djangoproject.com/ja/5.2/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"]}