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

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

参数：

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

attribute expression

从 ColumnElement.expression 属性继承 ColumnElement

返回列表达式。

检查接口的一部分；返回自身。

attribute foreign_keys: Set[ForeignKey] = frozenset({})

从 ColumnElement.foreign_keys 属性继承 ColumnElement

所有与此 Column 关联的 ForeignKey 标记对象的集合。

每个对象都是 Table 范围内的 ForeignKeyConstraint 的成员。

另请参阅

Table.foreign_keys

method get_children(*, column_tables=False, **kw)

从 ColumnClause.get_children() 方法继承 ColumnClause

返回此 HasTraverseInternals 的直接子元素 HasTraverseInternals。

这用于访问遍历。

**kw 可以包含更改返回的集合的标志，例如以便返回子项的子集以减少较大的遍历量，或者从不同上下文（例如模式级集合而不是子句级别）返回子项。

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 –
  boolean；当为 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.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 版本新功能：添加了“扩展”绑定参数
  如果传递了一个空列表，则呈现一个特殊的“空列表”表达式，该表达式特定于正在使用的数据库。在 SQLite 上，将会是：

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

• 自 1.3 版本新功能：“扩展”绑定参数现在支持空列表
• 一个 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)

参数：

其他 – 一系列文字、select()构造，或包括bindparam()构造，其中bindparam.expanding标志设置为 True。

attribute index: bool | None

Column.index参数的值。

不指示此Column是否实际上已被索引；请使用Table.indexes。

另请参见

Table.indexes的值。

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

与该SchemaItem关联的信息字典，允许将用户定义的数据与此关联。

当首次访问时，字典会自动生成。也可以在某些对象的构造函数中指定，例如Table和Column。

attribute inherit_cache: bool | None = True

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

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

如果与此类本地相关而不是其超类的属性不会更改与对象对应的 SQL，则可以在特定类上将此标志设置为True。

另请参见

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

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() 方法的 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

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

实现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() 方法的 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

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

attribute key: str = None

继承自 ColumnElement.key 属性的 ColumnElement

在某些情况下指代 Python 命名空间中的该对象的‘key’。

这通常指的是在可选择的.c集合中作为列的“key”存在，例如，sometable.c["somekey"]将返回一个具有“somekey”作为.key的Column。

attribute kwargs

继承自 DialectKWArgs.kwargs 属性的 DialectKWArgs

DialectKWArgs.dialect_kwargs的同义词。

method label(name: str | None) → Label[_T]

继承自 ColumnElement.label() 方法的 ColumnElement

生成一个列标签，即 AS 。

这是label()函数的快捷方式。

如果‘name’为None，将生成一个匿名标签名称。

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

实现特定于数据库的‘匹配’操作符。

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

实现NOT IN操作符。

这等同于在ColumnOperators.in_()中使用否定，即~x.in_(y)。

当other是一个空序列时，编译器会生成一个“空不在”表达式。这默认为表达式“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 的 ColumnOperators.not_like() 方法继承

实现NOT LIKE操作符。

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

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

另请参阅

ColumnOperators.like()

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

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

实现NOT ILIKE操作符。

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

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

另请参阅

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_() 重命名为 not_in()。先前的名称仍可用于向后兼容。

从 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() 重命名为 not_like()。先前的名称仍可用于向后兼容。

另请参阅

ColumnOperators.like()

method nulls_first() → ColumnOperators

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

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

在 1.4 版本中更改：nulls_first() 操作符在先前版本中的名称已更改为 nullsfirst()。以前的名称仍可用于向后兼容。

method nulls_last() → ColumnOperators

继承自 ColumnOperators.nulls_last() 方法的 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 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) → ColumnElement[Any]

继承自 ColumnElement.operate() 方法的 ColumnElement

对参数进行操作。

这是操作的最低级别，默认情况下引发 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 params(*optionaldict, **kwargs)

继承自 Immutable.params() 方法的 Immutable

返回一个副本，其中包含替换了 bindparam() 元素的内容。

返回此 ClauseElement 的副本，其中包含从给定字典中获取的值替换了 bindparam() 元素：

>>> clause = column('x') + bindparam('foo')
>>> print(clause.compile().params)
{'foo':None}
>>> print(clause.params({'foo':7}).compile().params)
{'foo':7}

attribute proxy_set: util.generic_fn_descriptor[FrozenSet[Any]]

继承自 ColumnElement.proxy_set 属性的 ColumnElement

我们正在代理的所有列的集合

从 2.0 开始，这些是明确取消注释的列。以前是有效取消注释的列，但没有强制执行。如果可能的话，注释的列基本上不应该进入集合，因为它们的哈希行为非常低效。

method references(column: Column[Any]) → bool

如果此列通过外键引用给定列，则返回 True。

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

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

继承自 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) → ColumnElement[Any]

继承自 ColumnElement.reverse_operate() 方法的 ColumnElement

对参数进行反向操作。

用法与 operate() 相同。

method self_group(against: OperatorType | None = None) → ColumnElement[Any]

继承自 ColumnElement.self_group() 方法的 ColumnElement

将“分组”应用于此 ClauseElement。

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

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

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

method shares_lineage(othercolumn: ColumnElement[Any]) → bool

继承自 ColumnElement.shares_lineage() 方法的 ColumnElement

如果给定的 ColumnElement 具有与此 ColumnElement 的共同祖先，则返回 True。

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

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

继承自 ColumnOperators.timetuple 属性的 ColumnOperators

Hack，允许在 LHS 上比较 datetime 对象。

attribute unique: bool | None

Column.unique参数的值。

不表示此Column实际上是否受唯一约束的约束; 使用Table.indexes和Table.constraints。

另见

Table.indexes

Table.constraints。

method unique_params(*optionaldict, **kwargs)

继承自 Immutable.unique_params() 方法的 Immutable

返回一个副本，其中bindparam()元素被替换。

与ClauseElement.params()具有相同的功能，除了将 unique=True 添加到受影响的绑定参数，以便可以使用多个语句。

class sqlalchemy.schema.MetaData

一个包含Table对象及其关联模式结构的集合。

包含一个Table对象的集合，以及一个可选的绑定到Engine或Connection的绑定。如果绑定，则集合中的Table对象及其列可能会参与隐式 SQL 执行。

Table 对象本身存储在 MetaData.tables 字典中。

MetaData 是一个线程安全的对象，用于读操作。在单个 MetaData 对象内构造新表，无论是显式地还是通过反射，可能不完全是线程安全的。

请参见

使用 MetaData 描述数据库 - 数据库元数据介绍

成员

init(), clear(), create_all(), drop_all(), reflect(), remove(), sorted_tables, tables

类签名

类 sqlalchemy.schema.MetaData (sqlalchemy.schema.HasSchemaAttr)

method __init__(schema: str | None = None, quote_schema: bool | None = None, naming_convention: _NamingSchemaParameter | None = None, info: _InfoType | None = None) → None

创建一个新的 MetaData 对象。

参数：

• schema –
  用于 Table、Sequence 和可能与此 MetaData 关联的其他对象的默认模式。默认为 None。
  请参见
  使用 MetaData 指定默认模式名称 - 关于如何使用 MetaData.schema 参数的详细信息。
  Table.schema
Sequence.schema
  
• quote_schema – 为使用本地 schema 名称的那些 Table、Sequence 和其他对象设置 quote_schema 标志。
  
• info – 可选数据字典，将填充到此对象的 SchemaItem.info 属性中。
  
• naming_convention –一个字典，指向将为那些未明确给出名称的 Constraint 和 Index 对象建立默认命名约定的值。此字典的键可以是：

• 一个约束或索引类，例如UniqueConstraint类，ForeignKeyConstraint类，Index类
  
• 已知约束类之一的字符串助记符；分别为外键（“fk”），主键（“pk”），索引（“ix”），检查（“ck”），唯一约束（“uq”）。
  
• 用户定义的可用于定义新命名标记的“令牌”的字符串名称。
  

• 与每个“约束类”或“约束助记符”键关联的值是字符串命名模板，例如"uq_%(table_name)s_%(column_0_name)s"，描述了名称应如何组成。与用户定义的“令牌”键关联的值应该是形式为fn(constraint, table)的可调用对象，接受约束/索引对象和Table作为参数，返回一个字符串结果。
  内置名称如下，其中一些可能仅适用于某些类型的约束：

• %(table_name)s - 与约束相关联的Table对象的名称。
• 
  
• %(referred_table_name)s - 与ForeignKeyConstraint的引用目标相关联的Table对象的名称。
• 
  
• %(column_0_name)s - 约束内索引位置“0”的Column的名称。
• 
  
• %(column_0N_name)s - 约束内所有Column对象的名称按顺序连接而成，不带分隔符。
• 
  
• %(column_0_N_name)s - 约束内所有Column对象的名称按顺序连接，用下划线作为分隔符。
• 
  
• %(column_0_label)s，%(column_0N_label)s，%(column_0_N_label)s - 第零个Column或所有Columns的标签，用或不用下划线分隔
• 
  
• %(column_0_key)s，%(column_0N_key)s，%(column_0_N_key)s - 第零个Column或所有Columns的键，用或不用下划线分隔。
• 
  
• %(referred_column_0_name)s，%(referred_column_0N_name)s，%(referred_column_0_N_name)s，%(referred_column_0_key)s，%(referred_column_0N_key)s，…渲染由ForeignKeyConstraint引用的列的名称/键/标签的列标记。
• 
  
• %(constraint_name)s - 一个特殊的键，引用了约束的现有名称。当存在这个键时，Constraint 对象的现有名称将被替换为使用此标记的模板字符串组成的名称。当存在此标记时，必须提前为 Constraint 指定一个显式名称。
• 
  
• 用户自定义：可以通过将其与 fn(constraint, table) 可调用对象一起传递到 naming_convention 字典中来实现任何其他标记。

• 1.3.0 版新增内容：- 添加了新的 %(column_0N_name)s、%(column_0_N_name)s 和相关标记，这些标记生成给定约束引用的所有列的名称、键或标签的串联。
  另请参阅
  配置约束命名约定 - 详细的用法示例。

method clear() → None

从此 MetaData 中清除所有 Table 对象。

method create_all(bind: _CreateDropBind, tables: _typing_Sequence[Table] | None = None, checkfirst: bool = True) → None

创建存储在此元数据中的所有表。

默认情况下是有条件的，不会尝试重新创建已经存在于目标数据库中的表。

参数：

• bind – 用于访问数据库的 Connection 或 Engine。
  
• tables – Table 对象的可选列表，这是 MetaData 中的总表的子集（其他表被忽略）。
  
• checkfirst – 默认为 True，不会为已经存在于目标数据库中的表发出 CREATE 操作。
  

method drop_all(bind: _CreateDropBind, tables: _typing_Sequence[Table] | None = None, checkfirst: bool = True) → None

删除存储在此元数据中的所有表。

默认情况下是有条件的，不会尝试删除目标数据库中不存在的表。

参数：

• bind – 用于访问数据库的 Connection 或 Engine。
  
• tables – Table 对象的可选列表，这是 MetaData 中的总表的子集（其他表被忽略）。
  
• checkfirst – 默认为 True，仅对确认存在于目标数据库中的表发出 DROP 操作。
  

method reflect(bind: Engine | Connection, schema: str | None = None, views: bool = False, only: _typing_Sequence[str] | Callable[[str, MetaData], bool] | None = None, extend_existing: bool = False, autoload_replace: bool = True, resolve_fks: bool = True, **dialect_kwargs: Any) → None

从数据库加载所有可用的表定义。

自动在此 MetaData 中为数据库中尚未存在的任何表创建 Table 条目。可以多次调用以获取最近添加到数据库中的表，但如果此 MetaData 中的表在数据库中不再存在，则不会采取任何特殊操作。

参数：

• bind – 用于访问数据库的 Connection 或 Engine。
  
• schema – 可选，从替代模式查询和反映表。如果为 None，则使用与此MetaData关联的模式（如果有）。
  
• views – 如果为 True，则还反映视图（物化和普通）。
  
• only –
  可选。仅加载可用命名表的子集。可以指定为名称序列或可调用对象。
  如果提供了名称序列，则只会反映这些表。如果请求了一个表但该表不可用，则会引发错误。已经存在于此MetaData中的命名表将被忽略。
  如果提供了可调用对象，则将用作布尔谓词来过滤潜在的表名称列表。可调用对象以表名称和此MetaData实例作为位置参数调用，并应为任何要反映的表返回一个真值。
  
• extend_existing – 传递给每个Table作为Table.extend_existing。
  
• autoload_replace – 传递给每个Table作为Table.autoload_replace。
  
• resolve_fks –
  如果为 True，则反映与每个Table中的ForeignKey对象链接的Table。对于MetaData.reflect()，这将导致反映可能不在要反映的表列表中的相关表，例如，如果引用的表位于不同的模式中或通过MetaData.reflect.only参数被省略。当为 False 时，不会跟随ForeignKey对象到它们链接的Table，但是如果相关表也是反映表列表的一部分，那么在MetaData.reflect()操作完成后，ForeignKey对象仍将解析为其相关的Table。默认为 True。
  1.3.0 版本中的新功能。
  另请参阅
  Table.resolve_fks
  
• **dialect_kwargs – 未在上述提及的其他关键字参数是方言特定的，并以<方言名称>_<参数名称>的形式传递。有关详细记录参数的文档，请参阅 Dialects 中有关单个方言的文档。
  

另请参阅

反映数据库对象

DDLEvents.column_reflect() - 用于自定义反映列的事件。通常用于使用TypeEngine.as_generic()泛化类型。

使用与数据库无关的类型反映 - 描述如何使用通用类型反映表格。

method remove(table: Table) → None

从此 MetaData 中删除给定的 Table 对象。

attribute sorted_tables

返回一个按外键依赖顺序排序的Table对象列表。

排序将首先将具有依赖关系的Table对象放置在依赖关系本身之前，表示它们可以被创建的顺序。要获取表格将被删除的顺序，请使用 Python 内置的reversed()。

警告

单独的MetaData.sorted_tables属性本身不能自动解决表格之间的依赖循环，这些循环通常是由相互依赖的外键约束引起的。当检测到这些循环时，这些表的外键将被忽略在排序中考虑。当此条件发生时，会发出警告，这将在未来的版本中引发异常。仍将以依赖顺序返回不属于循环的表。

要解决这些循环，可以将ForeignKeyConstraint.use_alter参数应用于创建循环的那些约束。或者，当检测到循环时，sort_tables_and_constraints()函数将自动将外键约束返回到单独的集合中，以便可以将其应用于模式。

从 1.3.17 版本开始更改：当由于循环依赖关系而无法对MetaData.sorted_tables进行适当排序时，会发出警告。这将在未来的版本中引发异常。此外，排序将继续以先前不属于循环的其他表的依赖顺序返回其他表，这不是以前的情况。

另请参阅

sort_tables()

sort_tables_and_constraints()

MetaData.tables

Inspector.get_table_names()

Inspector.get_sorted_table_and_fkc_names()

attribute tables: util.FacadeDict[str, Table]

一个以其名称或“表键”为键的Table对象字典。

具体键是由Table.key属性确定的；对于没有Table.schema属性的表，这与Table.name相同。对于具有模式的表，通常是schemaname.tablename的形式。

另请参阅

MetaData.sorted_tables

class sqlalchemy.schema.SchemaConst

一个枚举。

成员

BLANK_SCHEMA，NULL_UNSPECIFIED，RETAIN_SCHEMA

类签名

类sqlalchemy.schema.SchemaConst (enum.Enum)

attribute BLANK_SCHEMA = 2

表示在某些情况下，即使父 MetaData 指定了模式，Table 或 Sequence 应该具有“None”作为其模式。

另请参阅

MetaData.schema

Table.schema

Sequence.schema。

attribute NULL_UNSPECIFIED = 3

表示“nullable”关键字未传递给列的符号。

这用于区分将nullable=None传递给Column的用例，这在某些后端（如 SQL Server）中具有特殊含义。

attribute RETAIN_SCHEMA = 1

表示在某些情况下，对于正在复制的 Table、Sequence 或者 ForeignKey 对象，应该保留其已经具有的模式名称。

class sqlalchemy.schema.SchemaItem

数据库模式定义项的基类。

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