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

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

参数：

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

重新定义和创建新的操作符

在连接条件中使用自定义操作符

method operate(op: OperatorType, *other: Any, **kwargs: Any) → ColumnElement[Any]

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

对参数进行操作。

这是操作的最低级别，默认情况下引发 NotImplementedError。

在子类上覆盖这个方法可以使常见行为应用于所有操作。例如，覆盖 ColumnOperators 以将 func.lower() 应用于左右两侧：

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)

参数：

• op – 操作符可调用。
  
• *other – 操作的‘另一’侧。对于大多数操作，将是单个标量。
  
• **kwargs – 修饰符。这些可能由特殊操作符（如 ColumnOperators.contains()）传递。
  

method params(*optionaldict, **kwargs)

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

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

返回此 ClauseElement 的副本，其中的 bindparam() 元素替换为给定字典中的值：

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

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

继承自 ColumnElement.proxy_set 属性的 ColumnElement

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

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

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

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

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

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

实现特定于数据库的‘regexp match’运算符。

例如：

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

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

示例包括：

• PostgreSQL - 在否定时渲染 x ~ y 或 x !~ y。
  
• Oracle - 渲染 REGEXP_LIKE(x, y)
  
• SQLite - 使用 SQLite 的 REGEXP 占位符操作符，并调用 Python 的 re.match() 内置函数。
  
• 其他后端可能提供特殊的实现。
  
• 没有任何特殊实现的后端将生成操作符“REGEXP”或“NOT REGEXP”。例如，这与 SQLite 和 MySQL 兼容。
  

目前为止，Oracle、PostgreSQL、MySQL 和 MariaDB 实现了正则表达式支持。SQLite 提供了部分支持。第三方方言的支持可能有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。
  
• flags – 要应用的任何正则表达式字符串标志，仅作为纯 Python 字符串传递。这些标志是后端特定的。某些后端，例如 PostgreSQL 和  MariaDB，可能会将标志作为模式的一部分指定。在 PostgreSQL 中使用忽略大小写标志 ‘i’  时，将使用忽略大小写正则表达式匹配运算符 ~* 或 !~*。
  

新版本 1.4 中新增。

在版本 1.4.48 中更改，: 2.0.18 请注意，由于实现错误，先前的“flags”参数接受了 SQL  表达式对象，例如列表达式，而不仅仅是纯 Python  字符串。这个实现与缓存一起使用时不会正常工作，并且已被删除；只应传递字符串给“flags”参数，因为这些标志会作为 SQL  表达式中的文字内联值呈现。

另请参阅

ColumnOperators.regexp_replace()

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

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

实现了特定于数据库的“regexp replace”运算符。

例如：

stmt = select(
    table.c.some_column.regexp_replace(
        'b(..)',
        'XY',
        flags='g'
    )
)

ColumnOperators.regexp_replace() 尝试解析后端提供的类似 REGEXP_REPLACE 的函数，通常会生成函数 REGEXP_REPLACE()。然而，特定的正则表达式语法和可用标志不是跨后端通用的。

目前仅为 Oracle、PostgreSQL、MySQL 8 或更高版本和 MariaDB 实现了正则表达式替换支持。第三方方言的支持可能有所不同。

参数：

• pattern – 正则表达式模式字符串或列子句。
  
• pattern – 替换字符串或列子句。
  
• flags – 要应用的任何正则表达式字符串标志，仅作为纯 Python 字符串传递。这些标志是后端特定的。某些后端，例如 PostgreSQL 和 MariaDB，可能会将标志作为模式的一部分指定。
  

新版本 1.4 中新增。

在版本 1.4.48 更改为：2.0.18 请注意，由于实现错误，以前“flags”参数接受 SQL  表达式对象，例如列表达式，而不仅仅是普通的 Python 字符串。  这种实现与缓存不正确，因此已删除；应该仅传递字符串作为“flags”参数，因为这些标志将作为 SQL 表达式中的文字内联值呈现。

另请参阅

ColumnOperators.regexp_match()

method reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → ColumnElement[Any]

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

对参数进行反向操作。

使用方式与operate()相同。

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

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

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

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

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

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

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

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

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

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

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

实现startswith运算符。

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

column LIKE <other> || '%'

例如：

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

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

参数：

• other – 要比较的表达式。通常是一个普通字符串值，但也可以是任意的 SQL 表达式。除非设置ColumnOperators.startswith.autoescape标志为 True，否则 LIKE 通配符字符%和_默认不会被转义。
  
• autoescape –
  布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中的所有出现的"%"、"_"和转义字符本身，假定比较值是一个字面字符串而不是 SQL 表达式。
  一个表达式如下：

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

• 将呈现为：

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

• 具有值:param为"foo/%bar"。
• escape –
  一个字符，当给定时将使用ESCAPE关键字来建立该字符作为转义字符。然后可以将该字符放在%和_之前，以允许它们作为自身而不是通配符字符。
  一个表达式如下：

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

• 将呈现为：

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

• 参数也可以与ColumnOperators.startswith.autoescape结合使用：

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

• 在上述情况下，给定的文字参数将在传递到数据库之前转换为"foo^%bar^^bat"。

另请参见

ColumnOperators.endswith()

ColumnOperators.contains()

ColumnOperators.like()

attribute timetuple: Literal[None] = None

继承自 ColumnOperators 的 ColumnOperators.timetuple 属性

Hack，允许在左侧比较 datetime 对象。

attribute unique: bool | None

Column.unique参数的值。

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

另请参见

Table.indexes

Table.constraints。

method unique_params(*optionaldict, **kwargs)

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

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

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

class sqlalchemy.schema.MetaData

一组Table对象及其关联的模式构造。

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

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

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

另请参阅

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

成员

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

类签名

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

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

创建一个新的 MetaData 对象。

参数：

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

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

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

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

• 新版本 1.3.0 中新增：- 添加了新的 %(column_0N_name)s、%(column_0_N_name)s 等相关标记，用于生成由给定约束引用的所有列的名称、键或标签的连接。
  另请参阅
  配置约束命名约定 - 详细的使用示例。

method clear() → None

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

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

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

默认为条件性操作，不会尝试重新创建已经存在于目标数据库中的表。

参数：

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

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

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

默认为条件性操作，不会尝试删除目标数据库中不存在的表。

参数：

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

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

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

自动在此 MetaData 中为数据库中任何尚未存在于 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，则反映ForeignKey对象位于每个Table中的Table对象。对于MetaData.reflect()，这将导致反映可能不在要反映的表列表中的相关表，例如，如果引用的表位于不同模式中或通过MetaData.reflect.only参数省略。当为 False 时，不会跟随ForeignKey对象到它们链接的Table，但是如果相关表也是无论如何将被反映的表列表的一部分，则在MetaData.reflect()操作完成后，ForeignKey对象仍将解析为其相关的Table。默认为 True。
  版本 1.3.0 中的新功能。
  另请参阅
  Table.resolve_fks
  
• **dialect_kwargs – 上述未提及的额外关键字参数是特定于方言的，并以_的形式传递。有关各个方言的文档参数的详细信息，请参阅 Dialects。
  

另请参阅

反射数据库对象

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

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

method remove(table: Table) → None

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

attribute sorted_tables

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

排序将会先放置具有依赖关系的Table对象，然后才是依赖对象本身，代表着它们可以被创建的顺序。要获取表被删除的顺序，请使用reversed() Python 内置函数。

警告

MetaData.sorted_tables属性本身无法自动解决表之间的依赖关系循环，这通常是由相互依赖的外键约束引起的。当检测到这些循环时，这些表的外键将被从排序考虑中省略。当这种情况发生时会发出警告，这将在未来版本中引发异常。不属于循环的表仍将按照依赖关系顺序返回。

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

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

另请参阅

sort_tables()

sort_tables_and_constraints()

MetaData.tables

Inspector.get_table_names()

Inspector.get_sorted_table_and_fkc_names()

attribute tables: util.FacadeDict[str, Table]

一个由Table对象组成的字典，按它们的名称或“表键”键控。

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

另请参阅

MetaData.sorted_tables

class sqlalchemy.schema.SchemaConst

一个枚举。

成员

BLANK_SCHEMA, NULL_UNSPECIFIED, RETAIN_SCHEMA

类签名

类sqlalchemy.schema.SchemaConst (enum.Enum)

attribute BLANK_SCHEMA = 2

表示一个Table或Sequence应该具有“None”作为其模式，即使父MetaData已指定了一个模式。

另请参阅

MetaData.schema

Table.schema

Sequence.schema

attribute NULL_UNSPECIFIED = 3

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

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

attribute RETAIN_SCHEMA = 1

表示Table、Sequence或在某些情况下表示ForeignKey对象的符号，在进行Table.to_metadata()操作时，应保留其已有的模式名称。

class sqlalchemy.schema.SchemaItem

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

成员

info

类签名

类sqlalchemy.schema.SchemaItem（sqlalchemy.sql.expression.SchemaEventTarget，sqlalchemy.sql.visitors.Visitable）

attribute info

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

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

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

提供一个代理Column，将充当专用的插入哨兵列，允许对不具有相应主键配置的表进行有效的批量插入，并确保按顺序进行 RETURNING 排序。

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

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

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

另请参阅

orm_insert_sentinel()

Column.insert_sentinel

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

配置哨兵列

新版本 2.0.10 中新增。

class sqlalchemy.schema.Table

表示数据库中的表。

例如：

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

Table 对象根据其名称和可选模式名称在给定的 MetaData 对象中构建一个独特的实例。使用相同的名称和相同的 MetaData 参数再次调用 Table 构造函数将返回相同的 Table 对象 - 这样，Table 构造函数就像一个注册函数。

另请参阅

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

成员

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

Table的构造函数。

参数：

• name –
  此表在数据库中表示的名称。
  表名，以及schema参数的值，形成一个键，唯一标识拥有的MetaData集合中的此Table。对具有相同名称、元数据和模式名称的Table进行的其他调用将返回相同的Table对象。
  不包含大写字符的名称将被视为不区分大小写的名称，并且除非它们是保留字或包含特殊字符，否则不会被引用。包含任何数量大写字符的名称被视为区分大小写的名称，并将被发送为引用。
  要为表名启用无条件引用，请在构造函数中指定标志quote=True，或使用quoted_name构造来指定名称。
  
• metadata – 一个包含此表的MetaData对象。元数据用作将此表与通过外键引用的其他表关联的关联点。它还可以用于将此表与特定的Connection或Engine关联起来。
  
• *args – 附加的位置参数主要用于添加包含在此表中的Column对象的列表。类似于 CREATE TABLE 语句的风格，其他SchemaItem构造可以在此处添加，包括PrimaryKeyConstraint和ForeignKeyConstraint。
  
• autoload_replace –
  默认为True；当与Table.extend_existing一起使用Table.autoload_with时，指示应该用从 autoload 过程中检索到的相同名称的列替换已存在的Table对象中存在的Column对象。当为False时，已存在的列将被省略不包括在反射过程中。
  请注意，此设置不会影响通过调用Table程序指定的Column对象；当Table.extend_existing为True时，这些Column对象将始终替换同名的现有列。
  另请参阅
  Table.autoload_with
Table.extend_existing
  
• autoload_with –
  一个Engine或Connection对象，或由inspect()针对其中一个返回的Inspector对象，其将反映此Table对象。当设置为非None值时，autoload 过程将在此表针对给定的引擎或连接上进行。
  另请参阅
  反映数据库对象
  DDLEvents.column_reflect()
  使用与数据库无关的类型进行反射
  
• extend_existing –
  当为True时，表示如果此Table已经存在于给定的MetaData中，则将构造函数中的进一步参数应用于现有的Table。
  如果未设置Table.extend_existing或Table.keep_existing，并且新Table的给定名称指的是目标MetaData集合中已经存在的Table，并且此Table指定了额外的列或其他构造或修改表状态的标志，将引发错误。这两个互斥标志的目的是指定在指定匹配现有Table但指定了其他构造的情况下应采取什么操作。
  Table.extend_existing也将与Table.autoload_with一起工作，针对数据库运行新的反射操作，即使目标MetaData中已经存在同名的Table；新反射的Column对象和其他选项将被添加到Table的状态中，可能会覆盖同名的现有列和选项。
  与Table.autoload_with一直如此，Column对象可以在同一Table构造函数中指定，这将优先考虑。下面，现有表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 对象，通过 ForeignKey 对象，当指定 Table.autoload_with 时。默认为 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的给定名称引用的Table已经存在于目标MetaData集合中，并且这个Table指定了额外的列或其他构造或修改表状态的标志，将引发错误。这两个互斥标志的目的是指定当指定一个与现有的Table匹配的Table时应该采取什么操作，而又指定了额外的构造。
  参见
  Table.extend_existing
  
• listeners –
  一个形如 (, ) 的元组列表，将在构造时传递给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时，表示这个 Table 必须已经存在于给定的MetaData集合中，否则会引发异常。
  
• prefixes – 在 CREATE TABLE 语句中在 CREATE 之后插入的字符串列表。它们将用空格分隔。
  
• quote –
  强制对这个表的名称进行引用，对应为True或False。当保持默认值None时，根据名称是否区分大小写（至少有一个大写字符的标识符被视为区分大小写），或者是否为保留字来引用列标识符。这个标志只需要强制引用一个 SQLAlchemy 方言不知道的保留字。
  注意
  将此标志设置为False将不会为表反射提供不区分大小写的行为；表反射将始终以区分大小写的方式搜索混合大小写名称。 在 SQLAlchemy 中，仅通过使用所有小写字符的名称来指定不区分大小写的名称。
  
• quote_schema – 与‘quote’相同，但适用于模式标识符。
  
• schema –
  此表的模式名称，如果该表位于引擎的数据库连接的默认选择模式之外的模式中，则此名称是必需的。 默认为None。
  如果此Table的所有者MetaData指定了自己的MetaData.schema参数，则如果此处的模式参数设置为None，则该模式名称将应用于此Table。 要在否则将使用所设置的模式的MetaData上指定空白模式名称的Table，请指定特殊符号BLANK_SCHEMA。
  模式名称的引号规则与name参数的引号规则相同，即针对保留字或区分大小写的名称应用引号； 要为模式名称启用无条件引号，请将quote_schema=True标志传递给构造函数，或使用quoted_name构造来指定名称。
  
• comment –
  可选字符串，将在表创建时渲染 SQL 注释。
  自版本 1.2 新增：在Table中添加了Table.comment参数。
  
• **kw – 未提及的其他关键字参数是特定于方言的，并以_的形式传递。 有关详细信息，请参阅个别方言的文档 Dialects。
  

method add_is_dependent_on(table: Table) → None

为此表添加一个“dependency”。

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

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

method alias(name: str | None = None, flat: bool = False) → NamedFromClause

继承自 FromClause.alias() 方法的 FromClause

返回此 FromClause 的别名。

例如：

a2 = some_table.alias('a2')

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

另请参阅

使用别名

alias()

method append_column(column: ColumnClause[Any], replace_existing: bool = False) → None

向此 Table 添加一个 Column。

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

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

参数：

replace_existing –

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

在 1.4.0 版中新增。

method append_constraint(constraint: Index | Constraint) → None

向此 Table 添加一个 Constraint。

这将使约束包含在任何将来的 CREATE TABLE 语句中，假设没有将特定的 DDL 创建事件与给定的 Constraint 对象关联。

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

classmethod argument_for(dialect_name, argument_name, default)

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

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

例如：

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

DialectKWArgs.argument_for() 方法是一种通过将额外参数添加到DefaultDialect.construct_arguments 字典中的一种方法来为每个参数添加额外参数的方法。此字典为代表方言的各种模式级别构造提供了接受的参数名称列表。

新的方言通常应该一次性指定该字典，作为方言类的数据成员。通常情况下，用于额外添加参数名称的用例是针对同时使用自定义编译方案的最终用户代码，该编译方案使用额外的参数。

参数：

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

attribute autoincrement_column

返回当前表示“自动增量”列的Column对象，如果没有，则返回 None。

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

从版本 2.0.4 开始新的。

另请参见

Column.autoincrement

attribute 

继承自 FromClause 属性的 FromClause.c

FromClause.columns 的同义词

返回：

一个 ColumnCollection

attribute columns

继承自 FromClause.columns 属性的 FromClause

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

columns 或 c 集合，是使用绑定到表或其他可选择的列构建 SQL 表达式的入口点：

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

返回：

一个 ColumnCollection 对象。

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 – 一个可以提供Dialect以生成Compiled对象的Connection或Engine。如果bind和dialect参数都被省略，将使用默认的 SQL 编译器。
  
• column_keys – 用于 INSERT 和 UPDATE 语句，应在编译语句的 VALUES 子句中出现的列名列表。如果为None，则渲染目标表对象的所有列。
  
• dialect – 一个可以生成Compiled对象的Dialect实例。此参数优先于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 constraints: Set[Constraint]

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

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

另请参阅

Table.constraints

Table.primary_key

Table.foreign_key_constraints

Table.indexes

Inspector

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

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

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

参数：

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

另请参阅

Selectable.exported_columns - 用于操作的ColumnCollection。

ColumnCollection.corresponding_column() - 实现方法。

method create(bind: _CreateDropBind, checkfirst: bool = False) → None

为此 Table 发出一个 CREATE 语句，使用给定的 Connection 或 Engine 进行连接。

请参阅

MetaData.create_all().

method delete() → Delete

继承自 TableClause.delete() 方法的 TableClause

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

例如：

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

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

attribute description

继承自 TableClause.description 属性的 TableClause

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 drop(bind: _CreateDropBind, checkfirst: bool = False) → None

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

另请参阅

MetaData.drop_all().

attribute entity_namespace

继承自 FromClause.entity_namespace 属性的 FromClause

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

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

stmt.filter_by(address='some address')

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

attribute exported_columns

继承自 FromClause.exported_columns 属性的 FromClause

代表此 Selectable 的“导出”列的 ColumnCollection。

FromClause 对象的“导出”列与 FromClause.columns 集合是同义词。

自版本 1.4 新增。

另请参阅

Selectable.exported_columns

SelectBase.exported_columns

attribute foreign_key_constraints

被此 Table 引用的 ForeignKeyConstraint 对象。

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

另请参阅

Table.constraints

Table.foreign_keys

Table.indexes

attribute foreign_keys

继承自 FromClause.foreign_keys 属性的 FromClause

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

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

另请参阅

Table.foreign_key_constraints

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

继承自 HasTraverseInternals.get_children() 方法的 HasTraverseInternals

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

这用于访问遍历。

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

attribute implicit_returning = False

继承自 TableClause.implicit_returning 属性的 TableClause

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

attribute indexes: Set[Index]

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

另请参阅

Inspector.get_indexes()

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

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

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

attribute inherit_cache: bool | None = None

继承自 HasCacheKey.inherit_cache 属性的 HasCacheKey 对象

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

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

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

另请参阅

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

method insert() → Insert

继承自 TableClause.insert() 方法的 TableClause 对象

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

例如：

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

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

method is_derived_from(fromclause: FromClause | None) → bool

继承自 FromClause.is_derived_from() 方法的 FromClause 对象

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

一个例子就是一个表的别名是从该表派生出来的。

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

返回此Table的‘key’。

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

attribute kwargs

继承自 DialectKWArgs.kwargs 属性的 DialectKWArgs

DialectKWArgs.dialect_kwargs的同义词。

method lateral(name: str | None = None) → LateralFromClause

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

返回此Selectable的 LATERAL 别名。

返回值是Lateral构造，也由顶级lateral()函数提供。

另请参阅

LATERAL correlation - 使用概述。

method 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

method params(*optionaldict, **kwargs)

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

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

返回此 ClauseElement 的副本，其中的 bindparam() 元素替换为给定字典中取出的值：

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

attribute primary_key

继承自 FromClause.primary_key 属性的 FromClause

返回这个 _selectable.FromClause 的主键组成的 Column 对象的可迭代集合。

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

method replace_selectable(old: FromClause, alias: Alias) → Self

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

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

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

attribute schema: str | None = None

继承自 FromClause.schema 属性的 FromClause

为此FromClause定义‘schema’属性。

对于大多数对象，这通常是None，除了Table的情况，其中它被视为Table.schema参数的值。

method select() → Select

继承自 FromClause.select() 方法的 FromClause

返回此FromClause的 SELECT。

例如：

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

另请参阅

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

method self_group(against: OperatorType | None = None) → ClauseElement

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

对这个 ClauseElement 进行“分组”。

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

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

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

method 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 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 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对象和该约束的现有“目标模式”。该函数应返回应应用的字符串模式名称。要重置模式为“none”，请返回符号BLANK_SCHEMA。要不进行更改，请返回None或RETAIN_SCHEMA。
  从版本 1.4.33 开始更改：referred_schema_fn函数可能返回BLANK_SCHEMA或RETAIN_SCHEMA符号。
  例如：

def referred_schema_fn(table, to_schema,
                                constraint, referred_schema):
    if referred_schema == 'base_tables':
        return referred_schema
    else:
        return to_schema
new_table = table.to_metadata(m2, schema="alt_schema",
                        referred_schema_fn=referred_schema_fn)

• name – 可选的字符串名称，指示目标表名称。如果未指定或为 None，则保留表名称。这允许将 Table 复制到具有新名称的相同 MetaData 目标。
  

method 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() 获取完整描述。

method unique_params(*optionaldict, **kwargs)

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

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

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

method update() → Update

继承自 TableClause.update() 方法的 TableClause

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

例如：

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

查看 update() 获取参数和使用信息。

访问表和列

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 的最初迁移工具，现在已被视为过时。

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