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

原文：docs.sqlalchemy.org/en/20/contents.html

描述数据库与元数据

原文：docs.sqlalchemy.org/en/20/core/metadata.html

本节讨论了基本的Table、Column和MetaData对象。

请参阅

使用数据库元数据 - SQLAlchemy 的数据库元数据概念入门教程，位于 SQLAlchemy 统一教程中

一个元数据实体的集合存储在一个名为MetaData的对象中：

from sqlalchemy import MetaData
metadata_obj = MetaData()

MetaData是一个容器对象，它将数据库（或多个数据库）的许多不同特征组合在一起进行描述。

要表示一个表，请使用Table类。它的两个主要参数是表名称，然后是它将关联的MetaData对象。其余的位置参数大多是描述每列的Column对象：

from sqlalchemy import Table, Column, Integer, String
user = Table(
    "user",
    metadata_obj,
    Column("user_id", Integer, primary_key=True),
    Column("user_name", String(16), nullable=False),
    Column("email_address", String(60)),
    Column("nickname", String(50), nullable=False),
)

上面描述了一个名为user的表，其中包含四列。表的主键由user_id列组成。可以将多个列分配primary_key=True标志，表示多列主键，称为复合主键。

还要注意，每个列使用与通用化类型对应的对象来描述其数据类型，例如Integer和String。SQLAlchemy 具有几十种不同级别的类型以及创建自定义类型的能力。有关类型系统的文档可以在 SQL 数据类型对象中找到。

访问表和列

MetaData对象包含了我们与其关联的所有模式构造。它支持几种访问这些表对象的方法，例如sorted_tables访问器，它以外键依赖顺序返回每个Table对象的列表（也就是说，每个表都在其引用的所有表之前）：

>>> for t in metadata_obj.sorted_tables:
...     print(t.name)
user
user_preference
invoice
invoice_item

在大多数情况下，单个Table对象已经被明确声明，并且这些对象通常直接作为应用程序中的模块级变量访问。 一旦定义了一个Table，它就有了一整套访问器，允许检查其属性。 给定以下Table定义：

employees = Table(
    "employees",
    metadata_obj,
    Column("employee_id", Integer, primary_key=True),
    Column("employee_name", String(60), nullable=False),
    Column("employee_dept", Integer, ForeignKey("departments.department_id")),
)

请注意在这个表中使用的ForeignKey对象 - 这个结构定义了对远程表的引用，并在定义外键中进行了全面描述。 访问关于这个表的信息的方法包括：

# access the column "employee_id":
employees.columns.employee_id
# or just
employees.c.employee_id
# via string
employees.c["employee_id"]
# a tuple of columns may be returned using multiple strings
# (new in 2.0)
emp_id, name, type = employees.c["employee_id", "name", "type"]
# iterate through all columns
for c in employees.c:
    print(c)
# get the table's primary key columns
for primary_key in employees.primary_key:
    print(primary_key)
# get the table's foreign key objects:
for fkey in employees.foreign_keys:
    print(fkey)
# access the table's MetaData:
employees.metadata
# access a column's name, type, nullable, primary key, foreign key
employees.c.employee_id.name
employees.c.employee_id.type
employees.c.employee_id.nullable
employees.c.employee_id.primary_key
employees.c.employee_dept.foreign_keys
# get the "key" of a column, which defaults to its name, but can
# be any user-defined string:
employees.c.employee_name.key
# access a column's table:
employees.c.employee_id.table is employees
# get the table related by a foreign key
list(employees.c.employee_dept.foreign_keys)[0].column.table

提示

FromClause.c集合，与FromClause.columns集合同义，是ColumnCollection的一个实例，它提供了类似于字典的接口来访问列集合。 名称通常像属性名称那样访问，例如 employees.c.employee_name。 但是，对于具有空格的特殊名称或与字典方法名称匹配的名称，例如ColumnCollection.keys()或ColumnCollection.values()，必须使用索引访问，例如 employees.c['values'] 或 employees.c["some column"]。 有关更多信息，请参阅ColumnCollection。

创建和删除数据库表

一旦您定义了一些Table对象，假设您正在使用全新的数据库，您可能想要做的一件事是为这些表及其相关结构发出  CREATE 语句（顺便说一句，如果您已经有了一些首选的方法，比如与数据库一起提供的工具或现有的脚本系统 - 如果是这种情况，请随意跳过此部分 -  SQLAlchemy 不要求使用它来创建您的表）。

发出 CREATE 的常规方式是在MetaData对象上使用create_all()。此方法将发出查询，首先检查每个单独表的存在性，如果未找到，则发出 CREATE 语句：

engine = create_engine("sqlite:///:memory:")
metadata_obj = MetaData()
user = Table(
    "user",
    metadata_obj,
    Column("user_id", Integer, primary_key=True),
    Column("user_name", String(16), nullable=False),
    Column("email_address", String(60), key="email"),
    Column("nickname", String(50), nullable=False),
)
user_prefs = Table(
    "user_prefs",
    metadata_obj,
    Column("pref_id", Integer, primary_key=True),
    Column("user_id", Integer, ForeignKey("user.user_id"), nullable=False),
    Column("pref_name", String(40), nullable=False),
    Column("pref_value", String(100)),
)
metadata_obj.create_all(engine)
PRAGMA  table_info(user){}
CREATE  TABLE  user(
  user_id  INTEGER  NOT  NULL  PRIMARY  KEY,
  user_name  VARCHAR(16)  NOT  NULL,
  email_address  VARCHAR(60),
  nickname  VARCHAR(50)  NOT  NULL
)
PRAGMA  table_info(user_prefs){}
CREATE  TABLE  user_prefs(
  pref_id  INTEGER  NOT  NULL  PRIMARY  KEY,
  user_id  INTEGER  NOT  NULL  REFERENCES  user(user_id),
  pref_name  VARCHAR(40)  NOT  NULL,
  pref_value  VARCHAR(100)
) 

create_all()通常在表定义本身内联创建表之间的外键约束，并且出于这个原因，它也按照它们的依赖顺序生成表。有选项可以更改此行为，使其使用ALTER TABLE。

类似地，使用drop_all()方法可以删除所有表。此方法与create_all()完全相反-首先检查每个表的存在性，然后按依赖关系的相反顺序删除表。

创建和删除单个表可以通过Table的create()和drop()方法来完成。这些方法默认情况下会发出 CREATE 或 DROP 命令，而不管表是否存在：

engine = create_engine("sqlite:///:memory:")
metadata_obj = MetaData()
employees = Table(
    "employees",
    metadata_obj,
    Column("employee_id", Integer, primary_key=True),
    Column("employee_name", String(60), nullable=False, key="name"),
    Column("employee_dept", Integer, ForeignKey("departments.department_id")),
)
employees.create(engine)
CREATE  TABLE  employees(
  employee_id  SERIAL  NOT  NULL  PRIMARY  KEY,
  employee_name  VARCHAR(60)  NOT  NULL,
  employee_dept  INTEGER  REFERENCES  departments(department_id)
)
{} 

drop()方法：

employees.drop(engine)
DROP  TABLE  employees
{} 

要启用“首先检查表是否存在”的逻辑，请在create()或drop()中添加checkfirst=True参数：

employees.create(engine, checkfirst=True)
employees.drop(engine, checkfirst=False)

通过迁移修改数据库对象

虽然 SQLAlchemy 直接支持为模式构造发出 CREATE 和 DROP 语句，但是修改这些构造的能力，通常通过 ALTER 语句以及其他特定于数据库的构造，超出了 SQLAlchemy 本身的范围。虽然手动发出 ALTER 语句等很容易，例如通过将text()构造传递给Connection.execute()或使用DDL构造，但通常的做法是使用模式迁移工具自动化维护数据库模式与应用程序代码的关系。

SQLAlchemy 项目为此提供了Alembic迁移工具。Alembic 具有高度可定制的环境和极简的使用模式，支持诸如事务 DDL、自动生成“候选”迁移、生成 SQL 脚本的“脱机”模式以及分支解析支持等功能。

Alembic 取代了SQLAlchemy-Migrate项目，这是 SQLAlchemy 的原始迁移工具，现在被视为遗留工具。## 指定模式名称

大多数数据库支持多个“模式”（schemas）的概念 -  指代备选表格和其他结构的命名空间。一个“模式”的服务器端几何形状有多种形式，包括特定数据库范围内的“模式”名称（例如 PostgreSQL  模式）、命名的同级数据库（例如 MySQL / MariaDB  访问同一服务器上的其他数据库）、以及其他概念，比如其他用户名拥有的表格（Oracle、SQL  Server）甚至是指代备选数据库文件（SQLite ATTACH）或远程服务器（Oracle DBLINK with  synonyms）的名称。

所有上述方法（大多数）共同之处在于有一种引用这个备选表格集的方式，使用一个字符串名称。SQLAlchemy 将这个名称称为模式名称。在 SQLAlchemy 中，这只是一个与Table对象关联的字符串名称，然后以适合目标数据库的方式渲染成 SQL 语句，以便表格在其远程“模式”中被引用，无论目标数据库上的机制是什么。

“模式”名称可以直接与Table关联，使用Table.schema参数；当使用 ORM 与声明式表格配置时，参数通过__table_args__参数字典传递。

“模式”名称也可以与MetaData对象关联，在这种情况下，它将自动对所有与该MetaData关联的未另行指定名称的Table对象生效。最后，SQLAlchemy 还支持一种“动态”模式名称系统，通常用于多租户应用程序，以便单个Table元数据集可以根据每个连接或每个语句的基础动态配置的模式名称集。

另请参阅

使用声明式表格的显式模式名称 - 在使用 ORM 声明式表格配置时指定模式名称

最基本的例子是使用 Core Table 对象的Table.schema参数，如下所示：

metadata_obj = MetaData()
financial_info = Table(
    "financial_info",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("value", String(100), nullable=False),
    schema="remote_banks",
)

使用这个Table渲染的 SQL，比如下面的 SELECT 语句，将会明确使用remote_banks模式名称来限定表格名称financial_info：

>>> print(select(financial_info))
SELECT  remote_banks.financial_info.id,  remote_banks.financial_info.value
FROM  remote_banks.financial_info 

当使用显式模式名称声明Table对象时，它将使用模式和表名的组合存储在内部MetaData命名空间中。我们可以通过搜索键'remote_banks.financial_info'在MetaData.tables集合中查看此内容：

>>> metadata_obj.tables["remote_banks.financial_info"]
Table('financial_info', MetaData(),
Column('id', Integer(), table=<financial_info>, primary_key=True, nullable=False),
Column('value', String(length=100), table=<financial_info>, nullable=False),
schema='remote_banks')

此点名也是在引用用于与ForeignKey或ForeignKeyConstraint对象一起使用的表时必须使用的内容，即使引用表也在同一模式中：

customer = Table(
    "customer",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("financial_info_id", ForeignKey("remote_banks.financial_info.id")),
    schema="remote_banks",
)

参数Table.schema也可以与某些方言一起使用，以指示到特定表的多个标记路径（例如，点分）。

schema = "dbo.scott"

另请参阅

多部分模式名称 - 描述了在 SQL Server 方言中使用点分模式名称的情况。

从其他模式反射表

使用 MetaData 指定默认模式名称

MetaData对象还可以通过将MetaData.schema参数传递给顶层MetaData构造来为所有Table.schema参数设置一个明确的默认选项：

metadata_obj = MetaData(schema="remote_banks")
financial_info = Table(
    "financial_info",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("value", String(100), nullable=False),
)

以上，对于任何（直接与MetaData相关联的Table对象或Sequence对象）将Table.schema参数保持在其默认值None的情况，将会作为参数设置为值"remote_banks"。这包括使用模式限定名称在MetaData中对Table进行目录化，即：

metadata_obj.tables["remote_banks.financial_info"]

当使用ForeignKey或ForeignKeyConstraint对象引用此表时，可以使用模式限定名称或非模式限定名称来引用remote_banks.financial_info表：

# either will work:
refers_to_financial_info = Table(
    "refers_to_financial_info",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("fiid", ForeignKey("financial_info.id")),
)
# or
refers_to_financial_info = Table(
    "refers_to_financial_info",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("fiid", ForeignKey("remote_banks.financial_info.id")),
)

当使用设置了MetaData.schema的MetaData对象时，希望指定不应限定模式的Table可以使用特殊符号BLANK_SCHEMA：

from sqlalchemy import BLANK_SCHEMA
metadata_obj = MetaData(schema="remote_banks")
financial_info = Table(
    "financial_info",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("value", String(100), nullable=False),
    schema=BLANK_SCHEMA,  # will not use "remote_banks"
)

另见

MetaData.schema ### 应用动态模式命名约定

Table.schema参数使用的名称也可以应用于对每个连接或每个执行动态的查找，因此例如在多租户情况下，每个事务或语句可能针对一组不同的模式名称进行定位。本节模式名称的翻译描述了如何使用此功能。

另见

模式名称的翻译 ### 为新连接设置默认模式

上述方法都涉及在 SQL  语句中包含显式模式名称的方法。数据库连接实际上具有“默认”模式的概念，这是一个“模式”（或数据库、所有者等）的名称，如果表名没有显式地限定模式，则会发生。这些名称通常在登录级别配置，例如连接到  PostgreSQL 数据库时，默认的“模式”称为“public”。

通常情况下，默认的“模式”无法通过登录本身设置，而是在每次建立连接时有用地配置，使用诸如在 PostgreSQL 上使用“SET SEARCH_PATH”或在 Oracle 上使用“ALTER SESSION”的语句。这些方法可以通过使用PoolEvents.connect()事件来实现，该事件允许在首次创建 DBAPI 连接时访问该连接。例如，要将 Oracle 的 CURRENT_SCHEMA 变量设置为替代名称：

from sqlalchemy import event
from sqlalchemy import create_engine
engine = create_engine("oracle+cx_oracle://scott:tiger@tsn_name")
@event.listens_for(engine, "connect", insert=True)
def set_current_schema(dbapi_connection, connection_record):
    cursor_obj = dbapi_connection.cursor()
    cursor_obj.execute("ALTER SESSION SET CURRENT_SCHEMA=%s" % schema_name)
    cursor_obj.close()

在上述情况中，当上述Engine首次连接时，set_current_schema()事件处理程序将立即发生；由于该事件被“插入”到处理程序列表的开头，因此它将在方言自己的事件处理程序运行之前发生，特别是包括确定连接的“默认模式”的事件处理程序。

对于其他数据库，请查阅特定信息的数据库和/或方言文档，了解如何配置默认模式的详细信息。

在版本 1.4.0b2 中更改：上述方法现在无需建立额外的事件处理程序即可运行。

另请参见

在 Connect 上设置备用搜索路径 - 在 PostgreSQL 方言文档中。

模式和反射

SQLAlchemy 的模式功能与在 反射数据库对象 中介绍的表反射功能相互作用。请参阅 从其他模式反射表 部分，了解此功能的更多详细信息。

后端特定选项

Table 支持特定于数据库的选项。例如，MySQL 有不同的表后端类型，包括“MyISAM”和“InnoDB”。这可以通过 Table 使用 mysql_engine 表达：

addresses = Table(
    "engine_email_addresses",
    metadata_obj,
    Column("address_id", Integer, primary_key=True),
    Column("remote_user_id", Integer, ForeignKey(users.c.user_id)),
    Column("email_address", String(20)),
    mysql_engine="InnoDB",
)

其他后端可能也支持表级选项 - 这些将在每个方言的个别文档部分中描述。

列、表、MetaData API

attribute sqlalchemy.schema.BLANK_SCHEMA

指的是 SchemaConst.BLANK_SCHEMA。

attribute sqlalchemy.schema.RETAIN_SCHEMA

指的是 SchemaConst.RETAIN_SCHEMA

class sqlalchemy.schema.Column

代表数据库表中的列。

成员

eq(), init(), le(), lt(), ne(),  all_(), anon_key_label, anon_label, any_(), argument_for(), asc(),  between(), bitwise_and(), bitwise_lshift(), bitwise_not(), bitwise_or(),  bitwise_rshift(), bitwise_xor(), bool_op(), cast(), collate(),  compare(), compile(), concat(), contains(), copy(), desc(),  dialect_kwargs, dialect_options, distinct(), endswith(), expression,  foreign_keys, get_children(), icontains(), iendswith(), ilike(), in_(),  index, info, inherit_cache, is_(), is_distinct_from(), is_not(),  is_not_distinct_from(), isnot(), isnot_distinct_from(), istartswith(),  key, kwargs, label(), like(), match(), not_ilike(), not_in(),  not_like(), notilike(), notin_(), notlike(), nulls_first(),  nulls_last(), nullsfirst(), nullslast(), op(), operate(), params(),  proxy_set, references(), regexp_match(), regexp_replace(),  reverse_operate(), self_group(), shares_lineage(), startswith(),  timetuple, unique, unique_params()

类签名

类sqlalchemy.schema.Column（sqlalchemy.sql.base.DialectKWArgs，sqlalchemy.schema.SchemaItem，sqlalchemy.sql.expression.ColumnClause）

method __eq__(other: Any) → ColumnOperators

继承自 ColumnOperators 的 sqlalchemy.sql.expression.ColumnOperators.__eq__ 方法

实现==运算符。

在列上下文中，生成子句a = b。如果目标是None，则生成a IS NULL。

method __init__(_Column__name_pos: str | _TypeEngineArgument[_T] | SchemaEventTarget | None = None, _Column__type_pos: _TypeEngineArgument[_T] | SchemaEventTarget | None = None, *args: SchemaEventTarget, name: str | None = None, type_: _TypeEngineArgument[_T] | None = None, autoincrement: _AutoIncrementType = 'auto', default: Any | None = None, doc: str | None = None, key: str | None = None, index: bool | None = None, unique: bool | None = None, info: _InfoType | None = None, nullable: bool | Literal[SchemaConst.NULL_UNSPECIFIED] | None = SchemaConst.NULL_UNSPECIFIED, onupdate: Any | None = None, primary_key: bool = False, server_default: _ServerDefaultArgument | None = None, server_onupdate: FetchedValue | None = None, quote: bool | None = None, system: bool = False, comment: str | None = None, insert_sentinel: bool = False, _omit_from_statements: bool = False, _proxies: Any | None = None, **dialect_kwargs: Any)

构造一个新的Column对象。

参数：

• name –
  在数据库中表示此列的名称。此参数可以是第一个位置参数，也可以通过关键字指定。
  不包含大写字符的名称将被视为大小写不敏感的名称，并且除非它们是保留字，否则不会被引用。包含任意数量大写字符的名称将被引用并发送完全相同。请注意，即使对于标准化大写名称为大小写不敏感的数据库（例如 Oracle），此行为也适用。
  名称字段可以在构建时省略，并在与Table关联之前的任何时候应用。这是为了支持在declarative扩展中的方便使用。
  
• type_ –
  列的类型，使用一个继承自TypeEngine的实例来表示。如果类型不需要参数，则也可以发送类型的类，例如：

# use a type with arguments
Column('data', String(50))
# use no arguments
Column('level', Integer)

• type参数可以是第二个位置参数或通过关键字指定。
  如果type为None或省略，则首先默认为特殊类型NullType。如果并且当此Column被指定为引用另一列时，使用ForeignKey和/或ForeignKeyConstraint，远程引用列的类型也将被复制到此列中，在解析外键与该远程Column对象相匹配的时刻。
• *args – 附加的位置参数包括各种派生自SchemaItem的构造，这些构造将作为选项应用于列。这些包括Constraint、ForeignKey、ColumnDefault、Sequence、Computed和Identity的实例。在某些情况下，可能会提供等效的关键字参数，例如server_default、default和unique。
  
• autoincrement –为没有外键依赖的整数主键列设置“自动递增”语义（有关更具体的定义，请参见本文档字符串后面）。这可能会影响在创建表期间为此列发出的 DDL，以及在编译和执行 INSERT 语句时如何考虑该列。默认值是字符串"auto"，表示应自动为单列（即非复合）主键提供自动递增语义，该主键为 INTEGER 类型且没有其他客户端或服务器端默认构造指示。其他值包括True（强制此列具有自动递增语义以供复合主键使用）、False（此列永远不应具有自动递增语义）和字符串"ignore_fk"（外键列的特殊情况，请参见下文）。“自动递增语义”一词既指在 CREATE TABLE 语句中为列发出的 DDL 的类型，也指在调用诸如MetaData.create_all()和Table.create()等方法时，以及在编译和发出 INSERT 语句到数据库时如何考虑该列：

• DDL 渲染（即，MetaData.create_all()，Table.create()）：当用于没有其他默认生成构造与之关联的 Column（例如 Sequence 或 Identity 构造）时，该参数将暗示应该渲染数据库特定的关键字，如 PostgreSQL 中的 SERIAL，MySQL 中的 AUTO_INCREMENT，或 SQL Server 中的 IDENTITY。并非每个数据库后端都有“隐式”的默认生成器可用；例如，Oracle 后端总是需要一个显式的构造，例如 Identity，以便在渲染的 DDL 中包括自动生成的构造，也在数据库中生成。
  
• INSERT 语义（即，当 insert() 构造编译成 SQL 字符串并使用 Connection.execute() 或等效方法在数据库上执行时）：单行 INSERT 语句将自动为此列生成一个新的整数主键值，该值在语句被调用后可通过 Result 对象上的 CursorResult.inserted_primary_key 属性访问。当使用 ORM 持久化 ORM 映射对象到数据库时，这也适用，表示一个新的整数主键将可用作该对象的 identity key 的一部分。无论与 Column 关联的 DDL 构造是什么，此行为都会发生，并且与上面讨论的“DDL 渲染”行为无关。
  

• 该参数可以设置为 True，以指示作为复合（即多列）主键的列应具有自动递增语义，但请注意，主键中仅有一个列可以具有此设置。它还可以设置为 True，以指示在具有客户端或服务器端默认配置的列上具有自动递增语义，但请注意，并非所有方言都可以适应所有样式的默认值作为“自动递增”。它还可以在具有 INTEGER 数据类型的单列主键上设置为 False，以禁用该列的自动递增语义。
  仅对以下列有效：
  

• 整数衍生（即 INT、SMALLINT、BIGINT）。
  
• 主键的一部分
  
• 不通过ForeignKey来引用另一列，除非该值被指定为'ignore_fk'：

# turn on autoincrement for this column despite
# the ForeignKey()
Column('id', ForeignKey('other.id'),
            primary_key=True, autoincrement='ignore_fk')

• 通常不希望启用“自动递增”功能于通过外键引用另一列的情况，因为这样的列必须引用源自其他地方的值。
  该设置对满足上述条件的列有以下效果：
  

• 如果列尚未包括由后端支持的默认生成结构（如 Identity），则为该列发出的 DDL 将包含特定于数据库的关键字，用于表示该列为特定后端的“自动递增”列。主要 SQLAlchemy 方言的行为包括：

• MySQL 和 MariaDB 上的 AUTO INCREMENT
  
• 在 PostgreSQL 上的 SERIAL
  
• MS-SQL 上的 IDENTITY - 即使没有 Identity 结构，这也会发生，因为 Column.autoincrement 参数早于此结构存在。
  
• SQLite - SQLite 整数主键列隐式为“自动递增”，不会渲染任何附加关键字；不包括特殊的 SQLite 关键字 AUTOINCREMENT，因为这是不必要的，也不被数据库供应商推荐。有关更多背景信息，请参阅 SQLite 自动递增行为部分。
  
• Oracle - Oracle 方言目前没有默认的“自动递增”功能可用，因此建议使用 Identity 结构来实现此目的（也可以使用 Sequence 结构）。
  
• 第三方方言 - 请参阅这些方言的文档，了解其特定行为的详情。
  

• 当编译并执行单行insert()构造时，该构造未设置Insert.inline()修饰符，并且使用的数据库驱动程序不会自动在语句执行时检索新生成的主键值时，将自动检索此列的新生成的主键值：

• MySQL、SQLite - 调用 cursor.lastrowid()（请参阅www.python.org/dev/peps/pep-0249/#lastrowid）
  
• PostgreSQL、SQL Server、Oracle - 在渲染 INSERT 语句时使用 RETURNING 或等效结构，并在执行后检索新生成的主键值。
  
• 对于将 Table.implicit_returning 设置为 False 的Table对象的 PostgreSQL、Oracle - 仅对于 Sequence，在执行 INSERT 语句之前显式调用 Sequence，以便新生成的主键值对客户端可用。
  
• 对于将 Table.implicit_returning 设置为 False 的Table对象的 SQL Server - 在调用 INSERT 语句后使用 SELECT scope_identity() 构造来检索新生成的主键值。
  
• 第三方方言 - 请查阅这些方言的文档，了解其特定行为的详细信息。
  

• 对于使用参数列表（即“executemany”语义）调用的多行insert()构造，通常会禁用主键检索行为，但是可能有特殊的 API 可以用于检索“executemany”中新主键值的列表，例如 psycopg2 的“fast insertmany”功能。此类功能非常新，可能尚未在文档中充分介绍。
  

• default –
  表示此列的默认值的标量、Python 可调用对象或ColumnElement表达式，如果此列在 INSERT 的 VALUES 子句中未指定，则将在插入时调用此值。这是使用ColumnDefault作为位置参数的一种快捷方式；请参阅该类以获取有关参数结构的完整详细信息。
  将此参数与Column.server_default进行对比，后者在数据库端创建默认生成器。
  请参阅
  列插入/更新默认值
  
• doc – 可选的字符串，可被 ORM 或类似的程序用于在 Python 端记录属性。此属性不会渲染 SQL 注释；为此目的，请使用Column.comment参数。
  
• key – 可选的字符串标识符，将用于标识此Column对象在Table上。提供关键字时，这是应用程序中引用Column的唯一标识符，包括 ORM 属性映射；name字段仅在渲染 SQL 时使用。
  
• index –
  当为True时，表示将为此Column自动生成一个Index构造，这将导致在调用 DDL 创建操作时为Table发出“CREATE INDEX”语句。
  使用此标志等效于在Table构造本身的层次上显式使用Index构造：

Table(
    "some_table",
    metadata,
    Column("x", Integer),
    Index("ix_some_table_x", "x")
)

• 若要将Index.unique标志添加到Index中，请同时将Column.unique和Column.index标志设置为 True，这将导致发出“CREATE UNIQUE INDEX”DDL 指令而不是“CREATE INDEX”。
  索引的名称使用默认命名约定生成，对于Index构造，其形式为ix__。
  由于此标志仅旨在为常见情况（向表定义添加单列默认配置的索引）提供便利，因此大多数情况下应首选显式使用Index构造，包括跨越多个列的复合索引，具有 SQL 表达式或排序的索引，后端特定的索引配置选项以及使用特定名称的索引。
  注意
  Column.index属性在Column上并不表示此列是否已建立索引，只表示此标志是否在此处明确设置。要查看列上的索引，请查看Table.indexes集合或使用Inspector.get_indexes()。
  另请参阅
  索引
  配置约束命名约定
  Column.unique
• info – 可选数据字典，将填充到此对象的SchemaItem.info属性中。
  
• nullable –
  当设置为False时，在生成列的 DDL 时将添加“NOT NULL”短语。当设置为True时，通常不会生成任何内容（在 SQL 中默认为“NULL”），除非在一些非常特定的后端特定边缘情况下，“NULL”可能会显式呈现。除非Column.primary_key也为True或列指定为Identity，否则默认为True。此参数仅在发出 CREATE TABLE 语句时使用。
  注意
  当列指定为Identity时，DDL 编译器通常会忽略此参数。PostgreSQL 数据库允许通过将此参数显式设置为True来创建可空的标识列。
  
• onupdate –
  一个标量、Python 可调用对象或ClauseElement，表示要应用于列的默认值，在 UPDATE 语句中将在更新时调用，如果此列不在 UPDATE 语句的 SET 子句中，则将被应用。这是使用ColumnDefault作为位置参数与for_update=True的快捷方式。
  另请参阅
  列插入/更新默认值 - 完整讨论 onupdate
  
• primary_key – 如果为True，将此列标记为主键列。可以将多个列设置此标志以指定复合主键。作为替代，可以通过显式的PrimaryKeyConstraint对象来指定Table的主键。
  
• server_default –
  一个FetchedValue实例、str、Unicode 或text()构造，表示列的 DDL DEFAULT 值。
  字符串类型将原样输出，用单引号括起来：

Column('x', Text, server_default="val")
x TEXT DEFAULT 'val'

• text()表达式将原样呈现，不带引号：

Column('y', DateTime, server_default=text('NOW()'))
y DATETIME DEFAULT NOW()

• 字符串和 text()将在初始化时转换为DefaultClause对象。
  该参数还可以接受上下文中有效的 SQLAlchemy 表达式或构造的复杂组合：

from sqlalchemy import create_engine
from sqlalchemy import Table, Column, MetaData, ARRAY, Text
from sqlalchemy.dialects.postgresql import array
engine = create_engine(
    'postgresql+psycopg2://scott:tiger@localhost/mydatabase'
)
metadata_obj = MetaData()
tbl = Table(
        "foo",
        metadata_obj,
        Column("bar",
               ARRAY(Text),
               server_default=array(["biz", "bang", "bash"])
               )
)
metadata_obj.create_all(engine)

• 以上结果将创建一个带有以下 SQL 的表：

CREATE TABLE foo (
    bar TEXT[] DEFAULT ARRAY['biz', 'bang', 'bash']
)

• 使用FetchedValue表示数据库端已存在的列将生成一个默认值，在插入后可由 SQLAlchemy 进行后获取。这种构造不指定任何 DDL，实现留给数据库处理，比如通过触发器。
  请参见
  服务器调用的 DDL-显式默认表达式 - 服务器端默认值的完整讨论
• server_onupdate –
  FetchedValue实例表示数据库端的默认生成函数，比如触发器。这表明对 SQLAlchemy 而言，新生成的值将在更新后可用。这种构造实际上并不在数据库内部实现任何生成函数，而是必须单独指定。
  警告
  此指令当前不会生成  MySQL 的“ON UPDATE CURRENT_TIMESTAMP()”子句。有关如何生成此子句的背景，请参阅为 MySQL /  MariaDB 的 explicit_defaults_for_timestamp 渲染 ON UPDATE CURRENT  TIMESTAMP。
  请参见
  标记隐式生成的值、时间戳和触发列
  
• quote – 强制打开或关闭对此列名称的引用，对应True或False。当保持默认值None时，根据列标识符是否区分大小写（至少有一个大写字符的标识符被视为区分大小写），或者是否是保留字来引用列标识符。只有在需要强制引用 SQLAlchemy 方言未知的保留字时才需要此标志。
  
• unique –
  当值为True时，且Column.index参数保持默认值False，表示将自动生成一个UniqueConstraint构造用于此Column，这将导致在调用Table对象的 DDL 创建操作时，在CREATE TABLE语句中包含引用此列的“UNIQUE CONSTRAINT”子句。
  当此标志为True而同时将Column.index参数设置为True时，效果实际上是生成一个包含Index.unique参数设置为True的Index构造。有关详细信息，请参阅Column.index的文档。
  使用此标志等效于在Table构造本身的级别上显式使用UniqueConstraint构造：

Table(
    "some_table",
    metadata,
    Column("x", Integer),
    UniqueConstraint("x")
)

• 唯一约束对象的UniqueConstraint.name参数保持其默认值为None；在缺少封闭的MetaData的 naming convention 时，唯一约束构造将被发出为未命名的，这通常会调用数据库特定的命名约定来发生。
  由于此标志仅用作在表定义中添加单列，默认配置的唯一约束的便利，因此在大多数用例中应优先使用UniqueConstraint构造的显式使用，包括涵盖多个列的复合约束、特定于后端的索引配置选项以及使用特定名称的约束。
  注意
  Column上的Column.unique属性并不表示此列是否具有唯一约束，只表示此标志是否在此处明确设置了。要查看涉及此列的索引和唯一约束，请查看Table.indexes和/或Table.constraints集合，或使用Inspector.get_indexes()和/或Inspector.get_unique_constraints()
  另请参阅
  唯一约束
  配置约束命名约定
  Column.index
• system –
  当为True时，表示这是一个“系统”列，即数据库自动提供的列，并且不应包含在CREATE TABLE语句的列列表中。
  对于更复杂的场景，其中列应在不同的后端上以不同的条件呈现，请考虑CreateColumn的自定义编译规则。
  
• comment –
  在表创建时可选的字符串，将在 SQL 注释中显示。
  新功能在版本 1.2 中：将Column.comment参数添加到Column。
  
• insert_sentinel –
  将此Column标记为插入标记，用于优化对于没有其他限定主键配置的表的 insertmanyvalues 功能的性能。
  新功能在版本 2.0.10 中引入。
  另请参阅
  insert_sentinel() - 一站式助手，用于声明哨兵列
  “插入多个值”INSERT 语句行为
  配置 Sentinel 列
  

method __le__(other: Any) → ColumnOperators

从 ColumnOperators 的 sqlalchemy.sql.expression.ColumnOperators.__le__ 方法继承

实现<=运算符。

在列上下文中，生成子句a <= b。

method __lt__(other: Any) → ColumnOperators

继承自 ColumnOperators 的 sqlalchemy.sql.expression.ColumnOperators.__lt__ *方法。

实现<运算符。

在列上下文中，生成子句a < b。

method __ne__(other: Any) → ColumnOperators

继承自 ColumnOperators 的 sqlalchemy.sql.expression.ColumnOperators.__ne__ *方法。

实现!=运算符。

在列上下文中，生成子句a != b。如果目标是None，则生成a IS NOT NULL。

method all_() → ColumnOperators

继承自 ColumnOperators 的 ColumnOperators.all_() *方法。

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

查看all_()的文档以获取示例。

注意

请确保不要混淆较新的ColumnOperators.all_()方法与此方法的旧版版本，即专用于ARRAY的Comparator.all()方法，其使用不同的调用风格。

attribute anon_key_label

继承自 ColumnElement 的 ColumnElement.anon_key_label *属性。

自版本 1.4 起弃用：ColumnElement 的 ColumnElement.anon_key_label *属性现在是私有的，公共访问器已弃用。

attribute anon_label

继承自 ColumnElement 的 ColumnElement.anon_label *属性。

自版本 1.4 起弃用：ColumnElement 的 ColumnElement.anon_label *属性现在是私有的，公共访问器已弃用。

method any_() → ColumnOperators

继承自 ColumnOperators.any_() 方法的 ColumnOperators *。

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

有关示例，请参阅 any_() 的文档。

注意

请务必不要混淆较新的 ColumnOperators.any_() 方法与该方法的 旧版，Comparator.any() ，该方法专用于 ARRAY *，其调用方式不同。

classmethod argument_for(dialect_name, argument_name, default)

继承自 DialectKWArgs.argument_for() 方法的 DialectKWArgs *。

为这个类添加一种新的特定于方言的关键字参数。

例如：

Index.argument_for("mydialect", "length", None)
some_index = Index('a', 'b', mydialect_length=5)

DialectKWArgs.argument_for() 方法是一种逐个参数的方式向 DefaultDialect.construct_arguments *字典添加额外参数。此字典为方言代表的各种架构级别构造提供了一组接受的参数名称。

新的方言通常应将此字典一次性指定为方言类的数据成员。通常，用于添加额外参数名称的即席用例是对自定义编译方案也使用额外参数的最终用户代码。

参数：

• dialect_name – 方言的名称。方言必须是可定位的，否则会引发NoSuchModuleError。方言还必须包括一个现有的DefaultDialect.construct_arguments集合，表示它参与关键字参数验证和默认系统，否则会引发ArgumentError。如果方言不包括此集合，则已经可以代表该方言指定任何关键字参数。SQLAlchemy 内置的所有方言都包括此集合，但对于第三方方言，支持可能有所不同。
  
• argument_name – 参数的名称。
  
• default – 参数的默认值。
  

method asc() → ColumnOperators

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

根据父对象生成一个asc()子句。

method between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators

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

根据下限和上限生成一个between()子句。

method bitwise_and(other: Any) → ColumnOperators

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

执行位与操作，通常使用&运算符。

在 2.0.2 版本中新增。

另请参见

位运算符

method bitwise_lshift(other: Any) → ColumnOperators

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

执行位左移操作，通常使用<<运算符。

在 2.0.2 版本中新增。

另请参见

位运算符

method bitwise_not() → ColumnOperators

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

执行位非操作，通常通过~运算符实现。

版本 2.0.2 中新增。

另请参阅

位运算符

method bitwise_or(other: Any) → ColumnOperators

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

执行位或操作，通常通过|运算符实现。

版本 2.0.2 中新增。

另请参阅

位运算符

method bitwise_rshift(other: Any) → ColumnOperators

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

执行位右移操作，通常通过>>运算符实现。

版本 2.0.2 中新增。

另请参阅

位运算符

method bitwise_xor(other: Any) → ColumnOperators

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

执行位异或操作，通常通过^运算符实现，或者对于 PostgreSQL 使用#。

版本 2.0.2 中新增。

另请参阅

位运算符

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

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

返回自定义布尔运算符。

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

另请参阅

Operators.op()

method cast(type_: _TypeEngineArgument[_OPT]) → Cast[_OPT]

继承自 ColumnElement.cast() 方法，来自于 ColumnElement

生成类型转换，即 CAST( AS )。

这是一个快捷方式到 cast() 函数。

请参阅

数据转换和类型强制转换

cast()

type_coerce()

method collate(collation: str) → ColumnOperators

继承自 ColumnOperators.collate() 方法，来自于 ColumnOperators

生成一个针对父对象的 collate() 子句，给定排序规则字符串。

请参阅

collate()

method compare(other: ClauseElement, **kw: Any) → bool

继承自 ClauseElement.compare() 方法，来自于 ClauseElement

将此 ClauseElement 与给定的 ClauseElement 进行比较。

子类应该覆盖默认行为，即直接的标识比较。

**kw 是子类 compare() 方法消耗的参数，可能用于修改比较的条件（请参阅 ColumnElement）。

method compile(bind: _HasDialect | None = None, dialect: Dialect | None = None, **kw: Any) → Compiled

继承自 CompilerElement.compile() 方法，来自于 CompilerElement

编译这个 SQL 表达式。

返回值是一个 Compiled 对象。调用返回值的 str() 或 unicode() 方法将得到结果的字符串表示。Compiled 对象还可以使用 params 访问器返回一个绑定参数名称和值的字典。

参数:

• bind – 一个Connection或Engine，它可以提供一个Dialect以生成一个Compiled对象。如果省略了bind和dialect参数，则使用默认的 SQL 编译器。
  
• column_keys – 用于 INSERT 和 UPDATE 语句，列名列表，应出现在编译语句的 VALUES 子句中。如果为None，则从目标表对象中呈现所有列。
  
• dialect – 一个Dialect实例，可以生成一个Compiled对象。此参数优先于bind参数。
  
• compile_kwargs –
  可选的额外参数字典，将在所有“visit”方法中传递给编译器。这允许将任何自定义标志传递给自定义编译结构，例如。也用于通过literal_binds标志传递的情况：

from sqlalchemy.sql import table, column, select
t = table('t', column('x'))
s = select(t).where(t.c.x == 5)
print(s.compile(compile_kwargs={"literal_binds": True}))

另请参阅

如何将 SQL 表达式渲染为字符串，可能带有内联的绑定参数？

method concat(other: Any) → ColumnOperators

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

实现‘concat’运算符。

在列上下文中，生成子句a || b，或在 MySQL 上使用concat()运算符。

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

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

实现‘contains’运算符。

生成一个 LIKE 表达式，测试字符串值的中间匹配：

column LIKE '%' || <other> || '%'

例如：

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

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

参数：

• other – 要比较的表达式。这通常是一个普通的字符串值，但也可以是任意的 SQL 表达式。除非设置了ColumnOperators.contains.autoescape标志为 True，否则 LIKE 通配符字符%和_不会被默认转义。
  
• 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 copy(**kw: Any) → Column[Any]

自版本 1.4 起已弃用：Column.copy()方法已弃用，将在将来的版本中删除。

method desc() → ColumnOperators

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

对父对象生成 desc() 子句。

attribute dialect_kwargs

继承自 DialectKWArgs.dialect_kwargs 属性的 DialectKWArgs

作为方言特定选项指定的关键字参数的集合。

这里的参数以其原始的 _ 格式存在。只包括实际传递的参数；不同于 DialectKWArgs.dialect_options 集合，该集合包含了此方言已知的所有选项，包括默认值。

该集合也是可写的；接受形式为_的键，其值将被组装到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute dialect_options

继承自 DialectKWArgs.dialect_options 属性的 DialectKWArgs

作为方言特定选项指定的关键字参数的集合。

这是一个两级嵌套的注册表，键入为 和 。例如，postgresql_where 参数可以定位为：

arg = my_object.dialect_options['postgresql']['where']

在版本 0.9.2 中新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

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()

attribute expression

继承自 ColumnElement.expression 属性的 ColumnElement

返回列表达式。

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

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 的即时子元素。

这用于访问遍历。

**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 表达式。除非将ColumnOperators.icontains.autoescape标志设置为True，否则LIKE通配符字符%和_默认不会转义。
  
• 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 表达式。除非将标志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

继承自 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 中添加了“扩展”绑定参数
  如果传递了空列表，则渲染一个特殊的“空列表”表达式，该表达式特定于正在使用的数据库。在 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)

参数：

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

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。

另请参阅

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

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 表达式。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="^")

• 将呈现为：

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集合中表示的列的“键”，例如somekey的somekey将返回一个Column，其.key为“somekey”。

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

实现特定于数据库的 ‘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 是一个空序列，则编译器会生成一个“空的不在”表达式。 默认情况下，这会转换为表达式 “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 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() 改名为 not_like()。 先前的名称仍可用于向后兼容。

另请参阅

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是空序列，则编译器生成一个“空的不在其中”表达式。默认情况下，这默认为表达式“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.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中值的按位与。

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