Django数据库-字段类型

AutoField¶

类AutoField（** options）¶

会IntegerField根据可用ID自动递增。您通常不需要直接使用它；如果没有另外指定，主键字段将自动添加到模型中。请参阅自动主键字段。

BigAutoField¶

类BigAutoField（** options）¶

一个64位整数，非常类似于，AutoField不同之处在于它保证可以匹配从1到的数字9223372036854775807。

BigIntegerField¶

类BigIntegerField（** options）¶

一个64位整数，非常类似于，IntegerField不同之处在于它保证可以匹配从-9223372036854775808到的 数字9223372036854775807。此字段的默认表单窗口小部件是 NumberInput。

BinaryField¶

类BinaryField（max_length = None，** options）¶

一个用于存储原始二进制数据的字段。它可以分配bytes， bytearray或memoryview。

默认情况下，BinaryField设置editable为False，在这种情况下，它不能包含在中ModelForm。

BinaryField 有一个额外的可选参数：BinaryField.max_length¶

字段的最大长度（以字符为单位）。最大长度是在Django的验证中使用强制执行的 MaxLengthValidator。

滥用 BinaryField

尽管您可能会考虑将文件存储在数据库中，但在99％的情况下，请考虑这样做是不好的设计。此字段不能代替适当的静态文件处理。

BooleanField¶

类BooleanField（** options）¶

正确/错误字段。

窗口小部件此字段的默认形式CheckboxInput，或者NullBooleanSelect如果null=True。

默认值BooleanField是None当Field.default 没有定义。

CharField¶

类CharField（max_length = None，** options）¶

字符串字段，从小到大的字符串。

对于大量文本，请使用TextField。

此字段的默认表单窗口小部件是TextInput。

CharField 有一个额外的必需参数：CharField.max_length¶

字段的最大长度（以字符为单位）。max_length在数据库级别和Django的验证中使用强制执行 MaxLengthValidator。

注意

如果编写的应用程序必须可移植到多个数据库后端，则应注意max_length某些后端存在限制 。有关详细信息，请参考数据库后端说明。

DateField¶

类DateField（auto_now = False，auto_now_add = False，** options）¶

日期，在Python中由datetime.date实例表示。有一些额外的可选参数：DateField.auto_now¶

每次保存对象时自动将字段设置为现在。对于“最后修改的”时间戳有用。请注意，始终 使用当前日期。它不仅是您可以覆盖的默认值。

该字段仅在调用时自动更新Model.save()。以其他方式（例如）对其他字段进行更新时，该字段不会更新QuerySet.update()，尽管您可以在更新中为该字段指定自定义值。DateField.auto_now_add¶

首次创建对象时，将字段自动设置为现在。对于创建时间戳很有用。请注意，始终使用当前日期。它不仅是您可以覆盖的默认值。因此，即使您在创建对象时为此字段设置了一个值，也会将其忽略。如果您希望能够修改此字段，请设置以下内容，而不是 auto_now_add=True：

• 于DateField：default=date.today-从 datetime.date.today()
• 于DateTimeField：default=timezone.now-从 django.utils.timezone.now()

此字段的默认表单窗口小部件是 DateInput。管理员添加了JavaScript日历和“今天”的快捷方式。包括一个附加的invalid_date错误消息键。

选项auto_now_add，auto_now和default是互斥的。这些选项的任何组合都将导致错误。

注意

当前实现，设置auto_now或auto_now_add以 True会导致该领域拥有editable=False和blank=True 集。

注意

在auto_now和auto_now_add选项将始终使用的日期默认时区在创建或更新的时刻。如果您需要其他内容，则可能需要考虑使用自己的可调用默认值或替代值，save()而不是使用auto_now或auto_now_add；或使用aDateTimeField 代替aDateField并决定如何处理显示时间从datetime到date的转换。

DateTimeField¶

类DateTimeField（auto_now = False，auto_now_add = False，** options）¶

日期和时间，在Python中以datetime.datetime实例表示。接受与相同的额外参数DateField。

此字段的默认表单窗口小部件为单个 DateTimeInput。管理员使用TextInput带有JavaScript快捷方式的两个单独的 小部件。

DecimalField¶

类DecimalField（max_digits =无，decimal_places =无，**选项）¶

固定精度的十进制数字，在Python中由 Decimal实例表示。它使用验证输入 DecimalValidator。

有两个必需的参数：DecimalField.max_digits¶

数字中允许的最大位数。请注意，此数字必须大于或等于decimal_places。DecimalField.decimal_places¶

用数字存储的小数位数。

例如，要存储最大999分辨率为两位小数的数字，可以使用：

models.DecimalField(..., max_digits=5, decimal_places=2)

并以十位小数位的分辨率存储最多约十亿的数字：

models.DecimalField(..., max_digits=19, decimal_places=10)

此字段的默认表单窗口小部件为NumberInput when localizeisFalse或 TextInput其他方式。

注意

有关FloatField和DecimalField类之间的区别的更多信息 ，请参见FloatField与DecimalField。您还应该注意SQLite 对十进制字段的限制。

DurationField¶

类DurationField（** options）¶

一个用于存储时间的字段-用Python在Python中建模 timedelta。在PostgreSQL上使用时，使用的数据类型为interval，在Oracle上使用为。否则，将使用a微秒。INTERVAL DAY(9) TO SECOND(6)bigint

注意

DurationField在大多数情况下都可以算术运算。但是，在除PostgreSQL以外的所有数据库上，将a的值与实例DurationField 上的算术进行比较DateTimeField将无法按预期进行。

EmailField¶

类EmailField（max_length = 254，** options）¶

使用CharField来检查该值是否是有效的电子邮件地址的 EmailValidator。

FileField¶

类FileField（upload_to = None，max_length = 100，** options）¶

文件上传字段。

注意

primary_key不支持该参数，如果使用该参数将引发错误。

有两个可选参数：FileField.upload_to¶

此属性提供了一种设置上传目录和文件名的方法，并且可以通过两种方法进行设置。在两种情况下，该值都将传递给该 Storage.save()方法。

如果您指定一个字符串值或Path，则它可能包含 strftime()格式，该格式将被文件上传的日期/时间替换（以使上传的文件不会填满给定的目录）。例如：

class MyModel(models.Model):
    # file will be uploaded to MEDIA_ROOT/uploads
    upload = models.FileField(upload_to='uploads/')
    # or...
    # file will be saved to MEDIA_ROOT/uploads/2015/01/30
    upload = models.FileField(upload_to='uploads/%Y/%m/%d/')

如果使用默认值 FileSystemStorage，则将字符串值添加到MEDIA_ROOT路径中，以形成本地文件系统上将存储上载文件的位置。如果您使用其他存储，请查看该存储的文档以了解其处理方式upload_to。

upload_to也可以是可调用的，例如函数。这将被调用以获得上载路径，包括文件名。该可调用对象必须接受两个参数，并返回要传递给存储系统的Unix样式的路径（带有正斜杠）。这两个参数是：

例如：

def user_directory_path(instance, filename):
    # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
    return 'user_{0}/{1}'.format(instance.user.id, filename)

class MyModel(models.Model):
    upload = models.FileField(upload_to=user_directory_path)

在Django 3.0中进行了更改：

支持pathlib.Path增加了。FileField.storage¶

存储对象或返回存储对象的可调用对象。这可以处理文件的存储和检索。有关 如何提供此对象的详细信息，请参阅管理文件。在Django 3.1中进行了更改：

提供了可调用的功能。

此字段的默认表单窗口小部件是 ClearableFileInput。

在模型中使用FileField或ImageField（请参见下文）需要执行几个步骤：

1. 在设置文件中，您需要将目录定义MEDIA_ROOT为Django希望用来存储上载文件的目录的完整路径。（为了提高性能，这些文件未存储在数据库中。）定义 MEDIA_URL为该目录的基本公共URL。确保该目录可由Web服务器的用户帐户写入。
2. 将FileField或添加ImageField到模型中，定义upload_to用于指定MEDIA_ROOT要用于上载文件的子目录的选项 。
3. 将存储在数据库中的所有文件都是该文件的路径（相对于MEDIA_ROOT）。您很可能想使用urlDjango提供的便捷属性。例如，如果ImageField调用了 your，则mug_shot可以使用来获取模板中图像的绝对路径 。{{ object.mug_shot.url }}

例如，假设您MEDIA_ROOT的设置为'/home/media'，并且 upload_to设置为'photos/%Y/%m/%d'。所述'%Y/%m/%d' 的部分upload_to就是strftime()格式化; '%Y'是四位数的年份，'%m'是两位数的月份，'%d'是两位数的日期。如果您在2007年1月15日上传文件，该文件将保存在目录中/home/media/photos/2007/01/15。

如果要检索上载文件的磁盘上文件名或文件大小，可以分别使用name和 size属性。有关可用属性和方法的更多信息，请参见 File类参考和“管理文件” 主题指南。

注意

该文件被保存为在数据库中保存模型的一部分，因此，在保存模型之前，不能依赖磁盘上使用的实际文件名。

可以使用url属性获取上载文件的相对URL 。在内部，这将调用url()基础Storage类的方法。

请注意，每当处理上传的文件时，都应密切注意上传文件的位置以及文件的类型，以免出现安全漏洞。验证所有上载的文件，以确保文件符合您的想法。例如，如果您盲目地让某人未经验证将文件上传到Web服务器文档根目录中的目录，那么某人可以上传CGI或PHP脚本并通过访问您站点上的URL来执行该脚本。不要这样

还要注意，即使上传的HTML文件也可以由浏览器执行（尽管不能由服务器执行），它也可能构成等同于XSS或CSRF攻击的安全威胁。

FileField实例在数据库中创建为varchar 列，默认最大长度为100个字符。与其他字段一样，您可以使用max_length参数更改最大长度。

FileField和FieldFile¶

类FieldFile¶

当您FileField在模型上访问时，系统会为您提供实例，FieldFile作为代理来访问基础文件。

的APIFieldFile反映了的API File，但有一个主要区别：类包装的对象不一定是Python内置文件对象的包装。相反，它是Storage.open() 方法结果的包装，它可以是File对象，也可以是FileAPI的自定义存储的实现。

除了从File诸如 read()和继承的API之外write()，FieldFile还包括几种可用于与基础文件进行交互的方法：

警告

此类save()和的 两种方法delete()默认将关联的模型对象保存FieldFile在数据库中。FieldFile.name¶

文件名，包括从Storage关联 根目录到根目录的相对路径 FileField。FieldFile.size¶

基础Storage.size()方法的结果。FieldFile.url¶

一个只读属性，通过调用url()基础Storage类的方法 来访问文件的相对URL 。FieldFile.open（mode =’rb’）¶

在指定的中打开或重新打开与此实例关联的文件 mode。与标准的Pythonopen()方法不同，它不返回文件描述符。

由于在访问基础文件时会隐式打开该文件，因此可能无需调用此方法，除非将指针重置为基础文件或更改mode。FieldFile.close（）¶

行为类似于标准的Pythonfile.close()方法，并关闭与此实例关联的文件。FieldFile.save（name，content，save = True）¶

此方法采用文件名和文件内容，并将它们传递到该字段的存储类，然后将存储的文件与model字段关联。如果要手动将文件数据与FileField模型上的实例关联 ，save() 则使用该方法来保留该文件数据。

接受两个必需的参数：name这是文件的名称，和 content是包含文件内容的对象。可选save参数控制在更改与该字段关联的文件之后是否保存模型实例。默认为 True。

请注意，该content参数应该是的实例 django.core.files.File，而不是Python的内置文件对象。您可以File像这样从现有的Python文件对象构造一个：

from django.core.files import File
# Open an existing file using Python's built-in open()
f = open('/path/to/hello.world')
myfile = File(f)

或者，您可以像这样从Python字符串构造一个：

from django.core.files.base import ContentFile
myfile = ContentFile("hello world")

有关更多信息，请参阅管理文件。FieldFile.delete（save = True）¶

删除与此实例关联的文件，并清除该字段上的所有属性。注意：如果在delete()调用时碰巧打开了文件，此方法将关闭文件 。

可选save参数控制在删除与该字段关联的文件之后是否保存模型实例。默认为 True。

请注意，删除模型时，不会删除相关文件。如果需要清理孤立的文件，则需要自己处理（例如，使用可手动运行或计划通过cron定期运行的自定义管理命令）。

FilePathField¶

classFilePathField（path =”，match = None，递归= False，allow_files = True，allow_folders = False，max_length = 100，** options）¶

ACharField的选择仅限于文件系统上某个目录中的文件名。有一些特殊的参数，其中第一个是 必需的：FilePathField.path¶

需要。目录的绝对文件系统路径，从中可以FilePathField选择该目录 。范例："/home/images"。

path也可以是可调用的，例如在运行时动态设置路径的函数。例：

import os
from django.conf import settings
from django.db import models

def images_path():
    return os.path.join(settings.LOCAL_FILE_DIR, 'images')

class MyModel(models.Model):
    file = models.FilePathField(path=images_path)

在Django 3.0中进行了更改：

path 现在可以被调用了。FilePathField.match¶

可选的。作为字符串的正则表达式，FilePathField 将用于过滤文件名。请注意，正则表达式将应用于基本文件名，而不是完整路径。示例："foo.*\.txt$"，它将匹配名为，foo23.txt但不匹配bar.txt或的文件foo23.png。FilePathField.recursive¶

可选的。无论是True或False。默认值为False。指定是否path应包含的所有子目录FilePathField.allow_files¶

可选的。无论是True或False。默认值为True。指定是否应包含指定位置的文件。要么allow_folders必须是要么 True。FilePathField.allow_folders¶

可选的。无论是True或False。默认值为False。指定是否应包含指定位置的文件夹。要么allow_files必须是要么True。

一个潜在的陷阱是match适用于基本文件名，而不是完整路径。因此，此示例：

FilePathField(path="/home/images", match="foo.*", recursive=True)

…将匹配，/home/images/foo.png但不匹配，/home/images/foo/bar.png 因为match应用于基本文件名（foo.png和bar.png）。

FilePathField实例在数据库中创建为varchar 列，默认最大长度为100个字符。与其他字段一样，您可以使用max_length参数更改最大长度。

FloatField¶

类FloatField（** options）¶

在Python中由float实例表示的浮点数。

此字段的默认表单窗口小部件为NumberInput when localizeisFalse或 TextInput其他方式。

FloatField 与 DecimalField

该FloatField班有时夹杂了 DecimalField阶级。尽管它们均表示实数，但它们以不同的方式表示这些数字。FloatField在float 内部使用Python的类型，而在内部DecimalField使用Python的Decimal类型。有关两者之间区别的信息，请参见该decimal模块的Python文档。

ImageField¶

类ImageField（upload_to = None，height_field = None，width_field = None，max_length = 100，** options）¶

从继承所有属性和方法FileField，还验证上载的对象是有效的图像。

除了可用于特殊属性FileField，一个ImageField也具有height和width属性。

为了方便查询这些属性，ImageField有两个额外的可选参数：ImageField.height_field¶

每次保存模型实例时，模型字段的名称都会自动填充图像的高度。ImageField.width_field¶

每次保存模型实例时，模型字段的名称都会自动填充图像的宽度。

需要枕头库。

ImageField实例在数据库中创建为varchar 列，默认最大长度为100个字符。与其他字段一样，您可以使用max_length参数更改最大长度。

此字段的默认表单窗口小部件是 ClearableFileInput。

IntegerField¶

类IntegerField（** options）¶

一个整数。从-2147483648到的值2147483647在Django支持的所有数据库中都是安全的。

它使用MinValueValidator并 MaxValueValidator根据默认数据库支持的值来验证输入。

此字段的默认表单窗口小部件为NumberInput when localizeisFalse或 TextInput其他方式。

GenericIPAddressField¶

类GenericIPAddressField（protocol =’both’，unpack_ipv4 = False，** options）¶

字符串格式的IPv4或IPv6地址（例如192.0.2.30或 2a02:42fe::4）。此字段的默认表单窗口小部件是 TextInput。

IPv6地址规范化如下 RFC 4291＃section-2.2第2.2节，包括使用该节第3段中建议的IPv4格式，例如 ::ffff:192.0.2.0。例如，2001:0::0:01将被标准化为 2001::1，并::ffff:0a0a:0a0a到::ffff:10.10.10.10。所有字符均转换为小写。GenericIPAddressField.protocol¶

将有效输入限制为指定的协议。可接受的值为'both'（默认值）'IPv4' 或'IPv6'。匹配不区分大小写。GenericIPAddressField.unpack_ipv4¶

解压缩IPv4映射的地址，例如::ffff:192.0.2.1。如果启用此选项，则该地址将被解压缩到 192.0.2.1。默认设置为禁用。仅当protocol设置为时可以使用'both'。

如果允许空白值，则必须允许空值，因为空白值存储为空值。

JSONField¶

类JSONField（编码器=无，解码器=无，**选项）¶Django 3.1的新功能。

用于存储JSON编码数据的字段。在Python中，数据以其Python原生格式表示：字典，列表，字符串，数字，布尔值和 None。

JSONFieldMariaDB 10.2.7 +，MySQL 5.7.8 +，Oracle，PostgreSQL和SQLite 3.9.0+（已启用JSON1扩展）受支持。JSONField.encoder¶

一个可选的json.JSONEncoder子类，用于序列化标准JSON序列化器（例如datetime.datetime 或UUID）不支持的数据类型。例如，您可以使用 DjangoJSONEncoder该类。

默认为json.JSONEncoder。JSONField.decoder¶

一个可选的json.JSONDecoder子类，用于反序列化从数据库检索的值。该值将采用自定义编码器选择的格式（通常是字符串）。反序列化可能需要考虑以下事实：您不确定输入类型。例如，您冒着返回datetime实际上只是一个为datetimes选择的相同格式的字符串的 a的风险。

默认为json.JSONDecoder。

如果您给字段a default，请确保它是一个不变的对象（例如）str，或者是每次都返回一个新的可变对象的可调用对象（例如dict或函数）。提供像一个可变的默认对象default={}或default=[]所有股份模型实例之间的一个对象。

要JSONField在数据库中查询，请参阅查询JSONField。

索引编制

Index并且Field.db_index既创建一个B树索引，这是没有特别有用的，当查询JSONField。仅在PostgreSQL上，您可以使用 GinIndex更合适的方法。

PostgreSQL用户

PostgreSQL有两种基于JSON的本地数据类型：json和jsonb。它们之间的主要区别是它们的存储方式和查询方式。PostgreSQL的json字段存储为JSON的原始字符串表示形式，并且在基于键查询时必须即时对其进行解码。该jsonb字段是根据允许进行索引的JSON的实际结构存储的。权衡是写入jsonb现场的少量额外费用。JSONField用途jsonb。

Oracle用户

Oracle数据库不支持存储JSON标量值。仅支持JSON对象和数组（在Python中使用dict和 表示list）。

NullBooleanField¶

类NullBooleanField（** options）¶

就像BooleanField用null=True。

自版本3.1起不推荐使用：NullBooleanField不推荐使用BooleanField(null=True)。

PositiveBigIntegerField¶

类PositiveBigIntegerField（** options）¶Django 3.1的新功能。

类似于PositiveIntegerField，但仅允许在特定点（与数据库有关）下的值。从0到的值9223372036854775807在Django支持的所有数据库中都是安全的。

PositiveIntegerField¶

类PositiveIntegerField（** options）¶

类似于IntegerField，但必须为正数或零（0）。从0到的值2147483647在Django支持的所有数据库中都是安全的。0出于向后兼容的原因而接受该值。

PositiveSmallIntegerField¶

类PositiveSmallIntegerField（** options）¶

类似于PositiveIntegerField，但仅允许在特定点（与数据库有关）下的值。从0到的值32767在Django支持的所有数据库中都是安全的。

SlugField¶

类SlugField（max_length = 50，** options）¶

Slug是一个报纸术语。子弹是某事物的简短标签，仅包含字母，数字，下划线或连字符。它们通常在URL中使用。

像CharField一样，您可以指定max_length（也请阅读有关数据库可移植性的说明，并max_length在该部分中）。如果max_length未指定，则Django将使用默认长度50。

表示设置Field.db_index为True。

根据其他值自动预填充SlugField通常很有用。您可以使用在管理员中自动执行此操作 prepopulated_fields。

它使用validate_slug或 validate_unicode_slug进行验证。SlugField.allow_unicode¶

如果为True，则该字段除了接受ASCII字母外，还接受Unicode字母。默认为False。

SmallAutoField¶

类SmallAutoField（** options）¶Django 3.0的新功能。

类似于AutoField，但仅允许值低于特定（与数据库有关）的限制。从1到的值32767在Django支持的所有数据库中都是安全的。

SmallIntegerField¶

类SmallIntegerField（** options）¶

类似于IntegerField，但仅允许在特定点（与数据库有关）下的值。从-32768到的值32767在Django支持的所有数据库中都是安全的。

TextField¶

类TextField（** options）¶

大文本字段。此字段的默认表单窗口小部件是 Textarea。

如果指定max_length属性，它将反映在Textarea自动生成的表单字段的 小部件中。但是，它不是在模型或数据库级别强制执行的。使用 CharField了点。

TimeField¶

类TimeField（auto_now = False，auto_now_add = False，** options）¶

时间，在Python中以datetime.time实例表示。接受与相同的自动填充选项DateField。

此字段的默认表单窗口小部件是TimeInput。管理员添加了一些JavaScript快捷方式。

URLField¶

类URLField（max_length = 200，** options）¶

一个CharField一个URL，通过验证 URLValidator。

此字段的默认表单窗口小部件是URLInput。

像所有CharField子类一样，URLField采用可选 max_length参数。如果未指定 max_length，则使用默认值200。

UUIDField¶

类UUIDField（** options）¶

用于存储通用唯一标识符的字段。使用Python的 UUID类。在PostgreSQL上使用时，它存储在uuid数据类型中，否则存储在 中char(32)。

通用的唯一标识符是AutoFieldfor 的很好替代primary_key。数据库不会为您生成UUID，因此建议使用default：

import uuid
from django.db import models

class MyUUIDModel(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    # other fields

请注意，会将的可调用项（省略了括号）传递给default，而不是的实例UUID。

在PostgreSQL上查找

使用iexact，contains，icontains， startswith，istartswith，endswith，或 iendswith在PostgreSQL上查找不为值工作不带连字符，因为PostgreSQL将它们存储在一个连字符的UUID数据类型类型。