--- title: "PostgreSQL 固有の集計関数" version: 6.1 locale: ja source: https://docs.djangoproject.com/ja/6.1/ref/contrib/postgres/aggregates/ canonical: https://djangodocs.dev/ja/6.1/ref/contrib/postgres/aggregates/ --- # PostgreSQL 固有の集計関数 これらの機能は、 `django.contrib.postgres.aggregates` モジュールから利用可能です。これらについての詳細は、 [PostgreSQLドキュメント](https://www.postgresql.org/docs/current/functions-aggregate.html) に記載されています。 > **Note** > > すべての関数はデフォルトのエイリアスを持たないので、明示的にエイリアスを指定する必要があります。例えば: > > ```pycon > >>> SomeModel.objects.aggregate(arr=ArrayAgg("somefield")) > {'arr': [0, 1, 2]} > ``` > **一般的な集計オプション** > > すべての集計関数は、 [filter](/ja/6.1/ref/models/querysets/#aggregate-filter) キーワード引数を持ち、ほとんどの集計関数は [default](/ja/6.1/ref/models/querysets/#aggregate-default) キーワード引数も持っています。 ## 汎用的な集計関数 ### `ArrayAgg` #### `class ArrayAgg(expression, distinct=False, filter=None, default=None, order_by=(), **extra)` null を含む値のリストを配列に連結して返すか、値がない場合は `default` を返す。 #### `distinct` オプションの真偽値引数で、配列の値を区別するかどうかを指定する。デフォルトは `False` です。 #### `order_by` 結果リスト内の要素の並び順を指定する、省略可能なフィールド名の文字列 (降順を示すオプションの `""-""` 接頭辞を含む) または式 (もしくは文字列および/または式のタプルもしくはリスト)。 例: ``` from django.db.models import F ArrayAgg("a_field", order_by="-some_field") ArrayAgg("a_field", order_by=F("some_field").desc()) ``` ### `BitAnd` #### `class BitAnd(expression, filter=None, default=None, **extra)` すべての非 null 入力値のビットごとの `AND` を返し、すべての値が null の場合は `default` を返します。 > **Deprecated since Django 6.1** > > バージョン 6.1 で非推奨: This class is deprecated in favor of the generally available > [`BitAnd`](/ja/6.1/ref/models/querysets/#django.db.models.BitAnd) class. ### `BitOr` #### `class BitOr(expression, filter=None, default=None, **extra)` すべての非 null 入力値のビットごとの `OR` の `int` を返します。すべての値が null の場合は `default` を返します。 > **Deprecated since Django 6.1** > > バージョン 6.1 で非推奨: This class is deprecated in favor of the generally available > [`BitOr`](/ja/6.1/ref/models/querysets/#django.db.models.BitOr) class. ### `BitXor` #### `class BitXor(expression, filter=None, default=None, **extra)` Returns an `int` of the bitwise `XOR` of all non-null input values, or `default` if all values are null. > **Deprecated since Django 6.1** > > バージョン 6.1 で非推奨: This class is deprecated in favor of the generally available > [`BitXor`](/ja/6.1/ref/models/querysets/#django.db.models.BitXor) class. ### `BoolAnd` #### `class BoolAnd(expression, filter=None, default=None, **extra)` すべての入力値が true の場合は `True` を、すべての値が null または値が存在しない場合は `default` を、それ以外の場合は `False` を返します。 使用例: ``` class Comment(models.Model): body = models.TextField() published = models.BooleanField() rank = models.IntegerField() ``` ```pycon >>> from django.db.models import Q >>> from django.contrib.postgres.aggregates import BoolAnd >>> Comment.objects.aggregate(booland=BoolAnd("published")) {'booland': False} >>> Comment.objects.aggregate(booland=BoolAnd(Q(rank__lt=100))) {'booland': True} ``` ### `BoolOr` #### `class BoolOr(expression, filter=None, default=None, **extra)` 少なくとも1つの入力値が true の場合は `True` を、すべての値が null または値がない場合は `default` を、そうでない場合は `False` を返します。 使用例: ``` class Comment(models.Model): body = models.TextField() published = models.BooleanField() rank = models.IntegerField() ``` ```pycon >>> from django.db.models import Q >>> from django.contrib.postgres.aggregates import BoolOr >>> Comment.objects.aggregate(boolor=BoolOr("published")) {'boolor': True} >>> Comment.objects.aggregate(boolor=BoolOr(Q(rank__gt=2))) {'boolor': False} ``` ### `JSONBAgg` #### `class JSONBAgg(expressions, distinct=False, filter=None, default=None, order_by=(), **extra)` 入力値を `JSON` 配列として返します。値がない場合は `default` を返します。結果は [`キーとインデックスのルックアップ`](/ja/6.1/topics/db/queries/#std-fieldlookup-jsonfield.key) を使ってクエリできます。 #### `distinct` オプションの真偽値引数で、配列の値を区別するかどうかを指定する。デフォルトは `False` です。 #### `order_by` 結果リスト内の要素の並び順を指定する、省略可能なフィールド名の文字列 (降順を示すオプションの `""-""` 接頭辞を含む) または式 (もしくは文字列および/または式のタプルもしくはリスト)。 [`ArrayAgg.order_by`](#django.contrib.postgres.aggregates.ArrayAgg.order_by) と同じ例です。 使用例: ``` class Room(models.Model): number = models.IntegerField(unique=True) class HotelReservation(models.Model): room = models.ForeignKey("Room", on_delete=models.CASCADE) start = models.DateTimeField() end = models.DateTimeField() requirements = models.JSONField(blank=True, null=True) ``` ```pycon >>> from django.contrib.postgres.aggregates import JSONBAgg >>> Room.objects.annotate( ... requirements=JSONBAgg( ... "hotelreservation__requirements", ... order_by="-hotelreservation__start", ... ) ... ).filter(requirements__0__sea_view=True).values("number", "requirements") ``` ### `StringAgg` #### `class StringAgg(expression, delimiter, distinct=False, filter=None, default=None, order_by=())` > **Deprecated since Django 6.0** > > バージョン 6.0 で非推奨: The PostgreSQL `StringAgg` class is deprecated in favor of the > generally available [`StringAgg`](/ja/6.1/ref/models/querysets/#django.db.models.StringAgg) class. 入力値を文字列に連結し、`delimiter` 文字列で区切って返します。値がない場合は `default` を返します。 #### `delimiter` Required argument. A string, [`Value`](/ja/6.1/ref/models/expressions/#django.db.models.Value), or expression representing the string for separating values. For example, `Value(",")`. > **New in Django 6.0** > > Support for providing a `Value` or expression rather than a > string was added. > **Deprecated since Django 6.0** > > バージョン 6.0 で非推奨: Support for providing a string is deprecated. #### `distinct` 連結された値が重複するかどうかを決定するオプションの真偽値引数。デフォルトは `False` です。 #### `order_by` フィールド名 (降順を示すオプションの接頭辞 `"-"` を持つ) 、または結果文字列の要素の順序を指定する式 (または文字列や式のタプルやリスト) のオプションの文字列。 [`ArrayAgg.order_by`](#django.contrib.postgres.aggregates.ArrayAgg.order_by) と同じ例です。 使用例: ``` class Publication(models.Model): title = models.CharField(max_length=30) class Article(models.Model): headline = models.CharField(max_length=100) publications = models.ManyToManyField(Publication) ``` ```pycon >>> article = Article.objects.create(headline="NASA uses Python") >>> article.publications.create(title="The Python Journal") >>> article.publications.create(title="Science News") >>> from django.contrib.postgres.aggregates import StringAgg >>> Article.objects.annotate( ... publication_names=StringAgg( ... "publications__title", ... delimiter=", ", ... order_by="publications__title", ... ) ... ).values("headline", "publication_names") ``` ## 統計のための集計関数 ### `y` および `x` これらの関数の引数 `y` と `x` には、フィールド名または数値データを返す式を指定できます。どちらも必須です。 ### `Corr` #### `class Corr(y, x, filter=None, default=None)` 相関係数を `float` で返すか、マッチする行がない場合は `default` で返す。 ### `CovarPop` #### `class CovarPop(y, x, sample=False, filter=None, default=None)` 母集団の共分散を `float` で返すか、マッチする行がない場合は `default` で返す。 #### `sample` オプション。デフォルトでは `CovarPop` は一般母集団の共分散を返す。ただし、 `sample=True` の場合、戻り値はサンプル母集団の共分散になる。 ### `RegrAvgX` #### `class RegrAvgX(y, x, filter=None, default=None)` 独立変数の平均値 (`sum(x)/N`) を `float` で返すか、マッチする行がない場合は `default` で返す。 ### `RegrAvgY` #### `class RegrAvgY(y, x, filter=None, default=None)` 従属変数の平均値 (`sum(y)/N`) を `float` で返すか、マッチする行がない場合は `default` で返す。 ### `RegrCount` #### `class RegrCount(y, x, filter=None)` 両方の式が NULL ではない入力行の数を `int` で返す。 > **Note** > > `default` 引数はサポートされていません。 ### `RegrIntercept` #### `class RegrIntercept(y, x, filter=None, default=None)` `(x, y)` のペアによって決定される最小二乗法にフィットした一次方程式の y 切片を `float` で返します。マッチする行がない場合は `default` を返します。 ### `RegrR2` #### `class RegrR2(y, x, filter=None, default=None)` 相関係数の二乗を `float` で返すか、マッチする行がない場合は `default` で返します。 ### `RegrSlope` #### `class RegrSlope(y, x, filter=None, default=None)` `(x, y)` のペアによって決定される最小二乗法の一次方程式の傾きを `float` で返すか、マッチする行がない場合は `default` で返す。 ### `RegrSXX` #### `class RegrSXX(y, x, filter=None, default=None)` `sum(x^2) - sum(x)^2/N` ("独立変数の二乗和") を `float` で返すか、マッチする行がない場合は `default` で返す。 ### `RegrSXY` #### `class RegrSXY(y, x, filter=None, default=None)` `sum(x*y)-sum(x)*sum(y)/N` (独立変数と従属変数の "積和") を `float` で返すか、マッチする行がない場合は `default` で返す。 ### `RegrSYY` #### `class RegrSYY(y, x, filter=None, default=None)` `sum(y^2) - sum(y)^2/N` (従属変数の二乗和) を `float` で返すか、マッチする行がない場合は `default` で返す。 ## 使用例 この例では以下のテーブルを使用します: ```text | FIELD1 | FIELD2 | FIELD3 | |--------|--------|--------| | foo | 1 | 13 | | bar | 2 | (null) | | test | 3 | 13 | ``` 汎用的な集計関数の例をいくつか紹介します: ```pycon >>> TestModel.objects.aggregate(result=StringAgg("field1", delimiter=";")) {'result': 'foo;bar;test'} >>> TestModel.objects.aggregate(result=ArrayAgg("field2")) {'result': [1, 2, 3]} >>> TestModel.objects.aggregate(result=ArrayAgg("field1")) {'result': ['foo', 'bar', 'test']} ``` 次の例では、統計的集計関数の使い方を示します。基礎となる数学については説明しません (たとえば、 [wikipedia](https://ja.wikipedia.org/wiki/%E5%9B%9E%E5%B8%B0%E5%88%86%E6%9E%90) で読むことができます): ```pycon >>> TestModel.objects.aggregate(count=RegrCount(y="field3", x="field2")) {'count': 2} >>> TestModel.objects.aggregate( ... avgx=RegrAvgX(y="field3", x="field2"), avgy=RegrAvgY(y="field3", x="field2") ... ) {'avgx': 2, 'avgy': 13} ```