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

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

在使用 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，则数组将假定具有固定数量的维度。这影响了数组在数据库上的声明方式，以及它如何解释 Python 和结果值，以及如何与“getitem”运算符结合使用时的表达式行为。有关更多详细信息，请参见ARRAY的描述。
  
• zero_indexes=False – 当为 True 时，索引值将在 Python 零基础和 SQL 一基础索引之间转换，例如，在传递到数据库之前，所有索引值都将增加一个值。
  

class Comparator

为ARRAY定义比较操作。

此类型的方言特定形式上还有更多的操作符。参见Comparator。

类签名

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

method contains(*arg, **kw)

ARRAY.contains() 对于基本的数组类型没有实现。请使用特定于方言的数组类型。

另请参阅

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

构造一个布尔值。

参数：

• create_constraint –
  默认为 False。如果布尔值生成为 int/smallint，还会在表上创建一个 CHECK 约束，确保值为 1 或 0。
  注意
  强烈建议 CHECK 约束具有明确的名称，以支持模式管理问题。可以通过设置 Boolean.name 参数或设置适当的命名约定来建立这一点；参见配置约束命名约定以获取背景信息。
  在版本 1.4 中更改：-此标志现在默认为 False，表示对非本地枚举类型不会生成 CHECK 约束。
  
• name – 如果生成 CHECK 约束，请指定约束的名称。
  

class sqlalchemy.types.CHAR

SQL CHAR 类型。

成员

init()

类签名

类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 中使用长度，并且如果包含没有长度的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()

类签名

类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 中使用长度，并且如果包含没有长度的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.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 __init__(timezone: bool = False)

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

构建一个新的 DateTime。

参数：

timezone – boolean。指示日期时间类型是否应在仅在基本日期/时间持有类型上启用时区支持。建议在使用此标志时直接使用 TIMESTAMP 数据类型，因为一些数据库包括与时区功能的 TIMESTAMP 数据类型不同的独立通用日期/时间持有类型，例如 Oracle。

class sqlalchemy.types.DECIMAL

SQL DECIMAL 类型。

另请参阅

Numeric - 基本类型的文档。

成员

init()

类签名

class 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)

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

构建一个 Numeric。

参数：

• precision – 用于 DDL CREATE TABLE 的数字精度。
  
• scale – 用于 DDL CREATE TABLE 的数字规模。
  
• asdecimal – 默认为 True。返回值是否应作为 Python Decimal 对象发送，或作为浮点数发送。不同的 DBAPI 根据数据类型发送其中之一 - 数字类型将确保在 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 类型。

SQLAlchemy 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 序列化器和反序列化器使用了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

类签名

类 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()的实现。

另请参阅

扩展现有类型

参数：

方言 - 正在使用的方言实例。

method 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 索引值进行执行时处理。

类签名

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

class JSONIntIndexType

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

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

类签名

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

class JSONPathType

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

这允许对基于路径的索引值进行执行时处理，转换为特定的 SQL 语法。

类签名

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

class JSONStrIndexType

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

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

类签名

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

attribute NULL = symbol('JSON_NULL')

描述 NULL 的 JSON 值。

此值用于强制使用 JSON 值"null"作为值。Python 的None值将根据JSON.none_as_null 标志的设置被识别为 SQL NULL 或 JSON"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 __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

method bind_processor(dialect)

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

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

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

注意

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

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

参见

增强现有类型

参数：

方言 – 正在使用的方言实例。

attribute comparator_factory

Comparator 的别名。

attribute hashable = False

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

在 ORM 中用于去重结果列表。

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 参数。
  

attribute should_evaluate_none: bool

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

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

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

另请参阅

TypeEngine.evaluates_none() 方法。

class sqlalchemy.types.INTEGER

SQL INT 或 INTEGER 类型。

另请参阅

Integer - 基本类型的文档。

类签名

类 sqlalchemy.types.INTEGER（sqlalchemy.types.Integer）

class sqlalchemy.types.NCHAR

SQL NCHAR 类型。

成员

init()

类签名

类 sqlalchemy.types.NCHAR (sqlalchemy.types.Unicode)

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

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

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

参数：

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

SQL NVARCHAR 类型。

成员

init()

类签名

类 sqlalchemy.types.NVARCHAR (sqlalchemy.types.Unicode)

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

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

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

参数：

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

SQL NUMERIC 类型。

另请参阅

Numeric - 基础类型的文档。

成员

init()

类签名

类 sqlalchemy.types.NUMERIC（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 对象还是作为浮点数发送。根据数据类型不同，不同的 DBAPIs 会发送其中之一 - Numeric 类型将确保返回值在各个 DBAPIs 之间一致地是其中之一。
  
• decimal_return_scale - 转换浮点数为 Python decimal 时使用的默认精度。由于浮点数的不准确性，浮点数值通常会更长，而大多数浮点数数据库类型没有“标度”概念，因此默认情况下，float 类型在转换时查找前十位小数点。指定此值将覆盖该长度。包含显式“.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.REAL

SQL REAL 类型。

另请参阅

Float - 基本类型的文档。

成员

init()

类签名

类 sqlalchemy.types.REAL（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 版本的新功能。
  要创建一个与 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.SMALLINT

SQL SMALLINT 类型。

另请参阅

SmallInteger - 基础类型的文档。

类签名

类sqlalchemy.types.SMALLINT (sqlalchemy.types.SmallInteger)

class sqlalchemy.types.TEXT

SQL TEXT 类型。

成员

init()

类签名

类sqlalchemy.types.TEXT (sqlalchemy.types.Text)

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

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

创建一个保存字符串的类型。

参数：

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

SQL TIME 类型。

类签名

类 sqlalchemy.types.TIME（sqlalchemy.types.Time）

class sqlalchemy.types.TIMESTAMP

SQL TIMESTAMP 类型。

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

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