SqlAlchemy 2.0 中文文档（四十八）（4）-阿里云开发者社区

SqlAlchemy 2.0 中文文档（四十八）（3）https://developer.aliyun.com/article/1563009

范围和多范围类型

对于 psycopg、pg8000 和 asyncpg 方言，支持 PostgreSQL 范围和多范围类型；psycopg2 方言仅支持范围类型。

2.0.17 版本中的新功能：为 pg8000 方言添加了范围和多范围支持。需要 pg8000 1.29.8 或更高版本。

要传递给数据库的数据值可以作为字符串值传递，也可以使用 Range 数据对象。

2.0 版本中的新功能：添加了与后端无关的 Range 对象，用于表示范围。psycopg2-特定的范围类不再公开，仅由该特定方言内部使用。

例如，使用 TSRANGE 数据类型的完全类型化模型示例：

from datetime import datetime
from sqlalchemy.dialects.postgresql import Range
from sqlalchemy.dialects.postgresql import TSRANGE
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
class Base(DeclarativeBase):
    pass
class RoomBooking(Base):
    __tablename__ = "room_booking"
    id: Mapped[int] = mapped_column(primary_key=True)
    room: Mapped[str]
    during: Mapped[Range[datetime]] = mapped_column(TSRANGE)

为了表示上述 during 列的数据，Range 类型是一个简单的数据类，用于表示范围的边界。下面说明了将行插入上述 room_booking 表的示例：

from sqlalchemy import create_engine
from sqlalchemy.orm import Session
engine = create_engine("postgresql+psycopg://scott:tiger@pg14/dbname")
Base.metadata.create_all(engine)
with Session(engine) as session:
    booking = RoomBooking(
        room="101", during=Range(datetime(2013, 3, 23), datetime(2013, 3, 25))
    )
    session.add(booking)
    session.commit()

从任何范围列中选择也将返回 Range 对象，如下所示：

from sqlalchemy import select
with Session(engine) as session:
    for row in session.execute(select(RoomBooking.during)):
        print(row)

可用的范围数据类型如下：

INT4RANGE
INT8RANGE
NUMRANGE
DATERANGE
TSRANGE
TSTZRANGE

对象名称	描述
Range	表示一个 PostgreSQL 范围。

class sqlalchemy.dialects.postgresql.Range

表示一个 PostgreSQL 范围。

例如：

r = Range(10, 50, bounds="()")

调用风格与 psycopg 和 psycopg2 类似，部分原因是为了方便从直接使用这些对象的以前的 SQLAlchemy 版本进行迁移。

参数：

lower – 下限值，或为 None
upper – 上限值，或为 None
bounds – 仅关键字，可选的字符串值，是 "()"、"[)"、"(]"、"[]" 中的一个。默认为 ")"。
empty – 仅关键字，可选的布尔值，指示这是一个“空”范围

2.0 版本中的新功能。

成员

[eq(), adjacent_to(), contained_by(), contains(), difference(), intersection(), is_empty, isempty, lower, lower_inc, lower_inf, not_extend_left_of(), not_extend_right_of(), overlaps(), strictly_left_of(), strictly_right_of(), union(), upper, upper_inc, upper_inf

类签名

类sqlalchemy.dialects.postgresql.Range (typing.Generic)

method __eq__(other: Any) → bool

考虑边界包含性比较此范围与其他范围，如果它们相等则返回True。

method adjacent_to(other: Range[_T]) → bool

确定此范围是否与其他范围相邻。

method contained_by(other: Range[_T]) → bool

确定此范围是否被其他范围包含。

method contains(value: _T | Range[_T]) → bool

确定此范围是否包含值。

method difference(other: Range[_T]) → Range[_T]

计算此范围与其他范围之间的差异。

如果两个范围是“不相交”的，即既不相邻也不重叠，则引发ValueError异常。

method intersection(other: Range[_T]) → Range[_T]

计算此范围与其他范围的交集。

版本 2.0.10 中的新功能。

attribute is_empty

“空”属性的同义词。

attribute isempty

“空”属性的同义词。

attribute lower: _T | None

下限

attribute lower_inc

如果下限是包含的，则返回 True。

attribute lower_inf

如果此范围非空且下限为无穷大，则返回 True。

method not_extend_left_of(other: Range[_T]) → bool

确定此范围是否不延伸到其他范围的左侧。

method not_extend_right_of(other: Range[_T]) → bool

确定此范围是否不延伸到其他范围的右侧。

method overlaps(other: Range[_T]) → bool

确定此范围是否与其他范围重叠。

method strictly_left_of(other: Range[_T]) → bool

确定此范围是否完全位于其他范围的左侧。

method strictly_right_of(other: Range[_T]) → bool

确定此范围是否完全位于其他范围的右侧。

method union(other: Range[_T]) → Range[_T]

计算此范围与其他范围的并集。

如果两个范围是“不相交”的，即既不相邻也不重叠，则引发ValueError异常。

attribute upper: _T | None

上限

attribute upper_inc

如果上限是包含的，则返回 True。

attribute upper_inf

如果此范围非空且上限为无穷大，则返回 True。

多范围

PostgreSQL 14 及以上版本支持多范围。SQLAlchemy 的多范围数据类型处理Range类型的列表。

多范围仅受 psycopg、asyncpg 和 pg8000 方言的支持**。SQLAlchemy 的默认 postgresql 方言 psycopg2 方言不**支持多范围数据类型。

新版本 2.0 中：增加了对 MULTIRANGE 数据类型的支持。SQLAlchemy 将多范围值表示为 Range 对象的列表。

新版本 2.0.17：为 pg8000 方言添加了多范围支持。需要 pg8000 1.29.8 或更高版本。

新版本 2.0.26：添加了 MultiRange 序列。

下面的示例说明了 TSMULTIRANGE 数据类型的使用：

from datetime import datetime
from typing import List
from sqlalchemy.dialects.postgresql import Range
from sqlalchemy.dialects.postgresql import TSMULTIRANGE
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
class Base(DeclarativeBase):
    pass
class EventCalendar(Base):
    __tablename__ = "event_calendar"
    id: Mapped[int] = mapped_column(primary_key=True)
    event_name: Mapped[str]
    added: Mapped[datetime]
    in_session_periods: Mapped[List[Range[datetime]]] = mapped_column(TSMULTIRANGE)

插入和选择记录的示例：

from sqlalchemy import create_engine
from sqlalchemy import select
from sqlalchemy.orm import Session
engine = create_engine("postgresql+psycopg://scott:tiger@pg14/test")
Base.metadata.create_all(engine)
with Session(engine) as session:
    calendar = EventCalendar(
        event_name="SQLAlchemy Tutorial Sessions",
        in_session_periods=[
            Range(datetime(2013, 3, 23), datetime(2013, 3, 25)),
            Range(datetime(2013, 4, 12), datetime(2013, 4, 15)),
            Range(datetime(2013, 5, 9), datetime(2013, 5, 12)),
        ],
    )
    session.add(calendar)
    session.commit()
    for multirange in session.scalars(select(EventCalendar.in_session_periods)):
        for range_ in multirange:
            print(f"Start: {range_.lower} End: {range_.upper}")

注意

在上面的示例中，ORM 处理的 Range 类型列表不会自动检测特定列表值的就地更改；要使用 ORM 更新列表值，要么重新分配一个新列表给属性，要么使用 MutableList 类型修饰符。请参阅 Mutation Tracking 部分了解背景信息。

使用 MultiRange 序列推断多范围类型

在没有指定类型的情况下使用多范围作为文字值时，可以使用实用程序 MultiRange 序列：

from sqlalchemy import literal
from sqlalchemy.dialects.postgresql import MultiRange
with Session(engine) as session:
    stmt = select(EventCalendar).where(
        EventCalendar.added.op("<@")(
            MultiRange(
                [
                    Range(datetime(2023, 1, 1), datetime(2013, 3, 31)),
                    Range(datetime(2023, 7, 1), datetime(2013, 9, 30)),
                ]
            )
        )
    )
    in_range = session.execute(stmt).all()
with engine.connect() as conn:
    row = conn.scalar(select(literal(MultiRange([Range(2, 4)]))))
    print(f"{row.lower} -> {row.upper}")

使用简单的 list 而不是 MultiRange 将需要手动设置文字值的类型为适当的多范围类型。

新版本 2.0.26：添加了 MultiRange 序列。

可用的多范围数据类型如下：

INT4MULTIRANGE
INT8MULTIRANGE
NUMMULTIRANGE
DATEMULTIRANGE
TSMULTIRANGE
TSTZMULTIRANGE

多范围

多范围在 PostgreSQL 14 及以上版本中受支持。SQLAlchemy 的多范围数据类型处理 Range 类型的列表。

仅支持 psycopg、asyncpg 和 pg8000 方言的多范围。SQLAlchemy 的默认 postgresql 方言 psycopg2 方言 不支持 多范围数据类型。

新版本 2.0 中添加了对 MULTIRANGE 数据类型的支持。SQLAlchemy 将多范围值表示为 Range 对象的列表。

新版本 2.0.17 中为 pg8000 方言添加了多范围支持。需要 pg8000 1.29.8 或更高版本。

新版本 2.0.26 中新增了MultiRange 序列。

下面的示例说明了使用 TSMULTIRANGE 数据类型：

from datetime import datetime
from typing import List
from sqlalchemy.dialects.postgresql import Range
from sqlalchemy.dialects.postgresql import TSMULTIRANGE
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
class Base(DeclarativeBase):
    pass
class EventCalendar(Base):
    __tablename__ = "event_calendar"
    id: Mapped[int] = mapped_column(primary_key=True)
    event_name: Mapped[str]
    added: Mapped[datetime]
    in_session_periods: Mapped[List[Range[datetime]]] = mapped_column(TSMULTIRANGE)

说明插入和选择记录：

from sqlalchemy import create_engine
from sqlalchemy import select
from sqlalchemy.orm import Session
engine = create_engine("postgresql+psycopg://scott:tiger@pg14/test")
Base.metadata.create_all(engine)
with Session(engine) as session:
    calendar = EventCalendar(
        event_name="SQLAlchemy Tutorial Sessions",
        in_session_periods=[
            Range(datetime(2013, 3, 23), datetime(2013, 3, 25)),
            Range(datetime(2013, 4, 12), datetime(2013, 4, 15)),
            Range(datetime(2013, 5, 9), datetime(2013, 5, 12)),
        ],
    )
    session.add(calendar)
    session.commit()
    for multirange in session.scalars(select(EventCalendar.in_session_periods)):
        for range_ in multirange:
            print(f"Start: {range_.lower} End: {range_.upper}")

注意

在上面的示例中，ORM 处理的 Range 类型列表不会自动检测到特定列表值的就地更改；要使用 ORM 更新列表值，要么重新分配一个新列表给属性，要么使用 MutableList 类型修饰符。请参阅 Mutation Tracking 部分了解背景信息。

使用 MultiRange 序列推断多范围类型

当在不指定类型的情况下使用多范围作为文字时，可以使用实用程序 MultiRange 序列：

from sqlalchemy import literal
from sqlalchemy.dialects.postgresql import MultiRange
with Session(engine) as session:
    stmt = select(EventCalendar).where(
        EventCalendar.added.op("<@")(
            MultiRange(
                [
                    Range(datetime(2023, 1, 1), datetime(2013, 3, 31)),
                    Range(datetime(2023, 7, 1), datetime(2013, 9, 30)),
                ]
            )
        )
    )
    in_range = session.execute(stmt).all()
with engine.connect() as conn:
    row = conn.scalar(select(literal(MultiRange([Range(2, 4)]))))
    print(f"{row.lower} -> {row.upper}")

使用简单的 list 而不是 MultiRange 将需要手动设置文字值的类型为适当的多范围类型。

新版本 2.0.26 中新增了MultiRange 序列。

可用的多范围数据类型如下：

INT4MULTIRANGE
INT8MULTIRANGE
NUMMULTIRANGE
DATEMULTIRANGE
TSMULTIRANGE
TSTZMULTIRANGE #### 使用 MultiRange 序列推断多范围类型

当将多范围用作字面值而不指定类型时，可以使用实用程序MultiRange序列：

from sqlalchemy import literal
from sqlalchemy.dialects.postgresql import MultiRange
with Session(engine) as session:
    stmt = select(EventCalendar).where(
        EventCalendar.added.op("<@")(
            MultiRange(
                [
                    Range(datetime(2023, 1, 1), datetime(2013, 3, 31)),
                    Range(datetime(2023, 7, 1), datetime(2013, 9, 30)),
                ]
            )
        )
    )
    in_range = session.execute(stmt).all()
with engine.connect() as conn:
    row = conn.scalar(select(literal(MultiRange([Range(2, 4)]))))
    print(f"{row.lower} -> {row.upper}")

使用简单的list而不是MultiRange将需要手动设置字面值的类型为适当的多范围类型。

新版本 2.0.26 中新增了MultiRange序列。

可用的多范围数据类型如下：

INT4MULTIRANGE
INT8MULTIRANGE
NUMMULTIRANGE
DATEMULTIRANGE
TSMULTIRANGE
TSTZMULTIRANGE

网络数据类型

包含的网络数据类型有INET、CIDR、MACADDR。

对于INET和CIDR数据类型，这些数据类型的条件支持可用于发送和检索 Python ipaddress对象，包括ipaddress.IPv4Network、ipaddress.IPv6Network、ipaddress.IPv4Address、ipaddress.IPv6Address。这种支持目前是DBAPI 本身的默认行为，并且因 DBAPI 而异。SQLAlchemy 尚未实现自己的网络地址转换逻辑。

psycopg 和 asyncpg 完全支持这些数据类型；默认情况下，ipaddress系列的对象以行的形式返回。
psycopg2 方言只发送和接收字符串。
pg8000 方言支持ipaddress.IPv4Address和ipaddress.IPv6Address对象用于INET数据类型，但对于CIDR类型使用字符串。

要将所有上述 DBAPI 规范化为仅返回字符串，请使用native_inet_types参数，传递一个值为False：

e = create_engine(
    "postgresql+psycopg://scott:tiger@host/dbname", native_inet_types=False
)

使用上述参数，psycpg、asyncpg 和 pg8000 方言将禁用 DBAPI 对这些类型的自适应，并且仅返回字符串，与旧的 psycopg2 方言的行为相匹配。

该参数也可以设置为 True，在这种情况下，对于不支持或尚未完全支持将行转换为 Python ipaddress 数据类型的后端（当前为 psycopg2 和 pg8000），将引发 NotImplementedError。

2.0.18 版本新增：- 添加了 native_inet_types 参数。

PostgreSQL 数据类型

与所有 SQLAlchemy 方言一样，所有已知与 PostgreSQL 兼容的大写类型都可以从顶层方言导入，无论其来自sqlalchemy.types 还是本地方言：

from sqlalchemy.dialects.postgresql import (
    ARRAY,
    BIGINT,
    BIT,
    BOOLEAN,
    BYTEA,
    CHAR,
    CIDR,
    CITEXT,
    DATE,
    DATEMULTIRANGE,
    DATERANGE,
    DOMAIN,
    DOUBLE_PRECISION,
    ENUM,
    FLOAT,
    HSTORE,
    INET,
    INT4MULTIRANGE,
    INT4RANGE,
    INT8MULTIRANGE,
    INT8RANGE,
    INTEGER,
    INTERVAL,
    JSON,
    JSONB,
    JSONPATH,
    MACADDR,
    MACADDR8,
    MONEY,
    NUMERIC,
    NUMMULTIRANGE,
    NUMRANGE,
    OID,
    REAL,
    REGCLASS,
    REGCONFIG,
    SMALLINT,
    TEXT,
    TIME,
    TIMESTAMP,
    TSMULTIRANGE,
    TSQUERY,
    TSRANGE,
    TSTZMULTIRANGE,
    TSTZRANGE,
    TSVECTOR,
    UUID,
    VARCHAR,
)

特定于 PostgreSQL 的类型，或具有 PostgreSQL 特定的构造参数，如下所示：

对象名称	描述
AbstractMultiRange	PostgreSQL MULTIRANGE 类型的基类。
AbstractRange	单个和多个 Range SQL 类型的基类。
AbstractSingleRange	PostgreSQL RANGE 类型的基类。
ARRAY	PostgreSQL ARRAY 类型。
BIT
BYTEA
CIDR
CITEXT	提供 PostgreSQL 的 CITEXT 类型。
DATEMULTIRANGE	代表 PostgreSQL 的 DATEMULTIRANGE 类型。
DATERANGE	代表 PostgreSQL 的 DATERANGE 类型。
DOMAIN	代表 PostgreSQL 的 DOMAIN 类型。
ENUM	PostgreSQL ENUM 类型。
HSTORE	代表 PostgreSQL 的 HSTORE 类型。
INET
INT4MULTIRANGE	代表 PostgreSQL 的 INT4MULTIRANGE 类型。
INT4RANGE	代表 PostgreSQL 的 INT4RANGE 类型。
INT8MULTIRANGE	代表 PostgreSQL 的 INT8MULTIRANGE 类型。
INT8RANGE	代表 PostgreSQL 的 INT8RANGE 类型。
INTERVAL	PostgreSQL INTERVAL 类型。
JSON	代表 PostgreSQL 的 JSON 类型。
JSONB	代表 PostgreSQL 的 JSONB 类型。
JSONPATH	JSON Path 类型。
MACADDR
MACADDR8
MONEY	提供 PostgreSQL MONEY 类型。
MultiRange	表示一个多范围序列。
NUMMULTIRANGE	表示 PostgreSQL NUMMULTIRANGE 类型。
NUMRANGE	表示 PostgreSQL NUMRANGE 类型。
OID	提供 PostgreSQL OID 类型。
REGCLASS	提供 PostgreSQL REGCLASS 类型。
REGCONFIG	提供 PostgreSQL REGCONFIG 类型。
TIME	PostgreSQL TIME 类型。
TIMESTAMP	提供 PostgreSQL TIMESTAMP 类型。
TSMULTIRANGE	表示 PostgreSQL TSRANGE 类型。
TSQUERY	提供 PostgreSQL TSQUERY 类型。
TSRANGE	表示 PostgreSQL TSRANGE 类型。
TSTZMULTIRANGE	表示 PostgreSQL TSTZRANGE 类型。
TSTZRANGE	表示 PostgreSQL TSTZRANGE 类型。
TSVECTOR	`TSVECTOR` 类型实现了 PostgreSQL 文本搜索类型 TSVECTOR。

class sqlalchemy.dialects.postgresql.AbstractRange

单范围和多范围 SQL 类型的基类。

成员

adjacent_to(), contained_by(), contains(), difference(), intersection(), not_extend_left_of(), not_extend_right_of(), overlaps(), strictly_left_of(), strictly_right_of(), union()

类签名

类sqlalchemy.dialects.postgresql.AbstractRange（sqlalchemy.types.TypeEngine）

class comparator_factory

为范围类型定义比较操作。

类签名

类sqlalchemy.dialects.postgresql.AbstractRange.comparator_factory（sqlalchemy.types.Comparator）

method adjacent_to(other: Any) → ColumnElement[bool]

布尔表达式。如果列中的范围与操作数中的范围相邻，则返回 true。

method contained_by(other: Any) → ColumnElement[bool]

布尔表达式。如果列包含在右操作数内，则返回 true。

method contains(other: Any, **kw: Any) → ColumnElement[bool]

布尔表达式。如果右操作数（可以是元素或范围）包含在列中，则返回 true。

此运算符可能会忽略 kwargs，但需要符合 API 标准。

method difference(other: Any) → ColumnElement[bool]

范围表达式。返回两个范围的并集。如果结果范围不连续，将引发异常。

method intersection(other: Any) → ColumnElement[Range[_T]]

范围表达式。返回两个范围的交集。如果结果范围不连续，将引发异常。

method not_extend_left_of(other: Any) → ColumnElement[bool]

布尔表达式。如果列中的范围不向左延伸到操作数中的范围，则返回 true。

method not_extend_right_of(other: Any) → ColumnElement[bool]

布尔表达式。如果列中的范围不向右延伸到操作数中的范围，则返回 true。

method overlaps(other: Any) → ColumnElement[bool]

布尔表达式。如果列与右操作数重叠（具有共同的点），则返回 true。

method strictly_left_of(other: Any) → ColumnElement[bool]

布尔表达式。如果列严格位于右操作数的左侧，则返回 true。

method strictly_right_of(other: Any) → ColumnElement[bool]

布尔表达式。如果列严格位于右操作数的右侧，则返回 true。

method union(other: Any) → ColumnElement[bool]

范围表达式。返回两个范围的并集。如果结果范围不连续，将引发异常。

class sqlalchemy.dialects.postgresql.AbstractSingleRange

PostgreSQL 范围类型的基类。

这些是返回单个Range对象的类型。

另请参阅

PostgreSQL 范围函数

类签名

类sqlalchemy.dialects.postgresql.AbstractSingleRange（sqlalchemy.dialects.postgresql.ranges.AbstractRange）

class sqlalchemy.dialects.postgresql.AbstractMultiRange

PostgreSQL MULTIRANGE 类型的基类。

这些是返回一系列Range对象的类型。

类签名

类sqlalchemy.dialects.postgresql.AbstractMultiRange（sqlalchemy.dialects.postgresql.ranges.AbstractRange）

class sqlalchemy.dialects.postgresql.ARRAY

PostgreSQL 的 ARRAY 类型。

ARRAY 类型的构造方式与核心 ARRAY 类型相同；需要一个成员类型，并且建议如果要用于多个维度，则推荐指定维度数量：

from sqlalchemy.dialects import postgresql
mytable = Table("mytable", metadata,
        Column("data", postgresql.ARRAY(Integer, dimensions=2))
    )

ARRAY 类型提供了在核心 ARRAY 类型上定义的所有操作，包括对“维度”的支持，索引访问以及简单匹配，如 Comparator.any() 和 Comparator.all()。 ARRAY 类还提供了用于包含操作的 PostgreSQL 特定方法，包括 Comparator.contains()、Comparator.contained_by() 和 Comparator.overlap()，例如：

mytable.c.data.contains([1, 2])

默认情况��，索引访问是基于一的，以匹配 PostgreSQL 的索引访问；要进行基于零的索引访问，请设置 ARRAY.zero_indexes.

此外，ARRAY 类型不直接与 ENUM 类型一起使用。有关解决方法，请参见使用 ENUM 与 ARRAY 中的特殊类型。

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

当与 SQLAlchemy ORM 一起使用时，ARRAY 类型不会检测对数组的原地变异。为了检测这些变化，必须使用 sqlalchemy.ext.mutable 扩展，并使用 MutableList 类：

from sqlalchemy.dialects.postgresql import ARRAY
from sqlalchemy.ext.mutable import MutableList
class SomeOrmClass(Base):
    # ...
    data = Column(MutableList.as_mutable(ARRAY(Integer)))

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

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

另见

ARRAY - 基本数组类型

array - 生成字面数组值。

成员

init(), contains(), contained_by(), overlap()

类签名

class sqlalchemy.dialects.postgresql.ARRAY (sqlalchemy.types.ARRAY)

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

构造一个数组。

例如：

Column('myarray', ARRAY(Integer))

参数是：

参数：

item_type – 数组中项的数据类型。请注意，这里与维度无关，因此类似INTEGER[][]这样的多维数组，构造为ARRAY(Integer)，而不是ARRAY(ARRAY(Integer))或类似的形式。
as_tuple=False – 指定返回结果是否应从列表转换为元组。例如，Psycopg2 等 DBAPI 默认返回列表。返回元组时，结果是可哈希的。
dimensions – 如果非空，则数组将假定具有固定数量的维度。这将导致为此数组发出的 DDL 包括精确数量的方括号[]，并且还将优化类型的整体性能。请注意，PG 数组始终隐式地“非维度化”，这意味着无论如何声明，它们都可以存储任意数量的维度。
zero_indexes=False – 当为 True 时，索引值将在 Python 以零为基础和 PostgreSQL 以一为基础的索引之间转换，例如，将在传递到数据库之前的所有索引值上添加一个值为一的值。

class Comparator

为ARRAY定义比较操作。

请注意，这些操作是在基础Comparator类提供的操作之外提供的，包括Comparator.any()和Comparator.all()。

类签名

class sqlalchemy.dialects.postgresql.ARRAY.Comparator (sqlalchemy.types.Comparator)

method contains(other, **kwargs)

布尔表达式。测试元素是否为参数数组表达式的超集。

此运算符可能会忽略 kwargs，但对于 API 一致性，它们是必需的。

method contained_by(other)

布尔表达式。测试元素是否是参数数组表达式的元素的适当子集。

method overlap(other)

布尔表达式。测试数组是否与参数数组表达式有公共元素。

class sqlalchemy.dialects.postgresql.BIT

类签名

类 sqlalchemy.dialects.postgresql.BIT (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.BYTEA

成员

init()

类签名

类 sqlalchemy.dialects.postgresql.BYTEA (sqlalchemy.types.LargeBinary)

method __init__(length: int | None = None)

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

构造一个 LargeBinary 类型。

参数：

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

class sqlalchemy.dialects.postgresql.CIDR

类签名

类 sqlalchemy.dialects.postgresql.CIDR (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.CITEXT

提供 PostgreSQL CITEXT 类型。

2.0.7 版本中新增。

成员

init()

类签名

类 sqlalchemy.dialects.postgresql.CITEXT (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

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

class sqlalchemy.dialects.postgresql.DOMAIN

表示 DOMAIN PostgreSQL 类型。

域本上是一个具有可选约束的数据类型，用于限制允许的值集。例如：

PositiveInt = DOMAIN(
    "pos_int", Integer, check="VALUE > 0", not_null=True
)
UsPostalCode = DOMAIN(
    "us_postal_code",
    Text,
    check="VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'"
)

有关详细信息，请参阅PostgreSQL 文档。

版本 2.0 中新增。

成员

init()、create()、drop()

类签名

类sqlalchemy.dialects.postgresql.DOMAIN（sqlalchemy.dialects.postgresql.named_types.NamedType的sqlalchemy.types.SchemaType）

method __init__(name: str, data_type: _TypeEngineArgument[Any], *, collation: str | None = None, default: elements.TextClause | str | None = None, constraint_name: str | None = None, not_null: bool | None = None, check: elements.TextClause | str | None = None, create_type: bool = True, **kw: Any)

构造一个域。

参数：

name – 域的名称
data_type – 域的基础数据类型。这可以包括数组说明符。
collation – 用于域的可选排序规则。如果未指定排序规则，则使用基础数据类型的默认排序规则。如果指定了collation，则基础类型必须是可排序的。
default – DEFAULT 子句为域数据类型的列指定默认值。默认值应为字符串或text()值。如果未指定默认值，则默认值为 null 值。
constraint_name – 用于约束的可选名称。如果未指定，则后端会生成一个名称。
not_null – 此域的值不能为 null。默认情况下，域允许为 null。如果未指定，则不会发出空性条款。
check – CHECK 子句指定域的值必须满足的完整性约束或测试。约束必须是一个产生布尔结果的表达式，可以使用关键字 VALUE 来引用正在测试的值。与 PostgreSQL 不同，目前在 SQLAlchemy 中只允许一个检查子句。
schema – 可选的模式名称
metadata – 可选的MetaData对象，此DOMAIN将直接与之关联
create_type – 默认为 True。指示在创建父表时（可选地检查类型的存在），发出CREATE TYPE；并且在删除表时另外调用DROP TYPE。

method create(bind, checkfirst=True, **kw)

从 NamedType 的 NamedType.create() 方法继承

发出CREATEDDL 来创建此类型。

参数：

bind – 一个可连接的Engine、Connection或类似对象以发出 SQL。
checkfirst – 如果为 True，则在创建之前首先执行对 PG 目录的查询，以查看类型是否已存在。

method drop(bind, checkfirst=True, **kw)

继承自 NamedType 的 NamedType.drop() 方法

发出此类型的 DROP DDL。

参数：

bind – 一个可连接的Engine、Connection或类似对象，用于发出 SQL。
checkfirst – 如果为 True，则在删除之前首先执行对 PG 目录的查询，以查看类型是否实际存在。

class sqlalchemy.dialects.postgresql.DOUBLE_PRECISION

SQL DOUBLE PRECISION 类型。

SQLAlchemy 2.0 中的新功能。

另请参阅

Double - 基本类型的文档。

类签名

类 sqlalchemy.dialects.postgresql.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 decimal 时使用的默认精度。由于十进制不精确，浮点值通常会更长，并且大多数浮点数据库类型没有“精度”的概念，因此默认情况下，float 类型在转换时会寻找前十位小数。指定此值将覆盖该长度。请注意，如果未另行指定，具有“精度”的 MySQL 浮点类型将使用“精度”作为 decimal_return_scale 的默认值。

class sqlalchemy.dialects.postgresql.ENUM

PostgreSQL ENUM 类型。

这是Enum的一个子类，包括对 PG 的CREATE TYPE和DROP TYPE的支持。

当使用内置类型Enum并且将Enum.native_enum标志保留为默认值 True 时，PostgreSQL 后端将使用ENUM类型作为实现，因此将使用特殊的创建/删除规则。

ENUM 的创建/删除行为必然是复杂的，这是由于 ENUM 类型与父表的尴尬关系所决定的，即它可能仅“属于”单个表，也可能在多个表之间共享。

当以“内联”方式使用Enum或ENUM时，会发出与调用Table.create()和Table.drop()方法对应的CREATE TYPE和DROP TYPE：

table = Table('sometable', metadata,
    Column('some_enum', ENUM('a', 'b', 'c', name='myenum'))
)
table.create(engine)  # will emit CREATE ENUM and CREATE TABLE
table.drop(engine)  # will emit DROP TABLE and DROP ENUM

要在多个表之间使用通用枚举类型的最佳做法是独立声明Enum或ENUM，并将其与MetaData对象本身关联：

my_enum = ENUM('a', 'b', 'c', name='myenum', metadata=metadata)
t1 = Table('sometable_one', metadata,
    Column('some_enum', myenum)
)
t2 = Table('sometable_two', metadata,
    Column('some_enum', myenum)
)

当使用此模式时，仍然必须在个别表创建的级别上小心处理。发出 CREATE TABLE 而不同时指定checkfirst=True仍然会导致问题：

t1.create(engine) # will fail: no such type 'myenum'

如果我们指定了checkfirst=True，则个别的表级别创建操作将检查ENUM，如果不存在则创建：

# will check if enum exists, and emit CREATE TYPE if not
t1.create(engine, checkfirst=True)

当使用元数据级 ENUM 类型时，如果调用元数据范围的创建/删除操作，则该类型将始终被创建和删除：

metadata.create_all(engine)  # will emit CREATE TYPE
metadata.drop_all(engine)  # will emit DROP TYPE

该类型也可以直接创建和删除：

my_enum.create(engine)
my_enum.drop(engine)

成员

init(), create(), drop()

类签名

类sqlalchemy.dialects.postgresql.ENUM (sqlalchemy.dialects.postgresql.named_types.NamedType, sqlalchemy.types.NativeForEmulated, sqlalchemy.types.Enum)

method __init__(*enums, name: str | _NoArg | None = _NoArg.NO_ARG, create_type: bool = True, **kw)

构造一个ENUM。

参数与Enum的参数相同，但还包括以下参数。

参数：

create_type - 默认为 True。指示在创建父表时应发出CREATE TYPE，在可选地检查类型是否存在后；并且在删除表时还调用DROP TYPE。当为False时，将不执行检查，也不会发出CREATE TYPE或DROP TYPE，除非直接调用ENUM.create()或ENUM.drop()。在调用到无法访问实际数据库的 SQL 文件的创建方案时，将设置为False是有帮助的 - 可以使用ENUM.create()和ENUM.drop()方法将 SQL 发出到目标绑定。

method create(bind=None, checkfirst=True)

发出CREATE TYPE以适用于此ENUM。

如果底层方言不支持 PostgreSQL CREATE TYPE，则不采取任何操作。

参数：

bind - 可连接的Engine、Connection或类似对象，用于发出 SQL。
checkfirst - 如果为True，则首先对 PG 目录执行查询，以查看在创建之前类型是否不存在。

method drop(bind=None, checkfirst=True)

发出DROP TYPE以适用于此ENUM。

如果底层方言不支持 PostgreSQL DROP TYPE，则不采取任何操作。

参数：

bind - 可连接的Engine、Connection或类似对象，用于发出 SQL。
checkfirst - 如果为True，则首先对 PG 目录执行查询，以查看在删除之前类型是否实际存在。

class sqlalchemy.dialects.postgresql.HSTORE

表示 PostgreSQL HSTORE 类型。

HSTORE 类型存储包含字符串的字典，例如：

data_table = Table('data_table', metadata,
    Column('id', Integer, primary_key=True),
    Column('data', HSTORE)
)
with engine.connect() as conn:
    conn.execute(
        data_table.insert(),
        data = {"key1": "value1", "key2": "value2"}
    )

HSTORE 提供了广泛的操作，包括：

索引操作：

data_table.c.data['some key'] == 'some value'

包含操作：

data_table.c.data.has_key('some key')
data_table.c.data.has_all(['one', 'two', 'three'])

连接：

data_table.c.data + {"k1": "v1"}

有关特殊方法的完整列表，请参见comparator_factory。

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

与 SQLAlchemy ORM 一起使用时，可能希望将HSTORE的使用与现在属于sqlalchemy.ext.mutable扩展的MutableDict字典结合起来。此扩展将允许对字典进行“原地”更改，例如向当前字典添加新键或替换/删除现有键，以产生将被工作单元检测到的事件：

from sqlalchemy.ext.mutable import MutableDict
class MyClass(Base):
    __tablename__ = 'data_table'
    id = Column(Integer, primary_key=True)
    data = Column(MutableDict.as_mutable(HSTORE))
my_object = session.query(MyClass).one()
# in-place mutation, requires Mutable extension
# in order for the ORM to detect
my_object.data['some_key'] = 'some value'
session.commit()

当未使用sqlalchemy.ext.mutable扩展时，ORM 不会注意到对现有字典内容的任何更改，除非将该字典值重新分配给 HSTORE 属性本身，从而生成更改事件。

另请参见

hstore - 渲染 PostgreSQL 的 hstore() 函数。

成员

array(), contained_by(), contains(), defined(), delete(), has_all(), has_any(), has_key(), keys(), matrix(), slice(), vals(), init(), bind_processor(), comparator_factory, hashable, result_processor()

类签名

类sqlalchemy.dialects.postgresql.HSTORE（sqlalchemy.types.Indexable，sqlalchemy.types.Concatenable，sqlalchemy.types.TypeEngine）

class Comparator

为HSTORE定义比较操作。

类签名

类sqlalchemy.dialects.postgresql.HSTORE.Comparator（sqlalchemy.types.Comparator，sqlalchemy.types.Comparator）

method array()

文本数组表达式。返回交替键和值的数组。

method contained_by(other)

布尔表达式。测试键是否是参数 jsonb 表达式的键的正确子集。

method contains(other, **kwargs)

布尔表达式。测试键（或数组）是否是参数 jsonb 表达式的键的超集/包含。

kwargs 可能会被此操作符忽略，但对于 API 的一致性是必需的。

method defined(key)

布尔表达式。测试键的非 NULL 值的存在。请注意，键可能是一个 SQLA 表达式。

method delete(key)

HStore 表达式。返回删除给定键的此 hstore 的内容。请注意，键可能是一个 SQLA 表达式。

method has_all(other)

布尔表达式。测试 jsonb 中所有键的存在。

method has_any(other)

布尔表达式。测试 jsonb 中任何键的存在。

method has_key(other)

布尔表达式。测试键的存在。请注意，键可能是一个 SQLA 表达式。

method keys()

文本数组表达式。返回键的数组。

method matrix()

文本数组表达式。返回[key, value]对的数组。

method slice(array)

HStore 表达式。返回由键数组定义的 hstore 的子集。

method vals()

文本数组表达式。返回值的数组。

method __init__(text_type=None)

构建一个新的HSTORE。

参数：

text_type – 应用于索引值的类型。默认为Text。

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

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

由 ORM 在唯一化结果列表时使用。

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

class sqlalchemy.dialects.postgresql.INET

类签名

类 sqlalchemy.dialects.postgresql.INET (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.INTERVAL

PostgreSQL INTERVAL 类型。

成员

init()

类签名

类 sqlalchemy.dialects.postgresql.INTERVAL (sqlalchemy.types.NativeForEmulated, sqlalchemy.types._AbstractInterval)

method __init__(precision: int | None = None, fields: str | None = None) → None

构造一个 INTERVAL。

参数：

precision – 可选的整数精度值
fields –
字符串字段说明符。允许限制字段的存储，例如 "YEAR"、"MONTH"、"DAY TO HOUR" 等。
自版本 1.2 新增。

class sqlalchemy.dialects.postgresql.JSON

代表 PostgreSQL JSON 类型。

JSON 在与 PostgreSQL 后端一起使用时会自动使用，但基本的 JSON 数据类型不提供针对 PostgreSQL 特定比较方法的 Python 访问器，例如 Comparator.astext()；另外，要使用 PostgreSQL 的 JSONB，应显式使用 JSONB 数据类型。

另请参阅

JSON - 通用跨平台 JSON 数据类型的主要文档。

PostgreSQL 版本提供的操作符包括 JSON 的操作符：

索引操作（-> 操作符）：

data_table.c.data['some key']
data_table.c.data[5]

返回文本的索引操作（->> 操作符）：

data_table.c.data['some key'].astext == 'some value'

请注意，通过 Comparator.as_string 访问器也可获得等效功能。
带 CAST 的索引操作（相当于 CAST(col ->> ['some key'] AS )）：

data_table.c.data['some key'].astext.cast(Integer) == 5

请注意，等效功能可通过 Comparator.as_integer 和类似的访问器获得。
路径索引操作（#> 运算符）：

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

返回文本的路径索引操作（#>> 运算符）：

data_table.c.data[('key_1', 'key_2', 5, ..., 'key_n')].astext == 'some value'

索引操作返回一个表达式对象，默认情况下其类型为 JSON，以便对结果类型进行进一步的面向 JSON 的指令调用。

自定义序列化程序和反序列化程序是在方言级别指定的，即使用 create_engine()。这样做的原因是，当使用 psycopg2 时，DBAPI 仅允许在每个游标或每个连接级别上指定序列化程序。例如：

engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test",
                        json_serializer=my_serialize_fn,
                        json_deserializer=my_deserialize_fn
                )

当使用 psycopg2 方言时，json_deserializer 是通过 psycopg2.extras.register_default_json 注册到数据库中的。

另请参阅

JSON - 核心级别的 JSON 类型

JSONB

成员

astext, init(), comparator_factory

类签名

类 sqlalchemy.dialects.postgresql.JSON（sqlalchemy.types.JSON）

class Comparator

为 JSON 定义比较操作。

类签名

类 sqlalchemy.dialects.postgresql.JSON.Comparator（sqlalchemy.types.Comparator）

attribute astext

在索引表达式上，当在 SQL 中呈现时，请使用“astext”（例如“->>”）转换。

例如：

select(data_table.c.data['some key'].astext)

另请参阅

ColumnElement.cast()

method __init__(none_as_null=False, astext_type=None)

构造一个 JSON 类型。

参数：

none_as_null –
如果为 True，则将值 None 持久化为 SQL NULL 值，而不是 null 的 JSON 编码。请注意，当此标志为 False 时，仍然可以使用 null() 构造来持久化 NULL 值：

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

另请参阅
JSON.NULL
astext_type – 用于索引属性上的 Comparator.astext 访问器的类型。默认为 Text。

attribute comparator_factory

Comparator 的别名

class sqlalchemy.dialects.postgresql.JSONB

表示 PostgreSQL JSONB 类型。

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

data_table = Table('data_table', metadata,
    Column('id', Integer, primary_key=True),
    Column('data', JSONB)
)
with engine.connect() as conn:
    conn.execute(
        data_table.insert(),
        data = {"key1": "value1", "key2": "value2"}
    )

JSONB 类型包括所有由 JSON 提供的操作，包括索引操作的相同行为。它还添加了特定于 JSONB 的附加运算符，包括 Comparator.has_key()、Comparator.has_all()、Comparator.has_any()、Comparator.contains()、Comparator.contained_by()、Comparator.delete_path()、Comparator.path_exists() 和 Comparator.path_match()。

与 JSON 类型一样，当与 ORM 一起使用时，JSONB 类型不会检测到原地更改，除非使用了 sqlalchemy.ext.mutable 扩展。

自定义序列化器和反序列化器与JSON类共享，使用json_serializer和json_deserializer关键字参数。必须在方言级别使用create_engine()指定这些参数。当使用 psycopg2 时，序列化器与 jsonb 类型关联，使用psycopg2.extras.register_default_jsonb在每个连接基础上，与使用psycopg2.extras.register_default_json注册这些处理程序与 json 类型的方式相同。

另见

JSON

成员

contained_by()，contains()，delete_path()，has_all()，has_any()，has_key()，path_exists()，path_match()，comparator_factory

类签名

类sqlalchemy.dialects.postgresql.JSONB（sqlalchemy.dialects.postgresql.json.JSON）

class Comparator

为JSON定义比较操作。

类签名

类sqlalchemy.dialects.postgresql.JSONB.Comparator（sqlalchemy.dialects.postgresql.json.Comparator）

method contained_by(other)

布尔表达式。测试键是否是参数 jsonb 表达式的键的真子集。

method contains(other, **kwargs)

布尔表达式。测试键（或数组）是否是参数 jsonb 表达式的键的超集/包含。

kwargs 可能会被此运算符忽略，但在 API 符合性方面是必需的。

method delete_path(array)

JSONB 表达式。删除参数数组中指定的字段或数组元素。

输入可以是将强制转换为ARRAY的字符串列表，也可以是_postgres.array()的实例。

在 2.0 版本中新增。

method has_all(other)

布尔表达式。测试 jsonb 中是否存在所有键。

method has_any(other)

布尔表达式。测试 jsonb 中是否存在任何关键字。

method has_key(other)

布尔表达式。测试关键字是否存在。请注意，关键字可能是 SQLA 表达式。

method path_exists(other)

布尔表达式。测试是否存在由参数 JSONPath 表达式给出的项目。

在 2.0 版本中新增。

method path_match(other)

布尔表达式。测试 JSONPath 断言是否与参数 JSONPath 表达式匹配。

仅考虑结果的第一个项目。

新版本 2.0 中新增。

attribute comparator_factory

Comparator 的别名

class sqlalchemy.dialects.postgresql.JSONPATH

JSON 路径类型。

当使用 json 搜索函数时，通常需要将字面值强制转换为 json 路径，例如 jsonb_path_query_array 或 jsonb_path_exists：

stmt = sa.select(
    sa.func.jsonb_path_query_array(
        table.c.jsonb_col, cast("$.address.id", JSONPATH)
    )
)

类签名

类 sqlalchemy.dialects.postgresql.JSONPATH (sqlalchemy.dialects.postgresql.json.JSONPathType)

class sqlalchemy.dialects.postgresql.MACADDR

类签名

类 sqlalchemy.dialects.postgresql.MACADDR (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.MACADDR8

类签名

类 sqlalchemy.dialects.postgresql.MACADDR8 (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.MONEY

提供 PostgreSQL MONEY 类型。

根据驱动程序，使用此类型的结果行可能返回一个包含货币符号的字符串值。

因此，可能更好地使用 TypeDecorator 提供对基于数字的货币数据类型的转换：

import re
import decimal
from sqlalchemy import Dialect
from sqlalchemy import TypeDecorator
class NumericMoney(TypeDecorator):
    impl = MONEY
    def process_result_value(
        self, value: Any, dialect: Dialect
    ) -> None:
        if value is not None:
            # adjust this for the currency and numeric
            m = re.match(r"\$([\d.]+)", value)
            if m:
                value = decimal.Decimal(m.group(1))
        return value

或者，可以使用 TypeDecorator.column_expression() 方法进行 CAST 转换，如下所示：

import decimal
from sqlalchemy import cast
from sqlalchemy import TypeDecorator
class NumericMoney(TypeDecorator):
    impl = MONEY
    def column_expression(self, column: Any):
        return cast(column, Numeric())

新版本 1.2 中新增。

类签名

类 sqlalchemy.dialects.postgresql.MONEY (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.OID

提供 PostgreSQL OID 类型。

类签名

类 sqlalchemy.dialects.postgresql.OID (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.REAL

SQL REAL 类型。

另见

Float - 基本类型的文档。

类签名

类 sqlalchemy.dialects.postgresql.REAL (sqlalchemy.types.Float)

method __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 中的新功能。
要创建一个数据库无关的 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.dialects.postgresql.REGCONFIG

提供 PostgreSQL REGCONFIG 类型。

新版本 2.0.0rc1 中加入。

类签名

类 sqlalchemy.dialects.postgresql.REGCONFIG (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.REGCLASS

提供 PostgreSQL REGCLASS 类型。

新版本 1.2.7 中加入。

类签名

类 sqlalchemy.dialects.postgresql.REGCLASS (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.TIMESTAMP

提供 PostgreSQL TIMESTAMP 类型。

成员

init()

类签名

类 sqlalchemy.dialects.postgresql.TIMESTAMP (sqlalchemy.types.TIMESTAMP)

method __init__(timezone: bool = False, precision: int | None = None) → None

构造一个 TIMESTAMP。

参数：

timezone – 如果有时区则为布尔值，默认为 False
precision –
可选的整数精度值
新版本 1.4 中加入。

class sqlalchemy.dialects.postgresql.TIME

PostgreSQL TIME 类型。

成员

init()

类签名

类 sqlalchemy.dialects.postgresql.TIME (sqlalchemy.types.TIME)

method __init__(timezone: bool = False, precision: int | None = None) → None

构建一个 TIME。

参数：

timezone – 如果时区存在，则为布尔值，默认为 False
precision –
可选的整数精度值
版本 1.4 中的新功能。

class sqlalchemy.dialects.postgresql.TSQUERY

提供 PostgreSQL TSQUERY 类型。

版本 2.0.0rc1 中的新功能。

类签名

类 sqlalchemy.dialects.postgresql.TSQUERY (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.TSVECTOR

TSVECTOR 类型实现了 PostgreSQL 文本搜索类型 TSVECTOR。

可用于对自然语言文档进行全文查询。

另请参阅

全文搜索

类签名

类 sqlalchemy.dialects.postgresql.TSVECTOR (sqlalchemy.types.TypeEngine)

class sqlalchemy.dialects.postgresql.UUID

表示 SQL UUID 类型。

这是 Uuid 数据库不可知数据类型的 SQL 本机形式，并且向后兼容以前的仅限于 PostgreSQL 的 UUID 版本。

UUID 数据类型仅适用于具有名为 UUID 的 SQL 数据类型的数据库。对于没有这个确切命名类型的后端，包括 SQL Server，它将无法正常工作。对于具有本机支持的后端不可知 UUID 值，包括 SQL Server 的 UNIQUEIDENTIFIER 数据类型，请使用 Uuid 数据类型。

版本 2.0 中的新功能。

另请参阅

Uuid

类签名

类 sqlalchemy.dialects.postgresql.UUID (sqlalchemy.types.Uuid, sqlalchemy.types.NativeForEmulated)

method __init__(as_uuid: bool = True)

构建一个UUID类型。

参数：

as_uuid=True –

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

class sqlalchemy.dialects.postgresql.INT4RANGE

表示 PostgreSQL INT4RANGE 类型。

类签名

类 sqlalchemy.dialects.postgresql.INT4RANGE (sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange)

class sqlalchemy.dialects.postgresql.INT8RANGE

表示 PostgreSQL INT8RANGE 类型。

类签名

类 sqlalchemy.dialects.postgresql.INT8RANGE （sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange）

class sqlalchemy.dialects.postgresql.NUMRANGE

表示 PostgreSQL NUMRANGE 类型。

类签名

类 sqlalchemy.dialects.postgresql.NUMRANGE （sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange）

class sqlalchemy.dialects.postgresql.DATERANGE

表示 PostgreSQL DATERANGE 类型。

类签名

类 sqlalchemy.dialects.postgresql.DATERANGE （sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange）

class sqlalchemy.dialects.postgresql.TSRANGE

表示 PostgreSQL TSRANGE 类型。

类签名

类 sqlalchemy.dialects.postgresql.TSRANGE （sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange）

class sqlalchemy.dialects.postgresql.TSTZRANGE

表示 PostgreSQL TSTZRANGE 类型。

类签名

类 sqlalchemy.dialects.postgresql.TSTZRANGE （sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange）

class sqlalchemy.dialects.postgresql.INT4MULTIRANGE

表示 PostgreSQL INT4MULTIRANGE 类型。

类签名

类 sqlalchemy.dialects.postgresql.INT4MULTIRANGE （sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange）

class sqlalchemy.dialects.postgresql.INT8MULTIRANGE

表示 PostgreSQL INT8MULTIRANGE 类型。

类签名

类 sqlalchemy.dialects.postgresql.INT8MULTIRANGE （sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange）

class sqlalchemy.dialects.postgresql.NUMMULTIRANGE

表示 PostgreSQL NUMMULTIRANGE 类型。

类签名

类 sqlalchemy.dialects.postgresql.NUMMULTIRANGE （sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange）

class sqlalchemy.dialects.postgresql.DATEMULTIRANGE

表示 PostgreSQL DATEMULTIRANGE 类型。

类签名

class sqlalchemy.dialects.postgresql.DATEMULTIRANGE (sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange)

class sqlalchemy.dialects.postgresql.TSMULTIRANGE

表示 PostgreSQL TSRANGE 类型。

类签名

class sqlalchemy.dialects.postgresql.TSMULTIRANGE (sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange)

class sqlalchemy.dialects.postgresql.TSTZMULTIRANGE

表示 PostgreSQL TSTZRANGE 类型。

类签名

class sqlalchemy.dialects.postgresql.TSTZMULTIRANGE (sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange)

class sqlalchemy.dialects.postgresql.MultiRange

表示一个多范围序列。

这个列表子类是一个实用工具，可以根据单个范围值自动推断适当的多范围 SQL 类型。在操作文本多范围时，这是非常有用的：

import sqlalchemy as sa
from sqlalchemy.dialects.postgresql import MultiRange, Range
value = literal(MultiRange([Range(2, 4)]))
select(tbl).where(tbl.c.value.op("@")(MultiRange([Range(-3, 7)])))

在 2.0.26 版本中新增。

另请参阅

使用 MultiRange 序列来推断多范围类型.

类签名

class sqlalchemy.dialects.postgresql.MultiRange (builtins.list, typing.Generic)

SqlAlchemy 2.0 中文文档（四十八）（5）https://developer.aliyun.com/article/1563011

SqlAlchemy 2.0 中文文档（四十八）（4）

范围和多范围类型

多范围

使用 MultiRange 序列推断多范围类型

多范围

使用 MultiRange 序列推断多范围类型

网络数据类型

PostgreSQL 数据类型

热门文章

最新文章

相关电子书

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

SqlAlchemy 2.0 中文文档（四十八）（4）

范围和多范围类型

多范围

使用 MultiRange 序列推断多范围类型

多范围

使用 MultiRange 序列推断多范围类型

网络数据类型

PostgreSQL 数据类型

热门文章

最新文章

相关电子书