使用元数据描述数据库

本节讨论基本 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 的原始迁移工具，现在被视为遗留工具。

指定架构名称

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

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

“架构”名称可以直接与 Table 相关联，使用 Table.schema 参数；在使用 ORM 以及 声明式表 配置时，使用 __table_args__ 参数字典传递该参数。

“架构”名称也可以与 MetaData 对象相关联，它将自动对与该 MetaData 相关联且未显式指定其自身名称的所有 Table 对象生效。最后，SQLAlchemy 还支持一个“动态”架构名称系统，该系统通常用于多租户应用程序，以便一组 Table 元数据可以引用每个连接或每个语句的动态配置的架构名称集。

什么是“架构” ?

SQLAlchemy 对数据库“架构”的支持最初是为了支持 PostgreSQL 风格的架构而设计的。在这种风格中，首先有一个“数据库”，它通常只有一个“所有者”。在这个数据库中，可以有任意数量的“架构”，它们包含实际的表对象。

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

另请参阅

使用声明式表显式指定架构名称 - 在使用 ORM 声明式表 配置时指定架构名称。

最基本的示例是 Table.schema 参数，使用以下核心 Table 对象：

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 命名空间中。我们可以在 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 对象的表时必须使用的名称，即使引用表也在同一个模式中。

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

The Table.schema 参数也可用于某些方言，以指示指向特定表的多个标记（例如带点）路径。这在诸如 Microsoft SQL Server 之类的数据库中尤为重要，因为这些数据库通常具有带点的“数据库/所有者”标记。这些标记可以一次性直接放置在名称中，例如

schema = "dbo.scott"

另请参阅

Multipart Schema Names - 描述在 SQL Server 方言中使用带点模式名称。

从其他模式中反映表

使用 MetaData 指定默认模式名称

The 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 对象（或直接与 MetaData 关联的 Sequence 对象），如果将 Table.schema 参数保留为其默认值 None，则会像将参数设置为值 "remote_banks" 一样起作用。这包括 Table 在 MetaData 中使用限定模式的名称进行编目，即

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

应用动态模式命名约定

The Table.schema 参数使用的名称也可以应用于按连接或按执行方式动态查找的查找，以便例如在多租户情况下，每个事务或语句都可以针对特定的一组更改的模式名称。部分 Translation of Schema Names 描述了如何使用此功能。

另请参阅

模式名称的转换

为新连接设置默认模式

以上所有方法都涉及在 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()

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

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

Changed in version 1.4.0b2: 上述方法现在无需建立其他事件处理程序即可工作。

另请参阅

Setting Alternate Search Paths on Connect - 在 PostgreSQL 方言文档中。

模式和反映

SQLAlchemy 的模式功能与在 Reflecting Database Objects 中介绍的表反映功能交互。请参阅部分 Reflecting Tables from Other Schemas，了解有关此功能如何工作的更多详细信息。

后端特定选项

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

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

列、表、元数据 API

对象名称	描述
Column	表示数据库表中的列。
insert_sentinel([name, type_], *, [default, omit_from_statements])	提供一个代理 Column，它将充当专用的插入 sentinel 列，允许对没有其他合格主键配置的表进行高效的批量插入，并使用确定的 RETURNING 排序。
MetaData	一个 Table 对象及其关联的模式构造的集合。
SchemaConst	一个枚举。
SchemaItem	定义数据库模式的项目的基类。
Table	表示数据库中的表。

attribute sqlalchemy.schema.sqlalchemy.schema.sqlalchemy.schema.BLANK_SCHEMA

指的是 SchemaConst.BLANK_SCHEMA.

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

类签名

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

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

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

实现 == 运算符。

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

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

  The type argument may be the second positional argument or specified by keyword.

  如果type为None或被省略，它将首先默认为特殊类型NullType。如果并且当此Column被设置为使用ForeignKey和/或ForeignKeyConstraint引用另一个列时，远程引用列的类型也会被复制到此列，在该外键解析到该远程Column对象时。

• *args – 其他位置参数包括各种SchemaItem 派生结构，它们将作为选项应用于列。这些包括Constraint、ForeignKey、ColumnDefault、Sequence、Computed Identity 的实例。在某些情况下，可以使用等效的关键字参数，例如 server_default、default 和 unique。

• autoincrement –

  为 **没有外键依赖关系的整数主键列** 设置“自动递增”语义（有关更具体的定义，请参阅本文档字符串的后面部分）。这可能会影响DDL，该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')

  通常不希望对通过外键引用其他列的列启用“自动递增”，因为这样的列需要引用来自其他地方的值。

  该设置对符合上述条件的列具有以下影响

  • 为该列发出的 DDL，如果该列还没有包含后端支持的默认生成结构（如 Identity），将包括数据库特定的关键字，旨在将该列表示为特定后端的“自动递增”列。主要 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()（见 https://www.pythonlang.cn/dev/peps/pep-0249/#lastrowid）

    • PostgreSQL、SQL Server、Oracle - 在渲染 INSERT 语句时使用 RETURNING 或等效结构，然后在执行后检索最新生成的主键值

    • 对于将 Table.implicit_returning 设置为 False 的 Table 对象，PostgreSQL 和 Oracle 会在 INSERT 语句执行之前显式调用 Sequence，以确保新生成的 主键值可供客户端访问。

    • 对于将 Table.implicit_returning 设置为 False 的 Table 对象，SQL Server 会在 INSERT 语句执行之后使用 SELECT scope_identity() 结构来检索新生成的 主键值。

    • 第三方方言 - 请参阅这些方言的文档以了解其特定行为的详细信息。

  • 对于使用参数列表（即“executemany” 语义）调用 的多行 insert() 结构，主键检索行为通常会被禁用，但可能存在用于检索 “executemany” 操作产生的新主键值的列表的特殊 API，例如 psycopg2 的“fast insertmany” 功能。 此类功能非常新，可能尚未在文档中得到充分说明。

• default –

  表示此列的默认值的标量、Python 可调用对象或 ColumnElement 表达式，如果此列未在 INSERT 语句的 VALUES 子句中指定，则在插入时会调用此表达式。 这是使用 ColumnDefault 作为位置参数的简便方法；有关此参数的结构的详细信息，请参阅该类。

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

  另请参阅

  Column INSERT/UPDATE 默认值

• insert_default –

  Column.default 的别名，用于与 mapped_column() 兼容。

• 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 来创建可为空的标识列。

• onupdate –

  一个标量、Python 可调用对象或 ClauseElement，表示要在 UPDATE 语句中应用于该列的默认值，如果该列不在 UPDATE 语句的 SET 子句中，则在更新时会调用该值。这相当于使用 ColumnDefault 作为位置参数，并设置 for_update=True。

  另请参阅

  列 INSERT/UPDATE 默认值 - 对 onupdate 的完整讨论

• primary_key – 如果为 True，则将该列标记为主键列。多个列可以设置此标志来指定组合主键。作为替代方案，可以使用显式的 PrimaryKeyConstraint 对象指定 Table 的主键。

• server_default –

  一个 FetchedValue 实例、字符串、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，了解如何生成此子句的背景信息。

  另请参阅

  标记隐式生成的 value、时间戳和触发器列

• quote – 强制开启或关闭对该列名称的引用，对应于 True 或 False。当保持其默认值 None 时，列标识符将根据名称是否区分大小写（至少包含一个大写字母的标识符将被视为区分大小写）或它是否为保留字来引用。此标志仅用于强制引用 SQLAlchemy 方言未知的保留字。

• unique –

  当 True 且 Column.index 参数保持其默认值 False 时，表示将自动为此 Column 生成一个 UniqueConstraint 结构，这将在调用 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 的 命名约定 的情况下，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.comment 参数添加到 Column 中。

• insert_sentinel –

  将此 Column 标记为 插入哨兵，用于优化没有其他符合主键配置的表的 insertmanyvalues 功能的性能。

  版本 2.0.10 中的新增功能。

  另请参阅

  insert_sentinel() - 用于声明哨兵列的完整助手函数

  INSERT 语句的“插入多个值”行为

  配置哨兵列

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。

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

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

实现 != 运算符。

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

method sqlalchemy.schema.Column.all_() → ColumnOperators

继承自 ColumnOperators.all_() 方法 ColumnOperators

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

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

注意

请不要将较新的 ColumnOperators.all_() 方法与该方法的旧版本（即特定于 ARRAY 的 Comparator.all() 方法，使用不同的调用风格）混淆。

attribute sqlalchemy.schema.Column.anon_key_label

继承自 ColumnElement.anon_key_label 属性 ColumnElement

版本 1.4 中的弃用: 现在 ColumnElement.anon_key_label 属性已变为私有，并且公共访问器已弃用。

attribute sqlalchemy.schema.Column.anon_label

继承自 ColumnElement.anon_label 属性 ColumnElement

版本 1.4 中的弃用: 现在 ColumnElement.anon_label 属性已变为私有，并且公共访问器已弃用。

method sqlalchemy.schema.Column.any_() → ColumnOperators

继承自 ColumnOperators.any_() 方法 ColumnOperators

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

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

注意

请确保不要将较新的 ColumnOperators.any_() 方法与该方法的旧版混淆，即特定于 ARRAY 的 Comparator.any() 方法，该方法使用不同的调用方式。

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

The DialectKWArgs.argument_for() 方法是通过每个参数方式向 DefaultDialect.construct_arguments 字典添加额外参数。这个字典提供了方言代表各种架构级别结构接受的参数名称列表。

新方言通常应将此字典一次性指定为方言类的数据成员。为特定于特定用例添加参数名称的典型情况是针对也使用自定义编译方案的最终用户代码，该方案会使用这些附加参数。

参数:

• dialect_name – 方言名称。方言必须是可定位的，否则将引发 NoSuchModuleError。方言还必须包含一个已存在的 DefaultDialect.construct_arguments 集合，表明它参与了关键字参数验证和默认系统，否则将引发 ArgumentError。如果方言不包含此集合，则可以针对该方言指定任何关键字参数。所有打包在 SQLAlchemy 中的方言都包含此集合，但是对于第三方方言，支持情况可能会有所不同。

• argument_name – 参数名称。

• default – 参数的默认值。

method sqlalchemy.schema.Column.asc() → ColumnOperators

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

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

method sqlalchemy.schema.Column.between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators

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

针对父对象生成 between() 子句，并使用上下限范围。

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

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

生成按位 AND 操作，通常通过 & 运算符实现。

新版 2.0.2 中新增。

另请参阅

按位运算符

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

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

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

新版 2.0.2 中新增。

另请参阅

按位运算符

method sqlalchemy.schema.Column.bitwise_not() → ColumnOperators

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

生成按位取反操作，通常通过 ~ 运算符实现。

新版 2.0.2 中新增。

另请参阅

按位运算符

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

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

生成按位 OR 操作，通常通过 | 运算符实现。

新版 2.0.2 中新增。

另请参阅

按位运算符

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

继承自 ColumnOperators.bitwise_rshift() 方法 ColumnOperators

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

新版 2.0.2 中新增。

另请参阅

按位运算符

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

继承自 ColumnOperators.bitwise_xor() 方法 ColumnOperators

生成一个按位异或操作，通常通过 ^ 运算符实现，或在 PostgreSQL 中使用 #。

新版 2.0.2 中新增。

另请参阅

按位运算符

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

method sqlalchemy.schema.Column.cast(type_: _TypeEngineArgument[_OPT]) → Cast[_OPT]

继承自 ColumnElement.cast() 方法 ColumnElement

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

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

另请参阅

数据转换和类型强制转换

cast()

type_coerce()

method sqlalchemy.schema.Column.collate(collation: str) → ColumnOperators

继承自 ColumnOperators.collate() 方法 ColumnOperators

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

另请参阅

collate()

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

继承自 ClauseElement.compare() 方法 ClauseElement

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

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

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

method 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 表达式渲染为字符串，并可能将绑定参数内联？

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

继承自 ColumnOperators.concat() 方法 ColumnOperators

实现 ‘concat’ 操作符。

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

method 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 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.contains.autoescape 标志设置为 True。

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中的所有 "%"、"_" 和转义字符本身，该值被认为是文字字符串而不是 SQL 表达式。

  例如，表达式：

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

  将渲染为：

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

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字进行渲染，以将该字符设置为转义字符。然后，可以在 % 和 _ 的出现之前放置该字符，以允许它们作为自身，而不是通配符字符。

  例如，表达式：

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

  将渲染为：

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

  该参数还可以与 ColumnOperators.contains.autoescape 组合使用

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

  在上面，给定的文字参数将在传递给数据库之前转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.startswith()

ColumnOperators.endswith()

ColumnOperators.like()

method sqlalchemy.schema.Column.copy(**kw: Any) → Column[Any]

从版本 1.4 开始弃用： The Column.copy() 方法已弃用，将在将来的版本中移除。

method sqlalchemy.schema.Column.desc() → ColumnOperators

继承自 ColumnOperators.desc() 方法 ColumnOperators

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

attribute 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 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.endswith.autoescape 标志设置为 True。

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

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中的所有 "%"、"_" 和转义字符本身，该值被认为是文字字符串而不是 SQL 表达式。

  例如，表达式：

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

  将渲染为：

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字进行渲染，以将该字符设置为转义字符。然后，可以在 % 和 _ 的出现之前放置该字符，以允许它们作为自身，而不是通配符字符。

  例如，表达式：

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

  将渲染为：

  lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'

  该参数还可以与 ColumnOperators.contains.autoescape 组合使用

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

  在上面，给定的文字参数将在传递给数据库之前转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.contains()

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

• autoescape –

  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中的所有 "%"、"_" 和转义字符本身，该值被认为是文字字符串而不是 SQL 表达式。

  例如，表达式：

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

  将渲染为：

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'

  其中 :param 的值为 "foo/%bar"。

• escape –

  一个字符，当给出时，将使用 ESCAPE 关键字进行渲染，以将该字符设置为转义字符。然后，可以在 % 和 _ 的出现之前放置该字符，以允许它们作为自身，而不是通配符字符。

  例如，表达式：

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

  将渲染为：

  lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'

  该参数还可以与 ColumnOperators.iendswith.autoescape 结合使用。

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

  在上面，给定的文字参数将在传递给数据库之前转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.endswith()

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

方法 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 中新增: 添加了“扩展”绑定参数

  如果传递一个空列表，则将呈现一个特殊的“空列表”表达式，该表达式特定于所使用的数据库。在 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() 结构，其中包含 bindparam.expanding 标志设置为 True。

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 运算符。

通常，IS 在与 None 值（解析为 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 运算符。

通常，IS NOT 在与 None 值比较时自动生成，该值解析为 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 运算符。

通常，IS NOT 在与 None 值比较时自动生成，该值解析为 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 表达式。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 sqlalchemy.schema.Column.key: str = None

从 ColumnElement.key 属性继承，该属性属于 ColumnElement

在某些情况下，该对象在 Python 命名空间中的“键”。

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

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)

  版本 2.0 中变更: plainto_tsquery() 现在用于 PostgreSQL 代替 to_tsquery(); 为了与其他形式的兼容性，请参见 全文搜索。

• MySQL - 渲染 MATCH (x) AGAINST (y IN BOOLEAN MODE)

  另请参阅

  match - 带有附加功能的 MySQL 特定结构。

• Oracle - 渲染 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)。

版本 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 是一个空序列，编译器将生成一个“空不在”表达式。 这默认情况下会生成表达式“1 = 1”以在所有情况下产生真。 create_engine.empty_in_strategy 可用于更改此行为。

版本 1.4 中更改: not_in() 运算符已从以前版本中的 notin_() 重命名。旧名称仍然为了向后兼容而可用。

版本 1.2 中更改: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认情况下会为一个空的 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

方法 sqlalchemy.schema.Column.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() 重命名。旧名称仍然为了向后兼容而可用。

另请参阅

ColumnOperators.like()

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

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

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

实现 NOT IN 运算符。

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

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

版本 1.4 中更改: not_in() 运算符已从以前版本中的 notin_() 重命名。旧名称仍然为了向后兼容而可用。

版本 1.2 中更改: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认情况下会为一个空的 IN 序列生成一个“静态”表达式。

另请参阅

ColumnOperators.in_()

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

方法 sqlalchemy.schema.Column.nulls_first() → ColumnOperators

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

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

版本 1.4 中更改: nulls_first() 运算符已从以前版本中的 nullsfirst() 重命名。旧名称仍然为了向后兼容而可用。

方法 sqlalchemy.schema.Column.nulls_last() → ColumnOperators

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

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

版本 1.4 中更改: nulls_last() 运算符已从以前版本中的 nullslast() 重命名。旧名称仍然为了向后兼容而可用。

方法 sqlalchemy.schema.Column.nullsfirst() → ColumnOperators

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

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

版本 1.4 中更改: nulls_first() 运算符已从以前版本中的 nullsfirst() 重命名。旧名称仍然为了向后兼容而可用。

方法 sqlalchemy.schema.Column.nullslast() → ColumnOperators

继承自 ColumnOperators.nullslast() 方法 ColumnOperators

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

版本 1.4 中更改: nulls_last() 运算符已从以前版本中的 nullslast() 重命名。旧名称仍然为了向后兼容而可用。

方法 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，则该运算符将被视为“比较”运算符，即评估为布尔真/假值的运算符，如 ==、> 等。提供此标志是为了使 ORM 关系能够在使用自定义连接条件时确定该运算符是比较运算符。

  使用 is_comparison 参数已被使用 Operators.bool_op() 方法取代；这个更简洁的运算符自动设置此参数，但也提供了正确的 PEP 484 类型支持，因为返回的对象将表示“布尔”数据类型，即 BinaryExpression[bool]。

• return_type – 一个 TypeEngine 类或对象，它将强制由此运算符生成的表达式的返回类型为该类型。默认情况下，指定了 Operators.op.is_comparison 的运算符将解析为 Boolean，而那些没有指定的运算符将与左侧操作数的类型相同。

• python_impl –

  一个可选的 Python 函数，它可以像此运算符在数据库服务器上运行时一样评估两个 Python 值。对在 Python 中进行 SQL 表达式评估的函数很有用，例如用于 ORM 混合属性以及用于在多行更新或删除后匹配会话中的对象的 ORM“评估器”。

  例如：

  >>> expr = column('x').op('+', python_impl=lambda a, b: a + b)('y')

  上述表达式的运算符也将适用于非 SQL 左侧和右侧对象

  >>> expr.operator(5, 10)
  15

  版本 2.0 中的新增功能。

另请参阅

Operators.bool_op()

重新定义和创建新运算符

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

方法 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() 之类的特殊运算符传递。

method 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}

attribute sqlalchemy.schema.Column.proxy_set: util.generic_fn_descriptor[FrozenSet[Any]]

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

我们代理的所有列的集合

从 2.0 版本开始，这明确地是去注解的列。以前它实际上是去注解的列，但没有强制执行。如果可能的话，注解列基本上不应该进入集合，因为它们的哈希行为效率很低。

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

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

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

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

实现数据库特定的“正则表达式匹配”运算符。

例如：

stmt = select(table.c.some_column).where(
    table.c.some_column.regexp_match('^(b|c)')
)

ColumnOperators.regexp_match() 尝试解析为后端提供的类似 REGEXP 的函数或运算符，但是可用的特定正则表达式语法和标志不是后端无关的。

示例包括

• PostgreSQL - 渲染 x ~ y 或 x !~ y 当取反时。

• Oracle - 渲染 REGEXP_LIKE(x, y)

• SQLite - 使用 SQLite 的 REGEXP 占位符运算符并调用 Python re.match() 内置函数。

• 其他后端可能提供特殊实现。

• 没有特殊实现的后端将发出“REGEXP”或“NOT REGEXP”作为运算符。例如，这与 SQLite 和 MySQL 兼容。

目前，正则表达式支持已实现用于 Oracle、PostgreSQL、MySQL 和 MariaDB。SQLite 提供部分支持。第三方方言之间的支持可能会有所不同。

参数:

• pattern – 正则表达式模式字符串或列子句。

• flags – 要应用的任何正则表达式字符串标志，作为纯 Python 字符串传递。这些标志是后端特定的。一些后端，如 PostgreSQL 和 MariaDB，可以可选地将标志指定为模式的一部分。在 PostgreSQL 中使用忽略大小写标志“i”时，将使用忽略大小写正则表达式匹配运算符 ~* 或 !~*。

版本 1.4 中的新增功能。

版本 1.4.48 中的更改: 2.0.18 请注意，由于实现错误，以前“flags”参数除了纯 Python 字符串之外还接受 SQL 表达式对象，如列表达式。此实现与缓存不兼容，已移除；对于“flags”参数，应仅传递字符串，因为这些标志作为 SQL 表达式中的文字内联值渲染。

另请参阅

ColumnOperators.regexp_replace()

method sqlalchemy.schema.Column.regexp_replace(pattern: Any, replacement: Any, flags: str | None = None) → ColumnOperators

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

实现数据库特定的“正则表达式替换”运算符。

例如：

stmt = select(
    table.c.some_column.regexp_replace(
        'b(..)',
        'X
Y',
        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()

method 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。

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

方法 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 表达式。LIKE 通配符字符 % 和 _ 默认情况下不会转义，除非 ColumnOperators.startswith.autoescape 标志设置为 True。

• 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() 的功能相同，除了在受影响的绑定参数中添加 unique=True，以便可以使用多个语句。

class sqlalchemy.schema.MetaData

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

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

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

MetaData 是一个对读操作线程安全的对象。在一个 MetaData 对象中显式或通过反射构建新表可能不是完全线程安全的。

另请参阅

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

成员

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

类签名

class sqlalchemy.schema.MetaData (sqlalchemy.schema.HasSchemaAttr)

method 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 –

  用于 Table、Sequence 以及可能与该 MetaData 关联的其他对象的默认模式。默认为 None。

  另请参阅

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

  Table.schema

  Sequence.schema

• quote_schema – 为那些使用本地 schema 名称的 Table、Sequence 及其他对象设置 quote_schema 标志。

• info – 可选的数据字典，将被填充到该对象的 SchemaItem.info 属性中。

• naming_convention –

  一个字典，引用将为那些没有显式命名的 Constraint 和 Index 对象建立默认命名约定的值。

  该字典的键可以是

  • 约束或索引类，例如 UniqueConstraint、ForeignKeyConstraint 类、Index 类

  • 已知约束类的字符串助记符；"fk"、"pk"、"ix"、"ck"、"uq" 分别代表外键、主键、索引、检查和唯一约束。

  • 用于定义新命名标记的字符串用户定义“标记”名称。

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

  内置名称如下，其中一些可能只对某些类型的约束可用

  • %(table_name)s - 与约束关联的 Table 对象的名称。

  • %(referred_table_name)s - 与 ForeignKeyConstraint 的引用目标关联的 Table 对象的名称。

  • %(column_0_name)s - 约束中索引位置为“0”的 Column 的名称。

  • %(column_0N_name)s - 约束中所有 Column 对象的名称，按顺序排列，不使用分隔符连接。

  • %(column_0_N_name)s - 约束中所有 Column 对象的名称，按顺序排列，使用下划线作为分隔符连接。

  • %(column_0_label)s, %(column_0N_label)s, %(column_0_N_label)s - 第一个 Column 或所有 Columns 的标签，使用或不使用下划线分隔。

  • %(column_0_key)s, %(column_0N_key)s, %(column_0_N_key)s - 表示第零个或所有 Column 的键，使用下划线分隔或不分隔

  • %(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) 可调用对象一起传递到命名约定字典中来实现。

  版本 1.3.0 中的新功能： - 添加了新的 %(column_0N_name)s, %(column_0_N_name)s, 和相关标记，这些标记会生成由给定约束引用的所有列的名称、键或标签的串联。

  另请参阅

  配置约束命名约定 - 详细的使用示例。

method sqlalchemy.schema.MetaData.clear() → None

清除此元数据中的所有表对象。

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 实例作为位置参数调用，对于要反映的任何表，它都应返回一个真值。

• extend_existing – 传递给每个 Table 作为 Table.extend_existing。

• autoload_replace – 传递给每个 Table 作为 Table.autoload_replace。

• resolve_fks –

  如果为 True，则反映与位于每个 Table 中的 ForeignKey 对象关联的 Table 对象。对于 MetaData.reflect()，这将反映相关表的效果，否则这些表可能不在要反映的表列表中，例如，如果引用的表在不同的模式中或通过 MetaData.reflect.only 参数省略。当为 False 时，不会将 ForeignKey 对象跟踪到与其链接的 Table，但是如果相关表也是将要反映的表的列表的一部分，则 ForeignKey 对象将在 MetaData.reflect() 操作完成后，仍然解析为其相关的 Table。默认为 True。

  版本 1.3.0 中的新增功能。

  另请参阅

  Table.resolve_fks

• **dialect_kwargs – 以上未提及的额外关键字参数是特定于方言的，并且以 <dialectname>_<argname> 的形式传递。有关文档化参数的详细信息，请参阅 Dialects 中有关各个方言的文档。

另请参阅

反射数据库对象

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

Reflecting with Database-Agnostic Types - 描述如何使用通用类型反映表。

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 应该为其 schema 设置 ‘None’，即使父 MetaData 指定了 schema。

另请参阅

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、Sequence 或在某些情况下为 ForeignKey 对象，在将对象复制到 Table.to_metadata() 操作中时，应该保留其已有的 schema 名称。

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，它将充当专用的插入 sentinel 列，允许对没有其他合格主键配置的表进行高效的批量插入，并使用确定的 RETURNING 排序。

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

有关此对象使用方式的背景信息，请参阅 配置哨兵列 部分，该部分位于 “插入多行值” 行为的 INSERT 语句 部分中。

返回的 Column 默认情况下将是可空整数列，并使用仅在“插入多行值” 操作中使用的哨兵特定默认生成器。

另请参阅

orm_insert_sentinel()

Column.insert_sentinel

INSERT 语句的“插入多个值”行为

配置哨兵列

版本 2.0.10 中的新增功能。

class sqlalchemy.schema.Table

表示数据库中的表。

例如：

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

Table 对象基于其名称和在给定 MetaData 对象中的可选 schema 名称构造一个唯一的自身实例。使用相同的名称和相同的 MetaData 参数第二次调用 Table 构造函数将返回相同的 Table 对象 - 这样 Table 构造函数充当注册函数。

另请参阅

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

成员

__init__(), add_is_dependent_on(), alias(), append_column(), append_constraint(), argument_for(), autoincrement_column, c, columns, compare(), compile(), constraints, corresponding_column(), create(), delete(), description, dialect_kwargs, dialect_options, drop(), entity_namespace, exported_columns, foreign_key_constraints, foreign_keys, get_children(), implicit_returning, indexes, info, inherit_cache, insert(), is_derived_from(), join(), key, kwargs, lateral(), outerjoin(), params(), primary_key, replace_selectable(), schema, select(), self_group(), table_valued(), tablesample(), to_metadata(), tometadata(), unique_params(), update()

类签名

类 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.autoload_with 与 Table.extend_existing 结合使用时，指示在已存在的 Table 对象中存在的 Column 对象应替换为从自动加载过程中检索到的具有相同名称的列。如果为 False，则已存在名称的列将被从反射过程中省略。

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

  另请参阅

  Table.autoload_with

  Table.extend_existing

• autoload_with –

  一个 Engine 或 Connection 对象，或一个由 Inspector 对象返回的 inspect() 对象，该对象针对一个，此 Table 对象将被反映。当设置为非 None 值时，自动加载过程将针对给定的引擎或连接对该表进行。

  另请参阅

  反射数据库对象

  DDLEvents.column_reflect()

  Reflecting with Database-Agnostic Types

• 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 方言文档中的 Triggers）。

• include_columns – 一个字符串列表，表示要通过 autoload 操作加载的列的子集；不在此列表中的表列将不会在结果 Table 对象中表示。默认为 None，表示应反映所有列。

• resolve_fks –

  当 Table.autoload_with 指定时，是否反映通过 ForeignKey 对象与该表相关的 Table 对象。默认为 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.extend_existing 或 Table.keep_existing 未设置，并且新 Table 的给定名称引用了目标 MetaData 集合中已存在的 Table，并且此 Table 指定了额外的列或其他构造或标志来修改表的狀態，则会引发错误。这两个互斥标志的目的是指定当指定与现有 Table 相匹配的 Table 却指定了额外的构造时，应采取什么操作。

  另请参阅

  Table.extend_existing

• listeners –

  一个形式为 (<eventname>, <fn>) 的元组列表，这些元组将在构造时传递给 listen()。此 listen() 的备用挂钩允许在“自动加载”过程开始之前建立特定于此 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 时，表示此表必须已存在于给定的 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 上设置一个空白模式名称，该 Table 否则将使用其拥有 MetaData 上设置的模式，请指定特殊符号 BLANK_SCHEMA。

  模式名称的引用规则与 name 参数的引用规则相同，即对保留字或区分大小写名称应用引用；要为模式名称启用无条件引用，请在构造函数中指定标志 quote_schema=True，或使用 quoted_name 构造来指定名称。

• comment –

  在表创建时渲染 SQL 注释的可选字符串。

  版本 1.2 中新增： 在 Table 中添加了 Table.comment 参数。

• **kw – 以上未提及的额外关键字参数是特定于方言的，并以 <dialectname>_<argname> 的形式传递。有关已记录参数的详细信息，请参阅 Dialects 中有关个别方言的文档。

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

为该表添加一个“依赖项”。

这是另一个表对象，必须先创建该对象，然后才能创建此对象，或在删除此对象后删除该对象。

通常，表之间的依赖关系是通过 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 属性的值，然后将在此 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)

The 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 集合是使用与表绑定或其他可选择对象绑定的列构建 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

检查器

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

继承自 Selectable.corresponding_column() 方法的 Selectable

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

参数:

• column – 要匹配的目标 ColumnElement。

• require_embedded – 仅返回给定 ColumnElement 的对应列，如果给定 ColumnElement 实际上存在于此 Selectable 的子元素中。通常，如果列与此 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()。

属性 sqlalchemy.schema.Table.description

继承自 TableClause.description 属性 TableClause

属性 sqlalchemy.schema.Table.dialect_kwargs

继承自 DialectKWArgs.dialect_kwargs 属性 DialectKWArgs

作为特定于方言的选项指定给此结构的一组关键字参数。

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

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

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

属性 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 - 平坦字典形式

方法 sqlalchemy.schema.Table.drop(bind: _CreateDropBind, checkfirst: bool = False) → None

针对此 Table 发出 DROP 语句，使用给定的 Connection 或 Engine 进行连接。

另请参阅

MetaData.drop_all().

属性 sqlalchemy.schema.Table.entity_namespace

继承自 FromClause.entity_namespace 属性 FromClause

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

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

stmt.filter_by(address='some address')

它默认为 .c 集合，但内部可以使用“entity_namespace”注释覆盖它以提供其他结果。

属性 sqlalchemy.schema.Table.exported_columns

继承自 FromClause.exported_columns 属性 FromClause

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

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

版本 1.4 中的新增功能。

另请参阅

Selectable.exported_columns

SelectBase.exported_columns

属性 sqlalchemy.schema.Table.foreign_key_constraints

此 Table 引用到的 ForeignKeyConstraint 对象。

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

另请参阅

Table.constraints

Table.foreign_keys

Table.indexes

属性 sqlalchemy.schema.Table.foreign_keys

继承自 FromClause.foreign_keys 属性 FromClause

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

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

另请参阅

Table.foreign_key_constraints

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

继承自 HasTraverseInternals.get_children() 方法 HasTraverseInternals

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

这用于访问遍历。

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

属性 sqlalchemy.schema.Table.implicit_returning = False

继承自 TableClause.implicit_returning 属性 TableClause

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

属性 sqlalchemy.schema.Table.indexes: Set[Index]

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

另请参阅

Inspector.get_indexes()

属性 sqlalchemy.schema.Table.info

继承自 SchemaItem.info 属性 SchemaItem

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

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

属性 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。

例如，一个表的别名将从该表派生。

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 的‘键’。

此值用作 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 关联 - 用法概述。

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

继承自 FromClause.outerjoin() 方法 FromClause

返回一个从这个 FromClause 到另一个 FromClause 的 Join，并将 “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 – 连接的右侧；这可以是任何 FromClause 对象，例如 Table 对象，也可以是可选择兼容的对象，例如 ORM 映射的类。

• onclause – 表示连接 ON 子句的 SQL 表达式。如果保留为 None，FromClause.join() 将尝试根据外键关系连接两个表。

• full – 如果为 True，则呈现 FULL OUTER JOIN，而不是 LEFT OUTER JOIN。

另请参阅

FromClause.join()

Join

方法 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}

属性 sqlalchemy.schema.Table.primary_key

继承自 FromClause.primary_key 属性 FromClause

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

对于 Table 对象，该集合由 PrimaryKeyConstraint 表示，而它本身是 Column 对象的可迭代集合。

方法 sqlalchemy.schema.Table.replace_selectable(old: FromClause, alias: Alias) → Self

继承自 Selectable.replace_selectable() 方法 Selectable

用给定的 Alias 对象替换所有出现的 FromClause ‘old’，返回这个 FromClause 的副本。

从版本 1.4 起已弃用： 该 Selectable.replace_selectable() 方法已弃用，将在未来版本中删除。类似的功能可以通过 sqlalchemy.sql.visitors 模块获得。

属性 sqlalchemy.schema.Table.schema: str | None = None

继承自 FromClause.schema 属性 FromClause

为这个 FromClause 定义 ‘schema’ 属性。

这通常对于大多数对象来说是 None，除了 Table，它的值取自 Table.schema 参数。

方法 sqlalchemy.schema.Table.select() → Select

继承自 FromClause.select() 方法 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() 方法 ClauseElement

对这个 ClauseElement 应用一个“分组”。

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

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

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

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

继承自 NamedFromClause.table_valued() 方法 NamedFromClause

返回此 FromClause 的 TableValuedColumn 对象。

TableValuedColumn 是一个 ColumnElement，它代表表中的一整行。对这种结构的支持依赖于后端，并且以各种形式由 PostgreSQL、Oracle 和 SQL Server 等后端支持。

例如：

>>> from sqlalchemy import select, 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

版本 1.4.0b2 中的新增功能。

另请参阅

使用 SQL 函数 - 在 SQLAlchemy 统一教程 中

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

继承自 FromClause.tablesample() 方法 FromClause

返回此 FromClause 的 TABLESAMPLE 别名。

返回值是 TableSample 结构，它也由顶层 tablesample() 函数提供。

另请参阅

tablesample() - 使用指南和参数

method sqlalchemy.schema.Table.to_metadata(metadata: MetaData, schema: str | Literal[SchemaConst.RETAIN_SCHEMA] = SchemaConst.RETAIN_SCHEMA, referred_schema_fn: Callable[[Table, str | None, ForeignKeyConstraint, str | None], str | None] | None = None, name: str | None = None) → Table

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

例如：

m1 = MetaData()

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

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

版本 1.4 中的更改： Table.to_metadata() 函数已从 Table.tometadata() 重命名。

参数:

• metadata – 目标 MetaData 对象，将在其中创建新的 Table 对象。

• schema –

  可选字符串名称，指示目标模式。默认为特殊符号 RETAIN_SCHEMA，表示在新 Table 中不应对模式名称进行更改。如果设置为字符串名称，新的 Table 将以这个新名称作为 .schema。如果设置为 None，模式将设置为目标 MetaData 上设置的模式，通常也是 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 的引用表的模式名称。该调用函数接收此父 Table、我们要更改到的目标模式、ForeignKeyConstraint 对象以及该约束的现有“目标模式”。该函数应返回应应用的字符串模式名称。要将模式重置为“无”，请返回符号 BLANK_SCHEMA。要执行无更改操作，请返回 None 或 RETAIN_SCHEMA。

  版本 1.4.33 中的变更: The 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 目标，但使用新名称。

方法 sqlalchemy.schema.Table.tometadata(metadata: MetaData, schema: str | Literal[SchemaConst.RETAIN_SCHEMA] = SchemaConst.RETAIN_SCHEMA, referred_schema_fn: Callable[[Table, str | None, ForeignKeyConstraint, str | None], str | None] | None = None, name: str | None = None) → Table

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

版本 1.4 中的弃用: Table.tometadata() 已重命名为 Table.to_metadata()

有关完整说明，请参见 Table.to_metadata()。

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

继承自 Immutable.unique_params() 方法 Immutable

返回一个带有 bindparam() 元素替换的副本。

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

方法 sqlalchemy.schema.Table.update() → Update

继承自 TableClause.update() 方法 TableClause

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

例如：

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

有关参数和使用方法信息，请参见 update()。