PostgreSQL 特有模型字段

PostgreSQL 特有模型字段

所有这些字段都可以从 django.contrib.postgres.field 模块中获得。

对这些字段进行索引

Index 和 Field.db_index 都创建了一个 B 树索引，在查询复杂的数据类型时并不是特别有用。像 GinIndex 和 GistIndex 这样的索引比较适合，不过索引的选择取决于你使用的查询。一般来说，GiST 可能是 range 字段 和 HStoreField 的好选择，而 GIN 可能对 ArrayField 有帮助。

ArrayField

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

一个用于存储数据列表的字段。大多数字段类型都可以使用，你可以通过另一个字段实例作为 base_field。你也可以指定一个 size。ArrayField 可以嵌套来存储多维数组。

如果你给字段一个 default，确保它是一个可调用对象，比如 list （对于一个空的默认值），或者一个返回一个列表的可调用对象（比如一个函数）。错误地使用 default=[] 会创建一个可变的默认值，这个默认值在 ArrayField 的所有实例之间共享。

  • base_field

这是一个必要的参数。

Specifies the underlying data type and behavior for the array. It should be an instance of a subclass of Field. For example, it could be an IntegerField or a CharField. Most field types are permitted, with the exception of those handling relational data (ForeignKey, OneToOneField and ManyToManyField) and file fields ( FileField and 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 目前并没有强制执行这个限制。

备注

嵌套 `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], ] )


如果需要不规则的形状，则应将底层字段设为 null，并将值用 `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`

The [contains](<https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-contains>) lookup is overridden on ArrayField. The returned objects will be those where the values passed are a subset of the data. It uses the SQL operator `@>`. For example:

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.objects.filter(tags__contains=["django"]) <QuerySet [, ]>

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


#### `contained_by`

This is the inverse of the contains lookup - the objects returned will be those where the data is a subset of the values passed. It uses the SQL operator `<@`. For example:

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.objects.filter(tags__contained_by=["thoughts", "django", "tutorial"]) <QuerySet [, , ]>


#### `overlap`

Returns objects where the data shares any results with the values passed. Uses the SQL operator `&&`. For example:

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.objects.filter(tags__overlap=["thoughts", "tutorial"]) <QuerySet [, , ]>

Post.objects.filter(tags__overlap=Post.objects.values_list("tags")) <QuerySet [, , ]>


Changed in Django 4.2:

Support for `QuerySet.values()` and `values_list()` as a right-hand side was added.

#### `len`

Returns the length of the array. The lookups available afterward are those available for [IntegerField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.IntegerField> "django.db.models.IntegerField"). For example:

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

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


#### 索引转换

Index transforms index into the array. Any non-negative integer can be used. There are no errors if it exceeds the size of the array. The lookups available after the transform are those from the base_field. For example:

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.objects.filter(tags__1__iexact="Django") <QuerySet []>

Post.objects.filter(tags__276="javascript") 


备注

PostgreSQL 在编写原始 SQL 时，对数组字段使用基于 1 的索引。然而这些索引和 slices 中使用的索引使用基于 0 的索引，以与 Python 保持一致。

#### 切片转换

Slice transforms take a slice of the array. Any two non-negative integers can be used, separated by a single underscore. The lookups available after the transform do not change. For example:

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.objects.filter(tags__0_2__contains=["thoughts"]) <QuerySet [, ]>


备注

PostgreSQL 在编写原始 SQL 时，对数组字段使用基于 1 的索引。然而这些分片和 indexes 中使用的分片使用基于 0 的索引，以与 Python 保持一致。

带索引和切片的多维数组

PostgreSQL 在多维数组上使用索引和切片时，有一些相当神秘的行为。使用索引向下到达最终的底层数据总是可行的，但是大多数其他的切片在数据库层面的行为很奇怪，不能被 Django 以逻辑的、一致的方式支持。

## `CIText` 字段

 _class_ `CIText`(_**options_)

4.2 版后已移除.

一个用于创建由 [citext](&lt;https://www.postgresql.org/docs/current/citext.html>) 类型支持的不区分大小写的文本字段的混入。在使用它之前，请阅读 [性能考虑因素](&lt;https://www.postgresql.org/docs/current/citext.html#id-1.11.7.19.9>) 。

要使用 `citext`，使用 `CITextExtension ` 操作，在第一次 ``CreateModel` ` 迁移操作之前，在 PostgreSQL 中 [安装 citext 扩展](/read/django-5.0-zh/d175.md#create-postgresql-extensions)。

如果你使用的是 ArrayField 的 `CIText` 字段，你必须在你的 [INSTALLED_APPS](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS>) 中添加 `'django.contrib.postgres'`，否则字段值会以字符串形式出现，比如 `'{thoughts,django}'`。

提供了几个使用混入的字段：

_class_ `CICharField`(_**options_)

4.2 版后已移除: `CICharField` is deprecated in favor of `CharField(db_collation="…")` with a case-insensitive non-deterministic collation.

_class_ `CIEmailField`(_**options_)

4.2 版后已移除: `CIEmailField` is deprecated in favor of `EmailField(db_collation="…")` with a case-insensitive non-deterministic collation.

_class_ `CITextField`(_**options_)

4.2 版后已移除: `CITextField` is deprecated in favor of `TextField(db_collation="…")` with a case-insensitive non-deterministic collation.

这些字段分别是 [CharField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.CharField> "django.db.models.CharField")、[EmailField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.EmailField> "django.db.models.EmailField") 和 [TextField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.TextField> "django.db.models.TextField") 的子类。

`max_length` 不会在数据库中强制执行，因为 `citext` 与 PostgreSQL 的 `text` 类型相似。

不区分大小写的字节序

It’s preferable to use non-deterministic collations instead of the `citext` extension. You can create them using the [CreateCollation](&lt;/read/django-5.0-zh/75d1f2dff2898599.md#django.contrib.postgres.operations.CreateCollation> "django.contrib.postgres.operations.CreateCollation") migration operation. For more details, see [使用迁移来管理整理](/read/django-5.0-zh/d175.md#manage-postgresql-collations) and the PostgreSQL documentation about [non-deterministic collations](&lt;https://www.postgresql.org/docs/current/collation.html#COLLATION-NONDETERMINISTIC>).

## `HStoreField`

 _class_ `HStoreField`(_**options_)

一个用于存储键值对的字段。使用的 Python 数据类型是 `dict`。键必须是字符串，值可以是字符串或空值（Python 中的 `None`）。

要使用该字段，你需要：

  1. 在你的 [INSTALLED_APPS](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/settings/#std-setting-INSTALLED_APPS>) 中增加 `'django.contrib.postgres'`。
  2. 在 PostgreSQL 中 [安装 hstore 扩展](/read/django-5.0-zh/d175.md#create-postgresql-extensions)。

如果你跳过第一步，你会看到一个错误，比如 `can't adapt type 'dict'`，如果你跳过第二步，你会看到 `type "hstore" does not exist`。

备注

在某些情况下，可能需要要求或限制对某个字段有效的键。这可以使用 [KeysValidator](&lt;/read/django-5.0-zh/8d3ed07f661c6fa8.md#django.contrib.postgres.validators.KeysValidator> "django.contrib.postgres.validators.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


#### 键查找

To query based on a given key, you can use that key as the lookup name:

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

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


You can chain other lookups after key lookups:

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


or use `F()` expressions to annotate a key value. For example:

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


如果你想查询的键与另一个查找的名称冲突，你需要使用 hstorefield.contains 查找来代替。

备注

关键词转换也可以与以下链式进行： [contains](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-contains>)、[icontains](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-icontains>)、[endswith](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-endswith>)、[iendswith](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-iendswith>)、[iexact](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-iexact>)、[regex](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-regex>)、[iregex](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-iregex>)、[startswith](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-startswith>) 和 [istartswith](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-istartswith>) 查询。

警告

由于任何字符串都可能是 hstore 值中的一个键，因此除了下面列出的以外的任何查询都将被解释为键查询。不会出现任何错误。要格外小心输入错误，并始终检查你的查询是否按照你的意图工作。

#### `contains`

The [contains](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-contains>) lookup is overridden on HStoreField. The returned objects are those where the given `dict` of key-value pairs are all contained in the field. It uses the SQL operator `@>`. For example:

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.objects.filter(data__contains={"breed": "collie"}) <QuerySet []>


#### `contained_by`

This is the inverse of the contains lookup - the objects returned will be those where the key-value pairs on the object are a subset of those in the value passed. It uses the SQL operator `<@`. For example:

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.objects.filter(data__contained_by={"breed": "collie"}) <QuerySet []>


#### `has_key`

Returns objects where the given key is in the data. Uses the SQL operator `?`. For example:

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


#### `has_any_keys`

Returns objects where any of the given keys are in the data. Uses the SQL operator `?|`. For example:

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


#### `has_keys`

Returns objects where all of the given keys are in the data. Uses the SQL operator `?&`. For example:

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


#### `keys`

Returns objects where the array of keys is the given value. Note that the order is not guaranteed to be reliable, so this transform is mainly useful for using in conjunction with lookups on ArrayField. Uses the SQL function `akeys()`. For example:

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


#### `values`

Returns objects where the array of values is the given value. Note that the order is not guaranteed to be reliable, so this transform is mainly useful for using in conjunction with lookups on ArrayField. Uses the SQL function `avals()`. For example:

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


## 范围字段

有五种范围字段类型，对应 PostgreSQL 中内置的范围类型。这些字段用来存储一个范围的值，例如一个事件的开始和结束时间戳，或者一个活动适合的年龄范围。

All of the range fields translate to [psycopg Range objects](&lt;https://www.psycopg.org/psycopg3/docs/basic/pgtypes.html#adapt-range> "\(在 psycopg\)") in Python, but also accept tuples as input if no bounds information is necessary. The default is lower bound included, upper bound excluded, that is `[)` (see the PostgreSQL documentation for details about [different bounds](&lt;https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-IO>)). The default bounds can be changed for non-discrete range fields (DateTimeRangeField and DecimalRangeField) by using the `default_bounds` argument.

### `IntegerRangeField`

 _class_ `IntegerRangeField`(_**options_)

Stores a range of integers. Based on an [IntegerField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.IntegerField> "django.db.models.IntegerField"). Represented by an `int4range` in the database and a `django.db.backends.postgresql.psycopg_any.NumericRange` in Python.

无论在保存数据时指定的边界是什么，PostgreSQL 总是以规范的形式返回一个包括下限和排除上限的范围，即 `[)`。

### `BigIntegerRangeField`

 _class_ `BigIntegerRangeField`(_**options_)

Stores a range of large integers. Based on a [BigIntegerField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.BigIntegerField> "django.db.models.BigIntegerField"). Represented by an `int8range` in the database and a `django.db.backends.postgresql.psycopg_any.NumericRange` in Python.

无论在保存数据时指定的边界是什么，PostgreSQL 总是以规范的形式返回一个包括下限和排除上限的范围，即 `[)`。

### `DecimalRangeField`

 _class_ `DecimalRangeField`(_default_bounds=’[)’_ , _**options_)

Stores a range of floating point values. Based on a [DecimalField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.DecimalField> "django.db.models.DecimalField"). Represented by a `numrange` in the database and a `django.db.backends.postgresql.psycopg_any.NumericRange` in Python.

  * `default_bounds`

Optional. The value of `bounds` for list and tuple inputs. The default is lower bound included, upper bound excluded, that is `[)` (see the PostgreSQL documentation for details about [different bounds](&lt;https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-IO>)). `default_bounds` is not used for `django.db.backends.postgresql.psycopg_any.NumericRange` inputs.

### `DateTimeRangeField`

 _class_ `DateTimeRangeField`(_default_bounds=’[)’_ , _**options_)

Stores a range of timestamps. Based on a [DateTimeField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.DateTimeField> "django.db.models.DateTimeField"). Represented by a `tstzrange` in the database and a `django.db.backends.postgresql.psycopg_any.DateTimeTZRange` in Python.

  * `default_bounds`

Optional. The value of `bounds` for list and tuple inputs. The default is lower bound included, upper bound excluded, that is `[)` (see the PostgreSQL documentation for details about [different bounds](&lt;https://www.postgresql.org/docs/current/rangetypes.html#RANGETYPES-IO>)). `default_bounds` is not used for `django.db.backends.postgresql.psycopg_any.DateTimeTZRange` inputs.

### `DateRangeField`

 _class_ `DateRangeField`(_**options_)

Stores a range of dates. Based on a [DateField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.DateField> "django.db.models.DateField"). Represented by a `daterange` in the database and a `django.db.backends.postgresql.psycopg_any.DateRange` in 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


We will also use the following example objects:

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


##### `contained_by`

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


The `contained_by` lookup is also available on the non-range field types: [SmallAutoField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.SmallAutoField> "django.db.models.SmallAutoField"), [AutoField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.AutoField> "django.db.models.AutoField"), [BigAutoField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.BigAutoField> "django.db.models.BigAutoField"), [SmallIntegerField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.SmallIntegerField> "django.db.models.SmallIntegerField"), [IntegerField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.IntegerField> "django.db.models.IntegerField"), [BigIntegerField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.BigIntegerField> "django.db.models.BigIntegerField"), [DecimalField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.DecimalField> "django.db.models.DecimalField"), [FloatField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.FloatField> "django.db.models.FloatField"), [DateField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.DateField> "django.db.models.DateField"), and [DateTimeField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.DateTimeField> "django.db.models.DateTimeField"). For example:

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


##### `overlap`

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


#### 比较函数

范围字段支持标准查询：[lt](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-lt>)、[gt](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-gt>)、[lte](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-lte>) 和 [gte](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/querysets/#std-fieldlookup-gte>)。这些并没有特别大的帮助——它们先比较下界，然后在必要时才比较上界。这也是用于按范围字段排序的策略。最好是使用特定的范围比较运算符。

##### `fully_lt`

返回的范围严格小于传入的范围。换句话说，返回范围内的所有点都小于传入范围内的所有点。

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


##### `fully_gt`

返回的范围严格大于传入的范围。换句话说，返回范围内的所有点都大于传入范围内的所有点。

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


##### `not_lt`

返回的范围不包含任何小于传入范围的点，即返回范围的下界至少是传入范围的下界。

Event.objects.filter(ages__not_lt=NumericRange(0, 15)) <QuerySet [, ]>


##### `not_gt`

返回的范围不包含任何大于传入范围的点，也就是说，返回的范围的上界最多就是传入范围的上界。

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


##### `adjacent_to`

返回的范围与传入的范围共享一个边界。

Event.objects.filter(ages__adjacent_to=NumericRange(10, 21)) <QuerySet [, ]>


#### 使用边界进行查询

范围字段支持几个额外的查找。

##### `startswith`

返回的对象具有给定的下界。可以链入基础字段的有效查找。

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


##### `endswith`

返回的对象具有给定的上界。可以链入基础字段的有效查找。

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


##### `isempty`

返回的对象是空的范围。可以链到有效的查找 [BooleanField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.BooleanField> "django.db.models.BooleanField")。

Event.objects.filter(ages__isempty=True) 


##### `lower_inc`

根据传递的布尔值，返回具有包含或不包含下界的对象。可以链到有效的查找 [BooleanField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.BooleanField> "django.db.models.BooleanField") 的对象。

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


##### `lower_inf`

根据传递的布尔值，返回具有无界（无限）或仅有下界的对象。可以链到有效的查找 [BooleanField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.BooleanField> "django.db.models.BooleanField")。

Event.objects.filter(ages__lower_inf=True) 


##### `upper_inc`

根据传递的布尔值，返回具有包含或不包含上界的对象。可以链到有效的查找 [BooleanField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.BooleanField> "django.db.models.BooleanField") 的对象。

Event.objects.filter(ages__upper_inc=True) 


##### `upper_inf`

根据传递的布尔值，返回具有无界（无限）或仅有上界的对象。可以链到有效的查找 [BooleanField](&lt;https://docs.djangoproject.com/zh-hans/5.0/ref/models/fields/#django.db.models.BooleanField> "django.db.models.BooleanField")。

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


### 定义自己的范围类型

PostgreSQL allows the definition of custom range types. Django’s model and form field implementations use base classes below, and `psycopg` provides a [register_range()](&lt;https://www.psycopg.org/psycopg3/docs/basic/pgtypes.html#psycopg.types.range.register_range> "\(在 psycopg\)") to allow use of custom range types.

_class_ `RangeField`(_**options_)

模型范围字段的基类。

  * `base_field`

要使用的模型字段类。

  * `range_type`

The range type to use.

  * `form_field`

要使用的表单字段类。应该是 django.contrib.postgres.forms.BaseRangeField 的子类。

_class_ `django.contrib.postgres.forms.BaseRangeField`

表范围字段的基类。

  * `base_field`

要使用的表字段。

  * `range_type`

The range type to use.

### 范围操作

 _class_ `RangeOperators`

PostgreSQL 提供了一组 SQL 运算符，这些运算符可以和范围数据类型一起使用（参见 `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_ 。