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

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

Индексирование этих полей

Index и Field.db_index создают индекс B-дерева, который не особенно полезен при запросах к сложным типам данных. Такие индексы, как GinIndex и GistIndex, подходят лучше, хотя выбор индекса зависит от запросов, которые вы используете. В целом, GiST может быть хорошим выбором для range fields и 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).

Возможно вложение полей массива - вы можете указать экземпляр 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 не применяет это ограничение.

Примечание

При вложении ArrayField, независимо от того, используете вы параметр 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],
])

Если требуются неправильные формы, то базовое поле следует сделать нулевым, а значения дополнить символом None.

Запрос 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'])
>>> 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>]>

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

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

Index преобразует индекс в массив. Можно использовать любое неотрицательное целое число. Ошибки нет, если оно превышает 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 []>

Примечание

PostgreSQL использует индексацию на основе 1 для полей массива при написании необработанного SQL. Однако эти индексы и индексы, используемые в slices, используют индексацию на основе 0, чтобы соответствовать Python.

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

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

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

Примечание

PostgreSQL использует индексацию на основе 1 для полей массива при написании необработанного SQL. Однако эти срезы и срезы, используемые в indexes, используют индексацию на основе 0, чтобы соответствовать Python.

Многомерные массивы с индексами и срезами

PostgreSQL имеет довольно эзотерическое поведение при использовании индексов и срезов на многомерных массивах. Использование индексов для достижения конечных базовых данных всегда будет работать, но большинство других срезов ведут себя странно на уровне базы данных и не могут поддерживаться логически последовательным образом в Django.

CIText поля

class CIText(**options)[исходный код]

Миксин для создания нечувствительных к регистру текстовых полей, поддерживаемых типом citext. Перед использованием прочитайте о the performance considerations.

Чтобы использовать citext, используйте операцию CITextExtension для set up the citext extension в PostgreSQL перед первой операцией миграции CreateModel.

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

Предоставляется несколько полей, использующих миксин:

class CICharField(**options)[исходный код]
class CIEmailField(**options)[исходный код]
class CITextField(**options)[исходный код]

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

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

Нечувствительные к регистру коллизии

На PostgreSQL 12+ предпочтительнее использовать недетерминированные колляции вместо расширения citext. Вы можете создать их с помощью операции миграции CreateCollation. Для получения дополнительной информации смотрите Управление коллациями с помощью миграций и документацию PostgreSQL о non-deterministic collations.

HStoreField

class HStoreField(**options)[исходный код]

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

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

  1. Добавьте 'django.contrib.postgres' в ваш INSTALLED_APPS.
  2. Set up the hstore extension в PostgreSQL.

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

Примечание

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

Запрос 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>]>

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

Примечание

Ключевые преобразования также могут быть соединены в цепочку с: contains, icontains, endswith, iendswith, iexact, regex, iregex, startswith и istartswith.

Предупреждение

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

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. Эти поля используются для хранения диапазона значений; например, временные метки начала и окончания события или диапазон возрастов, для которых подходит то или иное мероприятие.

Все поля диапазона переводятся в psycopg2 Range objects в Python, но также принимают кортежи в качестве входных данных, если информация о границах не требуется. По умолчанию нижняя граница включена, верхняя исключена, то есть [) (подробности о different bounds см. в документации PostgreSQL).

IntegerRangeField

class IntegerRangeField(**options)[исходный код]

Хранит диапазон целых чисел. Основан на значении IntegerField. Представляется символом int4range в базе данных и NumericRange в Python.

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

BigIntegerRangeField

class BigIntegerRangeField(**options)[исходный код]

Хранит диапазон больших целых чисел. Основан на BigIntegerField. Представляется символом int8range в базе данных и NumericRange в Python.

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

DecimalRangeField

class DecimalRangeField(**options)[исходный код]

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

DateTimeRangeField

class DateTimeRangeField(**options)[исходный код]

Хранит диапазон временных меток. Основан на значении DateTimeField. Представляется символом tstzrange в базе данных и DateTimeTZRange в Python.

DateRangeField

class DateRangeField(**options)[исходный код]

Хранит диапазон дат. Основан на значении DateField. Представляется символом daterange в базе данных и 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 psycopg2.extras 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 psycopg2.extras 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 используют базовые классы, приведенные ниже, а psycopg2 предоставляет register_range() для разрешения использования пользовательских типов диапазонов.

class RangeField(**options)[исходный код]

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

base_field

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

range_type

Используемый тип диапазона psycopg2.

form_field

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

class django.contrib.postgres.forms.BaseRangeField

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

base_field

Поле формы, которое будет использоваться.

range_type

Используемый тип диапазона psycopg2.

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

class RangeOperators[исходный код]

PostgreSQL предоставляет набор операторов SQL, которые можно использовать вместе с типами данных range (см. the PostgreSQL documentation for the full details of range operators). Этот класс предназначен для того, чтобы избежать опечаток. Имена операторов совпадают с именами соответствующих поисков.

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. См. the PostgreSQL documentation for the full details.

Вернуться на верх