SqlAlchemy 2.0 中文文档（四十一）（8）

SqlAlchemy 2.0 中文文档（四十一）（7）https://developer.aliyun.com/article/1563086

类签名

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

method __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 bind_processor(dialect)

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

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

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

注意

此方法仅相对于特定方言的类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是与公共类型对象相同的类型对象，这意味着无法通过子类化TypeEngine类来提供备用TypeEngine.bind_processor()方法，除非明确地子类化UserDefinedType类。

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

另请参见

扩展现有类型

参数：

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

method coerce_compared_value(op, value)

查看TypeEngine.coerce_compared_value()以获取描述信息。

method literal_processor(dialect)

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

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

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

注意

此方法仅针对特定方言的类型对象调用，该对象通常私有于正在使用的方言，并且不是公共面向的类型对象，这意味着不可能通过子类化TypeEngine类来提供替代TypeEngine.literal_processor()方法，除非显式子类化UserDefinedType类。

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

另请参阅

扩展现有类型

attribute python_type

method 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 中发出。

class sqlalchemy.types.ARRAY

表示 SQL 数组类型。

注意

此类型为所有 ARRAY 操作提供了基础。然而，目前只有 PostgreSQL 后端支持 SQL 数组在 SQLAlchemy 中。建议在与 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对象组成的数组使用此数字来有效地访问数组结构内的字符串值，而不是使用每行类型检查。
  
• 当与 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]
})

索引访问默认为基于一的；要进行从零开始的索引转换，请设置ARRAY.zero_indexes。

ARRAY 类型还提供了操作符 Comparator.any() 和 Comparator.all()。PostgreSQL 特定版本的 ARRAY 还提供了额外的操作符。

在使用 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()

类签名

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

method __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 以零为基础和 SQL 以一为基础的索引之间转换，例如，在传递给数据库之前，所有索引值都将增加一个值。
  

class Comparator

为 ARRAY 定义比较操作。

此类型的特定于方言的形式上还提供了更多操作符。请参阅 Comparator。

类签名

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

method contains(*arg, **kw)

ARRAY.contains() 未为基本 ARRAY 类型实现。请使用特定于方言的 ARRAY 类型。

请参阅

ARRAY - PostgreSQL 特定版本。

method 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 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 - 基本类型的文档。

类签名

类sqlalchemy.types.BIGINT（sqlalchemy.types.BigInteger）

class sqlalchemy.types.BINARY

SQL BINARY 类型。

类签名

类sqlalchemy.types.BINARY（sqlalchemy.types._Binary）

class sqlalchemy.types.BLOB

SQL BLOB 类型。

成员

init()

类签名

类sqlalchemy.types.BLOB（sqlalchemy.types.LargeBinary）

method __init__(length: int | None = None)

继承自 LargeBinary 的 sqlalchemy.types.LargeBinary.__init__ 方法

构造一个 LargeBinary 类型。

参数：

length – 可选，用于 DDL 语句中的列长度，用于那些接受长度的二进制类型，如 MySQL BLOB 类型。

class sqlalchemy.types.BOOLEAN

SQL BOOLEAN 类型。

成员

init()

类签名

类sqlalchemy.types.BOOLEAN（sqlalchemy.types.Boolean）

method __init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)

继承自 Boolean 的 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 __init__(length: int | None = None, collation: str | None = None)

从 String 的 sqlalchemy.types.String.__init__ 方法继承

创建一个持有字符串的类型。

参数：

• length – 可选项，用于 DDL 和 CAST 表达式中列的长度。如果不会发出CREATE TABLE，可以安全地省略。某些数据库可能需要 DDL 中的length，如果包括了没有长度的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.CLOB

CLOB 类型。

此类型在 Oracle 和 Informix 中找到。

成员

init()

类签名

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

method __init__(length: int | None = None, collation: str | None = None)

从 String 的 sqlalchemy.types.String.__init__ 方法继承

创建一个持有字符串的类型。

参数：

• length – 可选项，用于 DDL 和 CAST 表达式中列的长度。如果不会发出CREATE TABLE，可以安全地省略。某些数据库可能需要 DDL 中的length，如果包括了没有长度的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 类型。

类签名

类 sqlalchemy.types.DATE（sqlalchemy.types.Date的）

class sqlalchemy.types.DATETIME

SQL DATETIME 类型。

成员

init()

类签名

类 sqlalchemy.types.DATETIME（sqlalchemy.types.DateTime的）

method __init__(timezone: bool = False)

继承自 DateTime 的 sqlalchemy.types.DateTime.__init__ 方法

构建一个新的 DateTime。

参数：

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

class sqlalchemy.types.DECIMAL

SQL DECIMAL 类型。

另请参阅

Numeric - 基本类型的文档。

成员

init()

类签名

类 sqlalchemy.types.DECIMAL（sqlalchemy.types.Numeric的）

method __init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)

继承自 Numeric 的 sqlalchemy.types.Numeric.__init__ 方法

构建一个 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()

类签名

类sqlalchemy.types.DOUBLE (sqlalchemy.types.Double)

method __init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)

从 Float 的 sqlalchemy.types.Float.__init__ 方法继承

构造一个 Float。

参数：

• precision –
  用于 DDL CREATE TABLE 中的数字精度。后端应尝试确保此精度指示通用Float 数据类型的数字位数。
  注意
  对于 Oracle 后端，在渲染 DDL 时，Float.precision 参数不被接受，因为 Oracle 不支持指定浮点精度为小数位数。相反，请使用 Oracle 特定的FLOAT 数据类型，并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 中的新功能。
  要创建一个数据库无关的Float，并为 Oracle 单独指定二进制精度，请使用 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()

类签名

类 sqlalchemy.types.DOUBLE_PRECISION（sqlalchemy.types.Double）

method __init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)

继承自 Float 的 sqlalchemy.types.Float.__init__ 方法

构造一个 Float。

参数：

• precision –
  DDL CREATE TABLE 中用于使用的数字精度。后端应尝试确保此精度指示了用于通用 Float 数据类型的数字位数。
  注意
  对于 Oracle 后端，在渲染 DDL 时，不接受 Float.precision 参数，因为 Oracle 不支持以小数位数指定的浮点精度。而是使用特定于 Oracle 的 FLOAT 数据类型，并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 中的新功能。
  要创建一个数据库无关的Float，并为 Oracle 单独指定二进制精度，请使用 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()

类签名

类 sqlalchemy.types.FLOAT（sqlalchemy.types.Float）

method __init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)

继承自 Float 的 sqlalchemy.types.Float.__init__ 方法

构造一个 Float。

参数：

• precision –
  用于 DDL CREATE TABLE 中的数字精度。后端 应该 尝试确保此精度指示通用 Float 数据类型的数字位数。
  注意
  对于 Oracle 后端，在渲染 DDL 时，不接受 Float.precision 参数，因为 Oracle 不支持将浮点精度指定为小数位数。相反，请使用特定于 Oracle 的 FLOAT 数据类型，并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 2.0 版本的新功能。
  要创建一个与数据库无关的 Float，并为 Oracle 单独指定二进制精度，请使用 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.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 数据类型的日益流行。

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默认使用 Python 的json.dumps和json.loads函数作为 JSON 序列化器和反序列化器；在 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

类签名

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

class Comparator

为 JSON 定义比较操作。

类签名

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

method as_boolean()

将索引值转换为布尔值。

例如：

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

版本 1.3.11 中的新功能。

method as_float()

将索引值转换为浮点数。

例如：

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 as_integer()

将索引值转换为整数。

例如：

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

版本 1.3.11 中的新功能。

method as_json()

将索引值转换为 JSON。

例如：

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

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

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

版本 1.3.11 中的新功能。

method as_numeric(precision, scale, asdecimal=True)

将索引值转换为数字/十进制数。

例如：

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 as_string()

将索引值转换为字符串。

例如：

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 表达式中索引 / 路径元素的常见函数。

类签名

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

method bind_processor(dialect)

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

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

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

注意

此方法仅与方言特定类型对象相关，该对象通常私有于正在使用的方言，并且与公共类型对象不同，这意味着无法通过子类化TypeEngine类来提供替代的TypeEngine.bind_processor()方法，除非显式地子类化UserDefinedType类。

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

参见

扩展现有类型

SqlAlchemy 2.0 中文文档（四十一）（9）https://developer.aliyun.com/article/1563088