Поля модели, специфичные для PostgreSQL

Все эти поля доступны из модуля django.contrib.postgres.fields.

Индексация этих полей

Index и Field.db_index оба создают индекс B-дерева, который не особенно полезен при запросах к сложным типам данных. Индексы, такие как GinIndex и GistIndex, более подходят, хотя выбор индекса зависит от используемых запросов. Обычно GiST может быть хорошим выбором для полей диапазона и HStoreField, а GIN может быть полезен для ArrayField.

Поле ArrayField

class ArrayField(base_field, size=None, **options)

Поле для хранения списков данных. Большинство типов полей могут быть использованы, и вы передаете другой экземпляр поля в качестве base_field. Вы также можете указать size. ArrayField можно вложить, чтобы хранить многомерные массивы.

Если вы зададите поле default, убедитесь, что это вызываемый объект, например, list (для пустого значения по умолчанию) или вызываемый объект, возвращающий список (например, функция). Неправильное использование default=[] создает изменяемое значение по умолчанию, которое используется всеми экземплярами ArrayField.

base_field

Это обязательный аргумент.

Указывает базовый тип данных и поведение для массива. Должен быть экземпляром подкласса Field. Например, это может быть IntegerField или CharField. Допускаются большинство типов полей, за исключением тех, которые обрабатывают реляционные данные (ForeignKey, OneToOneField и ManyToManyField) и файлы (FileField и ImageField).

Можно вкладывать поля массивов - вы можете указать экземпляр ArrayField как base_field. Например:

from django.contrib.postgres.fields import ArrayField
from django.db import models


class ChessBoard(models.Model):
    board = ArrayField(
        ArrayField(
            models.CharField(max_length=10, blank=True),
            size=8,
        ),
        size=8,
    )

Преобразование значений между базой данных и моделью, проверка данных и конфигурация, а также сериализация делегируются базовому полю.

size

Это необязательный аргумент.

Если он передан, массив будет иметь максимальный размер, как указано. Это будет передано в базу данных, хотя PostgreSQL в настоящее время не накладывает ограничения.

from django.contrib.postgres.fields import ArrayField
from django.db import models


class Board(models.Model):
    pieces = ArrayField(ArrayField(models.IntegerField()))


# Valid
Board(
    pieces=[
        [2, 3],
        [2, 1],
    ]
)

# Not valid
Board(
    pieces=[
        [2, 3],
        [2],
    ]
)

Запрос к полю ArrayField

Существует ряд пользовательских поисков и преобразований для ArrayField. Воспользуемся следующим примером модели:

from django.contrib.postgres.fields import ArrayField
from django.db import models


class Post(models.Model):
    name = models.CharField(max_length=200)
    tags = ArrayField(models.CharField(max_length=200), blank=True)

    def __str__(self):
        return self.name

contains

Поиск contains переопределен для ArrayField. Возвращаемые объекты будут теми, где переданные значения являются подмножеством данных. Используется оператор SQL @>. Например:

>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])

>>> Post.objects.filter(tags__contains=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>

>>> Post.objects.filter(tags__contains=["django"])
<QuerySet [<Post: First post>, <Post: Third post>]>

>>> Post.objects.filter(tags__contains=["django", "thoughts"])
<QuerySet [<Post: First post>]>

contained_by

Это обратный поиск contains - возвращаемые объекты будут теми, где данные являются подмножеством переданных значений. Используется оператор SQL <@. Например:

>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])

>>> Post.objects.filter(tags__contained_by=["thoughts", "django"])
<QuerySet [<Post: First post>, <Post: Second post>]>

>>> Post.objects.filter(tags__contained_by=["thoughts", "django", "tutorial"])
<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>

overlap

Возвращает объекты, где данные имеют какие-либо совпадения со значениями, переданными в параметре. Используется оператор SQL &&. Например:

>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts", "tutorial"])
>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])

>>> Post.objects.filter(tags__overlap=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>

>>> Post.objects.filter(tags__overlap=["thoughts", "tutorial"])
<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>

>>> Post.objects.filter(tags__overlap=Post.objects.values_list("tags"))
<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>

len

Возвращает длину массива. Доступные после этого поиски - это поиски, доступные для IntegerField. Например:

>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])

>>> Post.objects.filter(tags__len=1)
<QuerySet [<Post: Second post>]>

Преобразования индекса

Преобразования индекса индексируют в массив. Можно использовать любое неотрицательное целое число. Нет ошибок, если это значение превышает size массива. После преобразования доступны те же поиски, что и для base_field. Например:

>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])

>>> Post.objects.filter(tags__0="thoughts")
<QuerySet [<Post: First post>, <Post: Second post>]>

>>> Post.objects.filter(tags__1__iexact="Django")
<QuerySet [<Post: First post>]>

>>> Post.objects.filter(tags__276="javascript")
<QuerySet []>

Преобразования срезов

Преобразования срезов берут срез массива. Можно использовать любые два неотрицательных целых числа, разделенных одним символом подчеркивания. Доступные после преобразования поиски не меняются. Например:

>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.create(name="Third post", tags=["django", "python", "thoughts"])

>>> Post.objects.filter(tags__0_1=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>

>>> Post.objects.filter(tags__0_2__contains=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>

CIText поля

class CIText(**options)

Устарело начиная с версии 4.2.

Mixin для создания полей текста с игнорированием регистра, основанных на типе citext. Узнайте о ограничениях производительности перед использованием.

Для использования citext, используйте операцию CITextExtension для настройки расширения citext в PostgreSQL перед первой операцией миграции CreateModel.

Если вы используете ArrayField полей CIText, вам необходимо добавить 'django.contrib.postgres' в ваш INSTALLED_APPS, в противном случае значения полей будут отображаться как строки, например, '{thoughts,django}'.

Несколько полей, использующих этот mixin, предоставляются:

class CICharField(**options)

Устарело начиная с версии 4.2: CICharField устарело в пользу CharField(db_collation="…") с регистронезависимым, недетерминированным упорядочиванием.

class CIEmailField(**options)

Устарело начиная с версии 4.2: CIEmailField устарело в пользу EmailField(db_collation="…") с регистронезависимой недетерминированной сортировкой.

class CITextField(**options)

Устарело начиная с версии 4.2: CITextField устарело в пользу TextField(db_collation="…") с регистронезависимой недетерминированной сортировкой.

Эти поля наследуются от CharField, EmailField и TextField, соответственно.

max_length не будет проверяться в базе данных, так как citext ведет себя аналогично типу text PostgreSQL.

HStoreField

class HStoreField(**options)

Поле для хранения пар ключ-значение. Используемый тип данных Python — dict. Ключи должны быть строками, а значения могут быть строками или null (None в Python).

Чтобы использовать это поле, вам необходимо:

1. Добавить 'django.contrib.postgres' в свой INSTALLED_APPS.
2. Настроить расширение hstore в PostgreSQL.

Вы увидите ошибку, похожую на can't adapt type 'dict', если пропустите первый шаг, или type "hstore" does not exist, если пропустите второй.

Запросы к полю HStoreField

Помимо возможности запроса по ключу, для HStoreField доступно несколько пользовательских правил поиска.

Мы будем использовать следующую примерную модель:

from django.contrib.postgres.fields import HStoreField
from django.db import models


class Dog(models.Model):
    name = models.CharField(max_length=200)
    data = HStoreField()

    def __str__(self):
        return self.name

Поиск по ключу

Чтобы выполнить поиск по заданному ключу, вы можете использовать этот ключ в качестве имени правила поиска:

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie"})

>>> Dog.objects.filter(data__breed="collie")
<QuerySet [<Dog: Meg>]>

Вы можете цепочкой соединять другие правила поиска после поиска по ключу:

>>> Dog.objects.filter(data__breed__contains="l")
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

или использовать F() выражения для аннотирования значения ключа. Например:

>>> from django.db.models import F
>>> rufus = Dog.objects.annotate(breed=F("data__breed"))[0]
>>> rufus.breed
'labrador'

Если ключ, по которому вы хотите выполнить поиск, совпадает с именем другого правила поиска, необходимо использовать правило поиска hstorefield.contains вместо него.

contains

Правило поиска contains переопределяется для HStoreField. Возвращаются объекты, где все заданные dict пар ключ-значение содержатся в поле. Используется оператор SQL @>. Например:

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
>>> Dog.objects.create(name="Fred", data={})

>>> Dog.objects.filter(data__contains={"owner": "Bob"})
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

>>> Dog.objects.filter(data__contains={"breed": "collie"})
<QuerySet [<Dog: Meg>]>

contained_by

Это обратное правило поиска contains — возвращаются объекты, где пары ключ-значение объекта являются подмножеством пар в переданном значении. Используется оператор SQL <@. Например:

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
>>> Dog.objects.create(name="Fred", data={})

>>> Dog.objects.filter(data__contained_by={"breed": "collie", "owner": "Bob"})
<QuerySet [<Dog: Meg>, <Dog: Fred>]>

>>> Dog.objects.filter(data__contained_by={"breed": "collie"})
<QuerySet [<Dog: Fred>]>

has_key

Возвращает объекты, где заданный ключ присутствует в данных. Используется оператор SQL ?. Например:

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})

>>> Dog.objects.filter(data__has_key="owner")
<QuerySet [<Dog: Meg>]>

has_any_keys

Возвращает объекты, где любой из заданных ключей присутствует в данных. Используется оператор SQL ?|. Например:

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
>>> Dog.objects.create(name="Meg", data={"owner": "Bob"})
>>> Dog.objects.create(name="Fred", data={})

>>> Dog.objects.filter(data__has_any_keys=["owner", "breed"])
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

has_keys

Возвращает объекты, где все заданные ключи присутствуют в данных. Используется оператор SQL ?&. Например:

>>> Dog.objects.create(name="Rufus", data={})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})

>>> Dog.objects.filter(data__has_keys=["breed", "owner"])
<QuerySet [<Dog: Meg>]>

keys

Возвращает объекты, где массив ключей равен заданному значению. Обратите внимание, что порядок не гарантирован, поэтому эта трансформация в основном полезна для использования в сочетании с правилами поиска для ArrayField. Используется функция SQL akeys(). Например:

>>> Dog.objects.create(name="Rufus", data={"toy": "bone"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})

>>> Dog.objects.filter(data__keys__overlap=["breed", "toy"])
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

values

Возвращает объекты, где массив значений равен заданному значению. Обратите внимание, что порядок не гарантирован, поэтому эта трансформация в основном полезна для использования в сочетании с правилами поиска для ArrayField. Используется функция SQL avals(). Например:

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})

>>> Dog.objects.filter(data__values__contains=["collie"])
<QuerySet [<Dog: Meg>]>

Поля диапазонов

Существует пять типов полей диапазонов, соответствующих встроенным типам диапазонов в PostgreSQL. Эти поля используются для хранения диапазона значений; например, начальной и конечной даты и времени события или диапазона возрастов, для которых подходит определенная деятельность.

Все поля диапазонов преобразуются в объекты psycopg Range в Python, но также принимают кортежи в качестве входных данных, если никакие данные о границах не требуются. По умолчанию нижняя граница включена, верхняя исключена, то есть [) (см. документацию PostgreSQL для получения более подробной информации о различных границах). Границы по умолчанию могут быть изменены для полей диапазонов, не являющихся дискретными (DateTimeRangeField и DecimalRangeField) с помощью аргумента default_bounds.

IntegerRangeField

class IntegerRangeField(**options)

Хранит диапазон целых чисел. Основано на IntegerField. Представлено в базе данных как int4range и как django.db.backends.postgresql.psycopg_any.NumericRange в Python.

Независимо от границ, указанных при сохранении данных, PostgreSQL всегда возвращает диапазон в канонической форме, включающей нижнюю границу и исключающей верхнюю, то есть [).

BigIntegerRangeField

class BigIntegerRangeField(**options)

Хранит диапазон больших целых чисел. Основано на BigIntegerField. Представлено в базе данных как int8range и как django.db.backends.postgresql.psycopg_any.NumericRange в Python.

Независимо от границ, указанных при сохранении данных, PostgreSQL всегда возвращает диапазон в канонической форме, включающей нижнюю границу и исключающей верхнюю, то есть [).

DecimalRangeField

class DecimalRangeField(default_bounds='[)', **options)

Хранит диапазон значений с плавающей точкой. Основан на DecimalField. Представлен в базе данных как numrange и как django.db.backends.postgresql.psycopg_any.NumericRange в Python.

default_bounds

Новое в Django 4.1.

Необязательно. Значение bounds для входных данных типа список и кортеж. По умолчанию нижняя граница включена, верхняя — исключена, то есть [) (см. документацию PostgreSQL для получения подробной информации о разных границах). default_bounds не используется для входных данных типа django.db.backends.postgresql.psycopg_any.NumericRange.

DateTimeRangeField

class DateTimeRangeField(default_bounds='[)', **options)

Хранит диапазон временных меток. Основан на DateTimeField. Представлен в базе данных как tstzrange и как django.db.backends.postgresql.psycopg_any.DateTimeTZRange в Python.

default_bounds

Новое в Django 4.1.

Необязательно. Значение bounds для входных данных типа список и кортеж. По умолчанию нижняя граница включена, верхняя — исключена, то есть [) (см. документацию PostgreSQL для получения подробной информации о разных границах). default_bounds не используется для входных данных типа django.db.backends.postgresql.psycopg_any.DateTimeTZRange.

DateRangeField

class DateRangeField(**options)

Хранит диапазон дат. Основан на DateField. Представлен в базе данных как daterange и как django.db.backends.postgresql.psycopg_any.DateRange в Python.

Независимо от границ, указанных при сохранении данных, PostgreSQL всегда возвращает диапазон в канонической форме, включающий нижнюю границу и исключающий верхнюю границу, то есть [).

Запросы к полям диапазона

Существует ряд пользовательских поисковых запросов и преобразований для полей диапазона. Они доступны для всех вышеперечисленных полей, но мы будем использовать следующую примерную модель:

from django.contrib.postgres.fields import IntegerRangeField
from django.db import models


class Event(models.Model):
    name = models.CharField(max_length=200)
    ages = IntegerRangeField()
    start = models.DateTimeField()

    def __str__(self):
        return self.name

Мы также будем использовать следующие примерные объекты:

>>> import datetime
>>> from django.utils import timezone
>>> now = timezone.now()
>>> Event.objects.create(name="Soft play", ages=(0, 10), start=now)
>>> Event.objects.create(
...     name="Pub trip", ages=(21, None), start=now - datetime.timedelta(days=1)
... )

и NumericRange:

>>> from django.db.backends.postgresql.psycopg_any import NumericRange

Функции включения

Как и в других полях PostgreSQL, существуют три стандартных оператора включения: contains, contained_by и overlap, использующие операторы SQL @>, <@, и && соответственно.

contains

>>> Event.objects.filter(ages__contains=NumericRange(4, 5))
<QuerySet [<Event: Soft play>]>

contained_by

>>> Event.objects.filter(ages__contained_by=NumericRange(0, 15))
<QuerySet [<Event: Soft play>]>

Поиск contained_by также доступен для типов полей без диапазона: SmallAutoField, AutoField, BigAutoField, SmallIntegerField, IntegerField, BigIntegerField, DecimalField, FloatField, DateField и DateTimeField. Например:

>>> from django.db.backends.postgresql.psycopg_any import DateTimeTZRange
>>> Event.objects.filter(
...     start__contained_by=DateTimeTZRange(
...         timezone.now() - datetime.timedelta(hours=1),
...         timezone.now() + datetime.timedelta(hours=1),
...     ),
... )
<QuerySet [<Event: Soft play>]>

overlap

>>> Event.objects.filter(ages__overlap=NumericRange(8, 12))
<QuerySet [<Event: Soft play>]>

Функции сравнения

Поля диапазона поддерживают стандартные поисковые запросы: lt, gt, lte и gte. Они не очень полезны — они сначала сравнивают нижние границы, а затем верхние границы только при необходимости. Это также стратегия, используемая для сортировки по полю диапазона. Лучше использовать конкретные операторы сравнения диапазона.

fully_lt

Возвращаемые диапазоны строго меньше переданного диапазона. Другими словами, все точки в возвращаемом диапазоне меньше всех точек в переданном диапазоне.

>>> Event.objects.filter(ages__fully_lt=NumericRange(11, 15))
<QuerySet [<Event: Soft play>]>

fully_gt

Возвращаемые диапазоны строго больше переданного диапазона. Другими словами, все точки в возвращаемом диапазоне больше всех точек в переданном диапазоне.

>>> Event.objects.filter(ages__fully_gt=NumericRange(11, 15))
<QuerySet [<Event: Pub trip>]>

not_lt

Возвращаемые диапазоны не содержат точек, меньших переданного диапазона, то есть нижняя граница возвращаемого диапазона не меньше нижней границы переданного диапазона.

>>> Event.objects.filter(ages__not_lt=NumericRange(0, 15))
<QuerySet [<Event: Soft play>, <Event: Pub trip>]>

not_gt

Возвращаемые диапазоны не содержат точек, больших переданного диапазона, то есть верхняя граница возвращаемого диапазона не больше верхней границы переданного диапазона.

>>> Event.objects.filter(ages__not_gt=NumericRange(3, 10))
<QuerySet [<Event: Soft play>]>

adjacent_to

Возвращаемые диапазоны имеют общую границу с переданным диапазоном.

>>> Event.objects.filter(ages__adjacent_to=NumericRange(10, 21))
<QuerySet [<Event: Soft play>, <Event: Pub trip>]>

Запрос по границам

Поля диапазона поддерживают несколько дополнительных поисковых запросов.

startswith

Возвращаемые объекты имеют заданную нижнюю границу. Может быть соединен с корректными запросами для базового поля.

>>> Event.objects.filter(ages__startswith=21)
<QuerySet [<Event: Pub trip>]>

endswith

Возвращаемые объекты имеют заданную верхнюю границу. Может быть соединен с корректными запросами для базового поля.

>>> Event.objects.filter(ages__endswith=10)
<QuerySet [<Event: Soft play>]>

isempty

Возвращаемые объекты являются пустыми диапазонами. Может быть соединен с корректными запросами для BooleanField.

>>> Event.objects.filter(ages__isempty=True)
<QuerySet []>

lower_inc

Возвращает объекты, имеющие включительную или исключительную нижнюю границу, в зависимости от переданного булевого значения. Может быть соединен с корректными запросами для BooleanField.

>>> Event.objects.filter(ages__lower_inc=True)
<QuerySet [<Event: Soft play>, <Event: Pub trip>]>

lower_inf

Возвращает объекты, имеющие неограниченную (бесконечную) или ограниченную нижнюю границу, в зависимости от переданного булевого значения. Может быть соединен с корректными запросами для BooleanField.

>>> Event.objects.filter(ages__lower_inf=True)
<QuerySet []>

upper_inc

Возвращает объекты, имеющие включительную или исключительную верхнюю границу, в зависимости от переданного булевого значения. Может быть соединен с корректными запросами для BooleanField.

>>> Event.objects.filter(ages__upper_inc=True)
<QuerySet []>

upper_inf

Возвращает объекты, имеющие неограниченную (бесконечную) или ограниченную верхнюю границу, в зависимости от переданного булевого значения. Может быть соединен с корректными запросами для BooleanField.

>>> Event.objects.filter(ages__upper_inf=True)
<QuerySet [<Event: Pub trip>]>

Определение собственных типов диапазонов

PostgreSQL позволяет определять пользовательские типы диапазонов. Реализации полей модели и формы Django используют базовые классы ниже, и psycopg предоставляет register_range() для использования пользовательских типов диапазонов.

class RangeField(**options)

Базовый класс для полей диапазона модели.

base_field

Класс поля модели для использования.

range_type

Тип диапазона для использования.

form_field

Класс поля формы для использования. Должен быть подклассом django.contrib.postgres.forms.BaseRangeField.

class django.contrib.postgres.forms.BaseRangeField

Базовый класс для полей формы диапазона.

base_field

Поле формы для использования.

range_type

Тип диапазона для использования.

Операторы диапазонов

class RangeOperators

PostgreSQL предоставляет набор SQL-операторов, которые можно использовать вместе с типами данных диапазонов (см. документацию PostgreSQL для получения полной информации об операторах диапазонов). Этот класс предназначен как удобный способ избежать опечаток. Имена операторов перекрываются с именами соответствующих запросов.

class RangeOperators:
    EQUAL = "="
    NOT_EQUAL = "<>"
    CONTAINS = "@>"
    CONTAINED_BY = "<@"
    OVERLAPS = "&&"
    FULLY_LT = "<<"
    FULLY_GT = ">>"
    NOT_LT = "&>"
    NOT_GT = "&<"
    ADJACENT_TO = "-|-"

Выражения RangeBoundary()

class RangeBoundary(inclusive_lower=True, inclusive_upper=False)

inclusive_lower

Если True (по умолчанию), нижняя граница включена '[', в противном случае она исключена '('.

inclusive_upper

Если False (по умолчанию), верхняя граница исключена ')', в противном случае она включена ']'.

Выражение RangeBoundary() представляет собой границы диапазона. Его можно использовать с пользовательскими функциями диапазонов, ожидающими границы, например, для определения ExclusionConstraint. См. документацию PostgreSQL для получения полной информации.