# Django 6.0.7 ドキュメント

# データベース関数

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

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

    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` を使用してエミュレートできます。

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

`Extract()` uses the active timezone

When `USE_TZ` is `True`, Django saves values in `UTC` (or the connection's configured timezone). Since `tzinfo` defaults to `TIME_ZONE` when not provided, you may need to provide an explicit `tzinfo` to compare extracted values. The following example demonstrates what happens when "Europe/Berlin" is active and how to adjust for this:

    >>> from django.utils import timezone
    >>> from datetime import UTC, datetime
    >>> from django.db.models.functions import ExtractHour
    >>> start = datetime(2015, 6, 15, 14, 30, 50, 321)
    >>> start = timezone.make_aware(start)
    >>> exp = Experiment.objects.create(start_datetime=start)
    >>> find_this_exp = Experiment.objects.annotate(
    ...     extract_hour_start=ExtractHour("start_datetime")
    ... ).filter(extract_hour_start=start.hour)
    # Comparing local time to UTC finds no results.
    >>> find_this_exp.count()
    0
    >>> find_this_exp_adjusted = Experiment.objects.annotate(
    ...     extract_hour_start=ExtractHour("start_datetime", tzinfo=UTC)
    ... ).filter(extract_hour_start=start.hour)
    >>> find_this_exp_adjusted.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 UTC, datetime
    >>> from django.db.models.functions import (
    ...     ExtractDay,
    ...     ExtractMonth,
    ...     ExtractQuarter,
    ...     ExtractWeek,
    ...     ExtractIsoWeekDay,
    ...     ExtractWeekDay,
    ...     ExtractIsoYear,
    ...     ExtractYear,
    ... )
    >>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=UTC)
    >>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=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 UTC, datetime
    >>> 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=UTC)
    >>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=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 が使用されます。

### `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+11:00

- "month": 2015-06-01 00:00:00+10:00

- "week": 2015-06-15 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

The year and quarter have an offset of +11:00 because each result falls before the daylight saving time transition.

各 `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

`Trunc()` produces naive datetimes

When `USE_TZ` is `True`, Django saves values in `UTC` (or the connection's configured timezone). Since `tzinfo` defaults to `TIME_ZONE` when not provided, you may need to provide an explicit `tzinfo` to compare truncated values. The following example demonstrates what happens when "Europe/Berlin" is active and how to adjust for this:

    >>> from django.utils import timezone
    >>> from datetime import UTC, datetime
    >>> from django.db.models.functions import TruncSecond
    >>> start = datetime(2015, 6, 15, 14, 30, 50, 321)
    >>> start = timezone.make_aware(start)
    >>> exp = Experiment.objects.create(start_datetime=start)
    >>> find_this_exp = Experiment.objects.annotate(
    ...     trunc_start=TruncSecond("start_datetime")
    ... ).filter(trunc_start__lte=start)
    # Comparing local time to UTC finds no results.
    >>> find_this_exp.count()
    0
    >>> find_this_exp_adjusted = Experiment.objects.annotate(
    ...     trunc_start=TruncSecond("start_datetime", tzinfo=UTC)
    ... ).filter(trunc_start__lte=start)
    >>> find_this_exp_adjusted.count()
    1

#### `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 UTC, datetime
    >>> from django.db.models import Count
    >>> from django.db.models.functions import TruncMonth, TruncYear
    >>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=UTC)
    >>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=UTC)
    >>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=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 UTC, date, datetime
    >>> 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=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=UTC),
     'second': datetime.datetime(2014, 6, 15, 14, 30, 50, tzinfo=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 UTC, datetime
    >>> from django.db.models import Count, TimeField
    >>> from django.db.models.functions import TruncHour
    >>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=UTC)
    >>> start2 = datetime(2014, 6, 15, 14, 40, 2, 123, tzinfo=UTC)
    >>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=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

## JSON 関数

### `JSONArray`

class JSONArray(*expressions)

フィールド名または式のリストを受け取り、それらの値を含む JSON 配列を返します。

使用例:

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

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

## 数学関数

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

    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(expression, substring, **extra)

Returns a positive integer corresponding to the 1-indexed position of the first occurrence of `substring` inside `expression`, or 0 if `substring` is not found.

使用例:

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

## UUID functions

### `UUID4`

New in Django 6.1.

class UUID4

Generates a version 4 UUID, which is random and is generated using a cryptographically secure method.

Availability

Available on PostgreSQL, SQLite, MariaDB version 11.7 or later, and Oracle 23ai/26ai (23.9) or later.

### `UUID7`

New in Django 6.1.

class UUID7(shift=None)

Generates a version 7 UUID, which starts with a time-based component.

Availability

Available on PostgreSQL version 18 or later, MariaDB version 11.7 or later, and SQLite on Python version 3.14 or later.

`shift`

On PostgreSQL, `UUID7` also supports an optional `shift` value, which can be used to offset the timestamp of the generated UUID. This should be a `datetime.timedelta` or an expression with an `output_field` of `DurationField`. A positive value will shift the timestamp into the future and a negative value into the past.

## ウィンドウ関数

`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)

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