# Django 5.0.9.dev20240806133106 ドキュメント

# データベース関数

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

各関数の例では、以下のモデルを使用します：

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

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

## 比較および変換関数

### `Cast`

class `Cast`(expression, output_field)

式 `expression` の結果の型を `output_field` の型に強制的に変更します。

使用例:

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

### `Coalesce`

class `Coalesce`(*expressions, **extra)

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

使用例：

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

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

警告

MySQL で `Coalesce` に渡された Python の値は、明示的に正しいデータベース型にキャストされない限り、不正な型に変換される可能性があります：

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

### `Collate`

class `Collate`(expression, collation)

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

たとえば、SQLiteで大文字小文字を区別せずにフィルタリングする場合、以下のようにします：

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

また、PostgreSQLなどでのソートにも使用できます：

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

### `Greatest`

class `Greatest`(*expressions, **extra)

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

使用例:

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

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

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

`annotated_comment.last_updated` は `blog.modified` と `comment.modified` のうち最新のものになります。

警告

1つ以上の式が `null` である場合の `Greatest` の動作はデータベースによって異なります：

- PostgreSQL: `Greatest` は、非nullの式の中で最大のものを返します。すべての式が `null` の場合は `null` を返します。
- SQLite, Oracle, MySQL: いずれかの式が `null` である場合、`Greatest` は `null` を返します。

PostgreSQLの動作は、デフォルトとして提供する適切な最小値を知っていれば、 `Coalesce` を使用してエミュレートできます。

### `JSONObject`

class `JSONObject`(**fields)

キーと値のペアのリストを受け取り、それらのペアを含むJSONオブジェクトを返します。

使用例:

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

### `Least`

class `Least`(*expressions, **extra)

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

警告

1つ以上の式が `null` である場合の `Least` の動作はデータベースによって異なります：

- PostgreSQL: `Least` は、非nullの式の中で最小のものを返します。すべての式が `null` の場合は `null` を返します。
- SQLite, Oracle, MySQL: いずれかの式が `null` である場合、 `Least` は `null` を返します。

PostgreSQLの動作は、デフォルトとして提供する適切な最大値を知っていれば、 `Coalesce` を使用してエミュレートできます。

### `NullIf`

class `NullIf`(expression1, expression2)

2つの式を受け取り、等しい場合は `None` を返し、そうでない場合は `expression1` を返します。

Oracle に関する注意事項

Oracle の慣習 により、 `CharField` 型の式の場合、この関数は `None` の代わりに空の文字列を返します。

Oracle では最初の引数として `NULL` を受け付けないため、`expression1` に `Value(None)` を渡すことは禁止されています。

## 日時関連の関数

各関数の例では、以下のモデルを使用します：

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

### `Extract`

class `Extract`(expression, lookup_name=None, tzinfo=None, **extra)

日時の構成要素を数値として取り出します。

`DateField`, `DateTimeField`, `TimeField` または `DurationField` を表す `expression` と、`lookup_name` を受け取り、 `lookup_name` が参照する日付の部分を `IntegerField` として返します。Django は通常データベースの extract 関数を使うので、データベースがサポートしている `lookup_name` を使うことができます。通常 `zoneinfo` によって提供される `tzinfo` サブクラスを渡すと、特定のタイムゾーンの値を抽出できます。

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

- "year": 2015
- "iso_year": 2015
- "quarter": 2
- "month": 6
- "day": 15
- "week": 25
- "week_day": 2
- "iso_week_day": 1
- "hour": 23
- "minute": 30
- "second": 1

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

- "day": 16
- "week_day": 3
- "iso_week_day": 2
- "hour": 9

`week_day` の値

`week_day` `lookup_type` は、多くのデータベースや Python の標準関数とは異なる方法で計算されます。この関数は日曜日に `1`、月曜日に `2`、土曜日に `7` を返します。

Pythonでの等価な計算は以下のようになります：

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

`week` の値

`week` の `lookup_type` は ISO-8601 に基づいて計算されます。つまり、週は月曜日に始まります。年の最初の週は、その年の最初の木曜日を含む週です。つまり、最初の週はその週の日数の過半数（4日以上）がその年に含まれています。返される値は1から52または53の範囲です。

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

使用例:

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

#### `DateField` からの抽出 (extract)

class `ExtractYear`(expression, tzinfo=None, **extra)
  `lookup_name = 'year'`

class `ExtractIsoYear`(expression, tzinfo=None, **extra)

  ISO-8601 の週番号を持つ年を返します。

  `lookup_name = 'iso_year'`

class `ExtractMonth`(expression, tzinfo=None, **extra)
  `lookup_name = 'month'`

class `ExtractDay`(expression, tzinfo=None, **extra)
  `lookup_name = 'day'`

class `ExtractWeekDay`(expression, tzinfo=None, **extra)
  `lookup_name = 'week_day'`

class `ExtractIsoWeekDay`(expression, tzinfo=None, **extra)

  ISO-8601形式の曜日を返します。1が月曜日で7が日曜日になります。

  `lookup_name = 'iso_week_day'`

class `ExtractWeek`(expression, tzinfo=None, **extra)
  `lookup_name = 'week'`

class `ExtractQuarter`(expression, tzinfo=None, **extra)
  `lookup_name = 'quarter'`

これらは論理的には `Extract('date_field', lookup_name)` と等価です。各クラスは `DateField` と `DateTimeField` に `__(lookup_name)` として登録された `Transform` でもあります。たとえば `__year` のようなものです。

`DateField` は時間要素を持たないので、日付部分を扱う `Extract` サブクラスだけが `DateField` と一緒に使うことができます：

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

#### `DateTimeField` からの抽出 (extract)

以下に加え、上記の `DateField` のすべての抽出操作 (extract) は `DateTimeField` にも使用できます。

class `ExtractHour`(expression, tzinfo=None, **extra)
  `lookup_name = 'hour'`

class `ExtractMinute`(expression, tzinfo=None, **extra)
  `lookup_name = 'minute'`

class `ExtractSecond`(expression, tzinfo=None, **extra)
  `lookup_name = 'second'`

これらは論理的には `Extract('datetime_field', lookup_name)` と等価です。各クラスは `DateTimeField` に `__(lookup_name)` として登録された `Transform` でもあります。たとえば、 `__minute` のようなものです。

`DateTimeField` の例：

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

`USE_TZ` が `True` の場合、 datetime は UTC でデータベースに保存されます。異なるタイムゾーンが Django で有効な場合、 datetime はそのタイムゾーンに変換されてから値が抽出されます。以下の例では、メルボルンのタイムゾーン (UTC +10:00) に変換しています。これにより、返される日、曜日、時間の値が変わります：

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

明示的にタイムゾーンを `Extract` 関数に渡しても同じように動作し、アクティブなタイムゾーンよりも優先されます：

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

### `Now`

class `Now`

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

使用例:

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

PostgreSQL の場合の注意事項

PostgreSQLでは、SQLの `CURRENT_TIMESTAMP` は現在のトランザクションが開始した時刻を返します。そのため、データベース間の互換性を保つために、 `Now()` は代わりに `STATEMENT_TIMESTAMP` を使用します。トランザクションのタイムスタンプが必要な場合は、 `django.contrib.postgres.functions.TransactionNow` を使用してください。

Oracle

Oracle では、`CURRENT_TIMESTAMP` を `DateTimeField` にキャストする際の問題を回避するために `LOCALTIMESTAMP` という SQL が使用されます。

Changed in Django 4.2:

MySQLでマイクロ秒精度、SQLiteでミリ秒精度をサポートしました。

Changed in Django 5.0:

古いバージョンでは、Oracle上で `LOCALTIMESTAMP` の代わりに `CURRENT_TIMESTAMP` SQL構文が使用されていました。

### `Trunc`

class `Trunc`(expression, kind, output_field=None, tzinfo=None, **extra)

日付を重要な要素まで切り捨てます。

特定の年、時間、日に何かが起こったかどうかだけを気にしていて、正確な秒は気にしていない場合、`Trunc` (とそのサブクラス) はデータのフィルタや集計に便利です。例えば、 `Trunc` を使って一日の売上数を計算できます。

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

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

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

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

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

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

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

サブクラスはすべてトランスフォームとして定義されていますが、ルックアップ名は `Extract` サブクラスによってすでに予約されているため、フィールドは登録されていません。

使用例:

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

#### `DateField` の切り捨て

class `TruncYear`(expression, output_field=None, tzinfo=None, **extra)
  `kind = 'year'`

class `TruncMonth`(expression, output_field=None, tzinfo=None, **extra)
  `kind = 'month'`

class `TruncWeek`(expression, output_field=None, tzinfo=None, **extra)

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

  `kind = 'week'`

class `TruncQuarter`(expression, output_field=None, tzinfo=None, **extra)
  `kind = 'quarter'`

これらは論理的には `Trunc('date_field', kind)` と等価です。これらは `kind` 単位未満の日付のすべての部分を切り捨て、大ざっぱな日付のグループ化やフィルタリングに使用できます。 `expression` には `DateField` または `DateTimeField` の `output_field` を指定できます。

`DateField` は時間要素を持たないので、日付部分を扱う `Trunc` サブクラスだけが `DateField` と一緒に使用できます：

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

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

#### `DateTimeField` の切り捨て

class `TruncDate`(expression, tzinfo=None, **extra)
  `lookup_name = 'date'`
  `output_field = DateField()`

`TruncDate` は、組み込みの SQL の切り捨て関数を使わずに、 `expression` を日付にキャストします。また、 `DateTimeField` のトランスフォームとして `__date` が登録されています。

class `TruncTime`(expression, tzinfo=None, **extra)
  `lookup_name = 'time'`
  `output_field = TimeField()`

`TruncTime` は、組み込み SQL の切り捨て関数を使わずに、 `expression` を時刻にキャストします。また、 `DateTimeField` のトランスフォームとして `__time` が登録されています。

class `TruncDay`(expression, output_field=None, tzinfo=None, **extra)
  `kind = 'day'`

class `TruncHour`(expression, output_field=None, tzinfo=None, **extra)
  `kind = 'hour'`

class `TruncMinute`(expression, output_field=None, tzinfo=None, **extra)
  `kind = 'minute'`

class `TruncSecond`(expression, output_field=None, tzinfo=None, **extra)
  `kind = 'second'`

これらは論理的には `Trunc('datetime_field', kind)` と等価です。これらは `kind` 単位未満の日時のすべての部分を切り捨て、大ざっぱな datetime のグループ化やフィルタリングができます。 `expression` は `output_field` が `DateTimeField` である必要があります。

使用例:

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

#### `TimeField` の切り捨て

class `TruncHour`(expression, output_field=None, tzinfo=None, **extra)
  `kind = 'hour'`

class `TruncMinute`(expression, output_field=None, tzinfo=None, **extra)
  `kind = 'minute'`

class `TruncSecond`(expression, output_field=None, tzinfo=None, **extra)
  `kind = 'second'`

これらは論理的には `Trunc('time_field', kind)` と等価です。これらは `kind` 単位未満の時刻をすべて切り捨てるので、大ざっぱな時刻のグループ化やフィルタリングに使用できます。 `expression` は `output_field` に `TimeField` または `DateTimeField` を指定できます。

`TimeField` は日付コンポーネントを持たないので、時間部分を扱う `Trunc` サブクラスだけが `TimeField` と一緒に使用できます：

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

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

## 数学関数

数学関数の例では、以下のモデルを使用します：

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

### `Abs`

class `Abs`(expression, **extra)

数値フィールドまたは式の、絶対値を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `ACos`

class `ACos`(expression, **extra)

数値フィールドまたは式の、逆余弦（アークコサイン）を返します。式の値は -1 から 1 の範囲内でなければなりません。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `ASin`

class `ASin`(expression, **extra)

数値フィールドまたは式の、逆正弦（アークサイン）を返します。式の値は -1 から 1 の範囲でなければなりません。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `ATan`

class `ATan`(expression, **extra)

数値フィールドまたは式の逆正接（アークタンジェント）を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `ATan2`

class `ATan2`(expression1, expression2, **extra)

`expression1 / expression2` の逆正接（アークタンジェント）を返します。

使用例:

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

### `Ceil`

class `Ceil`(expression, **extra)

数値フィールドまたは式の値以上の最小の整数を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Cos`

class `Cos`(expression, **extra)

数値フィールドまたは式の、余弦（コサイン）を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Cot`

class `Cot`(expression, **extra)

数値フィールドまたは式の、余接（コタンジェント）を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Degrees`

class `Degrees`(expression, **extra)

数値フィールドまたは式を、ラジアンから度へ変換します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Exp`

class `Exp`(expression, **extra)

`e` (自然対数の底) を数値フィールドまたは式の値でべき乗した値を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Floor`

class `Floor`(expression, **extra)

数値フィールドまたは式の値未満の最大の整数値を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Ln`

class `Ln`(expression, **extra)

数値フィールドまたは式の、自然対数を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Log`

class `Log`(expression1, expression2, **extra)

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

使用例:

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

### `Mod`

class `Mod`(expression1, expression2, **extra)

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

使用例:

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

### `Pi`

class `Pi`(**extra)

数学定数 `π` の値を返します。

### `Power`

class `Power`(expression1, expression2, **extra)

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

使用例:

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

### `Radians`

class `Radians`(expression, **extra)

数値フィールドまたは式を、度からラジアンに変換します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Random`

class `Random`(**extra)

`0.0 ≤ x < 1.0` の範囲のランダムな値を返します。

### `Round`

class `Round`(expression, precision=0, **extra)

数値フィールドまたは式を `precision` (整数でなければなりません) 小数点以下の桁数に丸めます。デフォルトでは、最も近い整数に丸められます。半分の値を切り上げるか切り下げるかはデータベースによって異なります。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Sign`

class `Sign`(expression, **extra)

数値フィールドまたは式の符号 (-1, 0, 1) を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Sin`

class `Sin`(expression, **extra)

数値フィールドまたは式の、正弦（サイン）を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Sqrt`

class `Sqrt`(expression, **extra)

非負の数値フィールドまたは式の、平方根を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Tan`

class `Tan`(expression, **extra)

数値フィールドまたは式の、正接（タンジェント）を返します。

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

## テキスト関数

### `Chr`

class `Chr`(expression, **extra)

数値フィールドまたは式を受け取り、その式のテキスト表現を1文字として返します。Python の `chr()` 関数と同じように動作します。

`Length` と同様に、 `IntegerField` のトランスフォームとして登録できます。デフォルトのルックアップ名は `chr` です。

使用例:

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

### `Concat`

class `Concat`(*expressions, **extra)

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

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

使用例:

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

### `Left`

class `Left`(expression, length, **extra)

テキストフィールドまたは式の、最初から `length` で指定した文字数までを返します。

使用例:

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

### `Length`

class `Length`(expression, **extra)

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

使用例:

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

トランスフォームとして登録することもできます。たとえば：

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

### `Lower`

class `Lower`(expression, **extra)

単一のテキストフィールドまたは式を受け取り、小文字の表現を返します。

`Length` と同様に、トランスフォームとして登録することもできます。

使用例:

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

### `LPad`

class `LPad`(expression, length, fill_text=Value(' '), **extra)

指定されたテキストフィールドまたは式の値の左側を `fill_text` でパディングし、 `length` 文字の長さになるように値を返します。デフォルトの `fill_text` はスペースです。

使用例:

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

### `LTrim`

class `LTrim`(expression, **extra)

`Trim` と似ていますが、先頭の空白だけを取り除きます。

### `MD5`

class `MD5`(expression, **extra)

単一のテキストフィールドまたは式を受け取り、その文字列の MD5 ハッシュを返します。

`Length` と同様に、トランスフォームとして登録することもできます。

使用例:

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

### `Ord`

class `Ord`(expression, **extra)

単一のテキストフィールドまたは式を受け取り、その式の最初の文字の Unicode コードポイント値を返します。Python の `ord()` 関数と似たような動作をしますが、式が1文字より長くても例外を発生させません。

`Length` と同様に、トランスフォームとして登録することもできます。デフォルトのルックアップ名は `ord` です。

使用例:

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

### `Repeat`

class `Repeat`(expression, number, **extra)

テキストフィールドまたは式を `number` 回繰り返した値を返します。

使用例:

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

### `Replace`

class `Replace`(expression, text, replacement=Value(''), **extra)

`expression` 内で `text` を `replacement` で置き換えます。デフォルトの置換テキストは空文字列です。関数の引数は大文字小文字を区別します。

使用例:

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

### `Reverse`

class `Reverse`(expression, **extra)

単一のテキストフィールドまたは式を受け取り、その式の文字を逆順に返します。

`Length` と同様に、トランスフォームとして登録することもできます。デフォルトのルックアップ名は `reverse` です。

使用例:

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

### `Right`

class `Right`(expression, length, **extra)

テキストフィールドまたは式の最後から `length` で指定した文字数分を返します。

使用例:

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

### `RPad`

class `RPad`(expression, length, fill_text=Value(' '), **extra)

`LPad` と似ていますが、右側にパディングを行います。

### `RTrim`

class `RTrim`(expression, **extra)

`Trim` と似ていますが、末尾の空白だけを削除します。

### `SHA1`, `SHA224`, `SHA256`, `SHA384`, `SHA512`

class `SHA1`(expression, **extra)

class `SHA224`(expression, **extra)

class `SHA256`(expression, **extra)

class `SHA384`(expression, **extra)

class `SHA512`(expression, **extra)

単一のテキストフィールドまたは式を受け取り、文字列の特定のハッシュを返します。

`Length` と同様にトランスフォームとして登録することもできます。

使用例:

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

PostgreSQL

pgcrypto extension をインストールする必要があります。 `CryptoExtension` マイグレーションオペレーションを使ってインストールできます。

Oracle

Oracle は `SHA224` 関数をサポートしていません。

### `StrIndex`

class `StrIndex`(string, substring, **extra)

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

使用例:

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

警告

MySQL では、データベーステーブルの 照合順序 (collation) によって、文字列（この関数の `expression` や `substring` など）の比較が大文字小文字を区別するかどうかが決まります。デフォルトでは大文字と小文字は区別されません。

### `Substr`

class `Substr`(expression, pos, length=None, **extra)

フィールドまたは式から、位置 `pos` から始まる長さ `length` の部分文字列を返します。位置は1から始まるインデックスであるため、位置は0より大きくなければなりません。もし `length` が `None` であれば、文字列の残りの部分が返されます。

使用例:

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

### `Trim`

class `Trim`(expression, **extra)

テキストフィールドまたは式の値を、先頭と末尾の空白を除去して返します。

使用例:

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

### `Upper`

class `Upper`(expression, **extra)

単一のテキストフィールドまたは式を受け取り、大文字の表現を返します。

`Length` と同様に、トランスフォームとして登録することもできます。

使用例:

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

## ウィンドウ関数

`Window` 式において、要素の順位や行の `Ntile` を計算するために使用できる関数がいくつかあります。

### `CumeDist`

class `CumeDist`(*expressions, **extra)

ウィンドウまたはパーティション内の値の累積分布を計算します。累積分布は、現在の行の前の行または前の行の数をフレーム内の行の総数で割ったものとして定義されます。

### `DenseRank`

class `DenseRank`(*expressions, **extra)

`Rank` と等価ですが、ギャップを持ちません。

### `FirstValue`

class `FirstValue`(expression, **extra)

ウィンドウフレームの最初の行で評価された値を返します。そのような値が存在しない場合は `None` を返します。

### `Lag`

class `Lag`(expression, offset=1, default=None, **extra)

`offset` でオフセットされた値を計算し、そこに行が存在しない場合は `default` を返します。

`default` は `expression` と同じ型でなければなりませんが、これはデータベースでだけ検証され、Python では検証されません。

MariaDB と `default`

MariaDB は `default` パラメータを サポートしていません 。

### `LastValue`

class `LastValue`(expression, **extra)

`FirstValue` と同様に、与えられたフレーム句の最後の値を計算します。

### `Lead`

class `Lead`(expression, offset=1, default=None, **extra)

与えられた フレーム の先頭の値を計算します。 `offset` と `default` は現在の行を基準として評価されます。

`default` は `expression` と同じ型でなければなりませんが、これはデータベースでだけ検証され、Python では検証されません。

MariaDB と `default`

MariaDB は `default` パラメータを サポートしていません 。

### `NthValue`

class `NthValue`(expression, nth=1, **extra)

ウィンドウ内のオフセット `nth` (正の値である必要があります) からの相対行を計算します。行が存在しない場合は `None` を返します。

データベースによっては、存在しない n 番目の値の扱いが異なる場合があります。例えば、 Oracle は文字ベースの式の場合、 `None` ではなく空文字列を返します。Django はこのような場合、変換を行いません。

### `Ntile`

class `Ntile`(num_buckets=1, **extra)

フレーム句の各行に対してパーティションを計算し、1から `num_buckets` までの間で可能な限り均等に番号を割り振ります。行がいくつかのバケットに均等に分割されない場合、1つ以上のバケットがより頻繁に表されます。

### `PercentRank`

class `PercentRank`(*expressions, **extra)

フレーム句の行の相対順位を計算します。この計算は評価と等価です：

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

以下の表は、行の相対順位の計算について説明したものです：

行 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

### `Rank`

class `Rank`(*expressions, **extra)

`RowNumber` と同様に、この関数はウィンドウ内の行をランク付けします。計算された順位には隙間が生じることがあります。隙間のない順位を計算するには `DenseRank` を使用します。

### `RowNumber`

class `RowNumber`(*expressions, **extra)

ウィンドウフレーム のパーティショニングがない場合、フレーム句のソート、またはクエリ全体のソート順に従って行番号を計算します。