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

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

成员

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

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

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

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

另请参阅

orm_insert_sentinel()

Column.insert_sentinel

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

配置 Sentinel 列

新版本中新增功能 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 构造函数充当注册函数。

请参阅

描述数据库的元数据 - 数据库元数据介绍

成员

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 参数的值一起形成一个键，唯一标识此 Table 在所属的 MetaData 集合中。对具有相同名称、元数据和模式名称的 Table 的其他调用将返回相同的 Table 对象。
  不含大写字符的名称将被视为大小写不敏感的名称，并且除非它们是保留字或包含特殊字符，否则不会被引用。任何数量的大写字符被视为区分大小写的名称，并将作为引号发送。
  要为表名启用无条件引用，请在构造函数中指定标志 quote=True，或使用 quoted_name 构造指定名称。
  
• metadata – 一个 MetaData 对象，将包含此表。元数据用作将此表与其他通过外键引用的表关联的点。它也可以用于将此表与特定的 Connection 或 Engine 关联起来。
  
• *args – 主要用于添加此表中包含的 Column 对象列表的其他位置参数。类似于 CREATE TABLE 语句的风格，其他 SchemaItem 构造可以在此处添加，包括 PrimaryKeyConstraint 和 ForeignKeyConstraint。
  
• autoload_replace –
  默认为 True；与 Table.extend_existing 结合使用 Table.autoload_with 时，指示已存在的 Table 对象中的 Column 对象应该被从 autoload 过程中检索到的同名列替换。当 False 时，已存在的列将被从反射过程中省略。
  请注意，此设置不会影响程序化指定的 Column 对象，在自动加载时也会替换具有相同名称的现有列，当 Table.extend_existing 为 True 时。
  另请参见
  Table.autoload_with
Table.extend_existing
  
• autoload_with –
  一个 Engine 或 Connection 对象，或者通过 inspect() 对其进行检查后返回的 Inspector 对象，其中此 Table 对象将被反射。当设置为非 None 值时，将对此表针对给定引擎或连接进行自动加载。
  另请参见
  反射数据库对象
  DDLEvents.column_reflect()
  使用数据库无关类型进行反射
  
• extend_existing –
  当设为True时，表示如果此 Table 已经存在于给定的 MetaData 中，则将构造函数中的进一步参数应用于现有的 Table。
  如果未设置 Table.extend_existing 或 Table.keep_existing，并且新 Table 的给定名称引用的是已经存在于目标 MetaData 集合中的 Table，并且此 Table 指定了额外的列或其他结构或修改表状态的标志，那么将引发错误。这两个互斥标志的目的是指定当指定与现有 Table 匹配的 Table 时应采取的操作，但指定了其他构造。
  Table.extend_existing - Table.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_with属性
  Table.autoload_replace - Table.autoload_replace属性
  Table.keep_existing - Table.keep_existing属性
• implicit_returning – implicit_returning属性
  默认为 True - 表示返回值可以使用，通常由 ORM 使用，以便在支持 RETURNING 的后端上获取服务器生成的值，例如主键值和服务器端默认值。
  在现代 SQLAlchemy 中，通常没有理由修改此设置，除了一些特定于后端的情况（有关一个这样的示例，请参见 SQL Server 方言文档中的 Triggers）。
  
• include_columns – include_columns属性 - 一个字符串列表，指示要通过autoload操作加载的列的子集；不在此列表中的表列将不会在生成的Table对象上表示。默认为None，表示应反映所有列。
  
• resolve_fks – resolve_fks属性
  是否反映与此对象相关的Table对象，当指定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，而不会再次应用任何声明（特别是约束）。
  如果未设置Table.extend_existing或Table.keep_existing，并且新Table的给定名称指的是目标MetaData集合中已经存在的一个Table，并且这个Table指定了额外的列或其他构造或修改表状态的标志，将会引发错误。这两个互斥的标志的目的是指定当指定一个与现有Table匹配的Table时应采取的操作，但指定了额外的构造。
  另请参阅
  Table.extend_existing
  
• listeners –
  一个形如(<eventname>, <fn>)的元组列表，将在构建时传递给listen()。这个替代的钩子用于在“autoload”过程开始之前建立一个特定于这个Table的监听器函数。历史上，这是用于与DDLEvents.column_reflect()事件一起使用的，但请注意，现在可以直接将此事件钩子与MetaData对象关联起来：

def listen_for_reflect(table, column_info):
    "handle the column reflection event"
    # ...
t = Table(
    'sometable',
    autoload_with=engine,
    listeners=[
        ('column_reflect', listen_for_reflect)
    ])

• 另请参阅
  DDLEvents.column_reflect()
• must_exist – 当为True时，表示这个 Table 必须已经存在于给定的MetaData集合中，否则将引发异常。
  
• prefixes – 一个字符串列表，插入在 CREATE TABLE 语句中 CREATE 后面。它们将用空格分隔。
  
• quote –
  强制引用此表的名称打开或关闭，对应为True或False。当保持其默认值None时，根据名称是否区分大小写（至少有一个大写字符的标识符被视为区分大小写），或者它是否是保留字来引用列标识符。只有在需要强制引用 SQLAlchemy 方言不知道的保留字时才需要此标志。
  注意
  将此标志设置为 False 将不会为表反射提供不区分大小写的行为；表反射将始终以区分大小写的方式搜索混合大小写名称。 SQLAlchemy 中仅通过使用所有小写字符的名称来指定不区分大小写的名称。
  
• quote_schema - 与 ‘quote’ 相同，但适用于模式标识符。
  
• schema -
  此表的模式名称，如果表位于引擎的数据库连接的默认选定模式之外的模式中，则需要。 默认为 None。
  如果此 Table 的拥有者 MetaData 指定了自己的 MetaData.schema 参数，则如果此处的模式参数设置为 None，则将该模式名称应用于此 Table。 要在否则使用所设置的模式的拥有者 MetaData 的 Table 上设置空白模式名称，请指定特殊符号 BLANK_SCHEMA。
  模式名称的引用规则与 name 参数的规则相同，即对保留字或区分大小写的名称应用引用； 要为模式名称启用无条件引用，请在构造函数中指定标志 quote_schema=True，或使用 quoted_name 结构来指定名称。
  
• comment -
  可选字符串，将在表创建时呈现 SQL 注释。
  新版本 1.2 中：添加了 Table.comment 参数到 Table。
  
• **kw - 上面未提及的附加关键字参数是特定于方言的，并以 <dialectname>_<argname> 的形式传递。 有关有关个别方言的文档中记录的参数的详细信息，请参阅 方言 中的个别方言的文档。
  

method add_is_dependent_on(table: Table) → None

为此表添加一个‘依赖’。

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

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

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 还提供了当调用时可以生成此 SQL 的AddConstraint构造。

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 – 参数的默认值。
  

attribute autoincrement_column

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

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

版本 2.0.4 中的新功能。

另请参阅

Column.autoincrement

attribute c

继承自 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 – 一个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 constraints: Set[Constraint]

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

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

另请参阅

Table.constraints

Table.primary_key

Table.foreign_key_constraints

Table.indexes

Inspector

method 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

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

请参阅

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

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

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

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

请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute dialect_options

继承自 DialectKWArgs.dialect_options 属性的 DialectKWArgs

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

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

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

版本 0.9.2 中的新功能。

请参见

DialectKWArgs.dialect_kwargs - 平面字典形式

method 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

ForeignKeyConstraint 对象是由这个 Table 引用的。

此列表是从当前关联的 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，只是还会发出警告。

这个标志可以在特定类上设置为True，如果对应于对象的 SQL 不基于本类的局部属性而变化，而不是基于其超类。

请参阅

为自定义结构启用缓存支持 - 设置第三方或用户定义的 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 关联 - 用法概述。

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

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

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

例如：

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

上述相当于：

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

参数：

• right – 连接的右侧；这是任何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 的 Immutable.params() 方法

返回一个副本，并用 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

将所有 FromClause 中的 ‘old’ 替换为给定的 Alias 对象，返回此 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()构造用来放置到另一个select()的 FROM 子句中时。(注意，子查询通常应该使用Select.alias()方法创建，因为许多平台要求嵌套的 SELECT 语句必须具名)。

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

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

method table_valued() → TableValuedColumn[Any]

继承自 NamedFromClause 的 NamedFromClause.table_valued() 方法

返回这个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的 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对象以及该约束的现有“目标模式”。该函数应返回应用的字符串模式名称。要将模式重置为“无”，请返回符号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()获取参数和用法信息。