使用MetaData描述数据库¶

本节讨论基本的 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 对象包含我们与之关联的所有 schema 构造。它支持几种访问这些表对象的方法，例如 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
{}

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

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

通过迁移更改数据库对象¶

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

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

Alembic 取代了 SQLAlchemy-Migrate 项目，后者是 SQLAlchemy 的原始迁移工具，现在被认为是遗留工具。

指定 Schema 名称¶

大多数数据库都支持多个“schema”的概念 - 指的是表和其他构造的备用集合的命名空间。服务器端“schema”的几何结构采用多种形式，包括特定数据库范围下的“schema”名称（例如 PostgreSQL schema）、命名的同级数据库（例如 MySQL / MariaDB 对同一服务器上其他数据库的访问），以及其他概念，例如其他用户名拥有的表（Oracle 数据库、SQL Server），甚至是指备用数据库文件（SQLite ATTACH）或远程服务器（带有同义词的 Oracle 数据库 DBLINK）的名称。

以上所有方法（主要）的共同点是，有一种方法可以使用字符串名称引用此备用表集。SQLAlchemy 将此名称称为 schema 名称。在 SQLAlchemy 中，这仅仅是一个字符串名称，它与 Table 对象相关联，然后在 SQL 语句中以适合目标数据库的方式呈现，以便在其远程“schema”中引用该表，无论目标数据库上是什么机制。

“schema”名称可以直接与 Table 关联，方法是使用 Table.schema 参数；当将 ORM 与声明性表配置一起使用时，该参数通过 __table_args__ 参数字典传递。

“schema”名称也可以与 MetaData 对象关联，其中它将自动对与该 MetaData 关联的所有 Table 对象生效，否则这些对象不会指定自己的名称。最后，SQLAlchemy 还支持“动态”schema 名称系统，该系统通常用于多租户应用程序，以便一组 Table 元数据可以引用每个连接或每个语句动态配置的一组 schema 名称。

什么是“schema”？

SQLAlchemy 对数据库“schema”的支持旨在首先支持 PostgreSQL 风格的 schema。在这种风格中，首先有一个“数据库”，它通常只有一个“所有者”。在此数据库中，可以有任意数量的“schema”，然后这些 schema 包含实际的表对象。

特定 schema 中的表使用语法“<schemaname>.<tablename>”显式引用。将其与 MySQL 的架构进行对比，MySQL 只有“数据库”，但 SQL 语句可以一次引用多个数据库，使用相同的语法，只是它是“<database>.<tablename>”。在 Oracle 数据库上，此语法指的是另一个概念，即表的“所有者”。无论使用哪种数据库，SQLAlchemy 都使用短语“schema”来指代“<qualifier>.<tablename>”通用语法中的限定标识符。

另请参阅

使用声明性表的显式 Schema 名称 - 使用 ORM 声明性表配置时的 schema 名称规范

最基本的示例是使用 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 schema 名称显式限定表名 financial_info

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

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

>>> 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 对象一起使用，即使引用表也位于同一 schema 中

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 参数也可以与某些方言一起使用，以指示到特定表的多令牌（例如，点式）路径。这在 Microsoft SQL Server 等数据库上尤为重要，在这些数据库上，通常有点式“数据库/所有者”令牌。令牌可以直接一次放在名称中，例如

schema = "dbo.scott"

另请参阅

多部分 Schema 名称 - 描述了 SQL Server 方言中点式 schema 名称的用法。

从其他 Schema 反射表

使用 MetaData 指定默认 Schema 名称¶

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

上面，对于任何 Table 对象（或直接与 Sequence 对象关联的 MetaData 对象），将 Table.schema 参数保留为其默认值 None，将改为表现得好像该参数设置为值 "remote_banks"。这包括 Table 使用 schema 限定名称在 MetaData 中编目，即

metadata_obj.tables["remote_banks.financial_info"]

当使用 ForeignKey 或 ForeignKeyConstraint 对象引用此表时，可以使用 schema 限定名称或非 schema 限定名称来引用 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 对象时，希望指定不应进行 schema 限定的 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

应用动态 Schema 命名约定¶

Table.schema 参数使用的名称也可以应用于每个连接或每次执行动态查找，以便例如在多租户情况下，每个事务或语句都可以针对一组特定的 schema 名称，这些名称会更改。第 Schema 名称的转换节描述了如何使用此功能。

另请参阅

Schema 名称的转换

为新连接设置默认 Schema¶

以上方法都指的是在 SQL 语句中包含显式 schema 名称的方法。数据库连接实际上具有“默认”schema 的概念，它是如果表名未显式进行 schema 限定时发生的“schema”（或数据库、所有者等）的名称。这些名称通常在登录级别配置，例如在连接到 PostgreSQL 数据库时，默认的“schema”称为“public”。

在许多情况下，无法通过登录本身设置默认“schema”，而是每次建立连接时都应进行有用的配置，方法是使用诸如 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+oracledb://scott:tiger@localhost:1521?service_name=freepdb1"
)


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

上面，set_current_schema() 事件处理程序将在上面的 Engine 首次连接时立即发生；由于该事件“插入”到处理程序列表的开头，因此它也将在方言自身的事件处理程序运行之前发生，尤其包括将确定连接“默认 schema”的处理程序。

对于其他数据库，请查阅数据库和/或方言文档，以获取有关如何配置默认 schema 的具体信息。

在版本 1.4.0b2 中更改: 上面的方法现在可以工作，而无需建立额外的事件处理程序。

另请参阅

在连接时设置备用搜索路径 - 在 PostgreSQL 方言文档中。

Schema 和反射¶

SQLAlchemy 的 schema 功能与反射数据库对象中介绍的表反射功能交互。有关其工作原理的更多详细信息，请参见从其他 Schema 反射表部分。

后端特定选项¶

Table 支持特定于数据库的选项。例如，MySQL 具有不同的表后端类型，包括“MyISAM”和“InnoDB”。可以使用带有 mysql_engine 的 Table 来表示这一点

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",
)

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

Column、Table、MetaData API¶

对象名称	描述
Column	表示数据库表中的列。
insert_sentinel([name, type_], *, [default, omit_from_statements])	提供一个替代 `Column`，它将充当专用的插入哨兵列，从而允许对没有符合条件的主键配置的表进行高效的批量插入和确定性的 RETURNING 排序。
MetaData	`Table` 对象及其相关的模式构造的集合。
SchemaConst	一个枚举。
SchemaItem	用于定义数据库模式的项的基类。
Table	表示数据库中的表。

属性 sqlalchemy.schema.sqlalchemy.schema.sqlalchemy.schema.BLANK_SCHEMA: 指代 SchemaConst.BLANK_SCHEMA。

属性 sqlalchemy.schema.sqlalchemy.schema.sqlalchemy.schema.RETAIN_SCHEMA: 指代 SchemaConst.RETAIN_SCHEMA

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

类签名

class sqlalchemy.schema.Column (sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.schema.SchemaItem, sqlalchemy.sql.expression.ColumnClause)

方法 sqlalchemy.schema.Column.__eq__(other: Any) → ColumnOperators¶

继承自 sqlalchemy.sql.expression.ColumnOperators.__eq__ 方法，源自 ColumnOperators

实现 == 运算符。

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

方法 sqlalchemy.schema.Column.__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 = _NoArg.NO_ARG, insert_default: Any | None = _NoArg.NO_ARG, 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: _ServerOnUpdateArgument | 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 数据库这样将大写名称标准化为不区分大小写的数据库，此行为也适用。

名称字段可以在构造时省略，并在之后应用，在 Column 与 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()）：当用于没有其他默认生成构造（例如 Sequence 或 Identity 构造）的 Column 时，此参数将暗示数据库特定的关键字，例如 PostgreSQL 的 SERIAL, MySQL 的 AUTO_INCREMENT, 或 SQL Server 上的 IDENTITY 也应该被渲染。并非每个数据库后端都提供“隐含”的默认生成器；例如，Oracle 数据库后端始终需要一个显式的构造，如 Identity，与 Column 一起使用，以便渲染的 DDL 也包括在数据库中生成的自动生成构造。
- INSERT 语义（即，当 insert() 构造被编译为 SQL 字符串，然后使用 Connection.execute() 或等效方法在数据库上执行时）：单行 INSERT 语句将被识别为会为此列自动生成一个新的整数主键值。在语句执行后，可以通过 CursorResult.inserted_primary_key 属性在 Result 对象上访问此值。当 ORM 映射的对象被持久化到数据库时，这也适用于 ORM 的使用。这表明新的整数主键将可用于成为该对象的标识键的一部分。无论与 Column 关联的 DDL 构造如何，此行为都会发生，并且独立于前面注释中讨论的 “DDL 渲染” 行为。
该参数可以设置为 True，以指示复合主键（即多列主键）中的某一列应具有自动递增语义。但请注意，主键中只能有一列具有此设置。也可以将其设置为 True，以指示配置了客户端或服务端默认值的列的自动递增语义，但请注意，并非所有方言都能适应所有类型的默认值作为“自动递增”。还可以将其设置为 False，以禁用 INTEGER 类型单列主键的自动递增语义。

此设置仅对以下列有效：
- 整数类型衍生列（即 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.inline() 修饰符的单行 insert() 构造时，将在语句执行后使用特定于所用数据库驱动程序的方法自动检索此列新生成的主键值。
  - MySQL、SQLite - 调用 cursor.lastrowid()（请参阅 https://pythonlang.cn/dev/peps/pep-0249/#lastrowid）
  - PostgreSQL、SQL Server、Oracle 数据库 - 在呈现 INSERT 语句时使用 RETURNING 或等效构造，然后在执行后检索新生成的主键值
  - PostgreSQL、Oracle 数据库，对于将 Table.implicit_returning 设置为 False 的 Table 对象 - 对于 Sequence，仅在 INSERT 语句发生之前显式调用 Sequence，以便客户端可以使用新生成的主键值
  - SQL Server，对于将 Table.implicit_returning 设置为 False 的 Table 对象 - 在调用 INSERT 语句后，使用 SELECT scope_identity() 构造来检索新生成的主键值。
  - 第三方方言 - 有关其具体行为的详细信息，请查阅这些方言的文档。
- 对于使用参数列表（即“executemany”语义）调用的多行 insert() 构造，主键检索行为通常被禁用，但是，可能存在特殊的 API 可用于检索“executemany”的新主键值列表，例如 psycopg2 “fast insertmany”功能。这些功能非常新，可能尚未在文档中得到充分说明。
default¶ –
标量、Python 可调用对象或 ColumnElement 表达式，表示此列的默认值，如果在 insert 的 VALUES 子句中未另行指定此列，则会在 insert 时调用此值。这是使用 ColumnDefault 作为位置参数的快捷方式；有关参数结构的完整详细信息，请参阅该类。

将此参数与 Column.server_default 进行对比，后者在数据库端创建默认值生成器。

另请参阅

列 INSERT/UPDATE 默认值
insert_default¶ –
为了与 mapped_column() 兼容，Column.default 的别名。
doc¶ – 可选的字符串，可供 ORM 或类似工具用于记录 Python 端的属性。此属性不呈现 SQL 注释；请使用 Column.comment 参数来实现此目的。
key¶ – 可选的字符串标识符，用于在 Table 上标识此 Column 对象。当提供 key 时，这是应用程序中引用 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_<tablename>_<columnname>。

由于此标志仅旨在方便向表定义添加单列、默认配置索引的常见情况，因此对于大多数用例，应首选显式使用 Index 构造，包括包含多列的复合索引、带有 SQL 表达式或排序的索引、特定于后端的索引配置选项以及使用特定名称的索引。

注意

Column.index 上 Column 的属性不指示此列是否被索引，仅指示此处是否显式设置了此标志。要查看列上的索引，请查看 Table.indexes 集合或使用 Inspector.get_indexes()。

另请参阅

索引

配置约束命名约定

Column.unique
info¶ – 可选数据字典，将填充到此对象的 SchemaItem.info 属性中。
nullable¶ –
设置为 False 时，将导致在为列生成 DDL 时添加 “NOT NULL” 短语。当为 True 时，通常不生成任何内容（在 SQL 中，这默认为 “NULL”），但在某些非常特定的后端特定边缘情况下，“NULL” 可能会显式呈现。默认为 True，除非 Column.primary_key 也为 True 或列指定了 Identity，在这种情况下，它默认为 False。此参数仅在发出 CREATE TABLE 语句时使用。

注意

当列指定 Identity 时，DDL 编译器通常会忽略此参数。 PostgreSQL 数据库允许通过将此参数显式设置为 True 来实现可为空的 identity 列。
onupdate¶ –
标量、Python 可调用对象或 ClauseElement，表示要在 UPDATE 语句中应用于列的默认值，如果在 update 的 SET 子句中不存在此列，则会在 update 时调用此值。这是使用 for_update=True 的 ColumnDefault 作为位置参数的快捷方式。

另请参阅

列 INSERT/UPDATE 默认值 - 关于 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 时，指示将为此 Column 自动生成 UniqueConstraint 构造，这将导致在为 Table 对象调用 DDL 创建操作时，在发出的 CREATE TABLE 语句中包含引用此列的 “UNIQUE CONSTRAINT” 子句。

当此标志为 True，同时 Column.index 参数同时设置为 True 时，效果是生成 Index 构造，其中包括 Index.unique 参数设置为 True。有关更多详细信息，请参阅 Column.index 的文档。

使用此标志等同于在 Table 构造级别显式使用 UniqueConstraint 构造
```
Table("some_table", metadata, Column("x", Integer), UniqueConstraint("x"))
```
唯一约束对象的 UniqueConstraint.name 参数保留其默认值 None；在缺少封闭 MetaData 的命名约定的情况下，UNIQUE CONSTRAINT 构造将作为未命名发出，这通常会调用特定于数据库的命名约定来执行。

由于此标志仅旨在方便向表定义添加单列、默认配置的唯一约束的常见情况，因此对于大多数用例，应首选显式使用 UniqueConstraint 构造，包括包含多列的复合约束、特定于后端的索引配置选项以及使用特定名称的约束。

注意

Column.unique 上 Column 的属性不指示此列是否具有唯一约束，仅指示此处是否显式设置了此标志。要查看可能涉及此列的索引和唯一约束，请查看 Table.indexes 和/或 Table.constraints 集合，或使用 Inspector.get_indexes() 和/或 Inspector.get_unique_constraints()

另请参阅

UNIQUE 约束

配置约束命名约定

Column.index
system¶ –
当为 True 时，指示这是一个“系统”列，即数据库自动提供的列，不应包含在 CREATE TABLE 语句的列列表中。

对于应在不同后端有条件地以不同方式呈现列的更复杂场景，请考虑 CreateColumn 的自定义编译规则。
comment¶ –
可选字符串，将在表创建时呈现 SQL 注释。

1.2 版本新增: 为 Column 添加了 Column.comment 参数。
insert_sentinel¶ –
将此 Column 标记为插入哨兵，用于优化不具有合格主键配置的表的 insertmanyvalues 功能的性能。

2.0.10 版本新增。

另请参阅

insert_sentinel() - 用于声明哨兵列的 all-in-one 助手

INSERT 语句的 “Insert Many Values” 行为

配置哨兵列

method sqlalchemy.schema.Column.__le__(other: Any) → ColumnOperators¶

继承自 sqlalchemy.sql.expression.ColumnOperators.__le__ 方法，来自 ColumnOperators

实现 <= 运算符。

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

method sqlalchemy.schema.Column.__lt__(other: Any) → ColumnOperators¶

继承自 sqlalchemy.sql.expression.ColumnOperators.__lt__ 方法，来自 ColumnOperators

实现 < 运算符。

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

方法 sqlalchemy.schema.Column.__ne__(other: Any) → ColumnOperators¶

继承自 sqlalchemy.sql.expression.ColumnOperators.__ne__ 方法，来自 ColumnOperators

实现 != 运算符。

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

方法 sqlalchemy.schema.Column.all_() → ColumnOperators¶

继承自 ColumnOperators.all_() 方法，来自 ColumnOperators

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

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

注意

请务必不要将较新的 ColumnOperators.all_() 方法与此方法的旧版版本混淆，即特定于 ARRAY 的 Comparator.all() 方法，后者使用不同的调用样式。

属性 sqlalchemy.schema.Column.anon_key_label¶: 继承自 ColumnElement.anon_key_label 属性，来自 ColumnElement

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

属性 sqlalchemy.schema.Column.anon_label¶: 继承自 ColumnElement.anon_label 属性，来自 ColumnElement

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

方法 sqlalchemy.schema.Column.any_() → ColumnOperators¶

继承自 ColumnOperators.any_() 方法，来自 ColumnOperators

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

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

注意

请务必不要将较新的 ColumnOperators.any_() 方法与此方法的旧版版本混淆，即特定于 ARRAY 的 Comparator.any() 方法，后者使用不同的调用样式。

类方法 sqlalchemy.schema.Column.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¶ – 参数的默认值。

方法 sqlalchemy.schema.Column.asc() → ColumnOperators¶: 继承自 ColumnOperators.asc() 方法，来自 ColumnOperators

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

方法 sqlalchemy.schema.Column.between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators¶: 继承自 ColumnOperators.between() 方法，来自 ColumnOperators

生成针对父对象的 between() 子句，给定下限和上限范围。

方法 sqlalchemy.schema.Column.bitwise_and(other: Any) → ColumnOperators¶: 继承自 ColumnOperators.bitwise_and() 方法，来自 ColumnOperators

生成按位与运算，通常通过 & 运算符实现。

2.0.2 版本新增。

另请参阅

按位运算符

方法 sqlalchemy.schema.Column.bitwise_lshift(other: Any) → ColumnOperators¶: 继承自 ColumnOperators.bitwise_lshift() 方法，来自 ColumnOperators

生成按位左移运算，通常通过 << 运算符实现。

2.0.2 版本新增。

另请参阅

按位运算符

方法 sqlalchemy.schema.Column.bitwise_not() → ColumnOperators¶: 继承自 ColumnOperators.bitwise_not() 方法，来自 ColumnOperators

生成按位非运算，通常通过 ~ 运算符实现。

2.0.2 版本新增。

另请参阅

按位运算符

方法 sqlalchemy.schema.Column.bitwise_or(other: Any) → ColumnOperators¶: 继承自 ColumnOperators.bitwise_or() 方法，来自 ColumnOperators

生成按位或运算，通常通过 | 运算符实现。

2.0.2 版本新增。

另请参阅

按位运算符

方法 sqlalchemy.schema.Column.bitwise_rshift(other: Any) → ColumnOperators¶: 继承自 ColumnOperators.bitwise_rshift() 方法，来自 ColumnOperators

生成按位右移运算，通常通过 >> 运算符实现。

2.0.2 版本新增。

另请参阅

按位运算符

方法 sqlalchemy.schema.Column.bitwise_xor(other: Any) → ColumnOperators¶: 继承自 ColumnOperators.bitwise_xor() 方法，来自 ColumnOperators

生成按位异或运算，通常通过 ^ 运算符实现，或者对于 PostgreSQL 使用 # 运算符。

2.0.2 版本新增。

另请参阅

按位运算符

方法 sqlalchemy.schema.Column.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()

方法 sqlalchemy.schema.Column.cast(type_: _TypeEngineArgument[_OPT]) → Cast[_OPT]¶

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

生成类型转换，即 CAST(<expression> AS <type>)。

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

另请参阅

数据类型转换和类型强制转换

cast()

type_coerce()

方法 sqlalchemy.schema.Column.collate(collation: str) → ColumnOperators¶: 继承自 ColumnOperators.collate() 方法，来自 ColumnOperators

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

另请参阅

collate()

方法 sqlalchemy.schema.Column.compare(other: ClauseElement, **kw: Any) → bool¶

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

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

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

**kw 是子类 compare() 方法使用的参数，可用于修改比较的标准（请参阅 ColumnElement）。

方法 sqlalchemy.schema.Column.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 表达式呈现为字符串，可能带有内联的绑定参数？

方法 sqlalchemy.schema.Column.concat(other: Any) → ColumnOperators¶

继承自 ColumnOperators.concat() 方法，源自 ColumnOperators

实现 ‘concat’ 运算符。

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

方法 sqlalchemy.schema.Column.contains(other: Any, **kw: Any) → ColumnOperators¶

继承自 ColumnOperators.contains() 方法，源自 ColumnOperators

实现 ‘contains’ 运算符。

生成一个 LIKE 表达式，用于测试字符串值中间部分的匹配项

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

例如：

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

由于运算符使用 LIKE，因此出现在 <other> 表达式内部的通配符 "%" 和 "_" 也将表现得像通配符。对于文字字符串值，可以将 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()

方法 sqlalchemy.schema.Column.copy(**kw: Any) → Column[Any]¶: 在 1.4 版本中已弃用: Column.copy() 方法已弃用，并将在未来版本中删除。

方法 sqlalchemy.schema.Column.desc() → ColumnOperators¶: 继承自 ColumnOperators.desc() 方法，源自 ColumnOperators

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

属性 sqlalchemy.schema.Column.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性，源自 DialectKWArgs

指定为此构造的特定于方言的选项的关键字参数集合。

参数以其原始的 <dialect>_<kwarg> 格式存在于此处。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

该集合也是可写的；接受 <dialect>_<kwarg> 形式的键，其中值将组合到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

属性 sqlalchemy.schema.Column.dialect_options¶

继承自 DialectKWArgs.dialect_options 属性，源自 DialectKWArgs

指定为此构造的特定于方言的选项的关键字参数集合。

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

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

0.9.2 版本中的新功能。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

方法 sqlalchemy.schema.Column.distinct() → ColumnOperators¶: 继承自 ColumnOperators.distinct() 方法，源自 ColumnOperators

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

方法 sqlalchemy.schema.Column.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，因此出现在 <other> 表达式内部的通配符 "%" 和 "_" 也将表现得像通配符。对于文字字符串值，可以将 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()

属性 sqlalchemy.schema.Column.expression¶

继承自 ColumnElement.expression 属性，源自 ColumnElement

返回列表达式。

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

属性 sqlalchemy.schema.Column.foreign_keys: Set[ForeignKey] = frozenset({})¶

继承自 ColumnElement.foreign_keys 属性，源自 ColumnElement

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

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

另请参阅

Table.foreign_keys

方法 sqlalchemy.schema.Column.get_children(*, column_tables=False, **kw)¶

继承自 ColumnClause.get_children() 方法，源自 ColumnClause

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

这用于访问遍历。

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

方法 sqlalchemy.schema.Column.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，因此出现在 <other> 表达式内部的通配符 "%" 和 "_" 也将表现得像通配符。对于文字字符串值，可以将 ColumnOperators.icontains.autoescape 标志设置为 True，以对字符串值中出现的这些字符应用转义，以便它们作为自身匹配，而不是作为通配符匹配。或者，ColumnOperators.icontains.escape 参数将建立给定的字符作为转义字符，当目标表达式不是文字字符串时，这可能很有用。

参数:

other¶ – 要比较的表达式。这通常是纯字符串值，但也可以是任意 SQL 表达式。除非将 ColumnOperators.icontains.autoescape 标志设置为 True，否则 LIKE 通配符 % 和 _ 默认情况下不会转义。
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 sqlalchemy.schema.Column.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，因此出现在 <other> 表达式中的通配符 "%" 和 "_" 也将表现为通配符。对于文字字符串值，可以将 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 sqlalchemy.schema.Column.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 sqlalchemy.schema.Column.in_(other: Any) → ColumnOperators¶

继承自 ColumnOperators.in_() 方法，源自 ColumnOperators

实现 in 操作符。

在列上下文中，生成子句 column IN <other>。

给定的参数 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.expanding 标志的 bindparam() 构造。

attribute sqlalchemy.schema.Column.index: bool | None¶

Column.index 参数的值。

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

另请参阅

Table.indexes

attribute sqlalchemy.schema.Column.info¶

继承自 SchemaItem.info 属性，源自 SchemaItem

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

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

attribute sqlalchemy.schema.Column.inherit_cache: bool | None = True¶

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

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

如果与对象对应的 SQL 不会根据此类的局部属性（而不是其超类）而更改，则可以在特定类上将此标志设置为 True。

另请参阅

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

method sqlalchemy.schema.Column.is_(other: Any) → ColumnOperators¶

继承自 ColumnOperators.is_() 方法，源自 ColumnOperators

实现 IS 操作符。

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

另请参阅

ColumnOperators.is_not()

method sqlalchemy.schema.Column.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 sqlalchemy.schema.Column.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 sqlalchemy.schema.Column.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 sqlalchemy.schema.Column.isnot(other: Any) → ColumnOperators¶

继承自 ColumnOperators.isnot() 方法，源自 ColumnOperators

实现 IS NOT 操作符。

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

在版本 1.4 中变更：is_not() 操作符已从之前的版本中的 isnot() 重命名。为了向后兼容，之前的名称仍然可用。

另请参阅

ColumnOperators.is_()

method sqlalchemy.schema.Column.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 sqlalchemy.schema.Column.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，因此出现在 <other> 表达式中的通配符 "%" 和 "_" 也将表现为通配符。对于文字字符串值，可以将 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 sqlalchemy.schema.Column.key: str = None¶

继承自 ColumnElement.key 属性，源自 ColumnElement

“key”，在某些情况下，它在 Python 命名空间中引用此对象。

这通常指的是列的“key”，它存在于 selectable 的 .c 集合中，例如 sometable.c["somekey"] 将返回一个 Column，其 .key 为 “somekey”。

attribute sqlalchemy.schema.Column.kwargs¶: 继承自 DialectKWArgs.kwargs 属性，源自 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

method sqlalchemy.schema.Column.label(name: str | None) → Label[_T]¶

继承自 ColumnElement.label() 方法，源自 ColumnElement

生成列标签，即 <columnname> AS <name>。

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

如果 ‘name’ 是 None，则会生成一个匿名标签名。

method sqlalchemy.schema.Column.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 sqlalchemy.schema.Column.match(other: Any, **kwargs: Any) → ColumnOperators¶

继承自 ColumnOperators.match() 方法，源自 ColumnOperators

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

ColumnOperators.match() 尝试解析为后端提供的类似 MATCH 的函数或操作符。例如包括

PostgreSQL - 渲染 x @@ plainto_tsquery(y)

Changed in version 2.0: plainto_tsquery() 现在用于 PostgreSQL 而不是 to_tsquery()；为了与其他形式兼容，请参阅全文搜索。
MySQL - 渲染 MATCH {(}x{)} AGAINST {(}y IN BOOLEAN MODE{)}

另请参阅

match - MySQL 特定构造，具有附加功能。
Oracle Database - 渲染 CONTAINS(x, y)
其他后端可能会提供特殊的实现。
没有任何特殊实现的后端将发出操作符 “MATCH”。例如，这与 SQLite 兼容。

method sqlalchemy.schema.Column.not_ilike(other: Any, escape: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.not_ilike() 方法，源自 ColumnOperators

实现 NOT ILIKE 操作符。

这等效于对 ColumnOperators.ilike() 使用否定，即 ~x.ilike(y)。

Changed in version 1.4: not_ilike() 操作符在之前的版本中从 notilike() 重命名而来。之前的名称仍然可用以保持向后兼容性。

另请参阅

ColumnOperators.ilike()

method sqlalchemy.schema.Column.not_in(other: Any) → ColumnOperators¶

继承自 ColumnOperators.not_in() 方法，源自 ColumnOperators

实现 NOT IN 操作符。

这等效于对 ColumnOperators.in_() 使用否定，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将生成一个 “empty not in” 表达式。这默认为表达式 “1 = 1” 以在所有情况下产生 true。 create_engine.empty_in_strategy 可用于更改此行为。

Changed in version 1.4: not_in() 操作符在之前的版本中从 notin_() 重命名而来。之前的名称仍然可用以保持向后兼容性。

Changed in version 1.2: ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认为空 IN 序列生成 “静态” 表达式。

另请参阅

ColumnOperators.in_()

method sqlalchemy.schema.Column.not_like(other: Any, escape: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.not_like() 方法，源自 ColumnOperators

实现 NOT LIKE 操作符。

这等效于对 ColumnOperators.like() 使用否定，即 ~x.like(y)。

Changed in version 1.4: not_like() 操作符在之前的版本中从 notlike() 重命名而来。之前的名称仍然可用以保持向后兼容性。

另请参阅

ColumnOperators.like()

method sqlalchemy.schema.Column.notilike(other: Any, escape: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.notilike() 方法，源自 ColumnOperators

实现 NOT ILIKE 操作符。

这等效于对 ColumnOperators.ilike() 使用否定，即 ~x.ilike(y)。

Changed in version 1.4: not_ilike() 操作符在之前的版本中从 notilike() 重命名而来。之前的名称仍然可用以保持向后兼容性。

另请参阅

ColumnOperators.ilike()

method sqlalchemy.schema.Column.notin_(other: Any) → ColumnOperators¶

继承自 ColumnOperators.notin_() 方法，源自 ColumnOperators

实现 NOT IN 操作符。

这等效于对 ColumnOperators.in_() 使用否定，即 ~x.in_(y)。

如果 other 是一个空序列，编译器将生成一个 “empty not in” 表达式。这默认为表达式 “1 = 1” 以在所有情况下产生 true。 create_engine.empty_in_strategy 可用于更改此行为。

Changed in version 1.4: not_in() 操作符在之前的版本中从 notin_() 重命名而来。之前的名称仍然可用以保持向后兼容性。

Changed in version 1.2: ColumnOperators.in_() 和 ColumnOperators.not_in() 操作符现在默认为空 IN 序列生成 “静态” 表达式。

另请参阅

ColumnOperators.in_()

method sqlalchemy.schema.Column.notlike(other: Any, escape: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.notlike() 方法，源自 ColumnOperators

实现 NOT LIKE 操作符。

这等效于对 ColumnOperators.like() 使用否定，即 ~x.like(y)。

Changed in version 1.4: not_like() 操作符在之前的版本中从 notlike() 重命名而来。之前的名称仍然可用以保持向后兼容性。

另请参阅

ColumnOperators.like()

method sqlalchemy.schema.Column.nulls_first() → ColumnOperators¶: 继承自 ColumnOperators.nulls_first() 方法，源自 ColumnOperators

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

Changed in version 1.4: nulls_first() 操作符在之前的版本中从 nullsfirst() 重命名而来。之前的名称仍然可用以保持向后兼容性。

method sqlalchemy.schema.Column.nulls_last() → ColumnOperators¶: 继承自 ColumnOperators.nulls_last() 方法，源自 ColumnOperators

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

Changed in version 1.4: nulls_last() 操作符在之前的版本中从 nullslast() 重命名而来。之前的名称仍然可用以保持向后兼容性。

method sqlalchemy.schema.Column.nullsfirst() → ColumnOperators¶: 继承自 ColumnOperators.nullsfirst() 方法，源自 ColumnOperators

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

Changed in version 1.4: nulls_first() 操作符在之前的版本中从 nullsfirst() 重命名而来。之前的名称仍然可用以保持向后兼容性。

method sqlalchemy.schema.Column.nullslast() → ColumnOperators¶: 继承自 ColumnOperators.nullslast() 方法，源自 ColumnOperators

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

Changed in version 1.4: nulls_last() 操作符在之前的版本中从 nullslast() 重命名而来。之前的名称仍然可用以保持向后兼容性。

method sqlalchemy.schema.Column.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¶ –
遗留；如果为 True，则该运算符将被视为 “比较” 运算符，即评估为布尔值 true/false，如 ==、> 等。提供此标志是为了让 ORM 关系可以确定该运算符在自定义连接条件中使用时是比较运算符。

使用 is_comparison 参数已被使用 Operators.bool_op() 方法取代；这种更简洁的运算符会自动设置此参数，但也提供正确的 PEP 484 类型支持，因为返回的对象将表达 “boolean” 数据类型，即 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
```
New in version 2.0.

另请参阅

Operators.bool_op()

重新定义和创建新运算符

在连接条件中使用自定义运算符

method sqlalchemy.schema.Column.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()。

方法 sqlalchemy.schema.Column.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}

属性 sqlalchemy.schema.Column.proxy_set: util.generic_fn_descriptor[FrozenSet[Any]]¶

继承自 ColumnElement.proxy_set 属性，源自 ColumnElement

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

从 2.0 版本开始，这显式地是未注解的列。之前实际上是未注解的列，但没有强制执行。注解的列基本上不应该放入集合中，如果可能的话，因为它们的哈希行为性能非常差。

方法 sqlalchemy.schema.Column.references(column: Column[Any]) → bool¶: 如果此 Column 通过外键引用给定的列，则返回 True。

方法 sqlalchemy.schema.Column.regexp_match(pattern: Any, flags: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.regexp_match() 方法，源自 ColumnOperators

实现数据库特定的“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’ 时，将使用忽略大小写的 regexp match 操作符 ~* 或 !~*。

1.4 版本新增。

在 1.4.48 版本中更改：2.0.18 请注意，由于实现错误，“flags” 参数之前除了纯 Python 字符串外，还接受 SQL 表达式对象，例如列表达式。此实现无法正确地与缓存一起工作，并且已被删除；“flags” 参数应仅传递字符串，因为这些标志在 SQL 表达式中呈现为文字内联值。

另请参阅

ColumnOperators.regexp_replace()

方法 sqlalchemy.schema.Column.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” 参数之前除了纯 Python 字符串外，还接受 SQL 表达式对象，例如列表达式。此实现无法正确地与缓存一起工作，并且已被删除；“flags” 参数应仅传递字符串，因为这些标志在 SQL 表达式中呈现为文字内联值。

另请参阅

ColumnOperators.regexp_match()

方法 sqlalchemy.schema.Column.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → ColumnElement[Any]¶

继承自 ColumnElement.reverse_operate() 方法，源自 ColumnElement

对参数执行反向操作。

用法与 operate() 相同。

方法 sqlalchemy.schema.Column.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() 方法只返回 self。

方法 sqlalchemy.schema.Column.shares_lineage(othercolumn: ColumnElement[Any]) → bool¶: 继承自 ColumnElement.shares_lineage() 方法，源自 ColumnElement

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

方法 sqlalchemy.schema.Column.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，因此 <other> 表达式中存在的通配符 “%” 和 “_” 也将表现得像通配符。对于文字字符串值，可以将 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()

属性 sqlalchemy.schema.Column.timetuple: Literal[None] = None¶: 继承自 ColumnOperators.timetuple 属性，源自 ColumnOperators

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

属性 sqlalchemy.schema.Column.unique: bool | None¶

Column.unique 参数的值。

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

另请参阅

Table.indexes

Table.constraints.

方法 sqlalchemy.schema.Column.unique_params(*optionaldict, **kwargs)¶

继承自 Immutable.unique_params() 方法，源自 Immutable

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

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

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

方法 sqlalchemy.schema.MetaData.__init__(schema: str | None = None, quote_schema: bool | None = None, naming_convention: _NamingSchemaParameter | None = None, info: _InfoType | None = None) → None¶

创建一个新的 MetaData 对象。

参数:

schema¶ –
用于与此 MetaData 关联的 Table、Sequence 以及可能的其他对象的默认 schema。默认为 None。

另请参阅

使用 MetaData 指定默认模式名称 - 关于 MetaData.schema 参数如何使用的详细信息。

Table.schema

Sequence.schema
quote_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 sqlalchemy.schema.MetaData.clear() → None¶: 从此 MetaData 中清除所有 Table 对象。

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

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

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

参数:

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

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

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

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

参数:

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

method sqlalchemy.schema.MetaData.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 中为数据库中可用但尚未在 MetaData 中存在的任何表创建 Table 条目。可以多次调用以获取最近添加到数据库的表，但是如果此 MetaData 中的表在数据库中不再存在，则不会采取特殊操作。

参数:

bind¶ – 用于访问数据库的 Connection 或 Engine。
schema¶ – 可选，从备用模式查询和反射表。如果为 None，则使用与此 MetaData 关联的模式（如果有）。
views¶ – 如果为 True，则也反射视图（物化视图和平铺视图）。
only¶ –
可选。仅加载可用命名表的子集。可以指定为名称序列或可调用对象。

如果提供名称序列，则仅反射这些表。如果请求的表不可用，则会引发错误。此 MetaData 中已存在的命名表将被忽略。

如果提供可调用对象，它将用作布尔谓词来过滤潜在表名称的列表。将使用表名称和此 MetaData 实例作为位置参数调用可调用对象，并且对于要反射的任何表，应返回 true 值。
extend_existing¶ – 作为 Table.extend_existing 传递给每个 Table。
autoload_replace¶ – 作为 Table.autoload_replace 传递给每个 Table。
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¶ – 上面未提及的其他关键字参数是特定于方言的，并以 <dialectname>_<argname> 的形式传递。有关记录的参数的详细信息，请参阅方言中有关各个方言的文档。

另请参阅

反射数据库对象

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

使用数据库无关类型进行反射 - 描述了如何使用通用类型反射表。

method sqlalchemy.schema.MetaData.remove(table: Table) → None¶: 从此 MetaData 中删除给定的 Table 对象。

attribute sqlalchemy.schema.MetaData.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 sqlalchemy.schema.MetaData.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

类签名

class sqlalchemy.schema.SchemaConst (enum.Enum)

attribute sqlalchemy.schema.SchemaConst.BLANK_SCHEMA = 2¶: 符号，指示 Table 或 Sequence 的模式应为“None”，即使父 MetaData 已指定模式。

另请参阅

MetaData.schema

Table.schema

Sequence.schema

attribute sqlalchemy.schema.SchemaConst.NULL_UNSPECIFIED = 3¶

符号，指示“nullable”关键字未传递给 Column。

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

attribute sqlalchemy.schema.SchemaConst.RETAIN_SCHEMA = 1¶: 符号，指示在某些情况下，当对象被复制以进行 Table.to_metadata() 操作时，Table、 Sequence 或 ForeignKey 对象应保留其已有的模式名称。

class sqlalchemy.schema.SchemaItem¶

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

成员

info

类签名

class sqlalchemy.schema.SchemaItem (sqlalchemy.sql.expression.SchemaEventTarget, sqlalchemy.sql.visitors.Visitable)

attribute sqlalchemy.schema.SchemaItem.info¶

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

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

function sqlalchemy.schema.insert_sentinel(name: str | None = None, type_: _TypeEngineArgument[_T] | None = None, *, default: Any | None = None, omit_from_statements: bool = True) → Column[Any]¶

提供一个替代 Column，它将充当专用的插入哨兵列，从而允许对没有符合条件的主键配置的表进行高效的批量插入和确定性的 RETURNING 排序。

将此列添加到 Table 对象需要对应的数据库表实际存在此列。因此，如果将其添加到现有模型，则需要迁移现有数据库表（例如，使用 ALTER TABLE 或类似方法）以包含此列。

有关如何使用此对象的背景信息，请参阅配置哨兵列部分，该部分是 INSERT 语句的“插入多个值”行为部分的一部分。

默认情况下，返回的 Column 将是一个可为空的整数列，并使用仅在 “insertmanyvalues” 操作中使用的哨兵特定默认生成器。

另请参阅

orm_insert_sentinel()

Column.insert_sentinel

INSERT 语句的 “Insert Many Values” 行为

配置哨兵列

2.0.10 版本新增。

class sqlalchemy.schema.Table¶

表示数据库中的表。

例如：

mytable = Table(
    "mytable",
    metadata,
    Column("mytable_id", Integer, primary_key=True),
    Column("value", String(50)),
)

Table 对象基于其名称和给定 MetaData 对象中的可选模式名称，构造其自身的唯一实例。第二次使用相同的名称和相同的 MetaData 参数调用 Table 构造函数将返回 *相同* 的 Table 对象 - 通过这种方式，Table 构造函数充当注册函数。

另请参阅

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

类签名

class sqlalchemy.schema.Table (sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.schema.HasSchemaAttr, sqlalchemy.sql.expression.TableClause, sqlalchemy.inspection.Inspectable)

method sqlalchemy.schema.Table.__init__(name: str, metadata: MetaData, *args: SchemaItem, schema: str | Literal[SchemaConst.BLANK_SCHEMA] | None = None, quote: bool | None = None, quote_schema: bool | None = None, autoload_with: Engine | Connection | None = None, autoload_replace: bool = True, keep_existing: bool = False, extend_existing: bool = False, resolve_fks: bool = True, include_columns: Collection[str] | None = None, implicit_returning: bool = True, comment: str | None = None, info: Dict[Any, Any] | None = None, listeners: _typing_Sequence[Tuple[str, Callable[..., Any]]] | None = None, prefixes: _typing_Sequence[str] | None = None, _extend_on: Set[Table] | None = None, _no_init: bool = True, **kw: Any) → None¶

Table 的构造函数。

参数:

name¶ –
此表在数据库中表示的名称。

表名以及 schema 参数的值构成一个键，该键在所属的 MetaData 集合中唯一标识此 Table。使用相同的名称、元数据和模式名称再次调用 Table 将返回相同的 Table 对象。

不包含大写字符的名称将被视为不区分大小写的名称，除非它们是保留字或包含特殊字符，否则不会被引用。任何数量的大写字符的名称都被认为是区分大小写的，并将作为带引号的名称发送。

要为表名启用无条件引用，请为构造函数指定标志 quote=True，或使用 quoted_name 构造来指定名称。
metadata¶ – MetaData 对象，将包含此表。元数据用作将此表与通过外键引用的其他表关联的点。它也可以用于将此表与特定的 Connection 或 Engine 关联。
*args¶ – 其他位置参数主要用于添加此表内包含的 Column 对象列表。与 CREATE TABLE 语句的样式类似，此处可以添加其他 SchemaItem 构造，包括 PrimaryKeyConstraint 和 ForeignKeyConstraint。
autoload_replace¶ –
默认为 True；当结合 Table.extend_existing 使用 Table.autoload_with 时，指示应将已存在于 Table 对象中的 Column 对象替换为从自动加载过程中检索到的同名列。当 False 时，已存在于现有名称下的列将从反射过程中省略。

请注意，此设置不影响在 Table 的调用中以编程方式指定的 Column 对象，该调用也正在自动加载；当 Table.extend_existing 为 True 时，这些 Column 对象将始终替换同名的现有列。

另请参阅

Table.autoload_with

Table.extend_existing
autoload_with¶ –
一个 Engine 或 Connection 对象，或由 inspect() 针对其中一个返回的 Inspector 对象，此 Table 对象将通过它进行反射。当设置为非 None 值时，将针对给定的引擎或连接对此表执行自动加载过程。

另请参阅

反射数据库对象

DDLEvents.column_reflect()

使用数据库无关类型进行反射
extend_existing¶ –
当 True 时，指示如果此 Table 已经存在于给定的 MetaData 中，则将构造函数中的其他参数应用于现有的 Table。

如果未设置 Table.extend_existing 或 Table.keep_existing，并且新的 Table 的给定名称引用了已存在于目标 MetaData 集合中的 Table，并且此 Table 指定了其他列或其他构造或标志来修改表的状态，则会引发错误。这两个互斥标志的目的是指定当指定的 Table 与现有的 Table 匹配，但指定了其他构造时，应采取的操作。

Table.extend_existing 还可以与 Table.autoload_with 结合使用，以对数据库运行新的反射操作，即使目标 MetaData 中已存在同名的 Table ；新反射的 Column 对象和其他选项将添加到 Table 的状态中，可能会覆盖同名的现有列和选项。

与 Table.autoload_with 的情况一样，可以在同一 Table 构造函数中指定 Column 对象，这将优先。在下面，现有表 mytable 将使用从数据库反射的 Column 对象以及给定的名为 “y” 的 Column 对象进行扩充
```
Table(
    "mytable",
    metadata,
    Column("y", Integer),
    extend_existing=True,
    autoload_with=engine,
)
```
另请参阅

Table.autoload_with

Table.autoload_replace

Table.keep_existing
implicit_returning¶ –
默认为 True - 指示可以使用 RETURNING，通常由 ORM 使用，以便在支持 RETURNING 的后端上获取服务器生成的值，例如主键值和服务器端默认值。

在现代 SQLAlchemy 中，通常没有理由更改此设置，除了一些后端特定的情况（有关此类示例，请参阅 SQL Server 方言文档中的触发器）。
include_columns¶ – 字符串列表，指示要通过 autoload 操作加载的列的子集；此列表中不存在的表列将不会在生成的 Table 对象上表示。默认为 None，表示应反射所有列。
resolve_fks¶ –
是否在指定了 Table.autoload_with 时，反映与此表相关的 Table 对象，这些对象通过 ForeignKey 对象关联。默认为 True。设置为 False 将禁用在遇到 ForeignKey 对象时对相关表的反射；这可以用于节省 SQL 调用，或避免访问不了相关表的问题。请注意，如果相关表已存在于 MetaData 集合中，或稍后添加到其中，则与此 Table 关联的 ForeignKey 对象将正常解析为该表。

1.3 版本新增。

另请参阅

MetaData.reflect.resolve_fks
info¶ – 可选的数据字典，将填充到此对象的 SchemaItem.info 属性中。
keep_existing¶ –
当 True 时，表示如果此 Table 已经存在于给定的 MetaData 中，则忽略构造函数中对现有 Table 的进一步参数，并返回最初创建的 Table 对象。这允许一个函数在首次调用时定义一个新的 Table，但在后续调用时将返回相同的 Table，而不会再次应用任何声明（特别是约束）。

如果未设置 Table.extend_existing 或 Table.keep_existing，并且新的 Table 的给定名称引用了已存在于目标 MetaData 集合中的 Table，并且此 Table 指定了其他列或其他构造或标志来修改表的状态，则会引发错误。这两个互斥标志的目的是指定当指定的 Table 与现有的 Table 匹配，但指定了其他构造时，应采取的操作。

另请参阅

Table.extend_existing
listeners¶ –
形式为 (<eventname>, <fn>) 的元组列表，将在构造时传递给 listen()。这个 listen() 的替代钩子允许在 “autoload” 过程开始之前，为此 Table 建立特定的监听器函数。历史上，这主要用于 DDLEvents.column_reflect() 事件，但请注意，此事件钩子现在可以直接与 MetaData 对象关联
```
def listen_for_reflect(table, column_info):
    "handle the column reflection event"
    # ...


t = Table(
    "sometable",
    autoload_with=engine,
    listeners=[("column_reflect", listen_for_reflect)],
)
```
另请参阅

DDLEvents.column_reflect()
must_exist¶ – 当 True 时，表示此 Table 必须已存在于给定的 MetaData 集合中，否则会引发异常。
prefixes¶ – 要在 CREATE TABLE 语句中的 CREATE 之后插入的字符串列表。它们将以空格分隔。
quote¶ –
强制对此表的名称启用或禁用引号，分别对应于 True 或 False。当保留其默认值 None 时，将根据名称是否区分大小写（至少包含一个大写字符的标识符被视为区分大小写）或是否为保留字来引用列标识符。只有在强制引用 SQLAlchemy 方言未知的保留字时才需要此标志。

注意

将此标志设置为 False 不会为表反射提供不区分大小写的行为；表反射将始终以区分大小写的方式搜索混合大小写的名称。不区分大小写的名称在 SQLAlchemy 中仅通过使用全小写字符声明名称来指定。
quote_schema¶ – 与 ‘quote’ 相同，但应用于模式标识符。
schema¶ –
此表的模式名称，如果表驻留在引擎数据库连接的默认选定模式之外的模式中，则这是必需的。默认为 None。

如果此 Table 的拥有者 MetaData 指定了自己的 MetaData.schema 参数，则如果此处的 schema 参数设置为 None，则该模式名称将应用于此 Table。要在 Table 上设置空白模式名称，否则将使用在拥有者 MetaData 上设置的模式，请指定特殊符号 BLANK_SCHEMA。

模式名称的引用规则与 name 参数的规则相同，即为保留字或区分大小写的名称应用引号；要为模式名称启用无条件引用，请为构造函数指定标志 quote_schema=True，或使用 quoted_name 构造来指定名称。
comment¶ –
可选字符串，将在表创建时呈现 SQL 注释。

1.2 版本新增: 添加了 Table.comment 参数到 Table。
**kw¶ – 上面未提及的其他关键字参数是方言特定的，并以 <dialectname>_<argname> 的形式传递。有关已记录参数的详细信息，请参阅有关方言中各个方言的文档。

method sqlalchemy.schema.Table.add_is_dependent_on(table: Table) → None¶

为此 Table 添加一个“依赖项”。

这是另一个 Table 对象，它必须在此表之前创建，或在此表之后删除。

通常，表之间的依赖关系通过 ForeignKey 对象确定。但是，对于在外键之外创建依赖关系的其他情况（规则、继承），此方法可以手动建立此类链接。

method sqlalchemy.schema.Table.alias(name: str | None = None, flat: bool = False) → NamedFromClause¶

继承自 FromClause.alias() 方法，属于 FromClause

返回此 FromClause 的别名。

例如：

a2 = some_table.alias("a2")

上面的代码创建了一个 Alias 对象，该对象可以在任何 SELECT 语句中用作 FROM 子句。

另请参阅

使用别名

alias()

method sqlalchemy.schema.Table.append_column(column: ColumnClause[Any], replace_existing: bool = False) → None¶

将 Column 追加到此 Table。

新添加的 Column 的 “key”，即其 .key 属性的值，随后将在该 Table 的 .c 集合中可用，并且列定义将包含在此 Table 构造生成的任何 CREATE TABLE、SELECT、UPDATE 等语句中。

请注意，这不会更改表中在任何底层数据库中的定义，假设该表已在数据库中创建。关系数据库支持使用 SQL ALTER 命令向现有表添加列，对于已存在的表中不包含新添加的列的情况，需要发出该命令。

参数:

replace_existing¶ –

当 True 时，允许替换现有列。当 False 时（默认值），如果已存在具有相同 .key 的列，则会引发警告。sqlalchemy 的未来版本将改为引发警告。

1.4.0 版本新增。

method sqlalchemy.schema.Table.append_constraint(constraint: Index | Constraint) → None¶

将 Constraint 追加到此 Table。

这会使约束包含在任何未来的 CREATE TABLE 语句中，前提是特定的 DDL 创建事件尚未与给定的 Constraint 对象关联。

请注意，对于数据库中已存在的表，这不会自动在关系数据库中生成约束。要向现有关系数据库表添加约束，必须使用 SQL ALTER 命令。 SQLAlchemy 还提供了 AddConstraint 构造，当作为可执行子句调用时，可以生成此 SQL。

classmethod sqlalchemy.schema.Table.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¶ – 参数的默认值。

attribute sqlalchemy.schema.Table.autoincrement_column¶

返回当前表示 “自动递增” 列的 Column 对象（如果有），否则返回 None。

这基于 Column 的规则，如 Column.autoincrement 参数所定义，通常指的是单个整数列主键约束中不受外键约束的列。如果表没有这样的主键约束，则没有 “自动递增” 列。一个 Table 只能有一个列定义为 “自动递增” 列。

2.0.4 版本新增。

另请参阅

Column.autoincrement

attribute sqlalchemy.schema.Table.c¶

继承自 FromClause.c 属性，属于 FromClause

是 FromClause.columns 的同义词

返回:: 一个 ColumnCollection

attribute sqlalchemy.schema.Table.columns¶

继承自 FromClause.columns 属性，属于 FromClause

由此 FromClause 维护的 ColumnElement 对象的基于名称的集合。

columns 或 c 集合是使用表绑定或其他 selectable 绑定列构造 SQL 表达式的入口点

select(mytable).where(mytable.c.somecolumn == 5)

返回:: 一个 ColumnCollection 对象。

method sqlalchemy.schema.Table.compare(other: ClauseElement, **kw: Any) → bool¶

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

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

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

**kw 是子类 compare() 方法使用的参数，可用于修改比较的标准（请参阅 ColumnElement）。

method sqlalchemy.schema.Table.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 表达式呈现为字符串，可能带有内联的绑定参数？

attribute sqlalchemy.schema.Table.constraints: Set[Constraint]¶

与此 Table 关联的所有 Constraint 对象的集合。

包括 PrimaryKeyConstraint, ForeignKeyConstraint, UniqueConstraint, CheckConstraint。单独的集合 Table.foreign_key_constraints 指的是所有 ForeignKeyConstraint 对象的集合，而 Table.primary_key 属性指的是与 Table 关联的单个 PrimaryKeyConstraint。

另请参阅

Table.constraints

Table.primary_key

Table.foreign_key_constraints

Table.indexes

Inspector

method sqlalchemy.schema.Table.corresponding_column(column: KeyedColumnElement[Any], require_embedded: bool = False) → KeyedColumnElement[Any] | None¶

继承自 Selectable.corresponding_column() 方法，属于 Selectable

给定一个 ColumnElement，从此 Selectable 的 Selectable.exported_columns 集合中返回导出的 ColumnElement 对象，该对象通过一个共同的祖先列与原始 ColumnElement 相对应。

参数:

column¶ – 要匹配的目标 ColumnElement。
require_embedded¶ – 仅当给定的 ColumnElement 实际存在于此 Selectable 的子元素中时，才返回给定 ColumnElement 的对应列。通常，如果列仅与此 Selectable 的导出列之一共享一个共同的祖先，则该列将匹配。

另请参阅

Selectable.exported_columns - 用于操作的 ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

method sqlalchemy.schema.Table.create(bind: _CreateDropBind, checkfirst: bool = False) → None¶: 为此 Table 发出一个 CREATE 语句，使用给定的 Connection 或 Engine 进行连接。

另请参阅

MetaData.create_all().

method sqlalchemy.schema.Table.delete() → Delete¶

继承自 TableClause.delete() 方法，源自 TableClause

针对此 TableClause 生成一个 delete() 构造。

例如：

table.delete().where(table.c.id == 7)

有关参数和用法信息，请参阅 delete()。

attribute sqlalchemy.schema.Table.description¶: 继承自 TableClause.description 属性，源自 TableClause

attribute sqlalchemy.schema.Table.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性，源自 DialectKWArgs

指定为此构造的特定于方言的选项的关键字参数集合。

参数以其原始的 <dialect>_<kwarg> 格式存在于此处。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

该集合也是可写的；接受 <dialect>_<kwarg> 形式的键，其中值将组合到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute sqlalchemy.schema.Table.dialect_options¶

继承自 DialectKWArgs.dialect_options 属性，源自 DialectKWArgs

指定为此构造的特定于方言的选项的关键字参数集合。

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

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

0.9.2 版本中的新功能。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

method sqlalchemy.schema.Table.drop(bind: _CreateDropBind, checkfirst: bool = False) → None¶: 为此 Table 发出一个 DROP 语句，使用给定的 Connection 或 Engine 进行连接。

另请参阅

MetaData.drop_all().

attribute sqlalchemy.schema.Table.entity_namespace¶

继承自 FromClause.entity_namespace 属性，源自 FromClause

返回用于 SQL 表达式中基于名称的访问的命名空间。

这是用于解析 “filter_by()” 类型表达式的命名空间，例如

stmt.filter_by(address="some address")

它默认为 `.c` 集合，但内部可以使用 “entity_namespace” 注解来覆盖它，以提供替代结果。

attribute sqlalchemy.schema.Table.exported_columns¶

继承自 FromClause.exported_columns 属性，源自 FromClause

一个 ColumnCollection，表示此 Selectable 的“导出”列。

对于 FromClause 对象，“导出”列与 FromClause.columns 集合同义。

1.4 版本新增。

另请参阅

Selectable.exported_columns

SelectBase.exported_columns

attribute sqlalchemy.schema.Table.foreign_key_constraints¶

此 Table 引用的 ForeignKeyConstraint 对象。

此列表由当前关联的 ForeignKey 对象集合生成。

另请参阅

Table.constraints

Table.foreign_keys

Table.indexes

attribute sqlalchemy.schema.Table.foreign_keys¶

继承自 FromClause.foreign_keys 属性，源自 FromClause

返回此 FromClause 引用的 ForeignKey 标记对象集合。

每个 ForeignKey 都是 Table 范围的 ForeignKeyConstraint 的成员。

另请参阅

Table.foreign_key_constraints

method sqlalchemy.schema.Table.get_children(*, omit_attrs: Tuple[str, ...] = (), **kw: Any) → Iterable[HasTraverseInternals]¶

继承自 HasTraverseInternals.get_children() 方法，源自 HasTraverseInternals

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

这用于访问遍历。

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

attribute sqlalchemy.schema.Table.implicit_returning = False¶: 继承自 TableClause.implicit_returning 属性，源自 TableClause

TableClause 不支持拥有主键或列级默认值，因此隐式返回不适用。

attribute sqlalchemy.schema.Table.indexes: Set[Index]¶: 与此 Table 关联的所有 Index 对象的集合。

另请参阅

Inspector.get_indexes()

attribute sqlalchemy.schema.Table.info¶

继承自 SchemaItem.info 属性，源自 SchemaItem

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

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

attribute sqlalchemy.schema.Table.inherit_cache: bool | None = None¶

继承自 HasCacheKey.inherit_cache 属性，源自 HasCacheKey

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

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

如果与对象对应的 SQL 不会根据此类的局部属性（而不是其超类）而更改，则可以在特定类上将此标志设置为 True。

另请参阅

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

method sqlalchemy.schema.Table.insert() → Insert¶

继承自 TableClause.insert() 方法，源自 TableClause

针对此 TableClause 生成一个 Insert 构造。

例如：

table.insert().values(name="foo")

有关参数和用法信息，请参阅 insert()。

method sqlalchemy.schema.Table.is_derived_from(fromclause: FromClause | None) → bool¶

继承自 FromClause.is_derived_from() 方法，源自 FromClause

如果此 FromClause ‘派生自’ 给定的 FromClause`，则返回 `True`。

一个例子是 Table 的别名派生自该 Table。

method sqlalchemy.schema.Table.join(right: _FromClauseArgument, onclause: _ColumnExpressionArgument[bool] | None = None, isouter: bool = False, full: bool = False) → Join¶

继承自 FromClause.join() 方法，源自 FromClause

从此 FromClause 返回一个到另一个 FromClause 的 Join。

例如：

from sqlalchemy import join

j = user_table.join(
    address_table, user_table.c.id == address_table.c.user_id
)
stmt = select(user_table).select_from(j)

将发出类似于以下的 SQL

SELECT user.id, user.name FROM user
JOIN address ON user.id = address.user_id

参数:

right¶ – 连接的右侧；这是任何 FromClause 对象，例如 Table 对象，也可能是可选择兼容的对象，例如 ORM 映射的类。
onclause¶ – 表示连接的 ON 子句的 SQL 表达式。如果保留为 None`，则 FromClause.join() 将尝试基于外键关系连接两个表。
isouter¶ – 如果为 True，则渲染 LEFT OUTER JOIN，而不是 JOIN。
full¶ – 如果为 True，则渲染 FULL OUTER JOIN，而不是 LEFT OUTER JOIN。暗示了 FromClause.join.isouter。

另请参阅

join() - 独立函数

Join - 生成的对象类型

attribute sqlalchemy.schema.Table.key¶

返回此 Table 的 ‘key’。

此值用作 MetaData.tables 集合中的字典键。对于没有设置 Table.schema 的表，它通常与 Table.name 相同；否则，它通常采用 `schemaname.tablename` 的形式。

attribute sqlalchemy.schema.Table.kwargs¶: 继承自 DialectKWArgs.kwargs 属性，源自 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

method sqlalchemy.schema.Table.lateral(name: str | None = None) → LateralFromClause¶

继承自 Selectable.lateral() 方法，源自 Selectable

返回此 Selectable 的 LATERAL 别名。

返回值是由顶层 lateral() 函数提供的 Lateral 构造。

另请参阅

LATERAL correlation - 用法概述。

method sqlalchemy.schema.Table.outerjoin(right: _FromClauseArgument, onclause: _ColumnExpressionArgument[bool] | None = None, full: bool = False) → Join¶

继承自 FromClause.outerjoin() 方法，源自 FromClause

返回一个 Join，从当前的 FromClause 到另一个 FromClause，并将 “isouter” 标志设置为 True。

例如：

from sqlalchemy import outerjoin

j = user_table.outerjoin(
    address_table, user_table.c.id == address_table.c.user_id
)

以上等同于：

j = user_table.join(
    address_table, user_table.c.id == address_table.c.user_id, isouter=True
)

参数:

right¶ – join 的右侧；可以是任何 FromClause 对象，例如 Table 对象，也可以是兼容 selectable 的对象，例如 ORM 映射的类。
onclause¶ – 一个 SQL 表达式，表示 join 的 ON 子句。如果保留为 None，FromClause.join() 将尝试基于外键关系连接两个表。
full¶ – 如果为 True，则渲染 FULL OUTER JOIN，而不是 LEFT OUTER JOIN。

另请参阅

FromClause.join()

Join

method sqlalchemy.schema.Table.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 sqlalchemy.schema.Table.primary_key¶

继承自 FromClause.primary_key 的 attribute FromClause

返回 Column 对象的迭代集合，这些对象构成了此 _selectable.FromClause 的主键。

对于 Table 对象，此集合由 PrimaryKeyConstraint 表示，后者本身是 Column 对象的迭代集合。

method sqlalchemy.schema.Table.replace_selectable(old: FromClause, alias: Alias) → Self¶: 继承自 Selectable.replace_selectable() 的 method Selectable

将所有出现的 FromClause ‘old’ 替换为给定的 Alias 对象，并返回此 FromClause 的副本。

Deprecated since version 1.4: Selectable.replace_selectable() 方法已弃用，并将在未来的版本中移除。类似的功能可通过 sqlalchemy.sql.visitors 模块使用。

attribute sqlalchemy.schema.Table.schema: str | None = None¶

继承自 FromClause.schema 的 attribute FromClause

为此 FromClause 定义 ‘schema’ 属性。

对于大多数对象，这通常为 None，但 Table 对象除外，在 Table.schema 参数中获取其值。

method sqlalchemy.schema.Table.select() → Select¶

继承自 FromClause.select() 的 method FromClause

返回此 FromClause 的 SELECT。

例如：

stmt = some_table.select().where(some_table.c.id == 5)

另请参阅

select() - 通用方法，允许使用任意列列表。

method sqlalchemy.schema.Table.self_group(against: OperatorType | None = None) → ClauseElement¶

继承自 ClauseElement.self_group() 的 method ClauseElement

对此 ClauseElement 应用“分组”。

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

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

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

method sqlalchemy.schema.Table.table_valued() → TableValuedColumn[Any]¶

继承自 NamedFromClause.table_valued() 的 method NamedFromClause

为此 FromClause 返回 TableValuedColumn 对象。

TableValuedColumn 是一个 ColumnElement，表示表中的完整行。对此构造的支持取决于后端，并且 PostgreSQL、Oracle Database 和 SQL Server 等后端以各种形式支持它。

例如：

>>> fromsqlalchemyimportselect,column,func,table>>> a=table("a",column("id"),column("x"),column("y"))>>> stmt=select(func.row_to_json(a.table_valued()))>>> print(stmt)SELECT row_to_json(a) AS row_to_json_1
FROM a

New in version 1.4.0b2.

另请参阅

Working with SQL Functions - 在 SQLAlchemy Unified Tutorial 中

method sqlalchemy.schema.Table.tablesample(sampling: float | Function[Any], name: str | None = None, seed: roles.ExpressionElementRole[Any] | None = None) → TableSample¶

继承自 FromClause.tablesample() 的 method FromClause

返回此 FromClause 的 TABLESAMPLE 别名。

返回值是由顶层 tablesample() 函数提供的 TableSample 构造。

另请参阅

tablesample() - 使用指南和参数

返回与不同 MetaData 关联的此 Table 的副本。

例如：

m1 = MetaData()

user = Table("user", m1, Column("id", Integer, primary_key=True))

m2 = MetaData()
user_copy = user.to_metadata(m2)

Changed in version 1.4: Table.to_metadata() 函数已从 Table.tometadata() 重命名。

参数:

metadata¶ – 目标 MetaData 对象，新的 Table 对象将在其中创建。
schema¶ –
可选的字符串名称，指示目标 schema。默认为特殊符号 RETAIN_SCHEMA，表示新的 Table 中不应更改 schema 名称。如果设置为字符串名称，则新的 Table 将以此新名称作为 .schema。如果设置为 None，则 schema 将设置为目标 MetaData 上设置的 schema，通常也为 None，除非显式设置
```
m2 = MetaData(schema="newschema")

# user_copy_one will have "newschema" as the schema name
user_copy_one = user.to_metadata(m2, schema=None)

m3 = MetaData()  # schema defaults to None

# user_copy_two will have None as the schema name
user_copy_two = user.to_metadata(m3, schema=None)
```
referred_schema_fn¶ –
可选的可调用对象，可以提供该对象以提供应分配给 ForeignKeyConstraint 的引用表的 schema 名称。可调用对象接受此父 Table、我们要更改的目标 schema、ForeignKeyConstraint 对象以及该约束的现有“目标 schema”。该函数应返回应应用的字符串 schema 名称。要将 schema 重置为“none”，请返回符号 BLANK_SCHEMA。要不进行任何更改，请返回 None 或 RETAIN_SCHEMA。

Changed in version 1.4.33: referred_schema_fn 函数可以返回 BLANK_SCHEMA 或 RETAIN_SCHEMA 符号。

例如：
```
def referred_schema_fn(table, to_schema, constraint, referred_schema):
    if referred_schema == "base_tables":
        return referred_schema
    else:
        return to_schema


new_table = table.to_metadata(
    m2, schema="alt_schema", referred_schema_fn=referred_schema_fn
)
```
name¶ – 可选的字符串名称，指示目标表名称。如果未指定或为 None，则保留表名称。这允许将 Table 复制到同一个 MetaData 目标，并使用新名称。

返回与不同 MetaData 关联的此 Table 的副本。

Deprecated since version 1.4: Table.tometadata() 已重命名为 Table.to_metadata()

有关完整描述，请参阅 Table.to_metadata()。

method sqlalchemy.schema.Table.unique_params(*optionaldict, **kwargs)¶

继承自 Immutable.unique_params() 方法，源自 Immutable

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

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

method sqlalchemy.schema.Table.update() → Update¶

继承自 TableClause.update() 的 method TableClause

针对此 TableClause 生成一个 update() 构造。

例如：

table.update().where(table.c.id == 7).values(name="foo")

有关参数和用法信息，请参阅 update()。

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy Core

项目版本

使用MetaData描述数据库¶

访问表和列¶

创建和删除数据库表¶

通过迁移更改数据库对象¶

指定 Schema 名称¶

使用 MetaData 指定默认 Schema 名称¶

应用动态 Schema 命名约定¶

为新连接设置默认 Schema¶

Schema 和反射¶

后端特定选项¶

Column、Table、MetaData API¶