SqlAlchemy 2.0 中文文档（三十四）（3）

SqlAlchemy 2.0 中文文档（三十四）（2）https://developer.aliyun.com/article/1562818

参数：

• other – 待比较的表达式。通常是普通的字符串值，但也可以是任意的 SQL 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.endswith.autoescape 标志被设置为 True。
  
• autoescape –
  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中的所有 "%"、"_" 和转义字符本身的出现，假定比较值是字面字符串而不是 SQL 表达式。
  例如：

somecolumn.endswith("foo%bar", autoescape=True)

• 将呈现为：

somecolumn LIKE '%' || :param ESCAPE '/'

• 使用值 :param 作为 "foo/%bar"。
• escape –
  一个字符，当给定时，将使用 ESCAPE 关键字来将该字符设定为转义字符。然后可以将该字符放在 % 和 _ 的前面，以允许它们作为自身而不是通配符字符。
  例如：

somecolumn.endswith("foo/%bar", escape="^")

• 将呈现为：

somecolumn LIKE '%' || :param ESCAPE '^'

• 参数也可以与 ColumnOperators.endswith.autoescape 结合使用：

somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

• 在上述情况下，给定的字面参数将在传递到数据库之前转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.startswith()

ColumnOperators.contains()

ColumnOperators.like()

method icontains(other: Any, **kw: Any) → ColumnOperators

实现 icontains 操作符，例如 ColumnOperators.contains() 的不区分大小写版本。

生成一个 LIKE 表达式，用于对字符串值中间的大小写不敏感匹配进行测试：

lower(column) LIKE '%' || lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.icontains("foobar"))

由于该操作符使用 LIKE，在 表达式中存在的通配符字符 "%" 和 "_" 也将像通配符一样起作用。对于字面字符串值，可以将 ColumnOperators.icontains.autoescape 标志设置为 True，以对字符串值中这些字符的出现进行转义，使它们作为自身而不是通配符字符进行匹配。或者，ColumnOperators.icontains.escape 参数将建立一个给定字符作为转义字符，当目标表达式不是字面字符串时可能会有用。

参数：

• other – 要比较的表达式。通常是一个普通的字符串值，但也可以是任意的 SQL 表达式。LIKE 通配符 % 和 _ 默认情况下不会被转义，除非设置了 ColumnOperators.icontains.autoescape 标志为 True。
  
• autoescape –
  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中所有的 "%"、"_" 和转义字符本身的出现，假定比较值是一个字面字符串而不是 SQL 表达式。
  例如：

somecolumn.icontains("foo%bar", autoescape=True)

• 将呈现为：

lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'

• 其中:param的值为"foo/%bar"。
• escape –
  一个字符，当给定时，将使用ESCAPE关键字呈现，以将该字符作为转义字符。然后，可以将此字符放在%和_的前面，以允许它们作为自身而不是通配符字符。
  例如：

somecolumn.icontains("foo/%bar", escape="^")

• 将呈现为：

lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'

• 该参数还可以与ColumnOperators.contains.autoescape结合使用：

somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)

• 在上述情况下，给定的文字参数将在传递到数据库之前转换为"foo^%bar^^bat"。

另请参阅

ColumnOperators.contains()

method iendswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

实现iendswith运算符，例如，ColumnOperators.endswith()的不区分大小写版本。

生成一个对字符串值末尾进行不区分大小写匹配的 LIKE 表达式：

lower(column) LIKE '%' || lower(<other>)

例如：

stmt = select(sometable).\
    where(sometable.c.column.iendswith("foobar"))

由于该运算符使用LIKE，因此在表达式中存在的通配符字符"%"和"_"也将像通配符一样起作用。对于文字字符串值，可以将ColumnOperators.iendswith.autoescape标志设置为True，以对字符串值中这些字符的出现进行转义，使它们匹配为它们自身而不是通配符字符。或者，ColumnOperators.iendswith.escape参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时可能会有用。

参数：

• other – 要进行比较的表达式。通常是一个普通的字符串值，但也可以是任意的 SQL 表达式。除非将ColumnOperators.iendswith.autoescape标志设置为 True，否则 LIKE 通配符字符%和_默认不会被转义。
  
• autoescape –
  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中所有的"%"、"_"和转义字符本身的出现，假定比较值是一个文字字符串而不是 SQL 表达式。
  例如：

somecolumn.iendswith("foo%bar", autoescape=True)

• 将呈现为：

lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'

• 其中:param的值为"foo/%bar"。
• escape –
  一个字符，当给定时，将使用ESCAPE关键字呈现，以将该字符作为转义字符。然后，可以将此字符放在%和_的前面，以允许它们作为自身而不是通配符字符。
  例如：

somecolumn.iendswith("foo/%bar", escape="^")

• 将呈现为：

lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'

• 参数也可以与ColumnOperators.iendswith.autoescape结合使用：

somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

• 在上面的例子中，给定的文字参数将在传递给数据库之前转换为"foo^%bar^^bat"。

参见

ColumnOperators.endswith()

method ilike(other: Any, escape: str | None = None) → ColumnOperators

实现ilike运算符，例如，大小写不敏感的 LIKE。

在列上下文中，生成的表达式形式为：

lower(a) LIKE lower(other)

或者在支持 ILIKE 运算符的后端上：

a ILIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.ilike("%foobar%"))

参数：

• other – 要比较的表达式
  
• escape –
  可选的转义字符，呈现ESCAPE关键字，例如：

somecolumn.ilike("foo/%bar", escape="/")

参见

ColumnOperators.like()

method in_(other: Any) → ColumnOperators

实现in运算符。

在列上下文中，生成子句column IN 。

给定的参数other可以是：

• 一个文字值列表，例如：

stmt.where(column.in_([1, 2, 3]))

• 在这种调用形式中，项目列表将转换为与给定列表长度相同的一组绑定参数：

WHERE COL IN (?, ?, ?)

• 如果比较是针对包含多个表达式的tuple_()的元组，则可以提供一个元组列表：

from sqlalchemy import tuple_
stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))

• 一个空列表，例如：

stmt.where(column.in_([]))

• 在这种调用形式中，表达式呈现出一个“空集”表达式。这些表达式针对各个后端进行了定制，通常试图得到一个空的 SELECT 语句作为子查询。例如，在 SQLite 上，表达式是：

WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

• 从版本 1.4 开始更改：在所有情况下，空 IN 表达式现在都使用运行时生成的 SELECT 子查询。
• 如果包含了bindparam.expanding标志，则可以使用绑定的参数，例如bindparam()：

stmt.where(column.in_(bindparam('value', expanding=True)))

• 在这种调用形式中，表达式呈现出一个特殊的非 SQL 占位符表达式，看起来像：

WHERE COL IN ([EXPANDING_value])

• 此占位符表达式在语句执行时被拦截，以转换为前面所示的可变数量的绑定参数形式。如果执行语句为：

connection.execute(stmt, {"value": [1, 2, 3]})

• 数据库将为每个值传递一个绑定参数：

WHERE COL IN (?, ?, ?)

• 新版本 1.2 中：添加了“expanding”绑定参数
  如果传递了空列表，则会呈现一个特殊的“空列表”表达式，该表达式特定于正在使用的数据库。在 SQLite 上，这将是：

WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

• 新版本 1.3 中：现在“expanding”绑定参数支持空列表
• 一个select()构造，通常是相关的标量选择：

stmt.where(
    column.in_(
        select(othertable.c.y).
        where(table.c.x == othertable.c.x)
    )
)

• 在这种调用形式中，ColumnOperators.in_()呈现如下：

WHERE COL IN (SELECT othertable.y
FROM othertable WHERE othertable.x = table.x)

参数：

other – 一系列文字、一个 select() 构造，或者一个包含设置为 True 的 bindparam.expanding 标志的 bindparam() 构造。

method is_(other: Any) → ColumnOperators

实现 IS 操作符。

通常情况下，与 None 值进行比较时会自动生成 IS，其解析为 NULL。但是，在某些平台上，如果要与布尔值进行比较，则可能希望显式使用 IS。

另请参阅

ColumnOperators.is_not()

method is_distinct_from(other: Any) → ColumnOperators

实现 IS DISTINCT FROM 操作符。

在大多数平台上呈现“a IS DISTINCT FROM b”；在某些平台上，例如 SQLite 可以呈现“a IS NOT b”。

method is_not(other: Any) → ColumnOperators

实现 IS NOT 操作符。

通常情况下，与 None 值进行比较时会自动生成 IS NOT，其解析为 NULL。但是，在某些平台上，如果要与布尔值进行比较，则可能希望显式使用 IS NOT。

在版本 1.4 中更改：is_not() 操作符从以前的版本中重命名为 isnot()。以前的名称仍可用于向后兼容。

另请参阅

ColumnOperators.is_()

method is_not_distinct_from(other: Any) → ColumnOperators

实现 IS NOT DISTINCT FROM 操作符。

在大多数平台上呈现“a IS NOT DISTINCT FROM b”；在某些平台上，例如 SQLite 可以呈现“a IS b”。

在版本 1.4 中更改：is_not_distinct_from() 操作符从以前的版本中重命名为 isnot_distinct_from()。以前的名称仍可用于向后兼容。

method isnot(other: Any) → ColumnOperators

实现 IS NOT 操作符。

通常情况下，与 None 值进行比较时会自动生成 IS NOT，其解析为 NULL。但是，在某些平台上，如果要与布尔值进行比较，则可能希望显式使用 IS NOT。

在版本 1.4 中更改：is_not() 操作符从以前的版本中重命名为 isnot()。以前的名称仍可用于向后兼容。

另请参阅

ColumnOperators.is_()

method isnot_distinct_from(other: Any) → ColumnOperators

实现 IS NOT DISTINCT FROM 操作符。

在大多数平台上呈现“a IS NOT DISTINCT FROM b”；在某些平台上，例如 SQLite 可以呈现“a IS b”。

在版本 1.4 中更改：is_not_distinct_from() 操作符从以前的版本中重命名为 isnot_distinct_from()。以前的名称仍可用于向后兼容。

method istartswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

实现 istartswith 操作符，例如 ColumnOperators.startswith() 的不区分大小写版本。

生成一个 LIKE 表达式，用于对字符串值的开头进行不区分大小写的匹配：

lower(column) LIKE lower(<other>) || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.istartswith("foobar"))

由于运算符使用了LIKE，所以存在于表达式中的通配符字符"%"和"_"也将像通配符一样工作。对于字面字符串值，可以将ColumnOperators.istartswith.autoescape标志设置为True，以将这些字符在字符串值中的出现进行转义，使它们作为自身匹配，而不是作为通配符字符。另外，ColumnOperators.istartswith.escape参数将建立一个给定字符作为转义字符，当目标表达式不是字面字符串时，这可能会有用。

参数：

• other – 待比较的表达式。通常是普通字符串值，但也可以是任意的 SQL 表达式。除非设置了ColumnOperators.istartswith.autoescape标志为 True，否则 LIKE 通配符字符%和_不会被转义。
  
• autoescape –
  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中的所有"%"、"_"和转义字符本身的出现，假定比较值是字面字符串而不是 SQL 表达式。
  例如以下表达式：

somecolumn.istartswith("foo%bar", autoescape=True)

• 将呈现为：

lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'

• 值为:param，为"foo/%bar"。
• escape –
  当给定时，将呈现一个字符与ESCAPE关键字以建立该字符作为转义字符。然后可以将此字符放在%和_的前面以允许它们作为自身而不是通配符字符。
  例如以下表达式：

somecolumn.istartswith("foo/%bar", escape="^")

• 将呈现为：

lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'

• 此参数也可以与ColumnOperators.istartswith.autoescape组合使用：

somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)

• 在上述情况下，给定的字面参数将在传递到数据库之前转换为"foo^%bar^^bat"。

另见

ColumnOperators.startswith()

method like(other: Any, escape: str | None = None) → ColumnOperators

实现like运算符。

在列上下文中，产生表达式：

a LIKE other

例如：

stmt = select(sometable).\
    where(sometable.c.column.like("%foobar%"))

参数：

• other – 待比较的表达式
  
• escape –
  可选的转义字符，呈现ESCAPE关键字，例如：

somecolumn.like("foo/%bar", escape="/")

另见

ColumnOperators.ilike()

method match(other: Any, **kwargs: Any) → ColumnOperators

实现特定于数据库的‘match’运算符。

ColumnOperators.match() 尝试解析为后端提供的类似 MATCH 的函数或操作符。 例如：

• PostgreSQL - 渲染 x @@ plainto_tsquery(y)

自版本 2.0 起：现在对于 PostgreSQL 使用 plainto_tsquery() 而不是 to_tsquery()；为了与其他形式兼容，请参阅全文搜索。

• MySQL - 渲染 MATCH (x) AGAINST (y IN BOOLEAN MODE)
  另请参见
  match - 具有附加功能的 MySQL 特定构造。
  
• Oracle - 渲染 CONTAINS(x, y)
  
• 其他后端可能提供特殊实现。
  
• 没有任何特殊实现的后端将将操作符输出为“MATCH”。 例如，这与 SQLite 兼容。
  

method not_ilike(other: Any, escape: str | None = None) → ColumnOperators

实现 NOT ILIKE 操作符。

这相当于对 ColumnOperators.ilike() 使用否定，即 ~x.ilike(y)。

自版本 1.4 起：not_ilike() 操作符从先前版本的 notilike() 重命名。 以前的名称仍可用于向后兼容。

另请参见

ColumnOperators.ilike()

method not_in(other: Any) → ColumnOperators

实现 NOT IN 操作符。

这相当于对 ColumnOperators.in_() 使用否定，即 ~x.in_(y)。

如果 other 是一个空序列，则编译器会生成一个“空 not in” 表达式。 默认情况下，这将产生一个“1 = 1” 表达式，以在所有情况下产生 true。 可以使用 create_engine.empty_in_strategy 来更改此行为。

自版本 1.4 起：not_in() 操作符从先前版本的 notin_() 重命名。 以前的名称仍可用于向后兼容。

自版本 1.2 起：ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认为一个空的 IN 序列生成一个“静态” 表达式。

另请参见

ColumnOperators.in_()

method not_like(other: Any, escape: str | None = None) → ColumnOperators

实现 NOT LIKE 操作符。

这相当于对 ColumnOperators.like() 使用否定，即 ~x.like(y)。

从版本 1.4 开始更改：not_like() 操作符在先前版本中从 notlike() 重命名。 以前的名称仍然可用于向后兼容。

另请参阅

ColumnOperators.like()

method notilike(other: Any, escape: str | None = None) → ColumnOperators

实现 NOT ILIKE 操作符。

这相当于对 ColumnOperators.ilike() 使用否定，即 ~x.ilike(y)。

从版本 1.4 开始更改：not_ilike() 操作符在先前版本中从 notilike() 重命名。 以前的名称仍然可用于向后兼容。

另请参阅

ColumnOperators.ilike()

method notin_(other: Any) → ColumnOperators

实现 NOT IN 操作符。

这相当于对 ColumnOperators.in_() 使用否定，即 ~x.in_(y)。

在 other 是空序列的情况下，编译器生成一个“空的 not in” 表达式。 这默认为表达式 “1 = 1”，以在所有情况下生成 true。 create_engine.empty_in_strategy 可用于更改此行为。

从版本 1.4 开始更改：not_in() 操作符在先前版本中从 notin_() 重命名。 以前的名称仍然可用于向后兼容。

从版本 1.2 开始更改：ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认情况下会为空的 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

method notlike(other: Any, escape: str | None = None) → ColumnOperators

实现 NOT LIKE 操作符。

这相当于对 ColumnOperators.like() 使用否定，即 ~x.like(y)。

从版本 1.4 开始更改：not_like() 操作符在先前版本中从 notlike() 重命名。 以前的名称仍然可用于向后兼容。

另请参阅

ColumnOperators.like()

method nulls_first() → ColumnOperators

生成针对父对象的 nulls_first() 子句。

从版本 1.4 开始更改：nulls_first() 操作符在先前版本中从 nullsfirst() 重命名。 以前的名称仍然可用于向后兼容。

method nulls_last() → ColumnOperators

对父对象生成一个nulls_last()子句。

从版本 1.4 开始：nulls_last()运算符在以前的版本中从nullslast()重命名。以前的名称仍然可用以实现向后兼容。

method nullsfirst() → ColumnOperators

对父对象生成一个nulls_first()子句。

从版本 1.4 开始：nulls_first()运算符在以前的版本中从nullsfirst()重命名。以前的名称仍然可用以实现向后兼容。

method nullslast() → ColumnOperators

对父对象生成一个nulls_last()子句。

从版本 1.4 开始：nulls_last()运算符在以前的版本中从nullslast()重命名。以前的名称仍然可用以实现向后兼容。

method op(opstring: str, precedence: int = 0, is_comparison: bool = False, return_type: Type[TypeEngine[Any]] | TypeEngine[Any] | None = None, python_impl: Callable[..., Any] | None = None) → Callable[[Any], Operators]

继承自 Operators.op() 方法的 Operators

生成一个通用的操作符函数。

例如：

somecolumn.op("*")(5)

产生：

somecolumn * 5

此函数还可用于明确表示位运算符。例如：

somecolumn.op('&')(0xff)

是在somecolumn中的值的按位与。

参数：

• opstring – 一个字符串，将在此元素和传递给生成函数的表达式之间输出为中缀操作符。
  
• precedence –
  预期数据库在 SQL 表达式中应用于操作符的优先级。此整数值作为 SQL 编译器的提示，用于确定何时应在特定操作周围呈现显式括号。当应用于具有更高优先级的另一个操作符时，较低的数字将导致表达式被括在括号中。默认值0低于所有操作符，除了逗号（,）和AS操作符外。值为 100 将高于或等于所有操作符，-100 将低于或等于所有操作符。
  另请参见
  我正在使用 op()生成自定义操作符，但是我的括号不正确 - SQLAlchemy SQL 编译器如何渲染括号的详细描述
  
• is_comparison –
  legacy；如果为 True，则将操作符视为“比较”操作符，即评估为布尔值 true/false 的操作符，如==、>等。提供此标志是为了让 ORM 关系能够确定当在自定义连接条件中使用操作符时，该操作符是比较操作符。
  使用is_comparison参数已经被使用Operators.bool_op()方法取代；这个更简洁的操作符会自动设置这个参数，但也会提供正确的PEP 484类型支持，因为返回的对象将表示“布尔”数据类型，即BinaryExpression[bool]。
  
• return_type – 一个TypeEngine类或对象，它将强制此运算符生成的表达式的返回类型为该类型。默认情况下，指定Operators.op.is_comparison的运算符将解析为Boolean，而不指定的运算符将与左操作数的类型相同。
  
• python_impl –
  可选的  Python 函数，可以以与在数据库服务器上运行此运算符时运行相同的方式评估两个 Python 值。用于在 Python 中进行 SQL  表达式评估函数，例如用于 ORM 混合属性的函数，以及用于在多行更新或删除后匹配会话中的对象的 ORM “评估器”。
  例如：

>>> expr = column('x').op('+', python_impl=lambda a, b: a + b)('y')

• 上述表达式的运算符也将适用于非 SQL 左侧和右侧对象：

>>> expr.operator(5, 10)
15

• 新版本 2.0 中新增。

请参见

Operators.bool_op()

重新定义和创建新运算符

在连接条件中使用自定义运算符

method operate(op: OperatorType, *other: Any, **kwargs: Any) → Operators

从 Operators.operate() 方法继承

对参数执行操作。

这是操作的最低级别，默认情况下引发NotImplementedError。

在子类中重写这一点可以使常见行为应用于所有操作。例如，重写ColumnOperators以将func.lower()应用于左侧和右侧：

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 运算符可调用。
  
• *other – 操作的“其他”一侧。对于大多数操作，它将是一个单个标量。
  
• **kwargs – 修饰符。这些可能由特殊运算符传递，如ColumnOperators.contains()。
  

method regexp_match(pattern: Any, flags: str | None = None) → ColumnOperators

实现数据库特定的‘正则表达式匹配’运算符。

例如：

stmt = select(table.c.some_column).where(
    table.c.some_column.regexp_match('^(b|c)')
)

ColumnOperators.regexp_match() 试图解析为后端提供的类似 REGEXP 的函数或操作符，然而具体的正则表达式语法和可用标志与后端无关。

示例包括：

• PostgreSQL - 渲染为 x ~ y 或当否定时 x !~ y。
  
• Oracle - 渲染为 REGEXP_LIKE(x, y)
  
• SQLite - 使用 SQLite 的 REGEXP 占位符操作符，并调用 Python 的 re.match() 内置函数。
  
• 其他后端可能提供特殊实现。
  
• 没有任何特殊实现的后端将生成操作符为 “REGEXP” 或 “NOT REGEXP”。例如，这与 SQLite 和 MySQL 兼容。
  

正则表达式支持当前已经在 Oracle、PostgreSQL、MySQL 和 MariaDB 中实现。对于 SQLite，提供了部分支持。第三方方言的支持可能有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。
  
• flags – 要应用的任何正则表达式字符串标志，仅作为普通的 Python 字符串传递。这些标志是后端特定的。一些后端，如 PostgreSQL 和  MariaDB，可能也会将标志作为模式的一部分来指定。在 PostgreSQL 中使用忽略大小写标志 ‘i’  时，将使用忽略大小写的正则表达式匹配操作符 ~* 或 !~*。
  

新版本 1.4 中新增。

从版本 1.4.48 改变，：2.0.18 请注意，由于实现错误，“flags” 参数先前接受了 SQL  表达式对象，如列表达式，除了普通的 Python 字符串。这个实现与缓存一起无法正确工作，因此被删除；应该只传递字符串给 “flags”  参数，因为这些标志将作为 SQL 表达式中的文字内联值呈现。

另请参阅

ColumnOperators.regexp_replace()

method regexp_replace(pattern: Any, replacement: Any, flags: str | None = None) → ColumnOperators

实现了特定于数据库的“正则表达式替换”操作符。

例如：

stmt = select(
    table.c.some_column.regexp_replace(
        'b(..)',
        'XY',
        flags='g'
    )
)

ColumnOperators.regexp_replace() 试图解析为由后端提供的类似 REGEXP_REPLACE 的函数，通常会生成函数 REGEXP_REPLACE()。然而，具体的正则表达式语法和可用标志与后端相关。

正则表达式替换支持当前已在 Oracle、PostgreSQL、MySQL 8 或更高版本以及 MariaDB 中实现。第三方方言的支持可能有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。
  
• pattern – 替换字符串或列子句。
  
• flags – 要应用的任何正则表达式字符串标志，仅作为普通的 Python 字符串传递。这些标志是后端特定的。一些后端，如 PostgreSQL 和 MariaDB，可能也会将标志作为模式的一部分来指定。
  

新版本 1.4 中新增。

自版本 1.4.48 更改，: 2.0.18 请注意，由于实现错误，"flags"参数先前接受了 SQL  表达式对象，例如列表达式，而不仅仅是普通的 Python  字符串。该实现与缓存一起不正确地工作，并已被删除；"flags"参数应仅传递字符串，因为这些标志被呈现为 SQL 表达式中的文字内联值。

另请参见

ColumnOperators.regexp_match()

method reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → Operators

从 Operators 的 Operators.reverse_operate() 方法继承的

对参数进行反向操作。

使用方法与operate()相同。

method startswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators

实现startswith操作符。

生成一个 LIKE 表达式，用于测试字符串值开头的匹配：

column LIKE <other> || '%'

例如：

stmt = select(sometable).\
    where(sometable.c.column.startswith("foobar"))

由于该操作符使用LIKE，因此存在于表达式内部的通配符字符"%"和"_"也将像通配符一样运行。对于文字字符串值，可以将ColumnOperators.startswith.autoescape标志设置为True，以将这些字符的出现转义为字符串值内部的这些字符，使它们匹配为自身而不是通配符字符。或者，ColumnOperators.startswith.escape参数将建立一个给定的字符作为转义字符，当目标表达式不是文字字符串时可能会有用。

参数：

• other – 要比较的表达式。通常这是一个纯字符串值，但也可以是任意的 SQL 表达式。除非设置了ColumnOperators.startswith.autoescape标志为 True，否则LIKE通配符字符%和_默认不会被转义。
  
• autoescape –
  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中的所有出现的"%"、"_"和转义字符本身，假定比较值是一个文字字符串而不是 SQL 表达式。
  一个类似于：

somecolumn.startswith("foo%bar", autoescape=True)

• 将呈现为：

somecolumn LIKE :param || '%' ESCAPE '/'

• 其值为:param的值为"foo/%bar"。
• escape –
  一个字符，当给定时，将使用ESCAPE关键字来建立该字符作为转义字符。然后可以将该字符放在%和_之前的位置，以允许它们作为自身而不是通配符字符。
  诸如：

somecolumn.startswith("foo/%bar", escape="^")

• 将渲染为：

somecolumn LIKE :param || '%' ESCAPE '^'

• 参数也可以与 ColumnOperators.startswith.autoescape 结合使用：

somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)

• 在上述情况下，给定的文字参数将在传递到数据库之前转换为 "foo^%bar^^bat"。

另见

ColumnOperators.endswith()

ColumnOperators.contains()

ColumnOperators.like()

attribute timetuple: Literal[None] = None

黑客，允许在左边比较日期时间对象。

class sqlalchemy.sql.expression.Extract

表示一个 SQL EXTRACT 子句，extract(field FROM expr)。

类签名

类 sqlalchemy.sql.expression.Extract (sqlalchemy.sql.expression.ColumnElement)

class sqlalchemy.sql.expression.False_

表示 SQL 语句中的 false 关键字，或者等效的。

False_ 通过 false() 函数被访问为一个常量。

类签名

类 sqlalchemy.sql.expression.False_ (sqlalchemy.sql.expression.SingletonConstant, sqlalchemy.sql.roles.ConstExprRole, sqlalchemy.sql.expression.ColumnElement)

class sqlalchemy.sql.expression.FunctionFilter

表示一个函数 FILTER 子句。

这是针对聚合和窗口函数的特殊操作符，用于控制传递给它的行。仅受某些数据库后端支持。

调用 FunctionFilter 是通过 FunctionElement.filter() 进行的：

func.count(1).filter(True)

另见

FunctionElement.filter()

成员

filter(), over(), self_group()

类签名

类 sqlalchemy.sql.expression.FunctionFilter (sqlalchemy.sql.expression.ColumnElement)

method filter(*criterion: _ColumnExpressionArgument[bool]) → Self

对该函数进行额外的过滤。

这个方法向由FunctionElement.filter()设置的初始条件添加额外的条件。

多个条件在 SQL 渲染时通过AND连接在一起。

method over(partition_by: Iterable[_ColumnExpressionArgument[Any]] | _ColumnExpressionArgument[Any] | None = None, order_by: Iterable[_ColumnExpressionArgument[Any]] | _ColumnExpressionArgument[Any] | None = None, range_: typing_Tuple[int | None, int | None] | None = None, rows: typing_Tuple[int | None, int | None] | None = None) → Over[_T]

对这个过滤函数产生一个 OVER 子句。

用于聚合或所谓的“窗口”函数，适用于支持窗口函数的数据库后端。

表达式：

func.rank().filter(MyClass.y > 5).over(order_by='x')

是以下内容的简写：

from sqlalchemy import over, funcfilter
over(funcfilter(func.rank(), MyClass.y > 5), order_by='x')

查看over()获取完整描述。

method self_group(against: OperatorType | None = None) → Self | Grouping[_T]

对这个ClauseElement应用一个“分组”。

这个方法被子类重写以返回一个“分组”构造，即括号。特别是它被“二进制”表达式使用，当它们被放置到更大的表达式中时提供一个围绕自身的分组，以及当它们被放置到另一个select()的 FROM 子句中时，由select()构造使用。（请注意，子查询通常应该使用Select.alias()方法创建，因为许多平台要求嵌套的 SELECT 语句必须命名）。

当表达式组合在一起时，self_group()的应用是自动的 - 最终用户代码不应该直接使用这个方法。请注意，SQLAlchemy 的子句构造考虑了运算符优先级 - 因此在表达式中可能不需要括号，例如，x OR (y AND z) - AND 优先于 OR。

ClauseElement的基本self_group()方法只返回自身。

class sqlalchemy.sql.expression.Label

代表一个列标签（AS）。

代表一个标签，通常使用AS sql 关键字应用于任何列级元素。

成员

foreign_keys, primary_key, self_group()

类签名

类sqlalchemy.sql.expression.Label (sqlalchemy.sql.roles.LabeledColumnExprRole, sqlalchemy.sql.expression.NamedColumn)

attribute foreign_keys: AbstractSet[ForeignKey]

attribute primary_key: bool

method self_group(against=None)

对这个ClauseElement应用一个“分组”。

子类会重写此方法以返回“分组”结构，即括号。特别是，当“二进制”表达式放置到更大的表达式中时，它们会提供围绕自己的分组，以及当select()构造放置到另一个select()的 FROM 子句中时。 （请注意，子查询通常应使用Select.alias()方法创建，因为许多平台要求嵌套的 SELECT 语句具有名称）。

当表达式组合在一起时，self_group()的应用是自动的 - 最终用户代码不应直接使用此方法。请注意，SQLAlchemy 的子句构造考虑了操作符优先级 - 因此，可能不需要括号，例如，在表达式x OR (y AND z)中 - AND 优先于 OR。

ClauseElement的基本self_group()方法只返回自身。

class sqlalchemy.sql.expression.Null

在 SQL 语句中表示 NULL 关键字。

Null通过null()函数作为常量访问。

类签名

类sqlalchemy.sql.expression.Null (sqlalchemy.sql.expression.SingletonConstant，sqlalchemy.sql.roles.ConstExprRole，sqlalchemy.sql.expression.ColumnElement)

class sqlalchemy.sql.expression.Operators

比较基础和逻辑运算符。

实现基本方法Operators.operate()和Operators.reverse_operate()，以及Operators.__and__()，Operators.__or__()，Operators.__invert__()。

成员

and(), invert(), or(), sa_operate(), bool_op(), op(), operate(), reverse_operate()

通常通过其最常见的子类ColumnOperators使用。

method __and__(other: Any) → Operators

实现&运算符。

当与 SQL 表达式一起使用时，会导致一个 AND 操作，相当于and_()，即：

a & b

相当于：

from sqlalchemy import and_
and_(a, b)

在使用&时应注意运算符优先级；&运算符具有最高优先级。如果操作数包含进一步的子表达式，则应将其括在括号中：

(a == 2) & (b == 4)

method __invert__() → Operators

实现~运算符。

当与 SQL 表达式一起使用时，会导致一个 NOT 操作，相当于not_()，即：

~a

相当于：

from sqlalchemy import not_
not_(a)

method __or__(other: Any) → Operators

实现|运算符。

当与 SQL 表达式一起使用时，会导致一个 OR 操作，相当于or_()，即：

a | b

相当于：

from sqlalchemy import or_
or_(a, b)

在使用|时应注意运算符优先级；|运算符具有最高优先级。如果操作数包含进一步的子表达式，则应将其括在括号中：

(a == 2) | (b == 4)

method __sa_operate__(op: OperatorType, *other: Any, **kwargs: Any) → Operators

对参数进行操作。

这是操作的最低级别，通常默认引发NotImplementedError。

在子类上覆盖这个可以允许将常见行为应用于所有操作。例如，覆盖ColumnOperators以将func.lower()应用于左侧和右侧：

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 运算符可调用。
  
• *other – 操作的‘另一’侧。对于大多数操作，将是一个单一标量。
  
• **kwargs – 修饰符。这些可以通过特殊运算符传递，比如ColumnOperators.contains()。
  

method bool_op(opstring: str, precedence: int = 0, python_impl: Callable[[...], Any] | None = None) → Callable[[Any], Operators]

返回一个自定义布尔运算符。

此方法是调用Operators.op()并传递带有 True 的Operators.op.is_comparison标志的简写。使用Operators.bool_op()的一个关键优势是，在使用列构造时，返回表达式的“布尔”性质将出现在PEP 484中。

另请参阅

Operators.op()

method op(opstring: str, precedence: int = 0, is_comparison: bool = False, return_type: Type[TypeEngine[Any]] | TypeEngine[Any] | None = None, python_impl: Callable[..., Any] | None = None) → Callable[[Any], Operators]

生成一个通用运算符函数。

例如：

somecolumn.op("*")(5)

产生：

somecolumn * 5

此函数还可用于使位运算符明确。例如：

somecolumn.op('&')(0xff)

是somecolumn中值的按位 AND。

参数：

• opstring – 一个字符串，将作为此元素与传递给生成函数的表达式之间的中缀运算符输出。
  
• precedence –
  操作符在 SQL 表达式中预期数据库应用的优先级。此整数值作为 SQL 编译器的提示，用于了解何时应在特定操作周围呈现显式括号。较低的数字将导致在与具有较高优先级的另一个操作符应用时对表达式进行括号化。默认值为0，低于所有操作符，除了逗号（,）和 AS 操作符。值为 100 将高于或等于所有操作符，-100 将低于或等于所有操作符。
  另请参阅
  我正在使用 op() 生成自定义操作符，但我的括号不正确 - SQLAlchemy SQL 编译器如何呈现括号的详细描述
  
• is_comparison –
  传统的；如果为 True，则将该操作符视为“比较”操作符，即评估为布尔真/假值的操作符，如 ==、> 等。提供此标志是为了当在自定义连接条件中使用时，ORM 关系可以确认该操作符是比较操作符。
  使用 is_comparison 参数已被使用 Operators.bool_op() 方法替代；此更简洁的操作符会自动设置此参数，但也会提供正确的PEP 484类型支持，因为返回的对象将表示“布尔”数据类型，即 BinaryExpression[bool]。
  
• return_type – 一个TypeEngine类或对象，将强制此操作符生成的表达式的返回类型为该类型。默认情况下，指定Operators.op.is_comparison的操作符将解析为Boolean，而未指定的操作符将与左操作数相同类型。
  
• python_impl –
  一个可选的  Python 函数，可以在数据库服务器上运行此操作符时以与此操作符相同的方式评估两个 Python 值。对于在 Python 中的 SQL  表达式评估函数非常有用，例如 ORM 混合属性，以及用于在多行更新或删除后匹配会话中的对象的 ORM“评估器”。
  例如：

>>> expr = column('x').op('+', python_impl=lambda a, b: a + b)('y')

• 上述表达式的操作符也将适用于非 SQL 左右对象：

>>> expr.operator(5, 10)
15

• 新版本 2.0 中新增。

另请参阅

Operators.bool_op()

重新定义和创建新的操作符

在连接条件中使用自定义操作符

method operate(op: OperatorType, *other: Any, **kwargs: Any) → Operators

对参数进行操作。

这是操作的最低级别，默认情况下引发 NotImplementedError。

在子类上重写此方法可以使常见行为适用于所有操作。例如，重写 ColumnOperators 以将 func.lower() 应用于左侧和右侧：

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 操作符可调用。
  
• *other – 操作的“other”一侧。对于大多数操作，将是一个单一标量。
  
• **kwargs – 修饰符。这些可能会被特殊操作符（例如 ColumnOperators.contains()）传递。
  

method reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → Operators

对参数执行反向操作。

用法与 operate() 相同。

class sqlalchemy.sql.expression.Over

表示一个 OVER 子句。

这是针对所谓的“窗口”函数以及任何聚合函数的特殊操作符，它产生相对于结果集本身的结果。大多数现代 SQL 后端现在支持窗口函数。

成员

element

类签名

class sqlalchemy.sql.expression.Over (sqlalchemy.sql.expression.ColumnElement)

attribute element: ColumnElement[_T]

此 Over 对象引用的基础表达式对象。

class sqlalchemy.sql.expression.SQLColumnExpression

可用于指示任何 SQL 列元素或充当其替代物的对象的类型。

SQLColumnExpression 是 ColumnElement 的基类，并且在 ORM 元素的基类中也是 InstrumentedAttribute 中的一部分，可以在 PEP 484 类型提示中用于指示应该像列表达式一样行为的参数或返回值。

在版本 2.0.0b4 中新增。

类签名

class sqlalchemy.sql.expression.SQLColumnExpression (sqlalchemy.sql.expression.SQLCoreOperations, sqlalchemy.sql.roles.ExpressionElementRole, sqlalchemy.util.langhelpers.TypingOnly)

class sqlalchemy.sql.expression.TextClause

表示一个文字 SQL 文本片段。

例如：

from sqlalchemy import text
t = text("SELECT * FROM users")
result = connection.execute(t)

使用 text() 函数生成 TextClause 构造; 参见该函数以获取完整文档。

另请参见

text()

成员

bindparams(), columns(), self_group()

类签名

sqlalchemy.sql.expression.TextClause类（sqlalchemy.sql.roles.DDLConstraintColumnRole、sqlalchemy.sql.roles.DDLExpressionRole、sqlalchemy.sql.roles.StatementOptionRole、sqlalchemy.sql.roles.WhereHavingRole、sqlalchemy.sql.roles.OrderByRole、sqlalchemy.sql.roles.FromClauseRole、sqlalchemy.sql.roles.SelectStatementRole、sqlalchemy.sql.roles.InElementRole、sqlalchemy.sql.expression.Generative、sqlalchemy.sql.expression.Executable、sqlalchemy.sql.expression.DQLDMLClauseElement、sqlalchemy.sql.roles.BinaryElementRole、sqlalchemy.inspection.Inspectable）

method bindparams(*binds: BindParameter[Any], **names_to_values: Any) → Self

在这个TextClause结构中确定绑定参数的值和/或类型。

给定文本构造如下：

from sqlalchemy import text
stmt = text("SELECT id, name FROM user WHERE name=:name "
            "AND timestamp=:timestamp")

TextClause.bindparams()方法可用于使用简单的关键字参数来确定:name和:timestamp的初始值：

stmt = stmt.bindparams(name='jack',
            timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5))

在上面的代码中，将生成新的BindParameter对象，名称分别为name和timestamp，值分别为jack和datetime.datetime(2012, 10, 8, 15, 12, 5)。类型将根据给定的值推断，在这种情况下为String和DateTime。

当需要特定的类型行为时，可以使用位置参数*binds来直接指定bindparam()构造。这些构造必须至少包括key参数，然后是一个可选的值和类型：

from sqlalchemy import bindparam
stmt = stmt.bindparams(
                bindparam('name', value='jack', type_=String),
                bindparam('timestamp', type_=DateTime)
            )

在上面，我们为timestamp绑定指定了DateTime类型，并为name绑定指定了String类型。对于name，我们还设置了默认值为"jack"。

可以在语句执行时提供额外的绑定参数，例如：

result = connection.execute(stmt,
            timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5))

TextClause.bindparams()方法可以重复调用，在这里它将重用现有的BindParameter对象来添加新的信息。例如，我们可以首先调用TextClause.bindparams()来传递类型信息，然后第二次传递值信息，它将被合并：

stmt = text("SELECT id, name FROM user WHERE name=:name "
            "AND timestamp=:timestamp")
stmt = stmt.bindparams(
    bindparam('name', type_=String),
    bindparam('timestamp', type_=DateTime)
)
stmt = stmt.bindparams(
    name='jack',
    timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5)
)

TextClause.bindparams()方法还支持unique绑定参数的概念。这些是在语句编译时按名称“唯一化”的参数，因此多个text()构造可以合并在一起而不会冲突。要使用此功能，请在每个bindparam()对象上指定BindParameter.unique标志：

stmt1 = text("select id from table where name=:name").bindparams(
    bindparam("name", value='name1', unique=True)
)
stmt2 = text("select id from table where name=:name").bindparams(
    bindparam("name", value='name2', unique=True)
)
union = union_all(
    stmt1.columns(column("id")),
    stmt2.columns(column("id"))
)

上述语句将呈现为：

select id from table where name=:name_1
UNION ALL select id from table where name=:name_2

新版本 1.3.11 中新增：支持BindParameter.unique标志与text()构造一起使用。

method columns(*cols: _ColumnExpressionArgument[Any], **types: TypeEngine[Any]) → TextualSelect

将这个TextClause对象转换为一个TextualSelect对象，它扮演了与 SELECT 语句相同的角色。

TextualSelect是SelectBase层次结构的一部分，可以通过使用TextualSelect.subquery()方法嵌入到另一个语句中，以生成一个Subquery对象，然后可以从中进行 SELECT 操作。

此函数本质上填补了纯文本 SELECT 语句与 SQL 表达式语言中“可选择”的概念之间的差距：

from sqlalchemy.sql import column, text
stmt = text("SELECT id, name FROM some_table")
stmt = stmt.columns(column('id'), column('name')).subquery('st')
stmt = select(mytable).\
        select_from(
            mytable.join(stmt, mytable.c.name == stmt.c.name)
        ).where(stmt.c.id > 5)

在上面的示例中，我们按位置传递了一系列 column() 元素给 TextClause.columns() 方法。这些 column() 元素现在成为 TextualSelect.selected_columns 列集合的一部分，之后在调用 TextualSelect.subquery() 后成为 Subquery.c 集合的一部分。

我们传递给 TextClause.columns() 的列表达式也可以具有类型；当我们这样做时，这些 TypeEngine 对象将成为列的有效返回类型，因此 SQLAlchemy 的结果集处理系统可以用于返回值。对于诸如日期或布尔类型以及在某些方言配置中进行 Unicode 处理等类型，这通常是必需的：

stmt = text("SELECT id, name, timestamp FROM some_table")
stmt = stmt.columns(
            column('id', Integer),
            column('name', Unicode),
            column('timestamp', DateTime)
        )
for id, name, timestamp in connection.execute(stmt):
    print(id, name, timestamp)

作为上述语法的一种快捷方式，如果只需要类型转换，则可以使用仅指向类型的关键字参数：

stmt = text("SELECT id, name, timestamp FROM some_table")
stmt = stmt.columns(
            id=Integer,
            name=Unicode,
            timestamp=DateTime
        )
for id, name, timestamp in connection.execute(stmt):
    print(id, name, timestamp)

TextClause.columns() 的位置形式还提供了位置列定位的独特功能，当使用 ORM 处理复杂的文本查询时，这一点尤其有用。如果我们将模型中的列指定给 TextClause.columns()，则结果集将按位置与这些列匹配，这意味着文本 SQL 中列的名称或来源并不重要：

stmt = text("SELECT users.id, addresses.id, users.id, "
     "users.name, addresses.email_address AS email "
     "FROM users JOIN addresses ON users.id=addresses.user_id "
     "WHERE users.id = 1").columns(
        User.id,
        Address.id,
        Address.user_id,
        User.name,
        Address.email_address
     )
query = session.query(User).from_statement(stmt).options(
    contains_eager(User.addresses))

TextClause.columns() 方法提供了直接调用 FromClause.subquery() 和 SelectBase.cte() 对象的途径，用于针对文本 SELECT 语句：

stmt = stmt.columns(id=Integer, name=String).cte('st')
stmt = select(sometable).where(sometable.c.id == stmt.c.id)

参数：

• *cols – 一系列 ColumnElement 对象，通常是来自 Table 或 ORM 级列映射属性的 Column 对象，代表此文本字符串将从中进行选择的列集合。
  
• **types – 一个将字符串名称映射到TypeEngine类型对象的映射，指示从文本字符串中选择的名称使用的数据类型。最好使用*cols参数，因为它还指示位置顺序。
  

method self_group(against=None)

对这个ClauseElement应用一个“分组”。

子类会重写此方法以返回一个“分组”构造，即括号。特别是当“二进制”表达式被放置到更大的表达式中时，它们会提供一个围绕自身的分组，以及当select()构造被放置到另一个select()的 FROM 子句中时。 （请注意，子查询通常应使用Select.alias()方法创建，因为许多平台要求嵌套的 SELECT 语句必须命名）。

当表达式组合在一起时，self_group()的应用是自动的 - 最终用户代码不应直接使用此方法。请注意，SQLAlchemy 的子句构造会考虑运算符优先级 - 因此在表达式中可能不需要括号，例如，x OR (y AND z) - AND 优先于 OR。

ClauseElement的基本self_group()方法只返回自身。

class sqlalchemy.sql.expression.TryCast

表示一个 TRY_CAST 表达式。

TryCast用法的详细信息在try_cast()处。

另请参阅

try_cast()

数据转换和类型强制转换

成员

inherit_cache

类签名

类sqlalchemy.sql.expression.TryCast（sqlalchemy.sql.expression.Cast)

attribute inherit_cache: bool | None = True

指示此HasCacheKey实例是否应使用其直接超类使用的缓存键生成方案。

此属性默认为None，表示构造尚未考虑是否适合参与缓存；这在功能上等同于将值设置为False，只是还会发出警告。

这个标志可以在特定类上设置为True，如果与对象对应的 SQL 不基于此类的局部属性而改变，而不是其超类。

另请参阅

为自定义构造启用缓存支持 - 设置第三方或用户定义的 SQL 构造的HasCacheKey.inherit_cache 属性的一般指南。

class sqlalchemy.sql.expression.Tuple

表示 SQL 元组。

成员

self_group()

类签名

类sqlalchemy.sql.expression.Tuple（sqlalchemy.sql.expression.ClauseList，sqlalchemy.sql.expression.ColumnElement)

method self_group(against=None)

将“分组”应用于此 ClauseElement。

此方法被子类重写以返回一个“分组”构造，即括号。特别是它被“二元”表达式使用，当它们被放置到较大的表达式中时，提供一个围绕自身的分组，以及被 select() 构造在另一个 select() 的 FROM 子句中时。 （注意，子查询通常应使用 Select.alias() 方法创建，因为许多平台要求嵌套的 SELECT 语句具有名称）。

当表达式组合在一起时，self_group() 的应用是自动的 - 最终用户代码不应直接使用此方法。请注意，SQLAlchemy 的子句构造会考虑运算符优先级 - 因此可能不需要括号，例如，在表达式中像x OR (y AND z) - AND 的优先级高于 OR，可能不需要括号。

ClauseElement 的基本 self_group() 方法只返回自身。

class sqlalchemy.sql.expression.WithinGroup

表示 WITHIN GROUP (ORDER BY) 子句。

这是针对所谓的“有序集合聚合”和“假设集合聚合”函数的特殊运算符，包括 percentile_cont()、rank()、dense_rank() 等。

仅受某些数据库后端支持，如 PostgreSQL、Oracle 和 MS SQL Server。

WithinGroup 构造从方法 FunctionElement.within_group_type() 中提取其类型。如果此返回 None，则使用函数的 .type。

成员

over()

类签名

类 sqlalchemy.sql.expression.WithinGroup（sqlalchemy.sql.expression.ColumnElement）

method over(partition_by=None, order_by=None, range_=None, rows=None)

对此 WithinGroup 构造生成一个 OVER 子句。

此函数具有与 FunctionElement.over() 相同的签名。

class sqlalchemy.sql.elements.WrapsColumnExpression

定义一个 ColumnElement 作为具有特殊标签行为的包装器的混合体，用于已经具有名称的表达式。

从版本 1.4 新增。

另请参见

使用 CAST 或类似方法改进简单列表达式的列标签

类签名

类 sqlalchemy.sql.expression.WrapsColumnExpression（sqlalchemy.sql.expression.ColumnElement）

class sqlalchemy.sql.expression.True_

代表 SQL 语句中的 true 关键字或等效物。

通过 true() 函数访问 True_ 作为常量。

类签名

类 sqlalchemy.sql.expression.True_（sqlalchemy.sql.expression.SingletonConstant、sqlalchemy.sql.roles.ConstExprRole、sqlalchemy.sql.expression.ColumnElement）

class sqlalchemy.sql.expression.TypeCoerce

表示 Python 端的类型强制转换包装器。

TypeCoerce 提供了 type_coerce() 函数；请参阅该函数以获取使用详情。

另请参见

type_coerce()

cast()

成员

self_group()

类签名

类sqlalchemy.sql.expression.TypeCoerce（sqlalchemy.sql.expression.WrapsColumnExpression）

method self_group(against=None)

对此ClauseElement应用“分组”。

此方法被子类重写以返回一个“分组”构造，即括号。特别是它被“二元”表达式使用，当它们放置到更大的表达式中时提供一个围绕自身的分组，以及当它们被放置到另一个select()构造的 FROM 子句中时，也被select()构造使用。（请注意，子查询通常应使用Select.alias()方法创建，因为许多平台要求嵌套的 SELECT 语句必须命名）。

当表达式组合在一起时，自动应用self_group() - 最终用户代码不应直接使用此方法。请注意，SQLAlchemy 的子句构造考虑了运算符优先级 - 因此在表达式中可能不需要括号，例如x OR (y AND z) - AND 优先于 OR。

基本的self_group()方法在ClauseElement中只返回自身。

class sqlalchemy.sql.expression.UnaryExpression

定义一个“一元”表达式。

一元表达式有一个单独的列表达式和一个运算符。运算符可以放在列表达式的左侧（称为“运算符”）或右侧（称为“修饰符”）。

UnaryExpression是几个一元运算符的基础，包括desc()、asc()、distinct()、nulls_first()和nulls_last()。

成员

self_group()

类签名

类 sqlalchemy.sql.expression.UnaryExpression（sqlalchemy.sql.expression.ColumnElement）

method self_group(against=None)

对此 ClauseElement 应用“分组”。

此方法被子类重写以返回一个“分组”构造，即括号。特别是它被“二元”表达式使用，当放置到更大的表达式中时提供一个围绕自身的分组，以及当放置到另一个 select() 构造的 FROM 子句中时，由 select() 构造使用。（请注意，子查询通常应使用 Select.alias() 方法创建，因为许多平台要求嵌套的 SELECT 语句必须命名）。

随着表达式的组合，self_group() 的应用是自动的 - 最终用户代码不应直接使用此方法。请注意，SQLAlchemy 的子句构造考虑了运算符优先级 - 因此在表达式中可能不需要括号，例如在表达式 x OR (y AND z) 中 - AND 优先于 OR。

ClauseElement 的基本 self_group() 方法只返回自身。

列元素类型化实用程序

从 sqlalchemy 命名空间导入的独立实用函数，以提高类型检查器的支持。

function sqlalchemy.NotNullable(val: _TypedColumnClauseArgument[_T | None] | Type[_T] | None) → _TypedColumnClauseArgument[_T]

将列或 ORM 类型标记为非空。

这可以在选择和其他上下文中使用，以表达列的值不能为 null，例如由于可为空列上的 where 条件：

stmt = select(NotNullable(A.value)).where(A.value.is_not(None))

在运行时，此方法返回未更改的输入。

新版本 2.0.20 中新增。

function sqlalchemy.Nullable(val: _TypedColumnClauseArgument[_T]) → _TypedColumnClauseArgument[_T | None]

将列或 ORM 类型标记为可空。

这可以在选择和其他上下文中使用，以表达列的值可以为 null，例如由于外连接：

stmt1 = select(A, Nullable(B)).outerjoin(A.bs)
stmt2 = select(A.data, Nullable(B.data)).outerjoin(A.bs)

在运行时，此方法返回未更改的输入。

新版本 2.0.20 中新增。

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