SqlAlchemy 2.0 中文文档（二十七）（4）

SqlAlchemy 2.0 中文文档（二十七）（3）

参数：

• other – 待比较的表达式。通常是一个普通字符串值，但也可以是任意 SQL 表达式。默认情况下，LIKE 通配符字符%和_不会被转义，除非设置了ColumnOperators.istartswith.autoescape标志为 True。
  
• 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="^")
• 1

• 将渲染为：

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

继承自 ColumnOperators.like() 方法的 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

继承自 ColumnOperators.match() 方法的 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

继承自 ColumnOperators.not_ilike() 方法的 ColumnOperators

实现NOT ILIKE操作符。

这等同于使用ColumnOperators.ilike()进行否定，即~x.ilike(y)。

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

另请参见

ColumnOperators.ilike()

method not_in(other: Any) → ColumnOperators

继承自 ColumnOperators.not_in() 方法的 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

继承自 ColumnOperators.not_like() 方法的 ColumnOperators

实现NOT LIKE运算符。

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

自版本 1.4 起更改：not_like()运算符从先前版本的notlike()重命名。 以确保向后兼容性，先前的名称仍然可用。

另请参阅

ColumnOperators.like()

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

继承自 ColumnOperators.notilike() 方法的 ColumnOperators

实现NOT ILIKE运算符。

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

自版本 1.4 起更改：not_ilike()运算符从先前版本的notilike()重命名。 以确保向后兼容性，先前的名称仍然可用。

另请参阅

ColumnOperators.ilike()

method notin_(other: Any) → ColumnOperators

继承自 ColumnOperators.notin_() 方法 的 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

继承自 ColumnOperators.notlike() 方法 的 ColumnOperators

实现NOT LIKE运算符。

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

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

另请参阅

ColumnOperators.like()

method nulls_first() → ColumnOperators

继承自 ColumnOperators.nulls_first() 方法 的 ColumnOperators

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

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

method nulls_last() → ColumnOperators

继承自 ColumnOperators.nullslast() 方法的 ColumnOperators 类

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

1.4 版本更改：nulls_last() 操作符从之前的版本 nullslast() 重命名。 以前的名称仍可用于向后兼容。

method nullsfirst() → ColumnOperators

继承自 ColumnOperators.nullsfirst() 方法的 ColumnOperators 类

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

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

method nullslast() → ColumnOperators

继承自 ColumnOperators.nullslast() 方法的 ColumnOperators 类

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

1.4 版本更改：nulls_last() 操作符从之前的版本 nullslast() 重命名。 以前的名称仍可用于向后兼容。

method of_type(class_: _EntityType[Any]) → PropComparator[_T_co]

重新定义此对象，以便使用多态子类、with_polymorphic() 构造或 aliased() 构造。

返回一个新的 PropComparator，可以从中评估进一步的标准。

例如：

query.join(Company.employees.of_type(Engineer)).\
   filter(Engineer.name=='foo')

参数：

class_ – 表示标准为针对此特定子类的类或映射器。

另请参阅

使用关联在别名目标之间连接 - 在 ORM 查询指南中

连接到特定子类型或使用 with_polymorphic()实体

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，则该运算符将被视为“比较”运算符，即评估为布尔真/假值的运算符，如==，>等。提供此标志是为了 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 方法的 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()。
  

attribute property

返回与此PropComparator关联的MapperProperty。

这里的返回值通常是ColumnProperty或Relationship的实例。

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

继承自 ColumnOperators 方法的 ColumnOperators.regexp_match()

实现了数据库特定的‘regexp match’操作符。

例如：

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

继承自 ColumnOperators.regexp_replace() 的 ColumnOperators 方法

实现了一个特定于数据库的‘regexp replace’运算符。

例如：

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

继承自 ColumnOperators 的 ColumnOperators.startswith() 方法。

实现 startswith 操作符。

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

column LIKE <other> || '%'

例如：

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

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

参数:

• other – 要比较的表达式。通常是一个普通字符串值，但也可以是任意的 SQL 表达式。LIKE 通配符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.startswith.autoescape 标志设置为 True。
  
• 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

继承自 ColumnOperators.timetuple 的属性 ColumnOperators

Hack，允许在左侧比较日期时间对象。

class sqlalchemy.orm.Relationship

描述一个对象属性，该属性包含与相关数据库表对应的单个项目或项目列表。

公共构造函数是 relationship() 函数。

另请参阅

关系配置

2.0 版更改：将 Relationship 添加为 RelationshipProperty 的声明兼容子类。

SqlAlchemy 2.0 中文文档（二十七）（5）https://developer.aliyun.com/article/1560513