Поля модели, специфичные для 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).

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

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

Преобразования индексов индексируют массив. Можно использовать любые неотрицательные целые числа. Нет ошибок, если индекс выходит за пределы 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)

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

Для использования citext, используйте операцию CITextExtension для настройки расширения citext в 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 ведет себя аналогично типу text в PostgreSQL.

HStoreField

class HStoreField(**options)

Поле для хранения пар ключ-значение. Используемый в Python тип данных — dict. Ключи должны быть строками, а значения могут быть строками или нулевыми значениями (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>]>

Если ключ, по которому вы хотите выполнить поиск, совпадает с именем другого поиска, используйте поиск 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>]>

JSONField

class JSONField(encoder=None, **options)

Поле для хранения данных в формате JSON. В Python данные представлены в их родном формате: словари, списки, строки, числа, булевы значения и None.

encoder

Необязательный класс кодирования JSON для сериализации типов данных, не поддерживаемых стандартным сериализатором JSON (datetime, uuid, и т.д.). Например, вы можете использовать класс DjangoJSONEncoder или любой другой подкласс json.JSONEncoder.

При получении значения из базы данных оно будет в формате, выбранном пользовательским кодировщиком (чаще всего строка), поэтому вам понадобятся дополнительные шаги для преобразования значения обратно в исходный тип данных (Model.from_db() и Field.from_db_value() — два возможных крючка для этой цели). Ваша десериализация может потребовать учитывать тот факт, что вы не можете быть уверены в типе входных данных. Например, вы рискуете получить datetime , который фактически был строкой, которая просто оказалась в том же формате, что и datetime.

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

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

См. Запросы к полю JSONField для получения подробностей.

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

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

Все поля диапазонов преобразуются в объекты диапазона psycopg2 в Python, но также принимают кортежи в качестве входных данных, если информация о границах не требуется. Значение по умолчанию — включение нижней границы и исключение верхней, то есть [) (см. документацию 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 операторов, которые могут быть использованы вместе с типами данных диапазонов (см. документацию 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 для получения полной информации.