操作符参考¶

本节详细介绍可用于构造 SQL 表达式的操作符的用法。

这些方法根据 Operators 和 ColumnOperators 基类进行介绍。这些方法随后在这些类的后代中可用，包括

Column 对象
ColumnElement 对象，更普遍地说是 Core SQL 表达式语言列级表达式的根
InstrumentedAttribute 对象，它们是 ORM 级别的映射属性。

操作符首先在教程部分中介绍，包括

比较操作符¶

适用于多种数据类型的基本比较，包括数值、字符串、日期和许多其他类型

ColumnOperators.__eq__() (Python “==” 操作符)
```
>>> print(column("x") == 5)
x = :x_1
```
ColumnOperators.__ne__() (Python “!=” 操作符)
```
>>> print(column("x") != 5)
x != :x_1
```
ColumnOperators.__gt__() (Python “>” 操作符)
```
>>> print(column("x") > 5)
x > :x_1
```
ColumnOperators.__lt__() (Python “<” 操作符)
```
>>> print(column("x") < 5)
x < :x_1
```
ColumnOperators.__ge__() (Python “>=” 操作符)
```
>>> print(column("x") >= 5)
x >= :x_1
```
ColumnOperators.__le__() (Python “<=” 操作符)
```
>>> print(column("x") <= 5)
x <= :x_1
```

ColumnOperators.between():

>>> print(column("x").between(5,10))x BETWEEN :x_1 AND :x_2

IN 比较¶

SQL IN 操作符是 SQLAlchemy 中自成一体的主题。由于 IN 操作符通常用于针对固定值列表，SQLAlchemy 的绑定参数强制转换特性利用了一种特殊形式的 SQL 编译，该编译渲染一个临时的 SQL 字符串以进行编译，该字符串在第二步中形成最终的绑定参数列表。换句话说，“开箱即用”。

针对值列表的 IN 比较¶

IN 最常见的用法是通过将值列表传递给 ColumnOperators.in_() 方法

>>> print(column("x").in_([1,2,3]))x IN (__[POSTCOMPILE_x_1])

特殊绑定形式 __[POSTCOMPILE 在执行时被渲染为单独的参数，如下所示

>>> stmt=select(User.id).where(User.id.in_([1,2,3]))>>> result=conn.execute(stmt)SELECT user_account.id
FROM user_account
WHERE user_account.id IN (?, ?, ?)
[...] (1, 2, 3)

空 IN 表达式¶

SQLAlchemy 通过渲染一个后端特定的子查询来为空 IN 表达式生成数学上有效的结果，该子查询不返回任何行。再次换句话说，“开箱即用”

>>> stmt=select(User.id).where(User.id.in_([]))>>> result=conn.execute(stmt)SELECT user_account.id
FROM user_account
WHERE user_account.id IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
[...] ()

上面的 “空集” 子查询正确地概括，并且也以 IN 操作符的形式渲染，该操作符保持不变。

NOT IN¶

“NOT IN” 通过 ColumnOperators.not_in() 操作符可用

>>> print(column("x").not_in([1,2,3]))(x NOT IN (__[POSTCOMPILE_x_1]))

通常更容易通过 ~ 操作符进行否定来使用

>>> print(~column("x").in_([1,2,3]))(x NOT IN (__[POSTCOMPILE_x_1]))

元组 IN 表达式¶

元组与元组的比较在 IN 中很常见，除其他用例外，还适用于将行匹配到一组潜在的复合主键值的情况。 tuple_() 构造为元组比较提供了基本构建块。然后 Tuple.in_() 操作符接收元组列表

>>> fromsqlalchemyimporttuple_>>> tup=tuple_(column("x",Integer),column("y",Integer))>>> expr=tup.in_([(1,2),(3,4)])>>> print(expr)(x, y) IN (__[POSTCOMPILE_param_1])

为了说明渲染的参数

>>> tup=tuple_(User.id,Address.id)>>> stmt=select(User.name).join(Address).where(tup.in_([(1,1),(2,2)]))>>> conn.execute(stmt).all()SELECT user_account.name
FROM user_account JOIN address ON user_account.id = address.user_id
WHERE (user_account.id, address.id) IN (VALUES (?, ?), (?, ?))
[...] (1, 1, 2, 2)
[('spongebob',), ('sandy',)]

子查询 IN¶

最后，ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符与子查询一起使用。该形式提供了直接传入 Select 构造，而无需任何显式转换为命名子查询

>>> print(column("x").in_(select(user_table.c.id)))x IN (SELECT user_account.id
FROM user_account)

元组按预期工作

>>> print(...     tuple_(column("x"), column("y")).in_(...         select(user_table.c.id, address_table.c.id).join(address_table)...     )... )(x, y) IN (SELECT user_account.id, address.id
FROM user_account JOIN address ON user_account.id = address.user_id)

标识比较¶

这些操作符涉及测试特殊的 SQL 值，例如 NULL，布尔常量例如 true 或 false，某些数据库支持这些常量

ColumnOperators.is_():

此操作符将精确地提供 “x IS y” 的 SQL，最常见的是 “<expr> IS NULL”。 NULL 常量最容易使用常规 Python None 获取
```
>>> print(column("x").is_(None))
x IS NULL
```
如果需要，SQL NULL 也可以使用 null() 构造显式地使用
```
>>> from sqlalchemy import null
>>> print(column("x").is_(null()))
x IS NULL
```
当与 None 或 null() 值结合使用时，使用 ColumnOperators.__eq__() 重载操作符（即 ==）时，会自动调用 ColumnOperators.is_() 操作符。这样，通常不需要显式地使用 ColumnOperators.is_()，尤其是在与动态值一起使用时
```
>>> a = None
>>> print(column("x") == a)
x IS NULL
```
请注意，Python is 操作符未被重载。即使 Python 提供了重载诸如 == 和 != 等操作符的钩子，但它没有提供任何重新定义 is 的方法。

ColumnOperators.is_not():

与 ColumnOperators.is_() 类似，产生 “IS NOT”

>>> print(column("x").is_not(None))x IS NOT NULL

同样等效于 != None

>>> print(column("x")!=None)x IS NOT NULL

ColumnOperators.is_distinct_from():

产生 SQL IS DISTINCT FROM

>>> print(column("x").is_distinct_from("some value"))x IS DISTINCT FROM :x_1

ColumnOperators.isnot_distinct_from():

产生 SQL IS NOT DISTINCT FROM

>>> print(column("x").isnot_distinct_from("some value"))x IS NOT DISTINCT FROM :x_1

字符串比较¶

ColumnOperators.like():

>>> print(column("x").like("word"))x LIKE :x_1

ColumnOperators.ilike():

不区分大小写的 LIKE 在通用后端上使用 SQL lower() 函数。在 PostgreSQL 后端上，它将使用 ILIKE
```
>>> print(column("x").ilike("word"))
lower(x) LIKE lower(:x_1)
```

ColumnOperators.notlike():

>>> print(column("x").notlike("word"))x NOT LIKE :x_1

ColumnOperators.notilike():

>>> print(column("x").notilike("word"))lower(x) NOT LIKE lower(:x_1)

字符串包含¶

字符串包含操作符基本上是作为 LIKE 和字符串连接操作符的组合构建的，在大多数后端上是 ||，有时是像 concat() 这样的函数

ColumnOperators.startswith():

>>> print(column("x").startswith("word"))x LIKE :x_1 || '%'

ColumnOperators.endswith():

>>> print(column("x").endswith("word"))x LIKE '%' || :x_1

ColumnOperators.contains():

>>> print(column("x").contains("word"))x LIKE '%' || :x_1 || '%'

字符串匹配¶

匹配操作符始终是后端特定的，并且在不同的数据库上可能提供不同的行为和结果

ColumnOperators.match():

这是一个方言特定的操作符，如果可用，它会利用底层数据库的 MATCH 功能
```
>>> print(column("x").match("word"))
x MATCH :x_1
```

ColumnOperators.regexp_match():

此操作符是方言特定的。我们可以例如在 PostgreSQL 方言中说明它

>>> fromsqlalchemy.dialectsimportpostgresql>>> print(column("x").regexp_match("word").compile(dialect=postgresql.dialect()))x ~ %(x_1)s

或 MySQL

>>> fromsqlalchemy.dialectsimportmysql>>> print(column("x").regexp_match("word").compile(dialect=mysql.dialect()))x REGEXP %s

字符串变更¶

ColumnOperators.concat():

字符串连接
```
>>> print(column("x").concat("some string"))
x || :x_1
```
当处理从 String 派生的列表达式时，此操作符通过 ColumnOperators.__add__()，即 Python + 操作符可用
```
>>> print(column("x", String) + "some string")
x || :x_1
```
该操作符将产生适当的数据库特定构造，例如在 MySQL 上，历史上一直是 concat() SQL 函数
```
>>> print((column("x", String) + "some string").compile(dialect=mysql.dialect()))
concat(x, %s)
```

ColumnOperators.regexp_replace():

作为 ColumnOperators.regexp() 的补充，这为支持它的后端产生 REGEXP REPLACE 等效项

>>> print(column("x").regexp_replace("foo","bar").compile(dialect=postgresql.dialect()))REGEXP_REPLACE(x, %(x_1)s, %(x_2)s)

ColumnOperators.collate():

产生 COLLATE SQL 操作符，该操作符在表达式时提供特定的排序规则

>>> print(...     (column("x").collate("latin1_german2_ci") == "Müller").compile(...         dialect=mysql.dialect()...     )... )(x COLLATE latin1_german2_ci) = %s

要对字面值使用 COLLATE，请使用 literal() 构造

>>> fromsqlalchemyimportliteral>>> print(...     (literal("Müller").collate("latin1_german2_ci") == column("x")).compile(...         dialect=mysql.dialect()...     )... )(%s COLLATE latin1_german2_ci) = x

算术操作符¶

ColumnOperators.__add__(), ColumnOperators.__radd__() (Python “+” 操作符)
```
>>> print(column("x") + 5)
x + :x_1
>>> print(5 + column("x"))
:x_1 + x
```
请注意，当表达式的数据类型为 String 或类似类型时，ColumnOperators.__add__() 操作符会产生字符串连接。

ColumnOperators.__sub__(), ColumnOperators.__rsub__() (Python “-” 操作符)

>>> print(column("x")-5)x - :x_1
>>> print(5-column("x")):x_1 - x

ColumnOperators.__mul__(), ColumnOperators.__rmul__() (Python “*” 操作符)

>>> print(column("x")*5)x * :x_1
>>> print(5*column("x")):x_1 * x

ColumnOperators.__truediv__(), ColumnOperators.__rtruediv__() (Python “/” 操作符)。这是 Python truediv 操作符，它将确保发生整数真除法
```
>>> print(column("x") / 5)
x / CAST(:x_1 AS NUMERIC)
>>> print(5 / column("x"))
:x_1 / CAST(x AS NUMERIC)
```
在版本 2.0 中变更: Python / 操作符现在确保发生整数真除法
ColumnOperators.__floordiv__(), ColumnOperators.__rfloordiv__() (Python “//” 操作符)。这是 Python floordiv 操作符，它将确保发生向下取整除法。对于默认后端以及像 PostgreSQL 这样的后端，SQL / 操作符对于整数值通常以这种方式运行
```
>>> print(column("x") // 5)
x / :x_1
>>> print(5 // column("x", Integer))
:x_1 / x
```
对于默认不使用向下取整除法的后端，或者当与数值一起使用时，使用 FLOOR() 函数来确保向下取整除法
```
>>> print(column("x") // 5.5)
FLOOR(x / :x_1)
>>> print(5 // column("x", Numeric))
FLOOR(:x_1 / x)
```
2.0 版本新增: 支持 FLOOR 除法

ColumnOperators.__mod__(), ColumnOperators.__rmod__() (Python “%” 操作符)

>>> print(column("x")%5)x % :x_1
>>> print(5%column("x")):x_1 % x

位运算符¶

位运算符函数提供跨不同后端对位运算符的统一访问，预计这些运算符将在兼容的值上运行，例如整数和位字符串（例如 PostgreSQL BIT 和类似类型）。请注意，这些不是通用的布尔运算符。

2.0.2 版本新增: 为位运算添加了专用运算符。

ColumnOperators.bitwise_not(), bitwise_not()。可用作列级方法，针对父对象产生按位 NOT 子句
```
>>> print(column("x").bitwise_not())
~x
```
此操作符也可用作列表达式级别的方法，将按位 NOT 应用于单个列表达式
```
>>> from sqlalchemy import bitwise_not
>>> print(bitwise_not(column("x")))
~x
```

ColumnOperators.bitwise_and() 产生按位 AND

>>> print(column("x").bitwise_and(5))
x & :x_1

ColumnOperators.bitwise_or() 产生按位 OR

>>> print(column("x").bitwise_or(5))
x | :x_1

ColumnOperators.bitwise_xor() 产生按位 XOR

>>> print(column("x").bitwise_xor(5))
x ^ :x_1

对于 PostgreSQL 方言，“#” 用于表示按位 XOR；当使用这些后端之一时，这会自动发出

>>> from sqlalchemy.dialects import postgresql
>>> print(column("x").bitwise_xor(5).compile(dialect=postgresql.dialect()))
x # %(x_1)s

ColumnOperators.bitwise_rshift(), ColumnOperators.bitwise_lshift() 产生按位移位运算符

>>> print(column("x").bitwise_rshift(5))
x >> :x_1
>>> print(column("x").bitwise_lshift(5))
x << :x_1

使用合取和否定¶

如果我们重复使用 Select.where() 方法，最常见的合取 “AND” 会自动应用，以及诸如 Update.where() 和 Delete.where() 等类似方法

>>> print(...     select(address_table.c.email_address)...     .where(user_table.c.name == "squidward")...     .where(address_table.c.user_id == user_table.c.id)... )SELECT address.email_address
FROM address, user_account
WHERE user_account.name = :name_1 AND address.user_id = user_account.id

Select.where(), Update.where() 和 Delete.where() 也接受具有相同效果的多个表达式

>>> print(...     select(address_table.c.email_address).where(...         user_table.c.name == "squidward",...         address_table.c.user_id == user_table.c.id,...     )... )SELECT address.email_address
FROM address, user_account
WHERE user_account.name = :name_1 AND address.user_id = user_account.id

“AND” 合取及其伙伴 “OR” 都可以使用 and_() 和 or_() 函数直接使用

>>> fromsqlalchemyimportand_,or_>>> print(...     select(address_table.c.email_address).where(...         and_(...             or_(user_table.c.name == "squidward", user_table.c.name == "sandy"),...             address_table.c.user_id == user_table.c.id,...         )...     )... )SELECT address.email_address
FROM address, user_account
WHERE (user_account.name = :name_1 OR user_account.name = :name_2)
AND address.user_id = user_account.id

否定可以使用 not_() 函数。这通常会反转布尔表达式中的操作符

>>> fromsqlalchemyimportnot_>>> print(not_(column("x")==5))x != :x_1

它也可能在适当的时候应用诸如 NOT 之类的关键字

>>> fromsqlalchemyimportBoolean>>> print(not_(column("x",Boolean)))NOT x

合取操作符¶

上述合取函数 and_(), or_(), not_() 也可用作重载的 Python 操作符

注意

Python &, | 和 ~ 操作符在语言中具有高优先级；因此，对于本身包含表达式的操作数，通常必须应用括号，如下例所示。

Operators.__and__() (Python “&” 操作符)

Python 二进制 & 操作符被重载为与 and_() 的行为相同（请注意两个操作数周围的括号）
```
>>> print((column("x") == 5) & (column("y") == 10))
x = :x_1 AND y = :y_1
```
Operators.__or__() (Python “|” 操作符)

Python 二进制 | 操作符被重载为与 or_() 的行为相同（请注意两个操作数周围的括号）
```
>>> print((column("x") == 5) | (column("y") == 10))
x = :x_1 OR y = :y_1
```
Operators.__invert__() (Python “~” 操作符)

Python 二进制 ~ 操作符被重载为与 not_() 的行为相同，可以反转现有操作符，或者将 NOT 关键字应用于整个表达式
```
>>> print(~(column("x") == 5))
x != :x_1
>>> from sqlalchemy import Boolean
>>> print(~column("x", Boolean))
NOT x
```

SQLAlchemy 2.0 文档