类型层次结构

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

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

另请参阅

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

“驼峰式”数据类型

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

一个简单的“驼峰式”数据类型示例是 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 应用程序可能希望在一般情况下主要使用“驼峰式”类型，因为它们通常提供最佳的基本行为，并且可以自动移植到所有后端。

通用“驼峰式”数据类型的参考见下文 通用“驼峰式”类型。

“大写”数据类型

与“CamelCase”类型对比，“UPPERCASE”数据类型始终从特定的“CamelCase”数据类型继承，并且始终表示确切的数据类型。使用“UPPERCASE”数据类型时，类型的名称始终按原样呈现，而不考虑当前后端是否支持它。因此，在 SQLAlchemy 应用程序中使用“UPPERCASE”类型意味着需要特定的数据类型，这意味着应用程序通常在没有采取额外步骤的情况下，将仅限于那些按原样使用该类型的后端。 “UPPERCASE”类型示例包括VARCHAR、NUMERIC、INTEGER 和 TIMESTAMP，它们分别直接继承自之前提到的“CamelCase”类型String、Numeric、Integer 和 DateTime。

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

有关一般“UPPERCASE”数据类型集的参考请参见下面的SQL 标准和多个供应商“UPPERCASE”类型。

后端特定的“UPPERCASE”数据类型

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

特定后端还可以包括扩展了 sqlalchemy.types 模块中找到的相同“UPPERCASE”数据类型可用参数的“UPPERCASE”数据类型。例如，在创建 MySQL 字符串数据类型时，您可能希望指定 MySQL 特定的参数，例如 charset 或 national，它们在 MySQL 版本的 VARCHAR 中作为 MySQL 特定的参数 VARCHAR.charset 和 VARCHAR.national 可用。

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

在多个后端中使用“UPPERCASE”和后端特定类型

回顾“UPPERCASE”和“CamelCase”类型的存在，会自然而然地想到如何使用“UPPERCASE”数据类型来获得后端特定的选项，但前提是只有在使用该后端时才能使用。为了将与数据库无关的“CamelCase”和后端特定的“UPPERCASE”系统联系起来，可以使用 TypeEngine.with_variant() 方法来组合类型，以便在特定后端上使用特定行为。

例如，要使用 String 数据类型，但在 MySQL 上运行时使用 VARCHAR.charset 参数的 VARCHAR，当表在 MySQL 或 MariaDB 上创建时，可以按如下所示使用 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() - 其他使用示例和注意事项

通用“CamelCase”类型

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

对象名称	描述
BigInteger	用于更大 int 整数的类型。
Boolean	一个 bool 数据类型。
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

一个 bool 数据类型。

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

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

在版本 1.2 中更改： Boolean 数据类型现在断言传入的 Python 值已经处于纯布尔形式。

成员

__init__()、bind_processor()、literal_processor()、python_type、result_processor()

类签名

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

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

构造一个布尔值。

参数:

• create_constraint –

  默认为 False。如果布尔值被生成为 int/smallint，还会在表上创建一个 CHECK 约束，以确保值是 1 或 0。

  注意

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

  在版本 1.4 中更改: - 此标志现在默认为 False，这意味着对于非本地枚举类型，不会生成 CHECK 约束。

• name – 如果生成 CHECK 约束，请指定约束的名称。

方法 sqlalchemy.types.Boolean.bind_processor(dialect)

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

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.bind_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数:

dialect – 使用的方言实例。

方法 sqlalchemy.types.Boolean.literal_processor(dialect)

返回用于处理将直接呈现而无需使用绑定值的文字值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

属性 sqlalchemy.types.Boolean.python_type

方法 sqlalchemy.types.Boolean.result_processor(dialect, coltype)

返回用于处理结果行值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.result_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数:

• dialect – 使用的方言实例。

• coltype – 在 cursor.description 中接收到的 DBAPI coltype 参数。

类 sqlalchemy.types.Date

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

成员

get_dbapi_type(), literal_processor(), python_type

类签名

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

方法 sqlalchemy.types.Date.get_dbapi_type(dbapi)

返回底层 DB-API 中的对应类型对象（如果有）。

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

方法 sqlalchemy.types.Date.literal_processor(dialect)

返回用于处理将直接呈现而无需使用绑定值的文字值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

属性 sqlalchemy.types.Date.python_type

类 sqlalchemy.types.DateTime

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

日期和时间类型返回来自 Python datetime 模块的对象。大多数 DBAPI 都内置支持 datetime 模块，SQLite 是一个明显的例外。在 SQLite 的情况下，日期和时间类型存储为字符串，然后在返回行时将其转换为 datetime 对象。

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

成员

__init__()，get_dbapi_type()，literal_processor()，python_type

类签名

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

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

构造一个新的 DateTime。

参数:

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

方法 sqlalchemy.types.DateTime.get_dbapi_type(dbapi)

返回底层 DB-API 中的对应类型对象（如果有）。

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

方法 sqlalchemy.types.DateTime.literal_processor(dialect)

返回用于处理将直接呈现而无需使用绑定值的文字值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

属性 sqlalchemy.types.DateTime.python_type

类 sqlalchemy.types.Enum

通用枚举类型。

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

Enum 类型将使用后端的本机“ENUM”类型（如果可用）；否则，它使用 VARCHAR 数据类型。还有一种选择是在生成 VARCHAR（称为“非本机”）变体时自动生成 CHECK 约束；请参见 Enum.create_constraint 标志。

Enum 类型还在读写操作期间提供对 Python 中字符串值的验证。从数据库中的结果集中读取值时，字符串值始终与可能的 value 列表进行检查，如果未找到匹配项，则会引发 LookupError。在 SQL 语句中将值作为纯字符串传递给数据库时，如果 Enum.validate_strings 参数设置为 True，则会为不在给定可能的 value 列表中的任何字符串值引发 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()

类签名

类 sqlalchemy.types.Enum (sqlalchemy.types.String，sqlalchemy.types.SchemaType，sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

方法 sqlalchemy.types.Enum.__init__(*enums: object, **kw: Any)

构造一个枚举。

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

参数:

• *enums – 可以是单个符合 PEP-435 规范的枚举类型，也可以是一或多个字符串标签。

• create_constraint –

  默认值为 False。当创建非原生枚举类型时，还会在数据库中针对有效值构建 CHECK 约束。

  注意

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

  在版本 1.4 中更改: - 此标志现在默认为 False，这意味着对于非本地枚举类型，不会生成 CHECK 约束。

• metadata –

  将此类型直接与 MetaData 对象关联。对于作为独立模式结构存在于目标数据库中的类型（PostgreSQL），此类型将在 create_all() 和 drop_all() 操作中创建和删除。如果类型未与任何 MetaData 对象关联，它将与其中使用的每个 Table 关联，并在创建任何这些单个表时创建，并在执行存在性检查后创建。但是，只有当针对该 Table 对象的元数据调用 drop_all() 时，才会删除该类型。

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

  在版本 1.4.12 中更改: Enum 继承 MetaData.schema 参数，如果存在，则使用 MetaData 对象，通过 Enum.metadata 参数传递。

• name – 此类型的名称。对于 PostgreSQL 和任何将来支持的需要显式命名类型或显式命名约束以生成类型或使用该类型的表的数据库，此参数是必需的。如果使用了 PEP-435 枚举类，则默认情况下会使用其名称（转换为小写）。

• native_enum – 当可用时，使用数据库的原生 ENUM 类型。默认为 True。当为 False 时，对所有后端使用 VARCHAR + 检查约束。当为 False 时，可以使用 Enum.length 控制 VARCHAR 长度；当前如果 native_enum=True，则会忽略“length”。

• length –

  允许在使用非原生枚举数据类型时指定 VARCHAR 的自定义长度。默认情况下，它使用最长值的长度。

  在版本 2.0.0 中更改: 无论 Enum.native_enum 参数如何，Enum.length 参数始终用于 VARCHAR 渲染，对于那些使用 VARCHAR 作为枚举数据类型的后端。

• schema –

  此类型的模式名称。对于作为独立模式结构存在于目标数据库中的类型（PostgreSQL），此参数指定类型所在的命名模式。

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

  在版本 1.4.12 中更改: Enum 继承 MetaData.schema 参数，如果存在，则使用 MetaData 对象，通过 Enum.metadata 参数传递。

  否则，如果将 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]。

  在版本 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。

默认情况下，此类型返回 Python float 对象，除非 Float.asdecimal 标志设置为 True，在这种情况下，它们将被强制转换为 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 后端，在渲染 DDL 时不接受 Float.precision 参数，因为 Oracle 不支持以小数位数指定的浮点精度。相反，使用特定于 Oracle 的 FLOAT 数据类型并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版中的新增功能。

  要创建独立指定 Oracle 二进制精度的数据库无关 Float，请按如下方式使用 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 十进制数时使用的默认比例。由于十进制精度的原因，浮点值通常会长得多，并且大多数浮点数据库类型没有“比例”的概念，因此默认情况下，浮点类型在转换时会查找前十个小数位。指定此值将覆盖该长度。请注意，MySQL 浮点类型（确实包含“比例”）将使用“比例”作为 decimal_return_scale 的默认值，除非另有指定。

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

返回用于处理结果行值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.result_processor() 方法，除非显式子类化 UserDefinedType 类。

要为 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 类以提供备用 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

要为 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 中，使用本机 INTERVAL 类型；对于其他类型，值存储为相对于“纪元”（1970 年 1 月 1 日）的日期。

请注意，Interval 类型目前没有在不支持间隔类型的平台上提供日期算术运算。此类操作通常需要对表达式的两侧进行转换（例如，首先将两侧转换为整数纪元值），这目前是一个手动过程（例如，通过 expression.func）。

成员

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

类签名

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

class Comparator

类签名

类 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）。否则，无论如何将间隔数据表示为纪元值。

• second_precision – 对于支持“小数秒精度”参数的原生间隔类型，即 Oracle 和 PostgreSQL。

• day_precision – 对于支持“日精度”参数的原生间隔类型，即 Oracle。

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

给定一个 impl 类，假设“模拟”，将此类型适配到 impl。

impl 也应该是此类型的“模拟”版本，最有可能与此类型本身相同。

例如：sqltypes.Enum 适配到 Enum 类。

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

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

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.bind_processor() 方法，除非显式子类化 UserDefinedType 类。

要为 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 中的新内容： - 添加了 cache_ok 标志，以允许对 TypeDecorator 类的缓存进行一些配置。

版本 1.4.28 中的新内容： - 添加了 ExternalType 混合，它将 cache_ok 标志推广到 TypeDecorator 和 UserDefinedType 类。

另请参阅

SQL 编译缓存

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

建议在表达式中“强制转换”的 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 类以提供备用 TypeEngine.result_processor() 方法，除非显式子类化 UserDefinedType 类。

要为 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。

注意

当对返回 Python 浮点值的数据库类型使用 Numeric 数据类型时，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 对象发送，还是作为浮点数发送。不同的 DBAPI 根据数据类型发送其中之一 - Numeric 类型将确保返回值在不同的 DBAPI 中始终一致。

• decimal_return_scale – 从浮点数转换为 Python 十进制数时使用的默认比例。由于小数精度问题，浮点数通常会更长，而且大多数浮点数数据库类型没有“比例”的概念，因此默认情况下，浮点类型在转换时会查找前十个小数位。指定此值将覆盖该长度。包含显式“.scale”值的类型，例如基本 Numeric 以及 MySQL 浮点类型，将使用“.scale”的值作为 decimal_return_scale 的默认值，除非另有指定。

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

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

method sqlalchemy.types.Numeric.bind_processor(dialect)

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

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.bind_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数:

dialect – 所使用的 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 类以提供备用 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

attribute sqlalchemy.types.Numeric.python_type

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

返回用于处理结果行值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.result_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数:

• dialect – 所使用的 Dialect 实例。

• coltype – 在 cursor.description 中接收的 DBAPI coltype 参数。

class sqlalchemy.types.PickleType

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

PickleType 基于 Binary 类型，对传入的对象应用 Python 的 pickle.dumps()，并在传出时应用 pickle.loads()，允许任何可 pickle 的 Python 对象存储为序列化二进制字段。

为了允许与 PickleType 关联的元素的 ORM 更改事件传播，请参见 可变跟踪。

成员

__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。例如，:class: _mysql.LONGBLOB 类在使用 MySQL 时可能更有效。

  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 中的新内容： - 添加了 cache_ok 标志，以允许对 TypeDecorator 类的缓存进行一些配置。

版本 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()

类签名

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

方法 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
  

  注意

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

方法 sqlalchemy.types.String.bind_processor(dialect)

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

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.bind_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数:

dialect – 使用中的方言实例。

方法 sqlalchemy.types.String.get_dbapi_type(dbapi)

返回底层 DB-API 中的对应类型对象（如果有）。

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

方法 sqlalchemy.types.String.literal_processor(dialect)

返回用于处理将直接呈现而无需使用绑定值的文字值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

属性 sqlalchemy.types.String.python_type

方法 sqlalchemy.types.String.result_processor(dialect, coltype)

返回用于处理结果行值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.result_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数:

• dialect – 使用中的方言实例。

• coltype – 在 cursor.description 中接收到的 DBAPI coltype 参数。

类 sqlalchemy.types.Text

可变大小的字符串类型。

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

类签名

类 sqlalchemy.types.Text (sqlalchemy.types.String)

类 sqlalchemy.types.Time

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

成员

get_dbapi_type(), literal_processor(), python_type

类签名

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

方法 sqlalchemy.types.Time.get_dbapi_type(dbapi)

返回底层 DB-API 中的对应类型对象（如果有）。

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

方法 sqlalchemy.types.Time.literal_processor(dialect)

返回用于处理将直接呈现而无需使用绑定值的文字值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

属性 sqlalchemy.types.Time.python_type

类 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。

警告

某些数据库后端，特别是 SQL Server 和 pyodbc，已知在处理被标记为 NVARCHAR 类型而不是 VARCHAR 类型的方面存在不良行为，包括数据类型不匹配错误和未使用索引。有关使用 SQL Server 和 pyodbc 以及 cx_Oracle 等后端解决 Unicode 字符问题的更多信息，请参阅关于 DialectEvents.do_setinputsizes() 的部分。

另请参阅

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

DialectEvents.do_setinputsizes()

类签名

类 sqlalchemy.types.Unicode (sqlalchemy.types.String)

类 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 个字符的十六进制字符串）一起使用，请使用值为 False 的 Uuid.as_uuid 参数。

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 类以提供备用 TypeEngine.bind_processor() 方法，除非显式子类化 UserDefinedType 类。

要为 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 类以提供备用 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

attribute sqlalchemy.types.Uuid.python_type

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

返回用于处理结果行值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.result_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数:

• dialect – 使用中的方言实例。

• coltype – 在 cursor.description 中接收到的 DBAPI coltype 参数。

SQL 标准和多个供应商的“大写”类型

此类类型指的是 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 是核心的一部分，支持各种 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 对象的 ARRAY 使用此数字来有效地访问数组结构内部的字符串值，而无需诉诸逐行类型检查。

• 当与 Python getitem 访问器一起使用时，维数用于定义 [] 运算符应返回的类型，例如对于具有两个维度的 INTEGER 的 ARRAY

  >>> expr = table.c.column[5]  # returns ARRAY(Integer, dimensions=1)
  >>> expr = expr[6]  # returns Integer

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

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

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 将假设固定数量的维数。这会影响 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 类型未实现 ARRAY.contains()。使用特定于方言的 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

构造一个布尔值。

参数:

• create_constraint –

  默认为 False。如果布尔值被生成为 int/smallint，还会在表上创建一个 CHECK 约束，以确保值是 1 或 0。

  注意

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

  在版本 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，并且当发出 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
  

  注意

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

class sqlalchemy.types.CLOB

CLOB 类型。

此类型存在于 Oracle 和 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，并且在发出 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
  

  注意

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

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。

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 十进制数时使用的默认小数位数。由于小数位数不精确，浮点数通常会长得多，并且大多数浮点数数据库类型没有“小数位数”的概念，因此默认情况下，浮点数类型在转换时会寻找前十位小数位数。指定此值将覆盖该长度。包含显式“.scale”值的类型，例如基本 Numeric 以及 MySQL 浮点数类型，将使用“.scale”的值作为 decimal_return_scale 的默认值，如果未另行指定。

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

本机返回 Decimal 的 DBAPI（例如 psycopg2）在设置为 True 时将具有更好的精度和更高的性能，因为对 Decimal 的本机翻译减少了浮点数问题的数量，并且 Numeric 类型本身不需要应用任何进一步的转换。但是，另一个本机返回浮点数的 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 后端，在渲染 DDL 时不接受 Float.precision 参数，因为 Oracle 不支持以小数位数指定的浮点精度。相反，使用特定于 Oracle 的 FLOAT 数据类型并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版中的新增功能。

  要创建独立指定 Oracle 二进制精度的数据库无关 Float，请按如下方式使用 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 十进制数时使用的默认小数位数。由于十进制精度问题，浮点数通常会长得多，而且大多数浮点数据库类型都没有“小数位数”的概念，因此默认情况下，浮点类型在转换时会查找前十位小数。指定此值将覆盖该长度。请注意，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 后端，在渲染 DDL 时不接受 Float.precision 参数，因为 Oracle 不支持以小数位数指定的浮点精度。相反，使用特定于 Oracle 的 FLOAT 数据类型并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版中的新增功能。

  要创建独立指定 Oracle 二进制精度的数据库无关 Float，请按如下方式使用 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 十进制数时使用的默认小数位数。由于十进制精度问题，浮点数通常会长得多，而且大多数浮点数据库类型都没有“小数位数”的概念，因此默认情况下，浮点类型在转换时会查找前十位小数。指定此值将覆盖该长度。请注意，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 后端，在渲染 DDL 时不接受 Float.precision 参数，因为 Oracle 不支持以小数位数指定的浮点精度。相反，使用特定于 Oracle 的 FLOAT 数据类型并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版中的新增功能。

  要创建独立指定 Oracle 二进制精度的数据库无关 Float，请按如下方式使用 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 十进制数时使用的默认小数位数。由于十进制精度问题，浮点数通常会长得多，而且大多数浮点数据库类型都没有“小数位数”的概念，因此默认情况下，浮点类型在转换时会查找前十位小数。指定此值将覆盖该长度。请注意，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 是核心的一部分，以支持越来越流行的原生 JSON 数据类型。

The 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 的表达式运算符

The 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（即无值）的列与 "null" 的 JSON 编码字符串。要插入或选择 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)

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

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.bind_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数:

dialect – 使用的方言实例。

method sqlalchemy.types.JSON.JSONElementType.literal_processor(dialect)

返回用于处理将直接呈现而无需使用绑定值的文字值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

要为 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')

描述 NULL 的 json 值。

此值用于强制使用 "null" 作为 JSON 值。Python None 值将被识别为 SQL NULL 或 JSON "null"，具体取决于 JSON.none_as_null 标志的设置；JSON.NULL 常量可用于始终解析为 JSON "null"，而与此设置无关。这与 null() 结构形成对比，后者始终解析为 SQL 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 值持久化，而不是 null 的 JSON 编码。请注意，当此标志为 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

方法 sqlalchemy.types.JSON.bind_processor(dialect)

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

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.bind_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数:

dialect – 所使用的方言实例。

属性 sqlalchemy.types.JSON.comparator_factory

Comparator 的别名

属性 sqlalchemy.types.JSON.hashable = False

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

ORM 在对结果列表进行唯一化时使用此标志。

属性 sqlalchemy.types.JSON.python_type

方法 sqlalchemy.types.JSON.result_processor(dialect, coltype)

返回用于处理结果行值的转换函数。

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

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

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常特定于使用的方言，并且与面向公众的类型对象不同，这意味着不可能子类化 TypeEngine 类以提供备用 TypeEngine.result_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数:

• dialect – 所使用的方言实例。

• coltype – 在 cursor.description 中接收到的 DBAPI coltype 参数。

属性 sqlalchemy.types.JSON.should_evaluate_none: bool

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

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

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

另请参阅

TypeEngine.evaluates_none()

类 sqlalchemy.types.INTEGER

SQL INT 或 INTEGER 类型。

另请参阅

Integer - 基本类型的文档。

类签名

类 sqlalchemy.types.INTEGER (sqlalchemy.types.Integer)

类 sqlalchemy.types.NCHAR

SQL NCHAR 类型。

成员

__init__()

类签名

类 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，则可以安全地省略。某些数据库可能需要一个 length 用于 DDL，并且当发出 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
  

  注意

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

类 sqlalchemy.types.NVARCHAR

SQL NVARCHAR 类型。

成员

__init__()

类签名

类 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，则可以安全地省略。某些数据库可能需要一个 length 用于 DDL，并且当发出 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
  

  注意

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

类 sqlalchemy.types.NUMERIC

SQL NUMERIC 类型。

另请参阅

Numeric - 基本类型的文档。

成员

__init__()

类签名

类 sqlalchemy.types.NUMERIC (sqlalchemy.types.Numeric)

method 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 十进制数时使用的默认小数位数。由于十进制精度问题，浮点数通常要长得多，并且大多数浮点数据库类型没有“小数位数”的概念，因此默认情况下，浮点类型在转换时会查找前十个小数位。指定此值将覆盖该长度。包含显式“.scale”值的类型，例如基本 Numeric 以及 MySQL float 类型，如果未明确指定，则将使用“.scale”的值作为 decimal_return_scale 的默认值。

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

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

class sqlalchemy.types.REAL

SQL REAL 类型。

另请参阅

Float - 基础类型文档。

成员

__init__()

类签名

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

method 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 后端，在渲染 DDL 时不接受 Float.precision 参数，因为 Oracle 不支持以小数位数指定的浮点精度。相反，使用特定于 Oracle 的 FLOAT 数据类型并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版中的新增功能。

  要创建独立指定 Oracle 二进制精度的数据库无关 Float，请按如下方式使用 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 十进制数时使用的默认小数位数。由于十进制精度问题，浮点数通常要长得多，并且大多数浮点数据库类型没有“小数位数”的概念，因此默认情况下，浮点类型在转换时会查找前十个小数位。指定此值将覆盖该长度。请注意，MySQL float 类型（包含“小数位数”）将使用“小数位数”作为 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)

method sqlalchemy.types.TEXT.__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
  

  注意

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

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)

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

构造一个新的 TIMESTAMP。

参数:

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

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

返回底层 DB-API 中的对应类型对象（如果有）。

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

类 sqlalchemy.types.UUID

表示 SQL UUID 类型。

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

UUID 数据类型仅适用于具有名为 UUID 的 SQL 数据类型的数据库。它不适用于没有此确切类型名称的后端，包括 SQL Server。对于具有本地支持的与后端无关的 UUID 值，包括 SQL Server 的 UNIQUEIDENTIFIER 数据类型，请使用 Uuid 数据类型。

2.0 版新增。

另请参阅

Uuid

成员

__init__()

类签名

类 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 在字符串之间进行转换。

类 sqlalchemy.types.VARBINARY

SQL VARBINARY 类型。

类签名

类 sqlalchemy.types.VARBINARY (sqlalchemy.types._Binary)

类 sqlalchemy.types.VARCHAR

SQL VARCHAR 类型。

成员

__init__()

类签名

类 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，可以安全地省略。某些数据库可能需要 length 用于 DDL，并在发出 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
  

  注意

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