これらのフィールドは全て django.contrib.postgres.fields モジュールから利用できます。
Index と Field.db_index は両方とも B-tree インデックスを作成しますが、複雑なデータ型をクエリする際にはあまり役立ちません。 GinIndex や GistIndex などのインデックスの方が適しています。ただし、適切なインデックスの選択は使用しているクエリに依存します。一般的には、GiST は 範囲フィールド や HStoreField には適しており、GIN は ArrayField に役立つかもしれません。
ArrayFieldLink to this heading#データのリストを格納するためのフィールドです。ほとんどのフィールドタイプを使用でき、 base_field として別のフィールドインスタンスを渡します。 size を指定することもできます。ArrayField は、多次元配列を格納するためにネストすることもできます。
フィールドに default を与える場合は、それが list (空のデフォルトの場合) やリストを返す呼び出し可能オブジェクト (関数など) のような呼び出し可能オブジェクトであることを確認してください。 default=[] を誤って使用すると、すべての ArrayField インスタンスで共有される変更可能なデフォルトが作成されます。
これは必須の引数です。
\n配列のベースとなるデータ型や動作を指定します。これは、 Field のサブクラスのインスタンスである必要があります。例えば IntegerField や CharField などが考えられます。ほとんどのフィールドタイプが許容されますが、リレーショナルデータを処理するもの (ForeignKey, OneToOneField, ManyToManyField) やファイルフィールド (FileField, ImageField) は除外されます。
配列フィールドは入れ子にできます。 base_field として ArrayField のインスタンスを指定できます。たとえば:
from django.contrib.postgres.fields import ArrayField\nfrom django.db import models\n\n\nclass ChessBoard(models.Model):\n board = ArrayField(\n ArrayField(\n models.CharField(max_length=10, blank=True),\n size=8,\n ),\n size=8,\n )\nデータベースとモデル間の値の変換、データと設定の検証、シリアライズはすべて、基盤となるベースフィールドに委譲されます。
\nこれはオプションの引数です。
\n指定された場合、配列は指定された最大サイズを持ちます。これはデータベースに渡されますが、現在のところ PostgreSQL はこの制限を強制しません。
\nArrayField へのクエリLink to this heading#ArrayField には、カスタムルックアップやトランスフォームがいくつかあります。以下のモデル例を使用します。
from django.contrib.postgres.fields import ArrayField\nfrom django.db import models\n\n\nclass Post(models.Model):\n name = models.CharField(max_length=200)\n tags = ArrayField(models.CharField(max_length=200), blank=True)\n\n def __str__(self):\n return self.name\ncontainsLink to this heading#ArrayField 上で contains ルックアップはオーバーライドされます。返されるオブジェクトは、渡された値がデータの部分集合であるものです。これは SQL 演算子 @> を使用します。たとえば、:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])\n>>> Post.objects.create(name="Second post", tags=["thoughts"])\n>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])\n\n>>> Post.objects.filter(tags__contains=["thoughts"])\n<QuerySet [<Post: First post>, <Post: Second post>]>\n\n>>> Post.objects.filter(tags__contains=["django"])\n<QuerySet [<Post: First post>, <Post: Third post>]>\n\n>>> Post.objects.filter(tags__contains=["django", "thoughts"])\n<QuerySet [<Post: First post>]>\ncontained_byLink to this heading#これは contains ルックアップの逆です。返されるオブジェクトは、データが渡された値の部分集合であるものです。これにはSQL演算子 <@ が使用されます。たとえば:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])\n>>> Post.objects.create(name="Second post", tags=["thoughts"])\n>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])\n\n>>> Post.objects.filter(tags__contained_by=["thoughts", "django"])\n<QuerySet [<Post: First post>, <Post: Second post>]>\n\n>>> Post.objects.filter(tags__contained_by=["thoughts", "django", "tutorial"])\n<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>\noverlapLink to this heading#データが渡された値といずれか一致するオブジェクトを返します。SQL 演算子 (&&) を使用します。例:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])\n>>> Post.objects.create(name="Second post", tags=["thoughts", "tutorial"])\n>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])\n\n>>> Post.objects.filter(tags__overlap=["thoughts"])\n<QuerySet [<Post: First post>, <Post: Second post>]>\n\n>>> Post.objects.filter(tags__overlap=["thoughts", "tutorial"])\n<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>\n\n>>> Post.objects.filter(tags__overlap=Post.objects.values_list("tags"))\n<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>\nlenLink to this heading#配列の長さを返します。この後に利用可能なルックアップは IntegerField で利用可能なものです。たとえば:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])\n>>> Post.objects.create(name="Second post", tags=["thoughts"])\n\n>>> Post.objects.filter(tags__len=1)\n<QuerySet [<Post: Second post>]>\nインデックスは配列内のインデックスに変換されます。非負の整数ならどれでも使用できます。配列の size 属性を超えていてもエラーは発生しません。変換後に利用可能なルックアップは、 base_field 属性から得られるものです。たとえば:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])\n>>> Post.objects.create(name="Second post", tags=["thoughts"])\n\n>>> Post.objects.filter(tags__0="thoughts")\n<QuerySet [<Post: First post>, <Post: Second post>]>\n\n>>> Post.objects.filter(tags__1__iexact="Django")\n<QuerySet [<Post: First post>]>\n\n>>> Post.objects.filter(tags__276="javascript")\n<QuerySet []>\nスライス トランスフォームは、配列の一部を切り取ります。 2つの非負整数をアンダースコアで区切って使用できます。トランスフォーム後に利用可能なルックアップは変わりません。 例を挙げると、
\n>>> Post.objects.create(name="First post", tags=["thoughts", "django"])\n>>> Post.objects.create(name="Second post", tags=["thoughts"])\n>>> Post.objects.create(name="Third post", tags=["django", "python", "thoughts"])\n\n>>> Post.objects.filter(tags__0_1=["thoughts"])\n<QuerySet [<Post: First post>, <Post: Second post>]>\n\n>>> Post.objects.filter(tags__0_2__contains=["thoughts"])\n<QuerySet [<Post: First post>, <Post: Second post>]>\nHStoreFieldLink to this heading#キーと値のペアを格納するためのフィールド。Python のデータ型は dict です。キーは文字列でなければならず、値は文字列または NULL (Python では None) でなければなりません。
このフィールドを使用するには、次のようにします:
\nINSTALLED_APPS に 'django.contrib.postgres' を追加します。
PostgreSQL の hstore 拡張 を設定します。
最初のステップをスキップすると can't adapt type 'dict' というエラーが表示され、2番目のステップをスキップすると type "hstore" does not exist というエラーが表示されます。
HStoreField へのクエリLink to this heading#HStoreField では、キーによるクエリに加えて、多くのカスタムルックアップが利用可能です。
次のようなモデル例を使用します:
\nfrom django.contrib.postgres.fields import HStoreField\nfrom django.db import models\n\n\nclass Dog(models.Model):\n name = models.CharField(max_length=200)\n data = HStoreField()\n\n def __str__(self):\n return self.name\n指定されたキーに基づいてクエリを実行するには、そのキーをルックアップ名として使用します:
\n>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n>>> Dog.objects.create(name="Meg", data={"breed": "collie"})\n\n>>> Dog.objects.filter(data__breed="collie")\n<QuerySet [<Dog: Meg>]>\nキーのルックアップの後に他のルックアップを連結することもできます:
\n>>> Dog.objects.filter(data__breed__contains="l")\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\nF() 式を使ってキー値にアノテーションを付けることもできます。たとえば:
>>> from django.db.models import F\n>>> rufus = Dog.objects.annotate(breed=F("data__breed"))[0]\n>>> rufus.breed\n'labrador'\nクエリしたいキーが他のルックアップの名前と衝突する場合は、代わりに hstorefield.contains ルックアップを使用する必要があります。
containsLink to this heading#contains ルックアップは、HStoreField 上でオーバーライドされています。返されるオブジェクトは、指定されたキーと値の dict がフィールド内にすべて含まれるものです。SQL 演算子 @> を使用します。たとえば:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n>>> Dog.objects.create(name="Fred", data={})\n\n>>> Dog.objects.filter(data__contains={"owner": "Bob"})\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\n\n>>> Dog.objects.filter(data__contains={"breed": "collie"})\n<QuerySet [<Dog: Meg>]>\ncontained_byLink to this heading#これは、 contains ルックアップの逆です。返されるオブジェクトは、オブジェクト上のキーと値のペアが渡された値のサブセットであるものです。これは、SQL演算子 <@ を使用します。たとえば:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n>>> Dog.objects.create(name="Fred", data={})\n\n>>> Dog.objects.filter(data__contained_by={"breed": "collie", "owner": "Bob"})\n<QuerySet [<Dog: Meg>, <Dog: Fred>]>\n\n>>> Dog.objects.filter(data__contained_by={"breed": "collie"})\n<QuerySet [<Dog: Fred>]>\nhas_keyLink to this heading#与えられたキーがデータ内にあるオブジェクトを返します。SQL演算子は ? を使用します。例:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n\n>>> Dog.objects.filter(data__has_key="owner")\n<QuerySet [<Dog: Meg>]>\nhas_any_keysLink to this heading#与えられたキーのいずれかがデータ内にあるオブジェクトを返します。SQL演算子 ?| を使用します。例:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n>>> Dog.objects.create(name="Meg", data={"owner": "Bob"})\n>>> Dog.objects.create(name="Fred", data={})\n\n>>> Dog.objects.filter(data__has_any_keys=["owner", "breed"])\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\nhas_keysLink to this heading#与えられたキーが全てデータ中に含まれるオブジェクトを返します。SQL演算子 ?& を使用します。例:
>>> Dog.objects.create(name="Rufus", data={})\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n\n>>> Dog.objects.filter(data__has_keys=["breed", "owner"])\n<QuerySet [<Dog: Meg>]>\nkeysLink to this heading#与えられた値がキーの配列であるオブジェクトを返します。順序が信頼できるわけではないことに注意してください。したがって、このトランスフォームは主に ArrayField でのルックアップと組み合わせて使用するために便利です。SQL 関数 akeys() を使用します。例:
>>> Dog.objects.create(name="Rufus", data={"toy": "bone"})\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n\n>>> Dog.objects.filter(data__keys__overlap=["breed", "toy"])\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\nvaluesLink to this heading#値の配列が与えられた値であるオブジェクトを返します。このトランスフォームは主に ArrayField のルックアップと組み合わせて使用すると便利です。SQL 関数 avals() を使用します。たとえば:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n\n>>> Dog.objects.filter(data__values__contains=["collie"])\n<QuerySet [<Dog: Meg>]>\nPostgreSQLの組み込み範囲型に対応する5つの範囲フィールド型があります。これらのフィールドは値の範囲を格納するために使用されます。例えば、イベントの開始と終了のタイムスタンプや、アクティビティに適した年齢の範囲などです。
\nすべての範囲フィールドはPythonでは psycopg Range オブジェクト に変換されますが、境界情報が不要な場合はタプルを入力として受け付けます。デフォルトは下界を含み、上界を含まない [) です (different bounds の詳細についてはPostgreSQLのドキュメントを参照してください) 。離散範囲でないフィールド (DateTimeRangeField と DecimalRangeField) のデフォルトの境界は default_bounds 引数で変更できます。
IntegerRangeFieldLink to this heading#整数の範囲を格納します。 IntegerField に基づいています。データベースでは int4range で表現され、 Python では django.db.backends.postgresql.psycopg_any.NumericRange で表現されます。
データ保存時に指定された境界に関係なく、PostgreSQLは常に下界を含み上界を除いた正規形、つまり [) で範囲を返します。
BigIntegerRangeFieldLink to this heading#大きな整数の範囲を格納します。 BigIntegerField に基づいています。データベースでは int8range で表現され、 Python では django.db.backends.postgresql.psycopg_any.NumericRange で表現されます。
データ保存時に指定された境界に関係なく、PostgreSQLは常に下界を含み上界を除いた正規形、つまり [) で範囲を返します。
DecimalRangeFieldLink to this heading#浮動小数点値の範囲を格納します。 DecimalField に基づいています。データベースでは numrange で表現され、Python では django.db.backends.postgresql.psycopg_any.NumericRange で表現されます。
オプション。リストとタプルの入力に対する bounds の値。デフォルトは下限を含み、上限を除く [) です (different bounds の詳細については PostgreSQL のドキュメント を参照してください)。 default_bounds は django.db.backends.postgresql.psycopg_any.NumericRange 入力には使用されません。
DateTimeRangeFieldLink to this heading#タイムスタンプの範囲を格納します。 DateTimeField に基づいています。データベースでは tstzrange で表現され、Python では django.db.backends.postgresql.psycopg_any.DateTimeTZRange で表現されます。
オプション。リストとタプルの入力に対する bounds の値。デフォルトは下限を含み、上限を除く [) です (different bounds の詳細については PostgreSQL のドキュメント を参照してください)。 default_bounds は django.db.backends.postgresql.psycopg_any.DateTimeTZRange 入力には使用されません。
DateRangeFieldLink to this heading#日付の範囲を格納します。 DateField に基づいています。データベースでは daterange で表現され、Python では django.db.backends.postgresql.psycopg_any.DateRange で表現されます。
データ保存時に指定された境界に関係なく、PostgreSQLは常に下界を含み上界を除いた正規形、つまり [) で範囲を返します。
範囲フィールド用のカスタムルックアップとトランスフォームが多数あります。これらは上記のすべてのフィールドで利用できますが、次の例のモデルを使います:
\nfrom django.contrib.postgres.fields import IntegerRangeField\nfrom django.db import models\n\n\nclass Event(models.Model):\n name = models.CharField(max_length=200)\n ages = IntegerRangeField()\n start = models.DateTimeField()\n\n def __str__(self):\n return self.name\nまた、以下のオブジェクト例も使用します:
\n>>> import datetime\n>>> from django.utils import timezone\n>>> now = timezone.now()\n>>> Event.objects.create(name="Soft play", ages=(0, 10), start=now)\n>>> Event.objects.create(\n... name="Pub trip", ages=(21, None), start=now - datetime.timedelta(days=1)\n... )\nそして NumericRange も:
>>> from django.db.backends.postgresql.psycopg_any import NumericRange\n他の PostgreSQL フィールドと同様に、3つの標準の包含演算子があります。 contains, contained_by, overlap で、それぞれ SQL 演算子 @>, <@, && が使われます。
containsLink to this heading#>>> Event.objects.filter(ages__contains=NumericRange(4, 5))\n<QuerySet [<Event: Soft play>]>\ncontained_byLink to this heading#>>> Event.objects.filter(ages__contained_by=NumericRange(0, 15))\n<QuerySet [<Event: Soft play>]>\nまた、contained_by ルックアップは範囲以外のフィールド型でも利用できます: SmallAutoField, AutoField, BigAutoField, SmallIntegerField, IntegerField, BigIntegerField, DecimalField, FloatField, DateField, and DateTimeField 。たとえば:
>>> from django.db.backends.postgresql.psycopg_any import DateTimeTZRange\n>>> Event.objects.filter(\n... start__contained_by=DateTimeTZRange(\n... timezone.now() - datetime.timedelta(hours=1),\n... timezone.now() + datetime.timedelta(hours=1),\n... ),\n... )\n<QuerySet [<Event: Soft play>]>\noverlapLink to this heading#>>> Event.objects.filter(ages__overlap=NumericRange(8, 12))\n<QuerySet [<Event: Soft play>]>\n範囲フィールドは標準のルックアップをサポートしています: lt, gt, lte, および gte。これらはあまり有用ではありません。必要な場合のみ上限値を比較するように、まず下限値を比較します。これは範囲フィールドでのソートにも使用される戦略です。特定の範囲比較演算子を使用する方が良いです。
fully_ltLink to this heading#返される範囲は、渡された範囲よりも厳密に小さいです。つまり、返される範囲内のすべての点は、渡された範囲内のすべての点よりも小さいです。
\n>>> Event.objects.filter(ages__fully_lt=NumericRange(11, 15))\n<QuerySet [<Event: Soft play>]>\nfully_gtLink to this heading#返される範囲は、渡された範囲よりも厳密に大きいです。つまり、返される範囲のすべての点は、渡された範囲のすべての点よりも大きくなります。
\n>>> Event.objects.filter(ages__fully_gt=NumericRange(11, 15))\n<QuerySet [<Event: Pub trip>]>\nnot_ltLink to this heading#返される範囲には、渡された範囲より小さいポイントは含まれません。つまり、返される範囲の下限は少なくとも渡された範囲の下限となります。
\n>>> Event.objects.filter(ages__not_lt=NumericRange(0, 15))\n<QuerySet [<Event: Soft play>, <Event: Pub trip>]>\nnot_gtLink to this heading#返される範囲には、渡された範囲よりも大きい値が含まれませんい。つまり、返される範囲の上限は、渡された範囲の上限以下になります。
\n>>> Event.objects.filter(ages__not_gt=NumericRange(3, 10))\n<QuerySet [<Event: Soft play>]>\nadjacent_toLink to this heading#返される範囲は、渡された範囲と境界を共有します。
\n>>> Event.objects.filter(ages__adjacent_to=NumericRange(10, 21))\n<QuerySet [<Event: Soft play>, <Event: Pub trip>]>\n範囲フィールドはいくつかの追加ルックアップをサポートしています。
\nstartswithLink to this heading#返されるオブジェクトは与えられた下界を持つ。ベースフィールドの有効なルックアップに連結できます。
\n>>> Event.objects.filter(ages__startswith=21)\n<QuerySet [<Event: Pub trip>]>\nendswithLink to this heading#返されるオブジェクトは与えられた上限を持つ。ベースフィールドの有効なルックアップに連結できます。
\n>>> Event.objects.filter(ages__endswith=10)\n<QuerySet [<Event: Soft play>]>\nisemptyLink to this heading#返されるオブジェクトは空の範囲です。 BooleanField の有効なルックアップに連結できます。
>>> Event.objects.filter(ages__isempty=True)\n<QuerySet []>\nlower_incLink to this heading#与えられた真偽値に基づき、包含もしくは非包含な下限値を持つオブジェクトを返します。 BooleanField の有効なルックアップに連結できます。
>>> Event.objects.filter(ages__lower_inc=True)\n<QuerySet [<Event: Soft play>, <Event: Pub trip>]>\nlower_infLink to this heading#渡された真偽値に応じて、無限大または有界下限境界を持つオブジェクトを返します。 BooleanField に対して有効なルックアップに連結できます。
>>> Event.objects.filter(ages__lower_inf=True)\n<QuerySet []>\nupper_incLink to this heading#渡されたブール値に応じて、上限値を包含または非包含として持つオブジェクトを返します。これは、 BooleanField に対して有効なルックアップに連結できます。
>>> Event.objects.filter(ages__upper_inc=True)\n<QuerySet []>\nupper_infLink to this heading#渡された真偽値に応じて、上限が無制限 (無限) または有界のオブジェクトを返します。 BooleanField の有効なルックアップに連結できます。
>>> Event.objects.filter(ages__upper_inf=True)\n<QuerySet [<Event: Pub trip>]>\nPostgreSQLでは、独自の範囲型の定義が可能です。Djangoのモデルとフォームフィールドの実装は、以下の基本クラスを使用しており、 psycopg は独自の範囲型の使用を可能にする register_range() を提供しています。
モデル範囲フィールドの基底クラス。
\n使用するモデルフィールドクラス。
\n使用する範囲のタイプ。
\n使用するフォームフィールドクラス。これは django.contrib.postgres.forms.BaseRangeField のサブクラスである必要があります。
フォームの範囲フィールドの基底クラス。
\n使用するフォームフィールド。
\n使用する範囲のタイプ。
\nPostgreSQL は範囲データ型と共に使用できる SQL 演算子のセットを提供しています (範囲演算子の完全な詳細については the PostgreSQL documentation for the full details of range operators を参照してください) 。このクラスはタイプミスを避けるための便利な方法です。演算子名は対応するルックアップの名前と重複します。
\nclass RangeOperators:\n EQUAL = "="\n NOT_EQUAL = "<>"\n CONTAINS = "@>"\n CONTAINED_BY = "<@"\n OVERLAPS = "&&"\n FULLY_LT = "<<"\n FULLY_GT = ">>"\n NOT_LT = "&>"\n NOT_GT = "&<"\n ADJACENT_TO = "-|-"\nTrue (デフォルト) の場合、下限値は包含される '[' であり、そうでない場合は非包含 '(' です。
False (デフォルト) なら、上限は非包含 ')' となります。それ以外の場合は包含 ']' となります。
RangeBoundary() 式は範囲の境界を表します。これは、範囲の境界を期待するカスタム範囲関数と一緒に使用できます。たとえば、 ExclusionConstraint を定義する際に使用されます。詳細は PostgreSQLのドキュメント を参照してください。