类型层次结构¶

SQLAlchemy 为大多数常见的数据库数据类型提供了抽象，以及几种自定义数据类型的技术。

数据库类型使用 Python 类表示，所有这些类最终都扩展自名为 TypeEngine 的基本类型类。数据类型通常分为两类，每一类都在类型层次结构中以不同的方式表达自己。可以通过两种不同的命名约定（即 “驼峰式” 和 “大写”）的使用来识别单个数据类型类使用的类别。

另请参阅

使用 Table 对象设置 MetaData - 在 SQLAlchemy 统一教程中。演示了 TypeEngine 类型对象的最基本用法，以定义 Table 元数据，并在教程形式中介绍了类型对象的概念。

“驼峰式” 数据类型¶

基本类型具有 “驼峰式” 名称，例如 String、Numeric、Integer 和 DateTime。TypeEngine 的所有直接子类都是 “驼峰式” 类型。“驼峰式” 类型在最大程度上是 数据库无关的，这意味着它们都可以在任何数据库后端上使用，在这些后端上，它们的行为方式都适合于该后端，以便产生所需的行为。

一个简单的 “驼峰式” 数据类型示例是 String。在大多数后端上，在表规范中使用此数据类型将对应于目标后端上使用的 VARCHAR 数据库类型，从而将字符串值传递到数据库和从数据库传递，如下例所示

from sqlalchemy import MetaData
from sqlalchemy import Table, Column, Integer, String

metadata_obj = MetaData()

user = Table(
    "user",
    metadata_obj,
    Column("user_name", String, primary_key=True),
    Column("email_address", String(60)),
)

当在 Table 定义或任何 SQL 表达式中总体上使用特定的 TypeEngine 类时，如果不需要参数，则可以将其作为类本身传递，即不使用 () 实例化它。如果需要参数，例如上面 "email_address" 列中长度为 60 的参数，则可以实例化该类型。

另一个表达更多后端特定行为的 “驼峰式” 数据类型是 Boolean 数据类型。与 String 不同，后者表示所有数据库都具有的字符串数据类型，并非每个后端都具有真正的 “布尔” 数据类型；有些使用整数或 BIT 值 0 和 1，有些具有布尔文字常量 true 和 false，而另一些则没有。对于这种数据类型，Boolean 可以在 PostgreSQL 等后端上呈现 BOOLEAN，在 MySQL 后端上呈现 BIT，在 Oracle 数据库上呈现 SMALLINT。当使用此类型从数据库发送和接收数据时，根据使用的方言，它可能会解释 Python 数值或布尔值。

典型的 SQLAlchemy 应用程序可能希望在一般情况下主要使用 “驼峰式” 类型，因为它们通常会提供最佳的基本行为，并且可以自动移植到所有后端。

通用 “驼峰式” 数据类型的参考资料如下：通用 “驼峰式” 类型。

“大写” 数据类型¶

与 “驼峰式” 类型相反的是 “大写” 数据类型。这些数据类型始终从特定的 “驼峰式” 数据类型继承，并且始终表示 精确的 数据类型。当使用 “大写” 数据类型时，类型的名称始终按给定的形式精确呈现，而无需考虑当前后端是否支持它。因此，在 SQLAlchemy 应用程序中使用 “大写” 类型表明需要特定的数据类型，这反过来意味着，如果不采取其他步骤，该应用程序通常将仅限于那些完全按给定形式使用该类型的后端。“大写” 类型的示例包括 VARCHAR、NUMERIC、INTEGER 和 TIMESTAMP，它们分别直接从前面提到的 “驼峰式” 类型 String、Numeric、Integer 和 DateTime 继承。

作为 sqlalchemy.types 一部分的 “大写” 数据类型是常见的 SQL 类型，通常希望在至少两个（如果不是更多）后端上可用。

通用 “大写” 数据类型的参考资料如下：SQL 标准和多供应商 “大写” 类型。

后端特定的 “大写” 数据类型¶

大多数数据库还具有自己的数据类型，这些数据类型要么完全特定于这些数据库，要么添加了特定于这些数据库的附加参数。对于这些数据类型，特定的 SQLAlchemy 方言提供了 后端特定的 “大写” 数据类型，用于在其他后端上没有类似物的 SQL 类型。后端特定的大写数据类型的示例包括 PostgreSQL 的 JSONB、SQL Server 的 IMAGE 和 MySQL 的 TINYTEXT。

特定的后端也可能包括 “大写” 数据类型，这些数据类型扩展了与 sqlalchemy.types 模块中找到的相同 “大写” 数据类型中可用的参数。一个示例是，当创建 MySQL 字符串数据类型时，可能需要指定 MySQL 特定的参数，例如 charset 或 national，这些参数可从 MySQL 版本的 VARCHAR 中作为仅 MySQL 参数 VARCHAR.charset 和 VARCHAR.national 获得。

后端特定类型的 API 文档位于方言特定的文档中，列在方言中。

为多个后端使用 “大写” 和后端特定类型¶

回顾 “大写” 和 “驼峰式” 类型的存在引出了如何为后端特定选项使用 “大写” 数据类型的自然用例，但仅当使用该后端时。为了将数据库无关的 “驼峰式” 和后端特定的 “大写” 系统联系在一起，可以使用 TypeEngine.with_variant() 方法来组合类型，以便在特定后端上使用特定行为。

例如，要使用 String 数据类型，但在 MySQL 上运行时，当在 MySQL 或 MariaDB 上创建表时，使用 VARCHAR.charset 参数 VARCHAR，可以使用 TypeEngine.with_variant()，如下所示

from sqlalchemy import MetaData
from sqlalchemy import Table, Column, Integer, String
from sqlalchemy.dialects.mysql import VARCHAR

metadata_obj = MetaData()

user = Table(
    "user",
    metadata_obj,
    Column("user_name", String(100), primary_key=True),
    Column(
        "bio",
        String(255).with_variant(VARCHAR(255, charset="utf8"), "mysql", "mariadb"),
    ),
)

在上面的表定义中，"bio" 列在所有后端上都将具有字符串行为。在大多数后端上，它在 DDL 中将呈现为 VARCHAR。但是，在 MySQL 和 MariaDB 上（由以 mysql 或 mariadb 开头的数据库 URL 指示），它将呈现为 VARCHAR(255) CHARACTER SET utf8。

另请参阅

TypeEngine.with_variant() - 其他用法示例和说明

通用 “驼峰式” 类型¶

通用类型指定一个列，该列可以读取、写入和存储特定类型的 Python 数据。当发出 CREATE TABLE 语句时，SQLAlchemy 将选择目标数据库上可用的最佳数据库列类型。为了完全控制在 CREATE TABLE 中发出的列类型（例如 VARCHAR），请参阅 SQL 标准和多供应商 “大写” 类型和本章的其他部分。

对象名称	描述
BigInteger	用于更大的 `int` 整数的类型。
Boolean	布尔数据类型。
Date	用于 `datetime.date()` 对象的类型。
DateTime	用于 `datetime.datetime()` 对象的类型。
Double	用于双精度 `FLOAT` 浮点类型的类型。
Enum	通用枚举类型。
Float	表示浮点类型的类型，例如 `FLOAT` 或 `REAL`。
Integer	用于 `int` 整数的类型。
Interval	用于 `datetime.timedelta()` 对象的类型。
LargeBinary	用于大型二进制字节数据的类型。
MatchType	引用 MATCH 运算符的返回类型。
Numeric	非整数数值类型的基础，例如 `NUMERIC`、`FLOAT`、`DECIMAL` 和其他变体。
PickleType	保存 Python 对象，这些对象使用 pickle 序列化。
SchemaType	向类型添加功能，这些功能允许将模式级 DDL 与类型关联。
SmallInteger	用于较小的 `int` 整数的类型。
String	所有字符串和字符类型的基础。
Text	可变大小的字符串类型。
Time	用于 `datetime.time()` 对象的类型。
Unicode	可变长度的 Unicode 字符串类型。
UnicodeText	无界长度的 Unicode 字符串类型。
Uuid	表示数据库无关的 UUID 数据类型。

class sqlalchemy.types.BigInteger¶

用于更大的 int 整数的类型。

通常在 DDL 中生成 BIGINT，否则在 Python 端的作用类似于普通的 Integer。

类签名

class sqlalchemy.types.BigInteger (sqlalchemy.types.Integer)

class sqlalchemy.types.Boolean¶

布尔数据类型。

Boolean 通常在 DDL 端使用 BOOLEAN 或 SMALLINT，在 Python 端处理 True 或 False。

Boolean 数据类型当前具有两个级别的断言，即持久化的值是简单的 true/false 值。对于所有后端，仅接受 Python 值 None、True、False、1 或 0 作为参数值。对于那些不支持 “原生布尔” 数据类型的后端，可以选择在目标列上创建 CHECK 约束

Changed in version 1.2: Boolean 数据类型现在断言传入的 Python 值已经采用纯布尔形式。

成员

__init__(), bind_processor(), literal_processor(), python_type, result_processor()

类签名

class sqlalchemy.types.Boolean (sqlalchemy.types.SchemaType, sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Boolean.__init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)¶

构造一个 Boolean。

参数:

create_constraint¶ –
默认为 False。如果布尔值生成为 int/smallint，则还在表上创建 CHECK 约束，以确保值为 1 或 0。

注意

强烈建议 CHECK 约束具有显式名称，以便支持架构管理问题。可以通过设置 Boolean.name 参数或设置适当的命名约定来建立这一点；有关背景信息，请参阅配置约束命名约定。

Changed in version 1.4: - 此标志现在默认为 False，这意味着不会为非原生枚举类型生成 CHECK 约束。
name¶ – 如果生成 CHECK 约束，请指定约束的名称。

method sqlalchemy.types.Boolean.bind_processor(dialect)¶

返回用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收绑定参数值作为唯一的位置参数，并将返回要发送到 DB-API 的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.bind_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.bind_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_bind_param() 的实现。

另请参阅

增强现有类型

参数:: dialect¶ – 使用中的方言实例。

method sqlalchemy.types.Boolean.literal_processor(dialect)¶

返回一个转换函数，用于处理要直接呈现而不使用绑定的字面值。

当编译器使用 “literal_binds” 标志时，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并将返回一个字符串表示形式，以便在 SQL 语句中呈现。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.literal_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

增强现有类型

attribute sqlalchemy.types.Boolean.python_type¶

method sqlalchemy.types.Boolean.result_processor(dialect, coltype)¶

返回一个转换函数，用于处理结果行值。

返回一个可调用对象，它将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.result_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.result_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_result_value() 的实现。

另请参阅

增强现有类型

参数:

dialect¶ – 使用中的方言实例。
coltype¶ – 在 cursor.description 中接收的 DBAPI coltype 参数。

class sqlalchemy.types.Date¶

用于 datetime.date() 对象的类型。

成员

get_dbapi_type(), literal_processor(), python_type

类签名

class sqlalchemy.types.Date (sqlalchemy.types._RenderISO8601NoT, sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Date.get_dbapi_type(dbapi)¶

如果存在，则从底层 DB-API 返回相应的类型对象。

例如，这对于调用 setinputsizes() 很有用。

method sqlalchemy.types.Date.literal_processor(dialect)¶

返回一个转换函数，用于处理要直接呈现而不使用绑定的字面值。

当编译器使用 “literal_binds” 标志时，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并将返回一个字符串表示形式，以便在 SQL 语句中呈现。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.literal_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

增强现有类型

attribute sqlalchemy.types.Date.python_type¶

class sqlalchemy.types.DateTime¶

用于 datetime.datetime() 对象的类型。

日期和时间类型从 Python datetime 模块返回对象。大多数 DBAPI 都有对 datetime 模块的内置支持，但值得注意的例外是 SQLite。对于 SQLite，日期和时间类型存储为字符串，然后在返回行时转换回 datetime 对象。

对于 datetime 类型中的时间表示，某些后端包含其他选项，例如时区支持和秒的小数部分支持。对于秒的小数部分，请使用方言特定的数据类型，例如 TIME。对于时区支持，至少使用 TIMESTAMP 数据类型，如果不是方言特定的数据类型对象。

成员

__init__(), get_dbapi_type(), literal_processor(), python_type

类签名

class sqlalchemy.types.DateTime (sqlalchemy.types._RenderISO8601NoT, sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.DateTime.__init__(timezone: bool = False)¶

构造一个新的 DateTime。

参数:: timezone¶ – 布尔值。指示 datetime 类型应启用时区支持，如果仅在基本日期/时间持有类型上可用。建议在使用此标志时直接使用 TIMESTAMP 数据类型，因为某些数据库包含与支持时区的 TIMESTAMP 数据类型不同的单独的通用日期/时间持有类型，例如 Oracle 数据库。

method sqlalchemy.types.DateTime.get_dbapi_type(dbapi)¶

如果存在，则从底层 DB-API 返回相应的类型对象。

例如，这对于调用 setinputsizes() 很有用。

method sqlalchemy.types.DateTime.literal_processor(dialect)¶

返回一个转换函数，用于处理要直接呈现而不使用绑定的字面值。

当编译器使用 “literal_binds” 标志时，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并将返回一个字符串表示形式，以便在 SQL 语句中呈现。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.literal_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

增强现有类型

attribute sqlalchemy.types.DateTime.python_type¶

class sqlalchemy.types.Enum¶

通用枚举类型。

Enum 类型提供了一组可能的字符串值，列被约束为这些值。

如果后端提供原生的 “ENUM” 类型，Enum 类型将使用它；否则，它将使用 VARCHAR 数据类型。当生成 VARCHAR（所谓的 “非原生”）变体时，还存在自动生成 CHECK 约束的选项；请参阅 Enum.create_constraint 标志。

Enum 类型还提供在 Python 中对字符串值进行验证，包括读取和写入操作期间。当从结果集中的数据库读取值时，始终根据可能值的列表检查字符串值，如果找不到匹配项，则会引发 LookupError。当在 SQL 语句中将值作为纯字符串传递到数据库时，如果 Enum.validate_strings 参数设置为 True，则对于任何不在给定可能值列表中的字符串值，都会引发 LookupError；请注意，这会影响 LIKE 表达式与枚举值的使用（一种不常见的用例）。

枚举值的来源可以是字符串值列表，也可以是符合 PEP-435 的枚举类。对于 Enum 数据类型的目的，此类只需要提供一个 __members__ 方法。

当使用枚举类时，枚举对象用于输入和输出，而不是像纯字符串枚举类型那样使用字符串

import enum
from sqlalchemy import Enum


class MyEnum(enum.Enum):
    one = 1
    two = 2
    three = 3


t = Table("data", MetaData(), Column("value", Enum(MyEnum)))

connection.execute(t.insert(), {"value": MyEnum.two})
assert connection.scalar(t.select()) is MyEnum.two

在上面，每个元素的字符串名称，例如 “one”、“two”、“three”，都持久化到数据库中；Python Enum 的值，这里表示为整数，不使用；因此，每个枚举的值可以是任何类型的 Python 对象，无论它是否可持久化。

为了持久化值而不是名称，可以使用 Enum.values_callable 参数。此参数的值是用户提供的可调用对象，旨在与符合 PEP-435 的枚举类一起使用，并返回要持久化的字符串值列表。对于使用字符串值的简单枚举，诸如 lambda x: [e.value for e in x] 之类的可调用对象就足够了。

另请参阅

在类型映射中使用 Python Enum 或 pep-586 Literal 类型 - 关于将 Enum 数据类型与 ORM 的 ORM 注解声明式功能一起使用的背景信息。

ENUM - PostgreSQL 特定的类型，具有额外的功能。

ENUM - MySQL 特定的类型

成员

__init__(), create(), drop()

类签名

class sqlalchemy.types.Enum (sqlalchemy.types.String, sqlalchemy.types.SchemaType, sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Enum.__init__(*enums: object, **kw: Any)¶

构造一个枚举。

不适用于特定后端的关键字参数将被该后端忽略。

参数:

*enums¶ – 可以是正好一个符合 PEP-435 的枚举类型，也可以是一个或多个字符串标签。
create_constraint¶ –
默认为 False。当创建非原生枚举类型时，还在数据库上针对有效值构建 CHECK 约束。

注意

强烈建议 CHECK 约束具有显式名称，以便支持模式管理问题。可以通过设置 Enum.name 参数或设置适当的命名约定来建立这一点；有关背景信息，请参阅配置约束命名约定。

Changed in version 1.4: - 此标志现在默认为 False，这意味着不会为非原生枚举类型生成 CHECK 约束。
metadata¶ –
将此类型直接与 MetaData 对象关联。对于目标数据库上作为独立模式构造存在的类型 (PostgreSQL)，此类型将在 create_all() 和 drop_all() 操作中创建和删除。如果该类型未与任何 MetaData 对象关联，它将把自己与它使用的每个 Table 关联，并在创建这些单个表中的任何一个时创建，前提是检查了它的存在性。但是，只有在为该 Table 对象的元数据调用 drop_all() 时，才会删除该类型。

如果设置了 MetaData 对象的 MetaData.schema 参数的值，则如果未另行提供显式值，则将用作此对象上 Enum.schema 的默认值。

Changed in version 1.4.12: 当使用 Enum.metadata 参数传递时，Enum 继承 MetaData 对象的 MetaData.schema 参数（如果存在）。
name¶ – 此类型的名称。对于 PostgreSQL 和任何未来支持的数据库，这都是必需的，这些数据库需要显式命名的类型，或者显式命名的约束，以便生成类型和/或使用它的表。如果使用了 PEP-435 枚举类，则默认使用其名称（转换为小写）。
native_enum¶ – 在可用时使用数据库的原生 ENUM 类型。默认为 True。当为 False 时，对所有后端使用 VARCHAR + check 约束。当为 False 时，VARCHAR 长度可以使用 Enum.length 控制；当前，如果 native_enum=True，则 “length” 将被忽略。
length¶ –
允许在非原生枚举数据类型使用时为 VARCHAR 指定自定义长度。默认情况下，它使用最长值的长度。

Changed in version 2.0.0: 对于那些将 VARCHAR 用于枚举数据类型的后端，Enum.length 参数无条件地用于 VARCHAR 渲染，而与 Enum.native_enum 参数无关。
schema¶ –
此类型的模式名称。对于目标数据库上作为独立模式构造存在的类型 (PostgreSQL)，此参数指定类型所在的命名模式。

如果不存在，则模式名称将从 MetaData 集合中获取（如果作为 Enum.metadata 传递），对于包含 MetaData.schema 参数的 MetaData。

Changed in version 1.4.12: 当使用 Enum.metadata 参数传递时，Enum 继承 MetaData 对象的 MetaData.schema 参数（如果存在）。

否则，如果 Enum.inherit_schema 标志设置为 True，则模式将从关联的 Table 对象继承（如果存在）；当 Enum.inherit_schema 处于其默认值 False 时，不使用拥有表的模式。
quote¶ – 为类型的名称设置显式引用首选项。
inherit_schema¶ – 当 True 时，拥有 Table 的 “schema” 将复制到此 Enum 的 “schema” 属性，替换为 schema 属性传递的任何值。当使用 Table.to_metadata() 操作时，这也生效。
validate_strings¶ – 当为 True 时，在 SQL 语句中传递到数据库的字符串值将根据枚举值列表检查有效性。无法识别的值将导致引发 LookupError。
values_callable¶ –
一个可调用对象，它将被传递符合 PEP-435 的枚举类型，然后应返回要持久化的字符串值列表。这允许替代用法，例如使用枚举的字符串值而不是其名称持久化到数据库。可调用对象必须以与迭代 Enum 的 __member__ 属性相同的顺序返回要持久化的值。例如 lambda x: [i.value for i in x]。

New in version 1.2.3.
sort_key_function¶ –
一个 Python 可调用对象，可以用作 Python 内置函数 sorted() 中的 “key” 参数。SQLAlchemy ORM 要求映射的主键列必须以某种方式可排序。当使用不可排序的枚举对象（例如 Python 3 的 Enum 对象）时，可以使用此参数为对象设置默认排序键函数。默认情况下，枚举的数据库值用作排序函数。

1.3.8 版本新增。
omit_aliases¶ –
一个布尔值，为 true 时将从 pep 435 枚举中移除别名。默认为 True。

2.0 版本更改：此参数现在默认为 True。

method sqlalchemy.types.Enum.create(bind, checkfirst=False)¶: 继承自 SchemaType.create() 方法，该方法属于 SchemaType

为此类型发出 CREATE DDL（如果适用）。

method sqlalchemy.types.Enum.drop(bind, checkfirst=False)¶: 继承自 SchemaType.drop() 方法，该方法属于 SchemaType

为此类型发出 DROP DDL（如果适用）。

class sqlalchemy.types.Double¶

用于双精度 FLOAT 浮点类型的类型。

通常在 DDL 中生成 DOUBLE 或 DOUBLE_PRECISION，并在 Python 端表现得像普通的 Float。

2.0 版本新增。

类签名

class sqlalchemy.types.Double (sqlalchemy.types.Float)

class sqlalchemy.types.Float¶

表示浮点类型的类型，例如 FLOAT 或 REAL。

除非将 Float.asdecimal 标志设置为 True，否则此类型默认返回 Python float 对象，在这种情况下，它们将被强制转换为 decimal.Decimal 对象。

当在 Float 类型中未提供 Float.precision 时，某些后端可能会将此类型编译为 8 字节 / 64 位浮点数据类型。要使用 4 字节 / 32 位浮点数据类型，通常可以提供精度 <= 24，或者可以使用 REAL 类型。已知 PostgreSQL 和 MSSQL 方言就是这种情况，它们将类型呈现为 FLOAT，这在两者中都是 DOUBLE PRECISION 的别名。其他第三方方言可能具有类似的行为。

成员

__init__(), result_processor()

类签名

class sqlalchemy.types.Float (sqlalchemy.types.Numeric)

method sqlalchemy.types.Float.__init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)¶

构造一个 Float 对象。

参数:

precision¶ –
用于 DDL CREATE TABLE 中的数值精度。后端应该尝试确保此精度指示通用 Float 数据类型的位数。
注意

对于 Oracle Database 后端，呈现 DDL 时不接受 Float.precision 参数，因为 Oracle Database 不支持指定为小数位数的浮点精度。请改用 Oracle Database 特定的 FLOAT 数据类型，并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版本的新增功能。

要创建一个数据库无关的 Float，并为 Oracle Database 单独指定二进制精度，请使用 TypeEngine.with_variant()，如下所示
```
from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
)
```
asdecimal¶ – 与 Numeric 的标志相同，但默认为 False。请注意，将此标志设置为 True 会导致浮点转换。
decimal_return_scale¶ – 从浮点数转换为 Python decimal 时使用的默认刻度。由于十进制不精确性，浮点值通常会更长，并且大多数浮点数据库类型都没有“刻度”的概念，因此默认情况下，浮点类型在转换时会查找前十位小数位。指定此值将覆盖该长度。请注意，MySQL 浮点类型（包括“刻度”）如果未另行指定，则会将“刻度”用作 decimal_return_scale 的默认值。

method sqlalchemy.types.Float.result_processor(dialect, coltype)¶

返回一个转换函数，用于处理结果行值。

返回一个可调用对象，它将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.result_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.result_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_result_value() 的实现。

另请参阅

增强现有类型

参数:

dialect¶ – 正在使用的方言实例。
coltype¶ – 在 cursor.description 中接收到的 DBAPI coltype 参数。

class sqlalchemy.types.Integer¶

用于 int 整数的类型。

成员

get_dbapi_type(), literal_processor(), python_type

类签名

class sqlalchemy.types.Integer (sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Integer.get_dbapi_type(dbapi)¶

如果存在，则从底层 DB-API 返回相应的类型对象。

例如，这对于调用 setinputsizes() 很有用。

method sqlalchemy.types.Integer.literal_processor(dialect)¶

返回一个转换函数，用于处理要直接呈现而不使用绑定的字面值。

当编译器使用 “literal_binds” 标志时，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并将返回一个字符串表示形式，以便在 SQL 语句中呈现。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.literal_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

增强现有类型

attribute sqlalchemy.types.Integer.python_type¶

class sqlalchemy.types.Interval¶

用于 datetime.timedelta() 对象的类型。

Interval 类型处理 datetime.timedelta 对象。在 PostgreSQL 和 Oracle Database 中，使用原生 INTERVAL 类型；对于其他数据库，该值存储为相对于 “epoch”（1970 年 1 月 1 日）的日期。

请注意，Interval 类型目前在不支持原生 interval 类型的平台上不提供日期算术运算。此类操作通常需要转换表达式的两边（例如，首先将两边都转换为整数 epoch 值），这目前是一个手动过程（例如通过 expression.func）。

成员

__init__(), adapt_to_emulated(), bind_processor(), cache_ok, coerce_compared_value(), comparator_factory, impl, python_type, result_processor()

类签名

class sqlalchemy.types.Interval (sqlalchemy.types.Emulated, sqlalchemy.types._AbstractInterval, sqlalchemy.types.TypeDecorator)

class Comparator¶: 类签名

class sqlalchemy.types.Interval.Comparator (sqlalchemy.types.Comparator, sqlalchemy.types.Comparator)

method sqlalchemy.types.Interval.__init__(native: bool = True, second_precision: int | None = None, day_precision: int | None = None)¶

构造一个 Interval 对象。

参数:

native¶ – 当为 True 时，使用数据库提供的实际 INTERVAL 类型（如果支持，目前为 PostgreSQL、Oracle Database）。否则，将 interval 数据表示为 epoch 值，而无需考虑是否原生支持。
second_precision¶ – 对于支持 “秒的小数位精度” 参数的原生 interval 类型，例如 Oracle Database 和 PostgreSQL
day_precision¶ – 对于支持 “天精度” 参数的原生 interval 类型，例如 Oracle Database。

method sqlalchemy.types.Interval.adapt_to_emulated(impltype, **kw)¶

给定一个 impl 类，使此类型适应于假设为 “emulated” 的 impl。

impl 也应该是此类型的 “emulated” 版本，最有可能与此类型本身是同一个类。

例如：sqltypes.Enum 适应于 Enum 类。

method sqlalchemy.types.Interval.bind_processor(dialect: Dialect) → _BindProcessorType[dt.timedelta]¶

返回用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收绑定参数值作为唯一的位置参数，并将返回要发送到 DB-API 的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.bind_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.bind_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_bind_param() 的实现。

另请参阅

增强现有类型

参数:: dialect¶ – 正在使用的方言实例。

attribute sqlalchemy.types.Interval.cache_ok: bool | None = True¶

指示使用此 ExternalType 的语句是否 “可以安全地缓存”。

默认值 None 将发出警告，然后不允许缓存包含此类型的语句。设置为 False 以完全禁用使用此类型的语句被缓存，且不发出警告。当设置为 True 时，对象的类及其状态的选定元素将用作缓存键的一部分。例如，使用 TypeDecorator

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

上述类型的缓存键将等效于

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

缓存方案将从类型中提取与 __init__() 方法中参数名称相对应的属性。上面，“choices” 属性成为缓存键的一部分，但 “internal_only” 则不是，因为没有名为 “internal_only” 的参数。

可缓存元素的要求是它们是可哈希的，并且它们还指示每次给定缓存值时，使用此类型的表达式呈现的 SQL 相同。

为了适应引用不可哈希结构（如字典、集合和列表）的数据类型，可以通过将可哈希结构分配给与其参数名称相对应的属性名称，使这些对象 “可缓存”。例如，接受查找值字典的数据类型可以将此发布为排序的元组系列。给定一个先前不可缓存的类型，如下所示

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

其中 “lookup” 是一个字典。该类型将无法生成缓存键

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

如果我们确实设置了这样一个缓存键，它将无法使用。我们将获得一个元组结构，其中包含一个字典，该字典本身不能用作 “缓存字典”（例如 SQLAlchemy 的语句缓存）中的键，因为 Python 字典不可哈希

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

可以通过将排序的元组的元组分配给 “lookup” 属性来使该类型可缓存

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

在上面，LookupType({"a": 10, "b": 20}) 的缓存键将是

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

1.4.14 版本新增: - 为 TypeDecorator 类添加了 cache_ok 标志，以允许对缓存进行一些配置。

1.4.28 版本新增: - 添加了 ExternalType 混入类，它将 cache_ok 标志推广到 TypeDecorator 和 UserDefinedType 类。

另请参阅

SQL 编译缓存

method sqlalchemy.types.Interval.coerce_compared_value(op, value)¶

为表达式中 “coerced” 的 Python 值建议一个类型。

给定运算符和值，使类型有机会返回该值应强制转换成的类型。

此处的默认行为是保守的；如果右侧已经根据其 Python 类型强制转换为 SQL 类型，则通常保持不变。

此处的最终用户功能扩展通常应该通过 TypeDecorator，它提供了更宽松的行为，因为它默认将表达式的另一侧强制转换为此类型，因此对两边都应用了超出 DBAPI 所需的特殊 Python 转换。它还提供了公共方法 TypeDecorator.coerce_compared_value()，旨在供最终用户自定义此行为。

attribute sqlalchemy.types.Interval.comparator_factory¶: 别名为 Comparator

attribute sqlalchemy.types.Interval.impl¶: 别名为 DateTime

attribute sqlalchemy.types.Interval.python_type¶

method sqlalchemy.types.Interval.result_processor(dialect: Dialect, coltype: Any) → _ResultProcessorType[dt.timedelta]¶

返回一个转换函数，用于处理结果行值。

返回一个可调用对象，它将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.result_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.result_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_result_value() 的实现。

另请参阅

增强现有类型

参数:

dialect¶ – 正在使用的方言实例。
coltype¶ – 在 cursor.description 中接收到的 DBAPI coltype 参数。

class sqlalchemy.types.LargeBinary¶

用于大型二进制字节数据的类型。

LargeBinary 类型对应于目标平台的大型和/或不定长二进制类型，例如 MySQL 上的 BLOB 和 PostgreSQL 上的 BYTEA。它还处理 DBAPI 所需的必要转换。

成员

__init__()

类签名

class sqlalchemy.types.LargeBinary (sqlalchemy.types._Binary)

method sqlalchemy.types.LargeBinary.__init__(length: int | None = None)¶

构造一个 LargeBinary 类型。

参数:: length¶ – 可选，用于 DDL 语句的列长度，适用于接受长度的二进制类型，例如 MySQL BLOB 类型。

class sqlalchemy.types.MatchType¶

引用 MATCH 运算符的返回类型。

由于 ColumnOperators.match() 可能是通用 SQLAlchemy Core 中最开放式的运算符，因此我们无法在 SQL 求值时假定返回类型，因为 MySQL 返回浮点数而不是布尔值，而其他后端可能会执行不同的操作。因此，此类型充当占位符，目前是 Boolean 的子类。该类型允许方言在需要时注入结果处理功能，并在 MySQL 上返回浮点值。

类签名

class sqlalchemy.types.MatchType (sqlalchemy.types.Boolean)

class sqlalchemy.types.Numeric¶

非整数数值类型的基础，例如 NUMERIC、FLOAT、DECIMAL 和其他变体。

直接使用 Numeric 数据类型将呈现与可用精度数值对应的 DDL，例如 NUMERIC(precision, scale)。Float 子类将尝试呈现浮点数据类型，例如 FLOAT(precision)。

Numeric 类型默认返回 Python decimal.Decimal 对象，这是基于 Numeric.asdecimal 参数的默认值 True。如果此参数设置为 False，则返回的值将被强制转换为 Python float 对象。

Float 子类型更具体于浮点数，它将 Float.asdecimal 标志默认为 False，因此默认的 Python 数据类型是 float。

注意

当对数据库类型使用 Numeric 数据类型时，如果数据库类型向驱动程序返回 Python 浮点数值，则由 Numeric.asdecimal 指示的十进制转换精度可能会受到限制。特定数值/浮点数据类型的行为是所使用的 SQL 数据类型、正在使用的 Python DBAPI 以及 SQLAlchemy 方言中可能存在的策略的产物。建议需要特定精度/标度的用户通过实验可用的数据类型来确定最佳结果。

成员

__init__(), bind_processor(), get_dbapi_type(), literal_processor(), python_type, result_processor()

类签名

class sqlalchemy.types.Numeric (sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Numeric.__init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)¶

构造一个 Numeric 对象。

参数:

precision¶ – 数值精度，用于 DDL CREATE TABLE 中。
scale¶ – 数值标度，用于 DDL CREATE TABLE 中。
asdecimal¶ – 默认为 True。返回是否应将值作为 Python Decimal 对象或 float 发送。不同的 DBAPI 根据数据类型发送其中一种 - Numeric 类型将确保跨 DBAPI 返回值始终是其中一种。
decimal_return_scale¶ – 从 float 转换为 Python Decimal 时使用的默认标度。由于十进制不精确性，浮点值通常会更长，并且大多数浮点数据库类型没有“标度”的概念，因此默认情况下，float 类型在转换时会查找前十位小数位。指定此值将覆盖该长度。包含显式“.scale”值的类型，例如基本 Numeric 以及 MySQL 浮点类型，如果未另行指定，将使用“.scale”的值作为 decimal_return_scale 的默认值。

当使用 Numeric 类型时，应注意确保 asdecimal 设置适合正在使用的 DBAPI - 当 Numeric 应用从 Decimal->float 或 float->Decimal 的转换时，此转换会为接收到的所有结果列产生额外的性能开销。

原生返回 Decimal 的 DBAPI（例如 psycopg2）在设置为 True 时将具有更好的精度和更高的性能，因为原生转换为 Decimal 减少了浮点问题，并且 Numeric 类型本身不需要应用任何进一步的转换。但是，另一个原生返回 float 的 DBAPI *将* 产生额外的转换开销，并且仍然会受到浮点数据丢失的影响 - 在这种情况下，asdecimal=False 至少会消除额外的转换开销。

method sqlalchemy.types.Numeric.bind_processor(dialect)¶

返回用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收绑定参数值作为唯一的位置参数，并将返回要发送到 DB-API 的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.bind_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.bind_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_bind_param() 的实现。

另请参阅

增强现有类型

参数:: dialect¶ – 正在使用的方言实例。

method sqlalchemy.types.Numeric.get_dbapi_type(dbapi)¶

如果存在，则从底层 DB-API 返回相应的类型对象。

例如，这对于调用 setinputsizes() 很有用。

method sqlalchemy.types.Numeric.literal_processor(dialect)¶

返回一个转换函数，用于处理要直接呈现而不使用绑定的字面值。

当编译器使用 “literal_binds” 标志时，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并将返回一个字符串表示形式，以便在 SQL 语句中呈现。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.literal_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

增强现有类型

attribute sqlalchemy.types.Numeric.python_type¶

method sqlalchemy.types.Numeric.result_processor(dialect, coltype)¶

返回一个转换函数，用于处理结果行值。

返回一个可调用对象，它将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.result_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.result_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_result_value() 的实现。

另请参阅

增强现有类型

参数:

dialect¶ – 正在使用的方言实例。
coltype¶ – 在 cursor.description 中接收到的 DBAPI coltype 参数。

class sqlalchemy.types.PickleType¶

保存 Python 对象，这些对象使用 pickle 序列化。

PickleType 构建于 Binary 类型之上，对传入的对象应用 Python 的 pickle.dumps()，对输出的对象应用 pickle.loads()，从而允许将任何可 pickle 化的 Python 对象存储为序列化的二进制字段。

要允许 ORM 变更事件为与 PickleType 关联的元素传播，请参阅突变跟踪。

成员

__init__(), bind_processor(), cache_ok, compare_values(), impl, result_processor()

类签名

class sqlalchemy.types.PickleType (sqlalchemy.types.TypeDecorator)

method sqlalchemy.types.PickleType.__init__(protocol: int = 5, pickler: Any = None, comparator: Callable[[Any, Any], bool] | None = None, impl: _TypeEngineArgument[Any] | None = None)¶

构造一个 PickleType 对象。

参数:

protocol¶ – 默认为 pickle.HIGHEST_PROTOCOL。
pickler¶ – 默认为 pickle。可以是任何具有 pickle 兼容的 dumps 和 loads 方法的对象。
comparator¶ – 用于比较此类型值的 2 参数可调用谓词。如果保留为 None，则使用 Python “等于” 运算符来比较值。
impl¶ –
一个二进制存储 TypeEngine 类或实例，用于代替默认的 LargeBinary。例如，当使用 MySQL 时，_mysql.LONGBLOB 类可能更有效。

1.4.20 版本新增。

method sqlalchemy.types.PickleType.bind_processor(dialect)¶

为给定的 Dialect 提供绑定值处理函数。

此方法实现了 TypeEngine 绑定值转换的约定，通常通过 TypeEngine.bind_processor() 方法发生。

注意

TypeDecorator 的用户自定义子类**不应**实现此方法，而应实现 TypeDecorator.process_bind_param()，以便维护由实现类型提供的“内部”处理。

参数:: dialect¶ – 正在使用的方言实例。

attribute sqlalchemy.types.PickleType.cache_ok: bool | None = True¶

指示使用此 ExternalType 的语句是否 “可以安全地缓存”。

默认值 None 将发出警告，然后不允许缓存包含此类型的语句。设置为 False 以完全禁用使用此类型的语句被缓存，且不发出警告。当设置为 True 时，对象的类及其状态的选定元素将用作缓存键的一部分。例如，使用 TypeDecorator

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

上述类型的缓存键将等效于

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

缓存方案将从类型中提取与 __init__() 方法中参数名称相对应的属性。上面，“choices” 属性成为缓存键的一部分，但 “internal_only” 则不是，因为没有名为 “internal_only” 的参数。

可缓存元素的要求是它们是可哈希的，并且它们还指示每次给定缓存值时，使用此类型的表达式呈现的 SQL 相同。

为了适应引用不可哈希结构（如字典、集合和列表）的数据类型，可以通过将可哈希结构分配给与其参数名称相对应的属性名称，使这些对象 “可缓存”。例如，接受查找值字典的数据类型可以将此发布为排序的元组系列。给定一个先前不可缓存的类型，如下所示

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

其中 “lookup” 是一个字典。该类型将无法生成缓存键

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

如果我们确实设置了这样一个缓存键，它将无法使用。我们将获得一个元组结构，其中包含一个字典，该字典本身不能用作 “缓存字典”（例如 SQLAlchemy 的语句缓存）中的键，因为 Python 字典不可哈希

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

可以通过将排序的元组的元组分配给 “lookup” 属性来使该类型可缓存

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

在上面，LookupType({"a": 10, "b": 20}) 的缓存键将是

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

1.4.14 版本新增: - 为 TypeDecorator 类添加了 cache_ok 标志，以允许对缓存进行一些配置。

1.4.28 版本新增: - 添加了 ExternalType 混入类，它将 cache_ok 标志推广到 TypeDecorator 和 UserDefinedType 类。

另请参阅

SQL 编译缓存

method sqlalchemy.types.PickleType.compare_values(x, y)¶

给定两个值，比较它们是否相等。

默认情况下，此方法调用底层“impl”的 TypeEngine.compare_values()，而后者通常使用 Python 等于运算符 ==。

ORM 使用此函数来比较原始加载的值与拦截的“已更改”值，以确定是否发生了净更改。

attribute sqlalchemy.types.PickleType.impl¶: 别名： LargeBinary

method sqlalchemy.types.PickleType.result_processor(dialect, coltype)¶

为给定的 Dialect 提供结果值处理函数。

此方法实现了 TypeEngine 结果值转换的约定，通常通过 TypeEngine.result_processor() 方法发生。

注意

TypeDecorator 的用户自定义子类**不应**实现此方法，而应实现 TypeDecorator.process_result_value()，以便维护由实现类型提供的“内部”处理。

参数:

dialect¶ – 正在使用的方言实例。
coltype¶ – SQLAlchemy 数据类型

class sqlalchemy.types.SchemaType¶

向类型添加功能，这些功能允许将模式级 DDL 与类型关联。

支持必须显式创建/删除的类型（即 PG ENUM 类型）以及由表或模式级别约束、触发器和其他规则补充的类型。

SchemaType 类也可以作为 DDLEvents.before_parent_attach() 和 DDLEvents.after_parent_attach() 事件的目标，这些事件在类型对象与父 Column 关联时触发。

另请参阅

Enum

Boolean

成员

adapt(), copy(), create(), drop(), name

类签名

class sqlalchemy.types.SchemaType (sqlalchemy.sql.expression.SchemaEventTarget, sqlalchemy.types.TypeEngineMixin)

method sqlalchemy.types.SchemaType.adapt(cls: Type[TypeEngine | TypeEngineMixin], **kw: Any) → TypeEngine¶

method sqlalchemy.types.SchemaType.copy(**kw)¶

method sqlalchemy.types.SchemaType.create(bind, checkfirst=False)¶: 为此类型发出 CREATE DDL（如果适用）。

method sqlalchemy.types.SchemaType.drop(bind, checkfirst=False)¶: 为此类型发出 DROP DDL（如果适用）。

attribute sqlalchemy.types.SchemaType.name: str | None¶

class sqlalchemy.types.SmallInteger¶

用于较小的 int 整数的类型。

通常在 DDL 中生成 SMALLINT，否则在 Python 端的作用类似于普通的 Integer。

类签名

class sqlalchemy.types.SmallInteger (sqlalchemy.types.Integer)

class sqlalchemy.types.String¶

所有字符串和字符类型的基础。

在 SQL 中，对应于 VARCHAR。

当 String 类型在 CREATE TABLE 语句中使用时，通常需要 length 字段，因为 VARCHAR 在大多数数据库上都需要长度。

成员

__init__(), bind_processor(), get_dbapi_type(), literal_processor(), python_type, result_processor()

类签名

class sqlalchemy.types.String (sqlalchemy.types.Concatenable, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.String.__init__(length: int | None = None, collation: str | None = None)¶

创建一个字符串保持类型。

参数:

length¶ – 可选，列的长度，用于 DDL 和 CAST 表达式。如果不会发出 CREATE TABLE，则可以安全地省略。某些数据库可能需要 length 以用于 DDL，并且如果包含没有长度的 VARCHAR，则在发出 CREATE TABLE DDL 时将引发异常。该值是被解释为字节还是字符取决于数据库。
collation¶ –
可选，列级排序规则，用于 DDL 和 CAST 表达式。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如：
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
注意

在大多数情况下，对于期望存储非 ASCII 数据的 Column，应使用 Unicode 或 UnicodeText 数据类型。这些数据类型将确保在数据库上使用了正确的类型。

method sqlalchemy.types.String.bind_processor(dialect)¶

返回用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收绑定参数值作为唯一的位置参数，并将返回要发送到 DB-API 的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.bind_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.bind_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_bind_param() 的实现。

另请参阅

增强现有类型

参数:: dialect¶ – 正在使用的方言实例。

method sqlalchemy.types.String.get_dbapi_type(dbapi)¶

如果存在，则从底层 DB-API 返回相应的类型对象。

例如，这对于调用 setinputsizes() 很有用。

method sqlalchemy.types.String.literal_processor(dialect)¶

返回一个转换函数，用于处理要直接呈现而不使用绑定的字面值。

当编译器使用 “literal_binds” 标志时，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并将返回一个字符串表示形式，以便在 SQL 语句中呈现。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.literal_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

增强现有类型

attribute sqlalchemy.types.String.python_type¶

method sqlalchemy.types.String.result_processor(dialect, coltype)¶

返回一个转换函数，用于处理结果行值。

返回一个可调用对象，它将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.result_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.result_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_result_value() 的实现。

另请参阅

增强现有类型

参数:

dialect¶ – 使用中的方言实例。
coltype¶ – 在 cursor.description 中接收的 DBAPI coltype 参数。

class sqlalchemy.types.Text¶

可变大小的字符串类型。

在 SQL 中，通常对应于 CLOB 或 TEXT。一般来说，TEXT 对象没有长度；虽然有些数据库会在此处接受长度参数，但会被其他数据库拒绝。

类签名

class sqlalchemy.types.Text (sqlalchemy.types.String)

class sqlalchemy.types.Time¶

用于 datetime.time() 对象的类型。

成员

get_dbapi_type(), literal_processor(), python_type

类签名

class sqlalchemy.types.Time (sqlalchemy.types._RenderISO8601NoT, sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Time.get_dbapi_type(dbapi)¶

如果存在，则从底层 DB-API 返回相应的类型对象。

例如，这对于调用 setinputsizes() 很有用。

method sqlalchemy.types.Time.literal_processor(dialect)¶

返回一个转换函数，用于处理要直接呈现而不使用绑定的字面值。

当编译器使用 “literal_binds” 标志时，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并将返回一个字符串表示形式，以便在 SQL 语句中呈现。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.literal_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

增强现有类型

attribute sqlalchemy.types.Time.python_type¶

class sqlalchemy.types.Unicode¶

可变长度的 Unicode 字符串类型。

Unicode 类型是 String 的子类，它假定输入和输出字符串可能包含非 ASCII 字符，并且对于某些后端，意味着底层列类型显式支持非 ASCII 数据，例如 Oracle 数据库和 SQL Server 上的 NVARCHAR。这将影响方言级别的 CREATE TABLE 语句和 CAST 函数的输出。

Unicode 类型使用的字符编码通常由 DBAPI 本身确定，用于传输和接收数据到数据库。所有现代 DBAPI 都适应非 ASCII 字符串，但可能具有管理数据库编码的不同方法；如果必要，应按照方言部分中目标 DBAPI 的注释中详述的方式配置此编码。

在现代 SQLAlchemy 中，使用 Unicode 数据类型并不意味着 SQLAlchemy 本身内部有任何编码/解码行为。在 Python 3 中，所有字符串对象本质上都支持 Unicode，并且 SQLAlchemy 不会生成字节串对象，也不会容纳不返回 Python Unicode 对象作为字符串值结果集的 DBAPI。

警告

已知某些数据库后端，特别是使用 pyodbc 的 SQL Server，在关于被标记为 NVARCHAR 类型而不是 VARCHAR 类型的数据方面存在不良行为，包括数据类型不匹配错误和不使用索引。有关解决像使用 pyodbc 和 cx_Oracle 的 SQL Server 这样的后端的 Unicode 字符问题的背景信息，请参阅关于 DialectEvents.do_setinputsizes() 的章节。

另请参阅

UnicodeText - 无长度的文本对应物，对应于 Unicode。

DialectEvents.do_setinputsizes()

类签名

class sqlalchemy.types.Unicode (sqlalchemy.types.String)

class sqlalchemy.types.UnicodeText¶

无界长度的 Unicode 字符串类型。

有关此对象的 Unicode 行为的详细信息，请参阅 Unicode。

与 Unicode 类似，使用 UnicodeText 类型意味着后端正在使用支持 Unicode 的类型，例如 NCLOB、NTEXT。

类签名

class sqlalchemy.types.UnicodeText (sqlalchemy.types.Text)

class sqlalchemy.types.Uuid¶

表示数据库无关的 UUID 数据类型。

对于没有“原生” UUID 数据类型的后端，该值将使用 CHAR(32) 并将 UUID 存储为 32 个字符的字母数字十六进制字符串。

对于已知直接支持 UUID 或类似的 UUID 存储数据类型（例如 SQL Server 的 UNIQUEIDENTIFIER）的后端，“原生”模式默认启用，允许在这些后端上使用这些类型。

在其默认使用模式下，Uuid 数据类型期望Python uuid 对象，来自 Python uuid 模块

import uuid

from sqlalchemy import Uuid
from sqlalchemy import Table, Column, MetaData, String


metadata_obj = MetaData()

t = Table(
    "t",
    metadata_obj,
    Column("uuid_data", Uuid, primary_key=True),
    Column("other_data", String),
)

with engine.begin() as conn:
    conn.execute(
        t.insert(), {"uuid_data": uuid.uuid4(), "other_data": "some data"}
    )

要使 Uuid 数据类型与基于字符串的 Uuid（例如 32 个字符的十六进制字符串）一起使用，请传递 Uuid.as_uuid 参数，值为 False。

2.0 版本新增。

另请参阅

UUID - 完全表示 UUID 数据类型，没有任何后端无关的行为。

成员

__init__(), bind_processor(), coerce_compared_value(), literal_processor(), python_type, result_processor()

类签名

class sqlalchemy.types.Uuid (sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.Uuid.__init__(as_uuid: bool = True, native_uuid: bool = True)¶

构造 Uuid 类型。

参数:

as_uuid=True¶ –
如果为 True，则值将被解释为 Python uuid 对象，通过 DBAPI 转换为/从字符串转换。
native_uuid=True¶ – 如果为 True，则支持直接 UUID 数据类型或 UUID 存储值（例如 SQL Server 的 UNIQUEIDENTIFIER）的后端将在这些后端中使用。如果为 False，则无论是否原生支持，所有后端都将使用 CHAR(32) 数据类型。

method sqlalchemy.types.Uuid.bind_processor(dialect)¶

返回用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收绑定参数值作为唯一的位置参数，并将返回要发送到 DB-API 的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.bind_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.bind_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_bind_param() 的实现。

另请参阅

增强现有类型

参数:: dialect¶ – 使用中的方言实例。

method sqlalchemy.types.Uuid.coerce_compared_value(op, value)¶: 有关描述，请参阅 TypeEngine.coerce_compared_value()。

method sqlalchemy.types.Uuid.literal_processor(dialect)¶

返回一个转换函数，用于处理要直接呈现而不使用绑定的字面值。

当编译器使用 “literal_binds” 标志时，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并将返回一个字符串表示形式，以便在 SQL 语句中呈现。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.literal_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

增强现有类型

attribute sqlalchemy.types.Uuid.python_type¶

method sqlalchemy.types.Uuid.result_processor(dialect, coltype)¶

返回一个转换函数，用于处理结果行值。

返回一个可调用对象，它将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.result_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.result_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_result_value() 的实现。

另请参阅

增强现有类型

参数:

dialect¶ – 使用中的方言实例。
coltype¶ – 在 cursor.description 中接收的 DBAPI coltype 参数。

SQL 标准和多厂商 “UPPERCASE” 类型¶

此类型类别指的是要么是 SQL 标准的一部分，要么可能在数据库后端的子集中找到的类型。与 “通用” 类型不同，SQL 标准/多厂商类型不保证在所有后端上都能工作，并且只在那些显式按名称支持它们的后端上工作。也就是说，当发出 CREATE TABLE 时，该类型将始终在 DDL 中发出其确切名称。

对象名称	描述
ARRAY	表示 SQL 数组类型。
BIGINT	SQL BIGINT 类型。
BINARY	SQL BINARY 类型。
BLOB	SQL BLOB 类型。
BOOLEAN	SQL BOOLEAN 类型。
CHAR	SQL CHAR 类型。
CLOB	CLOB 类型。
DATE	SQL DATE 类型。
DATETIME	SQL DATETIME 类型。
DECIMAL	SQL DECIMAL 类型。
DOUBLE	SQL DOUBLE 类型。
DOUBLE_PRECISION	SQL DOUBLE PRECISION 类型。
FLOAT	SQL FLOAT 类型。
INT	别名 `INTEGER`
INTEGER	SQL INT 或 INTEGER 类型。
JSON	表示 SQL JSON 类型。
NCHAR	SQL NCHAR 类型。
NUMERIC	SQL NUMERIC 类型。
NVARCHAR	SQL NVARCHAR 类型。
REAL	SQL REAL 类型。
SMALLINT	SQL SMALLINT 类型。
TEXT	SQL TEXT 类型。
TIME	SQL TIME 类型。
TIMESTAMP	SQL TIMESTAMP 类型。
UUID	表示 SQL UUID 类型。
VARBINARY	SQL VARBINARY 类型。
VARCHAR	SQL VARCHAR 类型。

class sqlalchemy.types.ARRAY¶

表示 SQL 数组类型。

注意

此类型用作所有 ARRAY 操作的基础。然而，目前只有 PostgreSQL 后端在 SQLAlchemy 中支持 SQL 数组。建议在使用 PostgreSQL 的 ARRAY 类型时直接使用 PostgreSQL 特定的 sqlalchemy.dialects.postgresql.ARRAY 类型，因为它提供了特定于该后端的其他运算符。

ARRAY 是 Core 的一部分，用于支持各种 SQL 标准函数，例如明确涉及数组的 array_agg；然而，除了 PostgreSQL 后端和可能的一些第三方方言外，没有其他 SQLAlchemy 内置方言支持此类型。

ARRAY 类型是根据元素的“类型”构造的

mytable = Table("mytable", metadata, Column("data", ARRAY(Integer)))

上述类型表示 N 维数组，这意味着像 PostgreSQL 这样的支持后端将自动解释任何维度的值。要生成一个传递一维整数数组的 INSERT 构造

connection.execute(mytable.insert(), {"data": [1, 2, 3]})

ARRAY 类型可以根据固定数量的维度构造

mytable = Table(
    "mytable", metadata, Column("data", ARRAY(Integer, dimensions=2))
)

发送维度数量是可选的，但建议这样做，如果数据类型要表示多个维度的数组。此数字用于

当向数据库发出类型声明本身时，例如 INTEGER[][]
当将 Python 值转换为数据库值，反之亦然时，例如 Unicode 对象数组使用此数字来有效地访问数组结构内部的字符串值，而无需诉诸逐行类型检查
当与 Python getitem 访问器一起使用时，维度数量用于定义 [] 运算符应返回的类型种类，例如对于具有两个维度的 INTEGER 数组
```
>>> expr = table.c.column[5]  # returns ARRAY(Integer, dimensions=1)
>>> expr = expr[6]  # returns Integer
```

对于一维数组，没有维度参数的 ARRAY 实例通常会假定一维行为。

ARRAY 类型的 SQL 表达式支持 “索引” 和 “切片” 行为。 [] 运算符生成表达式构造，这将为 SELECT 语句生成适当的 SQL

select(mytable.c.data[5], mytable.c.data[2:7])

以及使用 Update.values() 方法时的 UPDATE 语句

mytable.update().values(
    {mytable.c.data[5]: 7, mytable.c.data[2:7]: [1, 2, 3]}
)

索引访问默认从 1 开始；对于从 0 开始的索引转换，设置 ARRAY.zero_indexes。

ARRAY 类型还为运算符 Comparator.any() 和 Comparator.all() 提供了支持。 ARRAY 的 PostgreSQL 特定版本还提供了其他运算符。

在使用 ORM 时检测 ARRAY 列中的更改

当与 SQLAlchemy ORM 一起使用时，ARRAY 类型不会检测到对数组的就地修改。为了检测这些，必须使用 sqlalchemy.ext.mutable 扩展，使用 MutableList 类

from sqlalchemy import ARRAY
from sqlalchemy.ext.mutable import MutableList


class SomeOrmClass(Base):
    # ...

    data = Column(MutableList.as_mutable(ARRAY(Integer)))

此扩展将允许对数组进行 “就地” 更改，例如 .append()，以生成将被工作单元检测到的事件。请注意，对数组内部元素的更改，包括就地修改的子数组，都不会被检测到。

或者，将新的数组值分配给替换旧数组值的 ORM 元素将始终触发更改事件。

另请参阅

sqlalchemy.dialects.postgresql.ARRAY

成员

__init__(), contains(), any(), all()

类签名

class sqlalchemy.types.ARRAY (sqlalchemy.sql.expression.SchemaEventTarget, sqlalchemy.types.Indexable, sqlalchemy.types.Concatenable, sqlalchemy.types.TypeEngine)

method sqlalchemy.types.ARRAY.__init__(item_type: _TypeEngineArgument[Any], as_tuple: bool = False, dimensions: int | None = None, zero_indexes: bool = False)¶

构造 ARRAY。

例如：

Column("myarray", ARRAY(Integer))

参数是：

参数:

item_type¶ – 此数组项的数据类型。请注意，此处维度无关紧要，因此像 INTEGER[][] 这样的多维数组构造为 ARRAY(Integer)，而不是 ARRAY(ARRAY(Integer)) 或类似形式。
as_tuple=False¶ – 指定是否应将返回结果从列表转换为元组。此参数通常不需要，因为 Python 列表与 SQL 数组对应良好。
dimensions¶ – 如果非 None，则 ARRAY 将假定固定数量的维度。这会影响数组在数据库上的声明方式、解释 Python 和结果值的方式，以及与 “getitem” 运算符结合使用的表达式行为方式。有关更多详细信息，请参阅 ARRAY 处的描述。
zero_indexes=False¶ – 当为 True 时，索引值将在 Python 从 0 开始的索引和 SQL 从 1 开始的索引之间转换，例如，在传递到数据库之前，所有索引值都将加 1。

class Comparator¶

定义 ARRAY 的比较操作。

在此类型的方言特定形式上提供了更多运算符。请参阅 Comparator。

类签名

class sqlalchemy.types.ARRAY.Comparator (sqlalchemy.types.Comparator, sqlalchemy.types.Comparator)

method sqlalchemy.types.ARRAY.Comparator.contains(*arg, **kw)¶: ARRAY.contains() 未为基本 ARRAY 类型实现。使用方言特定的 ARRAY 类型。

另请参阅

ARRAY - PostgreSQL 特定版本。

method sqlalchemy.types.ARRAY.Comparator.any(other, operator= None)¶

返回 other operator ANY (array) 子句。

遗留功能

此方法是 ARRAY 的特定构造，现在已被 any_() 函数取代，该函数具有不同的调用风格。 any_() 函数也通过 ColumnOperators.any_() 方法在方法级别镜像。

数组特定的 Comparator.any() 的用法如下：

from sqlalchemy.sql import operators

conn.execute(
    select(table.c.data).where(table.c.data.any(7, operator=operators.lt))
)

参数:

other¶ – 要比较的表达式
operator¶ – 来自 sqlalchemy.sql.operators 包的运算符对象，默认为 eq()。

另请参阅

any_()

Comparator.all()

method sqlalchemy.types.ARRAY.Comparator.all(other, operator= None)¶

返回 other operator ALL (array) 子句。

遗留功能

此方法是 ARRAY 的特定构造，现在已被 all_() 函数取代，该函数具有不同的调用风格。 all_() 函数也通过 ColumnOperators.all_() 方法在方法级别镜像。

数组特定 Comparator.all() 的用法如下

from sqlalchemy.sql import operators

conn.execute(
    select(table.c.data).where(table.c.data.all(7, operator=operators.lt))
)

参数:

other¶ – 要比较的表达式
operator¶ – 来自 sqlalchemy.sql.operators 包的运算符对象，默认为 eq()。

另请参阅

all_()

Comparator.any()

class sqlalchemy.types.BIGINT¶: SQL BIGINT 类型。

另请参阅

BigInteger - 基础类型的文档。

类签名

class sqlalchemy.types.BIGINT (sqlalchemy.types.BigInteger)

class sqlalchemy.types.BINARY¶: SQL BINARY 类型。

类签名

class sqlalchemy.types.BINARY (sqlalchemy.types._Binary)

class sqlalchemy.types.BLOB¶

SQL BLOB 类型。

成员

__init__()

类签名

class sqlalchemy.types.BLOB (sqlalchemy.types.LargeBinary)

method sqlalchemy.types.BLOB.__init__(length: int | None = None)¶

继承自 sqlalchemy.types.LargeBinary.__init__ 方法，源自 LargeBinary

构造一个 LargeBinary 类型。

参数:: length¶ – 可选，列的长度，用于 DDL 语句，适用于接受长度的二进制类型，例如 MySQL BLOB 类型。

class sqlalchemy.types.BOOLEAN¶

SQL BOOLEAN 类型。

成员

__init__()

类签名

class sqlalchemy.types.BOOLEAN (sqlalchemy.types.Boolean)

method sqlalchemy.types.BOOLEAN.__init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)¶

继承自 sqlalchemy.types.Boolean.__init__ 方法，源自 Boolean

构造一个 Boolean。

参数:

create_constraint¶ –
默认为 False。如果布尔值生成为 int/smallint，则还在表上创建 CHECK 约束，以确保值为 1 或 0。

注意

强烈建议 CHECK 约束具有显式名称，以便支持架构管理问题。可以通过设置 Boolean.name 参数或设置适当的命名约定来建立这一点；有关背景信息，请参阅配置约束命名约定。

Changed in version 1.4: - 此标志现在默认为 False，这意味着不会为非原生枚举类型生成 CHECK 约束。
name¶ – 如果生成 CHECK 约束，请指定约束的名称。

class sqlalchemy.types.CHAR¶

SQL CHAR 类型。

成员

__init__()

类签名

class sqlalchemy.types.CHAR (sqlalchemy.types.String)

method sqlalchemy.types.CHAR.__init__(length: int | None = None, collation: str | None = None)¶

继承自 sqlalchemy.types.String.__init__ 方法，源自 String

创建一个字符串保持类型。

参数:

length¶ – 可选，列的长度，用于 DDL 和 CAST 表达式。如果不会发出 CREATE TABLE，则可以安全地省略。某些数据库可能需要 length 以用于 DDL，并且如果包含没有长度的 VARCHAR，则在发出 CREATE TABLE DDL 时会引发异常。该值被解释为字节还是字符取决于具体数据库。
collation¶ –
可选，列级排序规则，用于 DDL 和 CAST 表达式。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如：
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
注意

在大多数情况下，对于期望存储非 ASCII 数据的 Column，应使用 Unicode 或 UnicodeText 数据类型。这些数据类型将确保在数据库上使用了正确的类型。

class sqlalchemy.types.CLOB¶

CLOB 类型。

此类型在 Oracle Database 和 Informix 中找到。

成员

__init__()

类签名

class sqlalchemy.types.CLOB (sqlalchemy.types.Text)

method sqlalchemy.types.CLOB.__init__(length: int | None = None, collation: str | None = None)¶

继承自 sqlalchemy.types.String.__init__ 方法，源自 String

创建一个字符串保持类型。

参数:

length¶ – 可选，列的长度，用于 DDL 和 CAST 表达式。如果不会发出 CREATE TABLE，则可以安全地省略。某些数据库可能需要 length 以用于 DDL，并且如果包含没有长度的 VARCHAR，则在发出 CREATE TABLE DDL 时会引发异常。该值被解释为字节还是字符取决于具体数据库。
collation¶ –
可选，列级排序规则，用于 DDL 和 CAST 表达式。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如：
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
注意

在大多数情况下，对于期望存储非 ASCII 数据的 Column，应使用 Unicode 或 UnicodeText 数据类型。这些数据类型将确保在数据库上使用了正确的类型。

class sqlalchemy.types.DATE¶: SQL DATE 类型。

类签名

class sqlalchemy.types.DATE (sqlalchemy.types.Date)

class sqlalchemy.types.DATETIME¶

SQL DATETIME 类型。

成员

__init__()

类签名

class sqlalchemy.types.DATETIME (sqlalchemy.types.DateTime)

method sqlalchemy.types.DATETIME.__init__(timezone: bool = False)¶

继承自 sqlalchemy.types.DateTime.__init__ 方法，源自 DateTime

构造一个新的 DateTime。

参数:: timezone¶ – 布尔值。指示 datetime 类型应启用时区支持（如果仅在基本日期/时间保持类型上可用）。建议在使用此标志时直接使用 TIMESTAMP 数据类型，因为某些数据库包含与时区感知 TIMESTAMP 数据类型不同的单独通用日期/时间保持类型，例如 Oracle Database。

class sqlalchemy.types.DECIMAL¶

SQL DECIMAL 类型。

另请参阅

Numeric - 基础类型的文档。

成员

__init__()

类签名

class sqlalchemy.types.DECIMAL (sqlalchemy.types.Numeric)

method sqlalchemy.types.DECIMAL.__init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)¶

继承自 sqlalchemy.types.Numeric.__init__ 方法，源自 Numeric

构造一个 Numeric 对象。

参数:

precision¶ – 数字精度，用于 DDL CREATE TABLE。
scale¶ – 数字刻度，用于 DDL CREATE TABLE。
asdecimal¶ – 默认为 True。返回是否应将值作为 Python Decimal 对象或浮点数发送。不同的 DBAPI 根据数据类型发送其中一种 - Numeric 类型将确保跨 DBAPI 一致地返回值。
decimal_return_scale¶ – 从浮点数转换为 Python 小数时使用的默认刻度。由于十进制精度不高，浮点值通常会更长，并且大多数浮点数据库类型没有“刻度”的概念，因此默认情况下，float 类型在转换时会查找前十位小数位。指定此值将覆盖该长度。包含显式“.scale”值的类型（例如基本 Numeric 以及 MySQL 浮点类型）将使用“.scale”的值作为 decimal_return_scale 的默认值（如果未另行指定）。

当使用 Numeric 类型时，应注意确保 asdecimal 设置适合正在使用的 DBAPI - 当 Numeric 应用从 Decimal->float 或 float->Decimal 的转换时，此转换会为接收到的所有结果列产生额外的性能开销。

原生返回 Decimal 的 DBAPI（例如 psycopg2）在设置为 True 时将具有更好的精度和更高的性能，因为原生转换为 Decimal 减少了浮点问题，并且 Numeric 类型本身不需要应用任何进一步的转换。但是，另一个原生返回 float 的 DBAPI *将* 产生额外的转换开销，并且仍然会受到浮点数据丢失的影响 - 在这种情况下，asdecimal=False 至少会消除额外的转换开销。

class sqlalchemy.types.DOUBLE¶

SQL DOUBLE 类型。

2.0 版本新增。

另请参阅

Double - 基础类型的文档。

成员

__init__()

类签名

class sqlalchemy.types.DOUBLE (sqlalchemy.types.Double)

method sqlalchemy.types.DOUBLE.__init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)¶

继承自 sqlalchemy.types.Float.__init__ 方法，源自 Float

构造一个 Float 对象。

参数:

precision¶ –
用于 DDL CREATE TABLE 中的数值精度。后端应该尝试确保此精度指示通用 Float 数据类型的位数。
注意

对于 Oracle Database 后端，呈现 DDL 时不接受 Float.precision 参数，因为 Oracle Database 不支持指定为小数位数的浮点精度。请改用 Oracle Database 特定的 FLOAT 数据类型，并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版本的新增功能。

要创建一个数据库无关的 Float，并为 Oracle Database 单独指定二进制精度，请使用 TypeEngine.with_variant()，如下所示
```
from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
)
```
asdecimal¶ – 与 Numeric 的标志相同，但默认为 False。请注意，将此标志设置为 True 会导致浮点转换。
decimal_return_scale¶ – 从浮点数转换为 Python 小数时使用的默认刻度。由于十进制精度不高，浮点值通常会更长，并且大多数浮点数据库类型没有“刻度”的概念，因此默认情况下，float 类型在转换时会查找前十位小数位。指定此值将覆盖该长度。请注意，MySQL 浮点类型（确实包含“刻度”）将使用“刻度”作为 decimal_return_scale 的默认值（如果未另行指定）。

class sqlalchemy.types.DOUBLE_PRECISION¶

SQL DOUBLE PRECISION 类型。

2.0 版本新增。

另请参阅

Double - 基础类型的文档。

成员

__init__()

类签名

class sqlalchemy.types.DOUBLE_PRECISION (sqlalchemy.types.Double)

method sqlalchemy.types.DOUBLE_PRECISION.__init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)¶

继承自 sqlalchemy.types.Float.__init__ 方法，源自 Float

构造一个 Float 对象。

参数:

precision¶ –
用于 DDL CREATE TABLE 中的数值精度。后端应该尝试确保此精度指示通用 Float 数据类型的位数。
注意

对于 Oracle Database 后端，呈现 DDL 时不接受 Float.precision 参数，因为 Oracle Database 不支持指定为小数位数的浮点精度。请改用 Oracle Database 特定的 FLOAT 数据类型，并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版本的新增功能。

要创建一个数据库无关的 Float，并为 Oracle Database 单独指定二进制精度，请使用 TypeEngine.with_variant()，如下所示
```
from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
)
```
asdecimal¶ – 与 Numeric 的标志相同，但默认为 False。请注意，将此标志设置为 True 会导致浮点转换。
decimal_return_scale¶ – 从浮点数转换为 Python 小数时使用的默认刻度。由于十进制精度不高，浮点值通常会更长，并且大多数浮点数据库类型没有“刻度”的概念，因此默认情况下，float 类型在转换时会查找前十位小数位。指定此值将覆盖该长度。请注意，MySQL 浮点类型（确实包含“刻度”）将使用“刻度”作为 decimal_return_scale 的默认值（如果未另行指定）。

class sqlalchemy.types.FLOAT¶

SQL FLOAT 类型。

另请参阅

Float - 基础类型的文档。

成员

__init__()

类签名

class sqlalchemy.types.FLOAT (sqlalchemy.types.Float)

method sqlalchemy.types.FLOAT.__init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)¶

继承自 sqlalchemy.types.Float.__init__ 方法，源自 Float

构造一个 Float 对象。

参数:

precision¶ –
用于 DDL CREATE TABLE 中的数值精度。后端应该尝试确保此精度指示通用 Float 数据类型的位数。
注意

对于 Oracle Database 后端，呈现 DDL 时不接受 Float.precision 参数，因为 Oracle Database 不支持指定为小数位数的浮点精度。请改用 Oracle Database 特定的 FLOAT 数据类型，并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版本的新增功能。

要创建一个数据库无关的 Float，并为 Oracle Database 单独指定二进制精度，请使用 TypeEngine.with_variant()，如下所示
```
from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
)
```
asdecimal¶ – 与 Numeric 的标志相同，但默认为 False。请注意，将此标志设置为 True 会导致浮点转换。
decimal_return_scale¶ – 从浮点数转换为 Python 小数时使用的默认刻度。由于十进制精度不高，浮点值通常会更长，并且大多数浮点数据库类型没有“刻度”的概念，因此默认情况下，float 类型在转换时会查找前十位小数位。指定此值将覆盖该长度。请注意，MySQL 浮点类型（确实包含“刻度”）将使用“刻度”作为 decimal_return_scale 的默认值（如果未另行指定）。

attribute sqlalchemy.types..sqlalchemy.types.INT¶: 别名 INTEGER

class sqlalchemy.types.JSON¶

表示 SQL JSON 类型。

注意

JSON 作为特定于供应商的 JSON 类型的外观提供。由于它支持 JSON SQL 操作，因此它仅在具有实际 JSON 类型的后端上工作，目前

PostgreSQL - 请参阅 sqlalchemy.dialects.postgresql.JSON 和 sqlalchemy.dialects.postgresql.JSONB 以获取后端特定的说明
MySQL - 请参阅 sqlalchemy.dialects.mysql.JSON 以获取后端特定的说明
SQLite 版本 3.9 及更高版本 - 请参阅 sqlalchemy.dialects.sqlite.JSON 以获取后端特定的说明
Microsoft SQL Server 2016 及更高版本 - 请参阅 sqlalchemy.dialects.mssql.JSON 以获取后端特定的说明

JSON 是 Core 的一部分，旨在支持本地 JSON 数据类型日益普及的趋势。

JSON 类型存储任意 JSON 格式的数据，例如

data_table = Table(
    "data_table",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("data", JSON),
)

with engine.connect() as conn:
    conn.execute(
        data_table.insert(), {"data": {"key1": "value1", "key2": "value2"}}
    )

JSON 特定的表达式运算符

JSON 数据类型提供以下额外的 SQL 操作

键索引操作
```
data_table.c.data["some key"]
```
整数索引操作
```
data_table.c.data[3]
```

路径索引操作

data_table.c.data[("key_1", "key_2", 5, ..., "key_n")]

特定 JSON 元素类型的数据转换器，在调用索引或路径操作之后
```
data_table.c.data["some key"].as_integer()
```
1.3.11 版本新增。

其他操作可能从 JSON 的特定于方言的版本中获得，例如 sqlalchemy.dialects.postgresql.JSON 和 sqlalchemy.dialects.postgresql.JSONB，它们都提供额外的 PostgreSQL 特定的操作。

将 JSON 元素转换为其他类型

索引操作，即通过使用 Python 方括号运算符调用表达式（如 some_column['some key']）来调用的操作，会返回一个表达式对象，其类型默认设置为 JSON，以便可以对结果类型调用进一步的 JSON 相关指令。然而，更常见的情况是，索引操作预期返回一个特定的标量元素，例如字符串或整数。为了以后端无关的方式访问这些元素，提供了一系列数据转换器

Comparator.as_string() - 将元素作为字符串返回
Comparator.as_boolean() - 将元素作为布尔值返回
Comparator.as_float() - 将元素作为浮点数返回
Comparator.as_integer() - 将元素作为整数返回

这些数据转换器由支持的方言实现，以确保对上述类型的比较能够按预期工作，例如

# integer comparison
data_table.c.data["some_integer_key"].as_integer() == 5

# boolean comparison
data_table.c.data["some_boolean"].as_boolean() == True

1.3.11 版本新增: 为基本 JSON 数据元素类型添加了特定于类型的转换器。

注意

数据转换器函数是 1.3.11 版本中的新功能，取代了先前文档中记录的使用 CAST 的方法；作为参考，之前的用法如下所示：

from sqlalchemy import cast, type_coerce
from sqlalchemy import String, JSON

cast(data_table.c.data["some_key"], String) == type_coerce(55, JSON)

上述情况现在可以直接这样使用：

data_table.c.data["some_key"].as_integer() == 5

有关 1.3.x 系列中先前比较方法的详细信息，请参阅 SQLAlchemy 1.2 的文档或版本发行包的 doc/ 目录中包含的 HTML 文件。

使用 ORM 时检测 JSON 列中的更改

当与 SQLAlchemy ORM 一起使用时，JSON 类型不会检测到对结构的就地修改。为了检测这些修改，必须使用 sqlalchemy.ext.mutable 扩展，最常见的是使用 MutableDict 类。此扩展将允许对数据结构的“就地”更改生成将被工作单元检测到的事件。有关涉及字典的简单示例，请参阅 HSTORE 中的示例。

或者，将 JSON 结构分配给 ORM 元素以替换旧结构将始终触发更改事件。

对 JSON null 与 SQL NULL 的支持

当处理 NULL 值时，JSON 类型建议使用两个特定的常量，以便区分评估为 SQL NULL 的列（例如，没有值）与 JSON 编码的字符串 "null"。要插入或选择 SQL NULL 值，请使用常量 null()。此符号可以用作使用 JSON 数据类型时的参数值，该数据类型包含特殊的逻辑，将此符号解释为列值应为 SQL NULL 而不是 JSON "null"

from sqlalchemy import null

conn.execute(table.insert(), {"json_value": null()})

要插入或选择 JSON "null" 值，请使用常量 JSON.NULL

conn.execute(table.insert(), {"json_value": JSON.NULL})

JSON 类型支持一个标志 JSON.none_as_null，当设置为 True 时，Python 常量 None 将评估为 SQL NULL 值，当设置为 False 时，Python 常量 None 将评估为 JSON "null" 值。 Python 值 None 可以与 JSON.NULL 和 null() 结合使用以指示 NULL 值，但必须注意 JSON.none_as_null 的值在这些情况下的值。

自定义 JSON 序列化器

JSON 使用的 JSON 序列化器和反序列化器默认为 Python 的 json.dumps 和 json.loads 函数；对于 psycopg2 方言，psycopg2 可能会使用其自己的自定义加载器函数。

为了影响序列化器/反序列化器，目前可以在 create_engine() 级别通过 create_engine.json_serializer 和 create_engine.json_deserializer 参数进行配置。例如，要关闭 ensure_ascii

engine = create_engine(
    "sqlite://",
    json_serializer=lambda obj: json.dumps(obj, ensure_ascii=False),
)

1.3.7 版本更改: SQLite 方言的 json_serializer 和 json_deserializer 参数从 _json_serializer 和 _json_deserializer 重命名。

另请参阅

sqlalchemy.dialects.postgresql.JSON

sqlalchemy.dialects.postgresql.JSONB

sqlalchemy.dialects.mysql.JSON

sqlalchemy.dialects.sqlite.JSON

成员

as_boolean(), as_float(), as_integer(), as_json(), as_numeric(), as_string(), bind_processor(), literal_processor(), NULL, __init__(), bind_processor(), comparator_factory, hashable, python_type, result_processor(), should_evaluate_none

类签名

class sqlalchemy.types.JSON (sqlalchemy.types.Indexable, sqlalchemy.types.TypeEngine)

class Comparator¶

定义 JSON 的比较操作。

类签名

class sqlalchemy.types.JSON.Comparator (sqlalchemy.types.Comparator, sqlalchemy.types.Comparator)

method sqlalchemy.types.JSON.Comparator.as_boolean()¶

将索引值视为布尔值。

这类似于使用 type_coerce，通常不会应用 CAST()。

例如：

stmt = select(mytable.c.json_column["some_data"].as_boolean()).where(
    mytable.c.json_column["some_data"].as_boolean() == True
)

1.3.11 版本新增。

method sqlalchemy.types.JSON.Comparator.as_float()¶

将索引值视为浮点数。

这类似于使用 type_coerce，通常不会应用 CAST()。

例如：

stmt = select(mytable.c.json_column["some_data"].as_float()).where(
    mytable.c.json_column["some_data"].as_float() == 29.75
)

1.3.11 版本新增。

method sqlalchemy.types.JSON.Comparator.as_integer()¶

将索引值视为整数。

这类似于使用 type_coerce，通常不会应用 CAST()。

例如：

stmt = select(mytable.c.json_column["some_data"].as_integer()).where(
    mytable.c.json_column["some_data"].as_integer() == 5
)

1.3.11 版本新增。

method sqlalchemy.types.JSON.Comparator.as_json()¶

将索引值视为 JSON。

这类似于使用 type_coerce，通常不会应用 CAST()。

例如：

stmt = select(mytable.c.json_column["some_data"].as_json())

这通常是索引元素在任何情况下的默认行为。

请注意，并非所有后端都支持完整 JSON 结构的比较。

1.3.11 版本新增。

method sqlalchemy.types.JSON.Comparator.as_numeric(precision, scale, asdecimal=True)¶

将索引值视为数值/十进制数。

这类似于使用 type_coerce，通常不会应用 CAST()。

例如：

stmt = select(mytable.c.json_column["some_data"].as_numeric(10, 6)).where(
    mytable.c.json_column["some_data"].as_numeric(10, 6) == 29.75
)

1.4.0b2 版本新增。

method sqlalchemy.types.JSON.Comparator.as_string()¶

将索引值视为字符串。

这类似于使用 type_coerce，通常不会应用 CAST()。

例如：

stmt = select(mytable.c.json_column["some_data"].as_string()).where(
    mytable.c.json_column["some_data"].as_string() == "some string"
)

1.3.11 版本新增。

class JSONElementType¶

JSON 表达式中索引/路径元素的通用函数。

类签名

class sqlalchemy.types.JSON.JSONElementType (sqlalchemy.types.TypeEngine)

method sqlalchemy.types.JSON.JSONElementType.bind_processor(dialect: Dialect) → _BindProcessorType[Any]¶

返回用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收绑定参数值作为唯一的位置参数，并将返回要发送到 DB-API 的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.bind_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.bind_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_bind_param() 的实现。

另请参阅

增强现有类型

参数:: dialect¶ – 使用中的 Dialect 实例。

method sqlalchemy.types.JSON.JSONElementType.literal_processor(dialect: Dialect) → _LiteralProcessorType[Any]¶

返回一个转换函数，用于处理要直接呈现而不使用绑定的字面值。

当编译器使用 “literal_binds” 标志时，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并将返回一个字符串表示形式，以便在 SQL 语句中呈现。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.literal_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

增强现有类型

class JSONIndexType¶

JSON 索引值的数据类型占位符。

这允许对 JSON 索引值进行执行时处理，以实现特殊的语法。

类签名

class sqlalchemy.types.JSON.JSONIndexType (sqlalchemy.types.JSONElementType)

class JSONIntIndexType¶

JSON 索引值的数据类型占位符。

这允许对 JSON 索引值进行执行时处理，以实现特殊的语法。

类签名

class sqlalchemy.types.JSON.JSONIntIndexType (sqlalchemy.types.JSONIndexType)

class JSONPathType¶

JSON 路径操作的占位符类型。

这允许将基于路径的索引值执行时处理为特定的 SQL 语法。

类签名

class sqlalchemy.types.JSON.JSONPathType (sqlalchemy.types.JSONElementType)

class JSONStrIndexType¶

JSON 索引值的数据类型占位符。

这允许对 JSON 索引值进行执行时处理，以实现特殊的语法。

类签名

class sqlalchemy.types.JSON.JSONStrIndexType (sqlalchemy.types.JSONIndexType)

attribute sqlalchemy.types.JSON.NULL = symbol('JSON_NULL')¶

描述 JSON 的 NULL 值。

此值用于强制使用 JSON 值 "null" 作为值。Python None 值将被识别为 SQL NULL 或 JSON "null"，具体取决于 JSON.none_as_null 标志的设置；无论此设置如何，JSON.NULL 常量都可用于始终解析为 JSON "null"。这与始终解析为 SQL NULL 的 null() 构造形成对比。例如：

from sqlalchemy import null
from sqlalchemy.dialects.postgresql import JSON

# will *always* insert SQL NULL
obj1 = MyObject(json_value=null())

# will *always* insert JSON string "null"
obj2 = MyObject(json_value=JSON.NULL)

session.add_all([obj1, obj2])
session.commit()

为了将 JSON NULL 设置为列的默认值，最透明的方法是使用 text()

Table(
    "my_table", metadata, Column("json_data", JSON, default=text("'null'"))
)

虽然可以在此上下文中使用 JSON.NULL，但 JSON.NULL 值将作为列的值返回，这在 ORM 或默认值的其他用途的上下文中可能是不希望的。使用 SQL 表达式意味着将在检索生成的默认值的上下文中从数据库重新获取该值。

method sqlalchemy.types.JSON.__init__(none_as_null: bool = False)¶

构造一个 JSON 类型。

参数:

none_as_null=False¶ –

如果为 True，则将值 None 持久化为 SQL NULL 值，而不是 JSON 编码的 null。请注意，当此标志为 False 时，null() 构造仍然可以用于持久化 NULL 值，该值可以直接作为参数值传递，JSON 类型会专门将其解释为 SQL NULL

from sqlalchemy import null

conn.execute(table.insert(), {"data": null()})

注意

JSON.none_as_null 不适用于传递给 Column.default 和 Column.server_default 的值；为这些参数传递 None 值意味着“没有默认值”。

此外，当在 SQL 比较表达式中使用时，Python 值 None 继续引用 SQL null，而不是 JSON NULL。JSON.none_as_null 标志明确指的是 INSERT 或 UPDATE 语句中值的持久化。JSON.NULL 值应用于希望与 JSON null 进行比较的 SQL 表达式。

另请参阅

JSON.NULL

method sqlalchemy.types.JSON.bind_processor(dialect)¶

返回用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收绑定参数值作为唯一的位置参数，并将返回要发送到 DB-API 的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.bind_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.bind_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_bind_param() 的实现。

另请参阅

增强现有类型

参数:: dialect¶ – 使用中的 Dialect 实例。

attribute sqlalchemy.types.JSON.comparator_factory¶: 别名：Comparator

attribute sqlalchemy.types.JSON.hashable = False¶

标志，如果为 False，则表示此类型的值不可哈希。

ORM 在对结果列表进行去重时使用。

attribute sqlalchemy.types.JSON.python_type¶

method sqlalchemy.types.JSON.result_processor(dialect, coltype)¶

返回一个转换函数，用于处理结果行值。

返回一个可调用对象，它将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定的类型对象调用，该对象通常对于正在使用的方言是私有的，并且与面向公共的类型对象不是同一类型对象。这意味着为了提供备用的 TypeEngine.result_processor() 方法，除非显式地子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.result_processor() 提供备用行为，请实现 TypeDecorator 类，并提供 TypeDecorator.process_result_value() 的实现。

另请参阅

增强现有类型

参数:

dialect¶ – 使用中的 Dialect 实例。
coltype¶ – 在 cursor.description 中接收到的 DBAPI coltype 参数。

attribute sqlalchemy.types.JSON.should_evaluate_none: bool¶

如果为 True，则 Python 常量 None 被视为由此类型显式处理。

ORM 使用此标志来指示正值 None 传递给 INSERT 语句中的列，而不是从 INSERT 语句中省略该列，这会触发列级默认值。它还允许对 Python None 具有特殊行为的类型（例如 JSON 类型）指示它们希望显式处理 None 值。

要在现有类型上设置此标志，请使用 TypeEngine.evaluates_none() 方法。

另请参阅

TypeEngine.evaluates_none()

class sqlalchemy.types.INTEGER¶: SQL INT 或 INTEGER 类型。

另请参阅

Integer - 基础类型的文档。

类签名

class sqlalchemy.types.INTEGER (sqlalchemy.types.Integer)

class sqlalchemy.types.NCHAR¶

SQL NCHAR 类型。

成员

__init__()

类签名

class sqlalchemy.types.NCHAR (sqlalchemy.types.Unicode)

方法 sqlalchemy.types.NCHAR.__init__(length: int | None = None, collation: str | None = None)¶

继承自 sqlalchemy.types.String.__init__ 方法，源自 String

创建一个字符串保持类型。

参数:

length¶ – 可选参数，列的长度，用于 DDL 和 CAST 表达式。如果没有 CREATE TABLE 操作，可以安全地忽略此参数。某些数据库可能要求在 DDL 中使用 length，并且当发出 CREATE TABLE DDL 且包含没有长度的 VARCHAR 时，会引发异常。该值是解释为字节还是字符取决于具体的数据库。
collation¶ –
可选，列级排序规则，用于 DDL 和 CAST 表达式。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如：
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
注意

在大多数情况下，对于期望存储非 ASCII 数据的 Column，应使用 Unicode 或 UnicodeText 数据类型。这些数据类型将确保在数据库上使用了正确的类型。

class sqlalchemy.types.NVARCHAR¶

SQL NVARCHAR 类型。

成员

__init__()

类签名

class sqlalchemy.types.NVARCHAR (sqlalchemy.types.Unicode)

方法 sqlalchemy.types.NVARCHAR.__init__(length: int | None = None, collation: str | None = None)¶

继承自 sqlalchemy.types.String.__init__ 方法，源自 String

创建一个字符串保持类型。

参数:

length¶ – 可选参数，列的长度，用于 DDL 和 CAST 表达式。如果没有 CREATE TABLE 操作，可以安全地忽略此参数。某些数据库可能要求在 DDL 中使用 length，并且当发出 CREATE TABLE DDL 且包含没有长度的 VARCHAR 时，会引发异常。该值是解释为字节还是字符取决于具体的数据库。
collation¶ –
可选，列级排序规则，用于 DDL 和 CAST 表达式。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如：
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
注意

在大多数情况下，对于期望存储非 ASCII 数据的 Column，应使用 Unicode 或 UnicodeText 数据类型。这些数据类型将确保在数据库上使用了正确的类型。

class sqlalchemy.types.NUMERIC¶

SQL NUMERIC 类型。

另请参阅

Numeric - 基础类型的文档。

成员

__init__()

类签名

class sqlalchemy.types.NUMERIC (sqlalchemy.types.Numeric)

方法 sqlalchemy.types.NUMERIC.__init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)¶

继承自 sqlalchemy.types.Numeric.__init__ 方法，源自 Numeric

构造一个 Numeric 对象。

参数:

precision¶ – 数值精度，用于 DDL CREATE TABLE。
scale¶ – 数值标度，用于 DDL CREATE TABLE。
asdecimal¶ – 默认为 True。返回是否应将值作为 Python Decimal 对象或浮点数发送。不同的 DBAPI 根据数据类型发送其中一种 - Numeric 类型将确保跨 DBAPI 返回的值是一致的。
decimal_return_scale¶ – 从浮点数转换为 Python decimals 时使用的默认标度。由于十进制精度不高，浮点值通常会更长，并且大多数浮点数据库类型没有“scale”的概念，因此默认情况下，float 类型在转换时会查找前十位小数。指定此值将覆盖该长度。包含显式 “.scale” 值的类型，例如基本 Numeric 以及 MySQL 浮点类型，如果未另行指定，将使用 “.scale” 的值作为 decimal_return_scale 的默认值。

当使用 Numeric 类型时，应注意确保 asdecimal 设置适合正在使用的 DBAPI - 当 Numeric 应用从 Decimal->float 或 float->Decimal 的转换时，此转换会为接收到的所有结果列产生额外的性能开销。

原生返回 Decimal 的 DBAPI（例如 psycopg2）在设置为 True 时将具有更好的精度和更高的性能，因为原生转换为 Decimal 减少了浮点问题，并且 Numeric 类型本身不需要应用任何进一步的转换。但是，另一个原生返回 float 的 DBAPI *将* 产生额外的转换开销，并且仍然会受到浮点数据丢失的影响 - 在这种情况下，asdecimal=False 至少会消除额外的转换开销。

class sqlalchemy.types.REAL¶

SQL REAL 类型。

另请参阅

Float - 基础类型的文档。

成员

__init__()

类签名

class sqlalchemy.types.REAL (sqlalchemy.types.Float)

方法 sqlalchemy.types.REAL.__init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)¶

继承自 sqlalchemy.types.Float.__init__ 方法，源自 Float

构造一个 Float 对象。

参数:

precision¶ –
用于 DDL CREATE TABLE 中的数值精度。后端应该尝试确保此精度指示通用 Float 数据类型的位数。
注意

对于 Oracle Database 后端，呈现 DDL 时不接受 Float.precision 参数，因为 Oracle Database 不支持指定为小数位数的浮点精度。请改用 Oracle Database 特定的 FLOAT 数据类型，并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版本的新增功能。

要创建一个数据库无关的 Float，并为 Oracle Database 单独指定二进制精度，请使用 TypeEngine.with_variant()，如下所示
```
from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
)
```
asdecimal¶ – 与 Numeric 相同的标志，但默认为 False。请注意，将此标志设置为 True 会导致浮点转换。
decimal_return_scale¶ – 从浮点数转换为 Python decimals 时使用的默认标度。由于十进制精度不高，浮点值通常会更长，并且大多数浮点数据库类型没有“scale”的概念，因此默认情况下，float 类型在转换时会查找前十位小数。指定此值将覆盖该长度。请注意，MySQL 浮点类型（确实包含“scale”）如果未另行指定，将使用 “scale” 作为 decimal_return_scale 的默认值。

class sqlalchemy.types.SMALLINT¶: SQL SMALLINT 类型。

另请参阅

SmallInteger - 基础类型的文档。

类签名

class sqlalchemy.types.SMALLINT (sqlalchemy.types.SmallInteger)

class sqlalchemy.types.TEXT¶

SQL TEXT 类型。

成员

__init__()

类签名

class sqlalchemy.types.TEXT (sqlalchemy.types.Text)

方法 sqlalchemy.types.TEXT.__init__(length: int | None = None, collation: str | None = None)¶

继承自 sqlalchemy.types.String.__init__ 方法，源自 String

创建一个字符串保持类型。

参数:

length¶ – 可选参数，列的长度，用于 DDL 和 CAST 表达式。如果没有 CREATE TABLE 操作，可以安全地忽略此参数。某些数据库可能要求在 DDL 中使用 length，并且当发出 CREATE TABLE DDL 且包含没有长度的 VARCHAR 时，会引发异常。该值是解释为字节还是字符取决于具体的数据库。
collation¶ –
可选，列级排序规则，用于 DDL 和 CAST 表达式。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如：
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
注意

在大多数情况下，对于期望存储非 ASCII 数据的 Column，应使用 Unicode 或 UnicodeText 数据类型。这些数据类型将确保在数据库上使用了正确的类型。

class sqlalchemy.types.TIME¶: SQL TIME 类型。

类签名

class sqlalchemy.types.TIME (sqlalchemy.types.Time)

class sqlalchemy.types.TIMESTAMP¶

SQL TIMESTAMP 类型。

TIMESTAMP 数据类型在某些后端（例如 PostgreSQL 和 Oracle 数据库）上支持时区存储。使用 TIMESTAMP.timezone 参数以启用这些后端的“TIMESTAMP WITH TIMEZONE”。

成员

__init__(), get_dbapi_type()

类签名

class sqlalchemy.types.TIMESTAMP (sqlalchemy.types.DateTime)

方法 sqlalchemy.types.TIMESTAMP.__init__(timezone: bool = False)¶

构造一个新的 TIMESTAMP。

参数:: timezone¶ – 布尔值。指示 TIMESTAMP 类型应启用时区支持（如果在目标数据库上可用）。在每个方言的基础上，类似于“TIMESTAMP WITH TIMEZONE”。如果目标数据库不支持时区，则忽略此标志。

方法 sqlalchemy.types.TIMESTAMP.get_dbapi_type(dbapi)¶

如果存在，则从底层 DB-API 返回相应的类型对象。

例如，这对于调用 setinputsizes() 很有用。

class sqlalchemy.types.UUID¶

表示 SQL UUID 类型。

这是 Uuid 数据库无关数据类型的 SQL 原生形式，并且向后兼容以前的仅 PostgreSQL 版本的 UUID。

UUID 数据类型仅在具有名为 UUID 的 SQL 数据类型的数据库上有效。它不适用于没有此精确命名类型的后端，包括 SQL Server。对于具有原生支持的后端无关 UUID 值，包括 SQL Server 的 UNIQUEIDENTIFIER 数据类型，请使用 Uuid 数据类型。

2.0 版本新增。

另请参阅

Uuid

成员

__init__()

类签名

class sqlalchemy.types.UUID (sqlalchemy.types.Uuid, sqlalchemy.types.NativeForEmulated)

方法 sqlalchemy.types.UUID.__init__(as_uuid: bool = True)¶

构造一个 UUID 类型。

参数:

as_uuid=True¶ –

如果为 True，则值将被解释为 Python uuid 对象，通过 DBAPI 转换为/从字符串转换。

class sqlalchemy.types.VARBINARY¶: SQL VARBINARY 类型。

类签名

class sqlalchemy.types.VARBINARY (sqlalchemy.types._Binary)

class sqlalchemy.types.VARCHAR¶

SQL VARCHAR 类型。

成员

__init__()

类签名

class sqlalchemy.types.VARCHAR (sqlalchemy.types.String)

方法 sqlalchemy.types.VARCHAR.__init__(length: int | None = None, collation: str | None = None)¶

继承自 sqlalchemy.types.String.__init__ 方法，源自 String

创建一个字符串保持类型。

参数:

length¶ – 可选参数，列的长度，用于 DDL 和 CAST 表达式。如果没有 CREATE TABLE 操作，可以安全地忽略此参数。某些数据库可能要求在 DDL 中使用 length，并且当发出 CREATE TABLE DDL 且包含没有长度的 VARCHAR 时，会引发异常。该值是解释为字节还是字符取决于具体的数据库。
collation¶ –
可选，列级排序规则，用于 DDL 和 CAST 表达式。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如：
```
>>> from sqlalchemy import cast, select, String
>>> print(select(cast("some string", String(collation="utf8"))))
SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
```
注意

在大多数情况下，对于期望存储非 ASCII 数据的 Column，应使用 Unicode 或 UnicodeText 数据类型。这些数据类型将确保在数据库上使用了正确的类型。

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy Core

项目版本

类型层次结构¶

“驼峰式” 数据类型¶

“大写” 数据类型¶

后端特定的 “大写” 数据类型¶

为多个后端使用 “大写” 和后端特定类型¶

通用 “驼峰式” 类型¶

SQL 标准和多厂商 “UPPERCASE” 类型¶