PostgreSQL 特定模型字段 — Django 文档
PostgreSQL 特定模型字段
所有这些字段都可以从 django.contrib.postgres.fields
模块获得。
索引这些字段
Index 和 Field.db_index 都创建了 B 树索引,这在查询复杂数据类型时不是特别有用。 GinIndex 和 GistIndex 等索引更适合,尽管索引选择取决于您使用的查询。 通常,对于 范围字段 和 HStoreField,GiST 可能是一个不错的选择,而 GIN 可能对 ArrayField 有帮助。
ArrayField
- class ArrayField(base_field, size=None, **options)
用于存储数据列表的字段。 大多数字段类型都可以使用,并且您将另一个字段实例作为 base_field 传递。 您还可以指定 大小 。
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
:lookup:`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
这是相反的 :lookup:`包含 ` 查找 - 返回的对象将是那些数据是传递值的子集的对象。 它使用 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>]>
索引转换
索引将索引转换为数组。 可以使用任何非负整数。 如果超过数组的 大小 ,则没有错误。 转换后可用的查找来自 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>]>
带有索引和切片的多维数组
在多维数组上使用索引和切片时,PostgreSQL 有一些相当深奥的行为。 使用索引来深入到最终的底层数据总是有效的,但大多数其他切片在数据库级别的行为很奇怪,并且无法以逻辑一致的方式被 Django 支持。
CIText 字段
- class CIText(**options)
创建由 citext 类型支持的不区分大小写的文本字段的 mixin。 在使用之前阅读 性能注意事项 。
要使用
citext
,在第一次CreateModel
迁移操作之前,使用CITextExtension操作在PostgreSQL中设置citext扩展。如果您使用
CIText
字段的 ArrayField,则必须在 :setting:`INSTALLED_APPS` 中添加'django.contrib.postgres'
,否则字段值将显示为类似'{thoughts,django}'
的字符串。提供了几个使用 mixin 的字段:
- class CICharField(**options)
- class CIEmailField(**options)
- class CITextField(**options)
这些字段分别是 CharField、EmailField 和 TextField 的子类。
max_length
不会在数据库中强制执行,因为citext
的行为类似于 PostgreSQL 的text
类型。
不区分大小写的排序规则
在 PostgreSQL 12+ 上,最好使用非确定性排序规则而不是 citext
扩展。 您可以使用 CreateCollation 迁移操作创建它们。 有关更多详细信息,请参阅 Managing collations using migrations 和关于 non-deterministic collations 的 PostgreSQL 文档。
HStoreField
- class HStoreField(**options)
用于存储键值对的字段。 使用的 Python 数据类型是
dict
。 键必须是字符串,值可以是字符串或空值(Python 中的None
)。要使用此字段,您需要:
在您的 :setting:`INSTALLED_APPS` 中添加
'django.contrib.postgres'
。
如果您跳过第一步,您将看到类似
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>]>
如果您希望查询的键与另一个查找的名称发生冲突,您需要改用 :lookup:`hstorefield.contains` 查找。
笔记
键转换也可以链接到::lookup:`contains`, :lookup:`icontains`, :lookup:`endswith`, :lookup:`iendswith`, :lookup:`iexact`, :lookup:`regex`, :lookup:`iregex`, [ X239X]:lookup:`startswith` 和 :lookup:`istartswith` 查找。
警告
由于任何字符串都可以是 hstore 值中的键,因此除下面列出的那些之外的任何查找都将被解释为键查找。 没有错误被提出。 输入错误时要格外小心,并始终检查您的查询是否按预期工作。
contains
:lookup:`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
这是相反的 :lookup:`包含 ` 查找 - 返回的对象将是那些对象上的键值对是传递值中键值对的子集的对象。 它使用 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 中,数据以其 Python 原生格式表示:字典、列表、字符串、数字、布尔值和
None
。- encoder
一个可选的 JSON 编码类,用于序列化标准 JSON 序列化程序(
datetime
、uuid
等)不支持的数据类型。 例如,您可以使用 DjangoJSONEncoder 类或任何其他json.JSONEncoder
子类。从数据库中检索值时,它将采用自定义编码器选择的格式(通常是字符串),因此您需要采取额外的步骤将值转换回初始数据类型 ( Model.from_db() 和 Field.from_db_value() 是用于此目的的两个可能的钩子)。 您的反序列化可能需要考虑到您无法确定输入类型的事实。 例如,您冒着返回
datetime
的风险,该字符串实际上是一个恰好与为datetime
选择的格式相同的字符串。
如果你给这个字段一个 default,确保它是一个可调用的,比如
dict
(对于一个空的默认值)或一个返回一个字典的可调用的(比如一个函数)。 不正确地使用default={}
会创建一个可变默认值,该默认值在JSONField
的所有实例之间共享。
笔记
PostgreSQL 有两种基于 JSON 的原生数据类型:json
和 jsonb
。 它们之间的主要区别在于它们的存储方式和查询方式。 PostgreSQL 的 json
字段存储为 JSON 的原始字符串表示形式,并且必须在基于键查询时即时解码。 jsonb
字段基于允许索引的 JSON 的实际结构进行存储。 权衡是写入 jsonb
字段的少量额外成本。 JSONField
使用 jsonb
。
自 3.1 版起已弃用: 改用 django.db.models.JSONField。
范围字段
有五种范围字段类型,对应于 PostgreSQL 中内置的范围类型。 这些字段用于存储一系列值; 例如事件的开始和结束时间戳,或活动适合的年龄范围。
在 Python 中,所有范围字段都转换为 psycopg2 范围对象 ,但如果不需要边界信息,也可以接受元组作为输入。 默认为包含下限,不包含上限,即 [)
(有关 不同边界 的详细信息,请参阅 PostgreSQL 文档)。
IntegerRangeField
- class IntegerRangeField(**options)
存储一系列整数。 基于 IntegerField。 由数据库中的
int4range
和 Python 中的NumericRange
表示。无论保存数据时指定的边界如何,PostgreSQL 总是以规范形式返回一个范围,该范围包括下限不包括上限,即
[)
。
BigIntegerRangeField
- class BigIntegerRangeField(**options)
存储一系列大整数。 基于 BigIntegerField。 由数据库中的
int8range
和 Python 中的NumericRange
表示。无论保存数据时指定的边界如何,PostgreSQL 总是以规范形式返回一个范围,该范围包括下限不包括上限,即
[)
。
DecimalRangeField
- class DecimalRangeField(**options)
- 存储一系列浮点值。 基于 DecimalField。 由数据库中的
numrange
和 Python 中的NumericRange
表示。
DateTimeRangeField
- class DateTimeRangeField(**options)
- 存储一系列时间戳。 基于 DateTimeField。 由数据库中的
tstzrange
和 Python 中的DateTimeTZRange
表示。
DateRangeField
- class DateRangeField(**options)
存储一系列日期。 基于 DateField。 由数据库中的
daterange
和 Python 中的DateRange
表示。无论保存数据时指定的边界如何,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和[X20TimeField] 例如:
>>> 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>]>
3.1 版更改: 支持 SmallAutoField、AutoField、BigAutoField、SmallIntegerField 和 [X1malFieldX]添加了 。
overlap
>>> Event.objects.filter(ages__overlap=NumericRange(8, 12))
<QuerySet [<Event: Soft play>]>
比较功能
范围字段支持标准查找: :lookup:`lt`、:lookup:`gt`、:lookup:`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
3.1 版中的新功能。
返回具有包含或不包含下限的对象,具体取决于传递的布尔值。 可以链接到 BooleanField 的有效查找。
>>> Event.objects.filter(ages__lower_inc=True)
<QuerySet [<Event: Soft play>, <Event: Pub trip>]>
lower_inf
3.1 版中的新功能。
返回具有无界(无限)或有界下界的对象,具体取决于传递的布尔值。 可以链接到 BooleanField 的有效查找。
>>> Event.objects.filter(ages__lower_inf=True)
<QuerySet []>
upper_inc
3.1 版中的新功能。
返回具有包含或不包含上限的对象,具体取决于传递的布尔值。 可以链接到 BooleanField 的有效查找。
>>> Event.objects.filter(ages__upper_inc=True)
<QuerySet []>
upper_inf
3.1 版中的新功能。
返回具有无界(无限)或有界上限的对象,具体取决于传递的布尔值。 可以链接到 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 文档 。