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

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

指定模式名称

大多数数据库支持多个“模式”的概念-指代替代表集和其他构造的命名空间。  “模式”的服务器端几何形状采用多种形式，包括特定数据库范围内的“模式”名称（例如，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元数据集可以引用每个连接或语句基础上动态配置的模式名称集。

另请参阅

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

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

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

使用此Table渲染的 SQL，比如下面的 SELECT 语句，将明确限定表名financial_info与remote_banks模式名一起使用：

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

在某些方言中，也可以使用 Table.schema 参数指定到达特定表的多令牌（例如，点分）路径。这在诸如 Microsoft SQL Server 这样的数据库上特别重要，因为通常会有点分的 “数据库/所有者” 令牌。可以一次直接将令牌放在名称中，例如：

schema = "dbo.scott"

另请参阅

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

从其他模式反映表

使用 MetaData 指定默认模式名称

MetaData 对象也可以通过将 MetaData.schema 参数传递给顶级 MetaData 结构来设置所有 Table.schema 参数的显式默认选项：

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

以上，对于任何将 Table.schema 参数保留在其默认值 None 的 Table 对象（或直接与 MetaData 关联的 Sequence 对象），将会像参数设置为值 "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 ### 应用动态模式命名约定

Table.schema 参数使用的名称也可以针对每个连接或每个执行基础上的动态查找应用，因此例如在多租户情况下，每个事务或语句可以针对一组动态变化的模式名称。模式名称的翻译 部分描述了此功能的使用方式。

另请参阅

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

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

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

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

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

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

从版本 1.4.0b2 开始更改：上述方法现在无需建立额外的事件处理程序即可工作。

另请参阅

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

模式和反射

SQLAlchemy 的模式特性与 反射数据库对象 中介绍的表反射特性相互作用。有关此工作原理的详细信息，请参阅 从其他模式反射表 部分。

使用 MetaData 指定默认模式名称

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

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

对于任何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

应用动态模式命名约定

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

另请参阅

模式名称的翻译

为新连接设置默认模式

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

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

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

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

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

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

另请参阅

在连接时设置替代搜索路径 - 参见 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",
)

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

列、表、MetaData API

attribute sqlalchemy.schema.BLANK_SCHEMA

指的是 SchemaConst.BLANK_SCHEMA.

attribute sqlalchemy.schema.RETAIN_SCHEMA

指的是 SchemaConst.RETAIN_SCHEMA

class sqlalchemy.schema.Column

表示数据库表中的列。

成员

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

类签名

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

method __eq__(other: Any) → ColumnOperators

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

实现==运算符。

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

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

构造一个新的Column对象。

参数：

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

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

• type参数可以是第二个位置参数，也可以通过关键字指定。
  如果type为None或被省略，它将首先默认为特殊类型NullType。如果此Column通过ForeignKey和/或ForeignKeyConstraint参考到另一个列，并且在该外键被解析为远程Column对象的时刻，远程引用列的类型也将被复制到此列。
• *args – 附加的位置参数包括各种派生自SchemaItem的构造，这些构造将被应用为列的选项。这些包括Constraint、ForeignKey、ColumnDefault、Sequence、Computed和Identity的实例。在某些情况下，还可以使用等效的关键字参数，如server_default、default和unique。
  
• autoincrement –设置“自动递增”语义，用于没有外键依赖的整数主键列（详见本文档字符串后面的更具体定义）。这可能会影响在创建表时为该列发出的 DDL，以及编译和执行 INSERT 语句时该列的考虑方式。默认值为字符串"auto"，表示应自动为具有整数类型且没有其他客户端或服务器端默认构造的单列（即非复合）主键接收自动递增语义。其他值包括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 后端总是需要在 Column 中包含一个明确的构造（如 Identity）才能使 DDL 渲染中包括自动生成构造也被生成到数据库中。
  
• INSERT 语义（即当 insert() 构造编译为 SQL 字符串并使用 Connection.execute() 或等效方法在数据库上执行时）：单行 INSERT 语句将会自动为该列生成一个新的整数主键值，该值可在语句调用后通过 Result 对象上的 CursorResult.inserted_primary_key 属性访问。当 ORM 将 ORM 映射对象持久化到数据库时，该行为也适用，表明一个新的整数主键将可用于成为该对象的 标识键 的一部分。此行为与 Column 关联的 DDL 构造无关，且独立于上述前一注中讨论的“DDL 渲染”行为。
  

• 可以将参数设置为 True，表示复合（即多列）主键的一部分的列应具有自动增量语义，但请注意，主键中只有一列可以具有此设置。也可以将其设置为 True，表示在客户端或服务器端配置了默认值的列应具有自动增量语义，但请注意，并非所有方言都能适应所有风格的默认值作为“自增”。也可以在数据类型为 INTEGER 的单列主键上将其设置为 False，以禁用该列的自动增量语义。
  仅仅对以下列有效：
  

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

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

• 在引用其他列的列上启用“自增”通常是不可取的，因为这样的列需要引用来自其他地方的值。
  对满足上述条件的列有以下影响：
  

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

• 在 MySQL 和 MariaDB 上的 AUTO INCREMENT
  
• 在 PostgreSQL 上的 SERIAL
  
• 在 MS-SQL 上的 IDENTITY - 这甚至在没有 Identity 结构的情况下也会发生，因为 Column.autoincrement 参数早于此结构。
  
• SQLite - SQLite 整数主键列隐式“自动增长”，不需要添加额外的关键词；不包括特殊的 SQLite 关键词 AUTOINCREMENT，因为这是不必要的，也不被数据库厂商推荐。更多背景信息请参阅 SQLite Auto Incrementing Behavior 章节。
  
• Oracle - 目前 Oracle 方言没有默认的“自增”功能可用，推荐使用 Identity 结构来实现此功能（也可以使用 Sequence 结构）。
  
• 第三方方言 - 请查阅这些方言的文档，了解其特定行为。
  

• 当编译和执行单行insert()构造时，如果没有设置Insert.inline()修饰符，此列的新生成的主键值将在语句执行时自动通过特定于正在使用的数据库驱动程序的方法检索：

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

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

• default -
  表示此列的默认值的标量、Python 可调用对象或ColumnElement表达式，如果此列在插入的 VALUES 子句中未指定，则将在插入时调用。这是使用ColumnDefault作为位置参数的快捷方式；请参阅该类以获取有关参数结构的完整详细信息。
  与Column.server_default相对的是在数据库端创建默认生成器的默认值。
  另请参阅
  列 INSERT/UPDATE 默认值
  
• 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__。
  由于此标志仅用作向表定义添加单列默认配置索引的常见情况的便利性，因此对于大多数用例，包括跨多列的复合索引、具有 SQL 表达式或排序的索引、特定于后端的索引配置选项以及使用特定名称的索引，应首选显式使用Index构造。
  注意
  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 –
  表示要应用于 UPDATE 语句中的列的默认值的标量、Python 可调用对象或 ClauseElement。如果该列在 UPDATE 的 SET 子句中不存在，将在更新时调用此默认值。这是使用 ColumnDefault 作为 for_update=True 的位置参数的一种捷径。
  另请参阅
  列的 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 创建操作时，包含引用此列的“UNIQUE CONSTRAINT”子句的CREATE TABLE语句被发出。
  当此标志设置为True时，同时Column.index参数也设置为True，则效果是生成一个包含Index.unique参数设置为True的Index构造。有关更多详细信息，请参阅Column.index的文档。
  使用此标志等效于在Table构造本身的级别上显式使用UniqueConstraint构造：

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

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

method __le__(other: Any) → ColumnOperators

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

实现 <= 运算符。

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

method __lt__(other: Any) → ColumnOperators

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

实现 < 运算符。

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

method __ne__(other: Any) → ColumnOperators

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

实现 != 运算符。

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

method all_() → ColumnOperators

继承自 ColumnOperators.all_() 方法的 ColumnOperators 属性

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

请参阅 all_() 的文档以获取示例。

注意

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

attribute anon_key_label

继承自 ColumnElement.anon_key_label 属性的 ColumnElement

自版本 1.4 弃用：ColumnElement.anon_key_label 属性现已私有化，公共访问器已弃用。

attribute anon_label

继承自 ColumnElement.anon_label 属性的 ColumnElement

自版本 1.4 弃用：ColumnElement.anon_label 属性现已私有化，公共访问器已弃用。

method any_() → ColumnOperators

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

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

请参阅 any_() 的文档以获取示例。

注意

一定不要将新版本的 ColumnOperators.any_() 方法与旧版方法混淆，旧版方法是专用于 ARRAY 的 Comparator.any() 方法，其调用风格不同。

classmethod argument_for(dialect_name, argument_name, default)

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

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

例如：

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

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

新的方言通常应该一次性将此字典作为方言类的数据成员来指定。临时添加参数名称的用例通常是针对终端用户代码的，该代码还使用了消耗附加参数的自定义编译方案。

参数：

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

method asc() → ColumnOperators

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

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

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

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

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

method bitwise_and(other: Any) → ColumnOperators

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

执行按位 AND 操作，通常通过 & 运算符。

新版本 2.0.2 中新增。

另请参阅

位运算符

method bitwise_lshift(other: Any) → ColumnOperators

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

生成一个按位 LSHIFT 操作，通常通过 << 运算符。

新版本 2.0.2 中新增。

另请参阅

位运算符

method bitwise_not() → ColumnOperators

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

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

版本 2.0.2 中的新功能。

另请参阅

位运算符

method bitwise_or(other: Any) → ColumnOperators

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

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

版本 2.0.2 中的新功能。

另请参阅

位运算符

method bitwise_rshift(other: Any) → ColumnOperators

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

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

版本 2.0.2 中的新功能。

另请参阅

位运算符

method bitwise_xor(other: Any) → ColumnOperators

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

执行按位异或操作，通常通过 ^ 运算符，或 PostgreSQL 中的 # 运算符。

版本 2.0.2 中的新功能。

另请参阅

位运算符

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

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

返回自定义布尔运算符。

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

另请参阅

Operators.op()

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

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

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

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

另请参阅

数据转换和类型强制转换

cast()

type_coerce()

method collate(collation: str) → ColumnOperators

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

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

另请参阅

collate()

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

继承自 ClauseElement.compare() 方法的 ClauseElement

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

子类应该重写默认行为，这是一个简单的身份比较。

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

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

继承自 CompilerElement.compile() 方法的 CompilerElement

编译这个 SQL 表达式。

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

参数：

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

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

另请参见

如何将 SQL 表达式呈现为字符串，可能包含内联的绑定参数？

method concat(other: Any) → ColumnOperators

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

实现‘concat’操作符。

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

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

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

实现‘contains’操作符。

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

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

例如：

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

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

参数：

• other – 要比较的表达式。通常这是一个简单的字符串值，但也可以是任意的 SQL 表达式。默认情况下，不对 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 copy(**kw: Any) → Column[Any]

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

method desc() → ColumnOperators

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

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

attribute dialect_kwargs

继承自 DialectKWArgs.dialect_kwargs 属性的 DialectKWArgs

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

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

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

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute dialect_options

继承自 DialectKWArgs.dialect_options 属性的 DialectKWArgs

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

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

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

从版本 0.9.2 开始新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

method distinct() → ColumnOperators

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

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

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

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

实现“endswith”操作符。

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

column LIKE '%' || <other>

例如：

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

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

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