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

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

参数：

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

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

• 将呈现为：

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

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

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

• 将呈现为：

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

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

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

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

另请参阅

ColumnOperators.startswith()

ColumnOperators.endswith()

ColumnOperators.like()

method desc() → ColumnOperators

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

生成一个针对父对象的desc()子句。

method distinct() → ColumnOperators

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

生成一个针对父对象的distinct()子句。

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

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

实现‘endswith’运算符。

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

column LIKE '%' || <other>

例如：

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

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

参数：

• other – 要比较的表达式。 这通常是一个简单的字符串值，但也可以是任意 SQL 表达式。 除非将ColumnOperators.endswith.autoescape标志设置为 True，否则不会默认转义 LIKE 通配符%和_。
  
• 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 has(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]

返回一个 SQL 表达式，如果此元素引用满足给定条件的成员，则表示为 true。

has()的通常实现是Comparator.has()。

参数：

• criterion – 针对成员类表或属性制定的可选 ClauseElement。
  
• **kwargs – 键/值对，对应于将通过等式与相应值进行比较的成员类属性名称。
  

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

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

继承自 ColumnOperators.iendswith() 方法的 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 表达式。LIKE 通配符字符%和_默认情况下不会被转义，除非设置了ColumnOperators.iendswith.autoescape标志为 True。
  
• 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

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

继承自 ColumnOperators.in_() 方法的 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()，如果它包含 bindparam.expanding 标志：

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() 构造，其中包括bindparam.expanding 标志。

method is_(other: Any) → ColumnOperators

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

实现IS运算符。

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

另请参见

ColumnOperators.is_not()

method is_distinct_from(other: Any) → ColumnOperators

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

实现IS DISTINCT FROM运算符。

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

method is_not(other: Any) → ColumnOperators

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

实现IS NOT运算符。

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

从版本 1.4 开始更改：is_not()运算符从先前版本的isnot()重命名。以前的名称仍可用于向后兼容。

另请参见

ColumnOperators.is_()

method is_not_distinct_from(other: Any) → ColumnOperators

从 ColumnOperators.is_not_distinct_from() 方法继承

实现 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

从 ColumnOperators.isnot() 方法继承

实现 IS NOT 运算符。

通常，当与 None 的值进行比较时，会自动生成 IS NOT，它解析为 NULL。 然而，在某些平台上，如果要与布尔值进行比较，则可能希望显式使用 IS NOT。

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

另请参阅

ColumnOperators.is_()

method isnot_distinct_from(other: Any) → ColumnOperators

从 ColumnOperators.isnot_distinct_from() 方法继承

实现 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

从 ColumnOperators.istartswith() 方法继承

实现 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参数将建立一个给定字符作为转义字符，当目标表达式不是字面字符串时可能会有用。

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