SqlAlchemy 2.0 中文文档（四十）（5）

SqlAlchemy 2.0 中文文档（四十）（4）https://developer.aliyun.com/article/1563003

约束 API

class sqlalchemy.schema.Constraint

表级 SQL 约束。

Constraint作为可以与Table对象关联的一系列约束对象的基类，包括PrimaryKeyConstraint、ForeignKeyConstraint、UniqueConstraint和CheckConstraint。

成员

init(), argument_for(), copy(), ddl_if(), dialect_kwargs, dialect_options, info, kwargs

类签名

类 sqlalchemy.schema.Constraint (sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.schema.HasConditionalDDL, sqlalchemy.schema.SchemaItem)

method __init__(name: _ConstraintNameArgument = None, deferrable: bool | None = None, initially: str | None = None, info: _InfoType | None = None, comment: str | None = None, _create_rule: Any | None = None, _type_bound: bool = False, **dialect_kw: Any) → None

创建一个 SQL 约束。

参数：

• name – 可选的，这个 Constraint 在数据库中的名称。
  
• deferrable – 可选布尔值。如果设置，当为这个约束发出 DDL 时，会发出 DEFERRABLE 或 NOT DEFERRABLE。
  
• initially – 可选字符串。如果设置，当为这个约束发出 DDL 时，会发出 INITIALLY 。
  
• info – 可选的数据字典，将被填充到此对象的 SchemaItem.info 属性中。
  
• comment –
  在外键约束创建时渲染 SQL 注释的可选字符串。

新版本 2.0 中新增。

• **dialect_kw – 附加的关键字参数是方言特定的，并以 _ 的形式传递。有关每个方言的文档参数的详细信息，请参见 Dialects 中的文档。
  
• _create_rule – 由一些也创建约束的数据类型内部使用。
  
• _type_bound – 用于内部指示此约束与特定数据类型相关联。
  

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 copy(**kw: Any) → Self

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

method ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

继承自 HasConditionalDDL.ddl_if() 方法的 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式类似于ExecutableDDLElement.execute_if()可调用对象，但增加了一个特性，即可以在 DDL 编译阶段为CreateTable等结构检查条件。HasConditionalDDL.ddl_if()目前适用于Index结构以及所有Constraint结构。

参数：

• dialect – 方言的字符串名称，或者表示多个方言类型的字符串名称元组。
  
• callable_ – 使用与ExecutableDDLElement.execute_if.callable_描述的相同形式构造的可调用对象。
  
• state – 如果存在，则将传递给可调用对象的任意对象。
  

2.0 版中的新功能。

另请参阅

控制约束和索引的 DDL 生成 - 背景和使用示例

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 - 扁平字典形式

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

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

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

attribute kwargs

继承自 DialectKWArgs.kwargs 属性的 DialectKWArgs

一个与DialectKWArgs.dialect_kwargs 同义的词语。

class sqlalchemy.schema.ColumnCollectionMixin

一个Column对象的ColumnCollection。

此集合代表此对象引用的列。

class sqlalchemy.schema.ColumnCollectionConstraint

代理列集合的约束。

成员

init(), argument_for(), columns, contains_column(), copy(), ddl_if(), dialect_kwargs, dialect_options, info, kwargs

类签名

class sqlalchemy.schema.ColumnCollectionConstraint (sqlalchemy.schema.ColumnCollectionMixin, sqlalchemy.schema.Constraint)

method __init__(*columns: _DDLColumnArgument, name: _ConstraintNameArgument = None, deferrable: bool | None = None, initially: str | None = None, info: _InfoType | None = None, _autoattach: bool = True, _column_flag: bool = False, _gather_expressions: List[_DDLColumnArgument] | None = None, **dialect_kw: Any) → None

参数：

• *columns – 一系列列名或列对象。
  
• name – 可选，此约束在数据库中的名称。
  
• deferrable – 可选布尔值。如果设置，当为此约束发���DDL 时，发出 DEFERRABLE 或 NOT DEFERRABLE。
  
• initially – 可选字符串。如果设置，当为此约束发出 DDL 时，发出 INITIALLY 。
  
• **dialect_kw – 其他关键字参数，包括方言特定参数，将传播到Constraint超类。
  

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 columns: ReadOnlyColumnCollection[str, Column[Any]]

继承自 ColumnCollectionMixin.columns 属性，来自于 ColumnCollectionMixin

一个 ColumnCollection 表示这个约束的列集合。

method contains_column(col: Column[Any]) → bool

如果此约束包含给定的列，则返回 True。

注意，此对象还包含一个属性 .columns，它是一个 ColumnCollection，包含了 Column 对象。

method copy(*, target_table: Table | None = None, **kw: Any) → ColumnCollectionConstraint

从版本 1.4 开始不推荐使用：ColumnCollectionConstraint.copy() 方法已弃用，将在未来的版本中删除。

method ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

继承自 HasConditionalDDL.ddl_if() 方法，来自于 HasConditionalDDL

为此模式项应用条件性 DDL 规则。

这些规则的工作方式类似于 ExecutableDDLElement.execute_if() 可调用对象，额外的功能是可以在 DDL 编译阶段检查条件，例如 CreateTable 这样的结构。 HasConditionalDDL.ddl_if() 目前也适用于 Index 结构以及所有 Constraint 结构。

参数：

• dialect – 方言的字符串名称，或指示多个方言类型的字符串名称的元组。
  
• callable_ – 一个可调用对象，其构造方式与 ExecutableDDLElement.execute_if.callable_ 中描述的形式相同。
  
• state – 如果存在，将传递给可调用对象的任意对象。
  

新版本 2.0 中新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

attribute dialect_kwargs

从 DialectKWArgs.dialect_kwargs 属性继承

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

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

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

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute dialect_options

从 DialectKWArgs.dialect_options 属性继承

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

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

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

新版本 0.9.2 中新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

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

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

attribute kwargs

继承自 DialectKWArgs.kwargs 属性的 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

class sqlalchemy.schema.CheckConstraint

表或列级别的 CHECK 约束。

可以包含在表或列的定义中。

成员

init(), argument_for(), columns, contains_column(), copy(), ddl_if(), dialect_kwargs, dialect_options, info, kwargs

类签名

类 sqlalchemy.schema.CheckConstraint (sqlalchemy.schema.ColumnCollectionConstraint)

method __init__(sqltext: _TextCoercedExpressionArgument[Any], name: _ConstraintNameArgument = None, deferrable: bool | None = None, initially: str | None = None, table: Table | None = None, info: _InfoType | None = None, _create_rule: Any | None = None, _autoattach: bool = True, _type_bound: bool = False, **dialect_kw: Any) → None

构造一个 CHECK 约束。

参数：

• sqltext –
  包含约束定义的字符串，将直接使用，或者是一个 SQL 表达式构造。如果给定为字符串，则对象将转换为 text() 对象。如果文本字符串包含冒号字符，请使用反斜杠进行转义：

CheckConstraint(r"foo ~ E'a(?\:b|c)d")

• 警告
  CheckConstraint 的CheckConstraint.sqltext 参数可以作为 Python 字符串参数传递，该字符串参数将被视为可信任的 SQL 文本并按照给定的方式呈现。不要将不受信任的输入传递给此参数。
• name – 可选，约束的数据库中名称。
  
• deferrable – 可选布尔值。如果设置，则在为此约束发出 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。
  
• initially – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 INITIALLY 。
  
• info – 可选数据字典，将填充到此对象的SchemaItem.info属性中。
  

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 columns: ReadOnlyColumnCollection[str, Column[Any]]

继承自 ColumnCollectionMixin 的 ColumnCollectionMixin.columns 属性

表示此约束的列集合。

method contains_column(col: Column[Any]) → bool

继承自 ColumnCollectionConstraint 的 ColumnCollectionConstraint.contains_column() 方法

如果此约束包含给定列，则返回 True。

请注意，此对象还包含一个属性 .columns，它是 Column 对象的 ColumnCollection。

method copy(*, target_table: Table | None = None, **kw: Any) → CheckConstraint

自版本 1.4 弃用：CheckConstraint.copy() 方法已弃用，将在未来的版本中移除。

method ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

继承自 HasConditionalDDL 的 HasConditionalDDL.ddl_if() 方法

将条件 DDL 规则应用于此模式项。

这些规则的工作方式与 ExecutableDDLElement.execute_if() 可调用对象类似，额外的功能是可以在 DDL 编译阶段检查标准，例如 CreateTable 构造。 HasConditionalDDL.ddl_if() 目前也适用于 Index 构造以及所有 Constraint 构造。

参数：

• dialect – 方言的字符串名称，或字符串名称的元组，以指示多个方言类型。
  
• callable_ – 使用与ExecutableDDLElement.execute_if.callable_中描述的相同形式构建的可调用对象。
  
• state – 将传递给可调用对象的任意对象（如果存在）。
  

自版本 2.0 新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

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 - 扁平字典形式

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

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

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

attribute kwargs

继承自 DialectKWArgs.kwargs 属性的 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

class sqlalchemy.schema.ForeignKey

定义两列之间的依赖关系。

ForeignKey 被指定为 Column 对象的参数，例如：

t = Table("remote_table", metadata,
    Column("remote_id", ForeignKey("main_table.id"))
)

请注意，ForeignKey 仅是一个标记对象，定义了两列之间的依赖关系。在所有情况下，实际约束都由 ForeignKeyConstraint 对象表示。当ForeignKey与一个 Column 相关联，而这个列又与一个 Table 相关联时，此对象将自动生成。反之，当 ForeignKeyConstraint 应用于一个 Table 时，ForeignKey 标记将自动在每个相关联的 Column 上存在，这些列也与约束对象相关联。

请注意，您不能使用 ForeignKey 对象定义“复合”外键约束，即多个父/子列的分组约束。要定义此分组，必须使用 ForeignKeyConstraint 对象，并应用于 Table。相关联的ForeignKey对象将自动创建。

与单个 Column 对象相关联的 ForeignKey 对象可在该列的 foreign_keys 集合中找到。

关于外键配置的更多示例在定义外键中。

成员

init(), argument_for(), column, copy(), dialect_kwargs, dialect_options, get_referent(), info, kwargs, references(), target_fullname

类签名

类 sqlalchemy.schema.ForeignKey (sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.schema.SchemaItem)

method __init__(column: _DDLColumnArgument, _constraint: ForeignKeyConstraint | None = None, use_alter: bool = False, name: _ConstraintNameArgument = None, onupdate: str | None = None, ondelete: str | None = None, deferrable: bool | None = None, initially: str | None = None, link_to_name: bool = False, match: str | None = None, info: _InfoType | None = None, comment: str | None = None, _unresolvable: bool = False, **dialect_kw: Any)

构建一个列级的外键。

构造时生成 ForeignKey 对象，与父 Table 对象的约束集合关联的 ForeignKeyConstraint。

参数：

• column – 键关系的单个目标列。Column 对象或列名称字符串：tablename.columnkey 或 schema.tablename.columnkey。columnkey 是分配给列的 key（默认为列名称本身），除非 link_to_name 为 True，此时使用列的呈现名称。
  
• name – 可选字符串。如果未提供约束，则键的数据库名称。
  
• onupdate – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 ON UPDATE 。典型值包括 CASCADE、DELETE 和 RESTRICT。
  
• ondelete – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 ON DELETE 。典型值包括 CASCADE、DELETE 和 RESTRICT。
  
• deferrable – 可选布尔值。如果设置，则在为此约束发出 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。
  
• initially – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 INITIALLY 。
  
• link_to_name – 如果为 True，则 column 中给定的字符串名称是引用列的呈现名称，而不是其本地分配的 key。
  
• use_alter –
  传递给底层 ForeignKeyConstraint，以指示约束应从 CREATE TABLE/ DROP TABLE 语句外部生成/删除。有关详细描述，请参阅 ForeignKeyConstraint.use_alter。
  另请参阅
  ForeignKeyConstraint.use_alter
  通过 ALTER 创建/删除外键约束
  
• match – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 MATCH 。典型值包括 SIMPLE、PARTIAL 和 FULL。
  
• info – 可选数据字典，将填充到此对象的 SchemaItem.info 属性中。
  
• comment –
  可选字符串，将在创建外键约束时呈现 SQL 注释。

版本 2.0 中的新内容。

• **dialect_kw – 附加的关键字参数是方言特定的，并以 _ 的形式传递。这些参数最终由相应的 ForeignKeyConstraint 处理。有关文档化参数的详细信息，请参阅 Dialects 中关于各个方言的文档。
  

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 column

返回由此 ForeignKey 引用的目标 Column。

如果没有建立目标列，则会引发异常。

method copy(*, schema: str | None = None, **kw: Any) → ForeignKey

自版本 1.4 起弃用：ForeignKey.copy() 方法已弃用，并将在未来版本中移除。

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 get_referent(table: FromClause) → Column[Any] | None

返回由此 ForeignKey 引用的给定 Table（或任何 FromClause）中的 Column。

如果此 ForeignKey 未引用给定的 Table，则返回 None。

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

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

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

attribute kwargs

从 DialectKWArgs.kwargs 属性继承 DialectKWArgs

DialectKWArgs.dialect_kwargs的同义词。

method references(table: Table) → bool

如果给定的Table被此ForeignKey引用，则返回 True。

attribute target_fullname

为此ForeignKey返回基于字符串的“列规范”。

这通常是传递给对象构造函数的基于字符串的“tablename.colname”参数的等效值。

class sqlalchemy.schema.ForeignKeyConstraint

表级外键约束。

定义单列或复合外键引用约束。对于简单的、单列外键，向Column的定义中添加一个ForeignKey是一个简写等效于未命名的、单列ForeignKeyConstraint。

外键配置示例在定义外键中。

成员

init(), argument_for(), column_keys, columns,  contains_column(), copy(), ddl_if(), dialect_kwargs, dialect_options,  elements, info, kwargs, referred_table

类签名

类sqlalchemy.schema.ForeignKeyConstraint（sqlalchemy.schema.ColumnCollectionConstraint）

method __init__(columns: _typing_Sequence[_DDLColumnArgument], refcolumns: _typing_Sequence[_DDLColumnArgument], name: _ConstraintNameArgument = None, onupdate: str | None = None, ondelete: str | None = None, deferrable: bool | None = None, initially: str | None = None, use_alter: bool = False, link_to_name: bool = False, match: str | None = None, table: Table | None = None, info: _InfoType | None = None, comment: str | None = None, **dialect_kw: Any) → None

构造一个支持复合的外键。

参数：

• columns – 本地列名称的序列。这些命名列必须在父表中定义并存在。除非 link_to_name 为 True，否则名称应与每个列（默认为名称）给定的 key 匹配。
  
• refcolumns – 外键列名称或 Column 对象的序列。这些列必须全部位于同一个表中。
  
• name – 可选项，键的数据库内名称。
  
• onupdate – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 ON UPDATE 。典型值包括 CASCADE、DELETE 和 RESTRICT。
  
• ondelete – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 ON DELETE 。典型值包括 CASCADE、DELETE 和 RESTRICT。
  
• deferrable – 可选布尔值。如果设置，则在发出 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。
  
• initially – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 INITIALLY 。
  
• link_to_name – 如果为 True，则 column 中给定的字符串名称是引用列的渲染名称，而不是其在本地分配的 key。
  
• use_alter –
  如果为 True，则不会将此约束的 DDL 作为 CREATE TABLE 定义的一部分发出。相反，在完整的表集合创建之后，通过 ALTER TABLE 语句生成它，并在删除完整的表集合之前通过 ALTER TABLE 语句将其删除。
  使用 ForeignKeyConstraint.use_alter 特别适用于两个或多个表在相互依赖的外键约束关系中建立的情况；但是，MetaData.create_all() 和 MetaData.drop_all() 方法将自动执行此解析，因此通常不需要此标志。
  另请参阅
  通过 ALTER 创建/删除外键约束
  
• match – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 MATCH 。典型值包括 SIMPLE、PARTIAL 和 FULL。
  
• info – 将填充到此对象的 SchemaItem.info 属性中的可选数据字典。
  
• comment –
  在外键约束创建时渲染一个 SQL 注释的可选字符串。

在 2.0 版中新增。

• **dialect_kw – 额外的关键字参数是方言特定的，并以 <方言名称>_<参数名称> 的形式传递。有关文档化参数的详细信息，请参阅方言中有关各个方言的文档。
  

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 column_keys

返回一个字符串键列表，表示此ForeignKeyConstraint中的本地列。

此列表是发送到ForeignKeyConstraint构造函数的原始字符串参数，或者如果约束已使用Column对象初始化，则是每个元素的字符串.key。

attribute columns: ReadOnlyColumnCollection[str, Column[Any]]

继承自 ColumnCollectionMixin.columns 属性

代表此约束的ColumnCollection表示列的集合。

method contains_column(col: Column[Any]) → bool

继承自 ColumnCollectionConstraint.contains_column() 方法的 ColumnCollectionConstraint

如果此约束包含给定列，则返回 True。

请注意，这个对象还包含一个属性.columns，它是一个ColumnCollection对象的集合，其中包含Column对象。

method copy(*, schema: str | None = None, target_table: Table | None = None, **kw: Any) → ForeignKeyConstraint

自版本 1.4 弃用：ForeignKeyConstraint.copy()方法已弃用，并将在将来的版本中移除。

method ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

继承自 HasConditionalDDL.ddl_if() 方法的 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式类似于ExecutableDDLElement.execute_if()可调用对象，只是增加了一个特性，即在 DDL 编译阶段可以检查条件，例如CreateTable构造。HasConditionalDDL.ddl_if()当前还适用于Index构造以及所有Constraint构造。

参数：

• dialect – 方言的字符串名称，或者一个字符串名称的元组，表示多个方言类型。
  
• callable_ – 使用与ExecutableDDLElement.execute_if.callable_描述的相同形式构造的可调用对象。
  
• state – 任意的对象，如果存在，将传递给可调用对象。
  

从版本 2.0 开始新添加。

另请参阅

控制约束和索引的 DDL 生成 - 背景和使用示例

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 - 平面字典形式

attribute elements: List[ForeignKey]

一系列ForeignKey对象。

每个ForeignKey代表单个引用列/被引用列对。

此集合旨在为只读。

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

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

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

attribute kwargs

继承自 DialectKWArgs.kwargs 属性，属于 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

attribute referred_table

此 ForeignKeyConstraint 引用的 Table 对象。

这是一个动态计算的属性，如果约束和/或父表尚未与包含所引用表的元数据集关联，则可能不可用。

class sqlalchemy.schema.HasConditionalDDL

定义一个包含 HasConditionalDDL.ddl_if() 方法的类，允许对 DDL 进行条件渲染。

目前适用于约束和索引。

成员

ddl_if()

版本 2.0 中新增。

method ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

将一个条件 DDL 规则应用到此模式项。

这些规则的工作方式与 ExecutableDDLElement.execute_if() 可调用对象类似，但增加了一个功能，即可以在 DDL 编译阶段检查条件，例如 CreateTable。 HasConditionalDDL.ddl_if() 目前也适用于 Index 构造以及所有 Constraint 构造。

参数：

• dialect – 方言的字符串名称，或字符串名称的元组，表示多个方言类型。
  
• callable_ – 使用与 ExecutableDDLElement.execute_if.callable_ 描述的形式构建的可调用对象。
  
• state – 如果存在，将传递给可调用对象的任意对象。
  

版本 2.0 中新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和使用示例

class sqlalchemy.schema.PrimaryKeyConstraint

表级主键约束。

PrimaryKeyConstraint 对象会自动出现在任何 Table 对象上；它被分配一组与标记为 Column.primary_key 标志相对应的 Column 对象：

>>> my_table = Table('mytable', metadata,
...                 Column('id', Integer, primary_key=True),
...                 Column('version_id', Integer, primary_key=True),
...                 Column('data', String(50))
...     )
>>> my_table.primary_key
PrimaryKeyConstraint(
 Column('id', Integer(), table=<mytable>,
 primary_key=True, nullable=False),
 Column('version_id', Integer(), table=<mytable>,
 primary_key=True, nullable=False)
)

Table 的主键也可以通过显式使用 PrimaryKeyConstraint 对象来指定；在这种用法模式下，“约束”的“名称”也可以指定，以及方言可能识别的其他选项：

my_table = Table('mytable', metadata,
            Column('id', Integer),
            Column('version_id', Integer),
            Column('data', String(50)),
            PrimaryKeyConstraint('id', 'version_id',
                                 name='mytable_pk')
        )

两种列规范样式通常不应混合使用。如果 PrimaryKeyConstraint 中存在的列与标记为 primary_key=True 的列不匹配，则会发出警告，如果两者都存在；在这种情况下，列严格来自 PrimaryKeyConstraint 声明，并且其他标记为 primary_key=True 的列将被忽略。这种行为旨在与先前的行为向后兼容。

对于需要在 PrimaryKeyConstraint 上指定特定选项的用例，但仍然希望使用 primary_key=True 标志的常规样式的情况，可以指定一个空的 PrimaryKeyConstraint，它将从基于标志的 Table 中采用主键列集合：

my_table = Table('mytable', metadata,
            Column('id', Integer, primary_key=True),
            Column('version_id', Integer, primary_key=True),
            Column('data', String(50)),
            PrimaryKeyConstraint(name='mytable_pk',
                                 mssql_clustered=True)
        )

成员

argument_for(), columns, contains_column(), copy(), ddl_if(), dialect_kwargs, dialect_options, info, kwargs

类签名

类 sqlalchemy.schema.PrimaryKeyConstraint（sqlalchemy.schema.ColumnCollectionConstraint）

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 columns: ReadOnlyColumnCollection[str, Column[Any]]

继承自 ColumnCollectionMixin.columns 属性的 ColumnCollectionMixin

表示此约束的列集合的 ColumnCollection。

method contains_column(col: Column[Any]) → bool

继承自 ColumnCollectionConstraint.contains_column() 方法的 ColumnCollectionConstraint

如果此约束包含给定列，则返回 True。

请注意，此对象还包含一个名为.columns的属性，它是Column对象的ColumnCollection。

method copy(*, target_table: Table | None = None, **kw: Any) → ColumnCollectionConstraint

继承自 ColumnCollectionConstraint.copy() 方法的 ColumnCollectionConstraint

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

method ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

继承自 HasConditionalDDL.ddl_if() 方法的 HasConditionalDDL

对此模式项应用条件 DDL 规则。

这些规则的工作方式类似于ExecutableDDLElement.execute_if()可调用对象，额外的特性是可以在 DDL 编译阶段检查条件，例如CreateTable这样的构造函数。HasConditionalDDL.ddl_if()目前也适用于Index构造以及所有Constraint构造。

参数：

• dialect – 方言的字符串名称，或表示多个方言类型的字符串名称元组。
  
• callable_ – 使用与ExecutableDDLElement.execute_if.callable_中描述的相同形式构造的可调用对象。
  
• state – 如果存在，将传递给可调用对象的任意对象。
  

从版本 2.0 开始新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和使用示例

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 - 平面字典形式

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

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

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

attribute kwargs

继承自 DialectKWArgs.kwargs 属性的 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

class sqlalchemy.schema.UniqueConstraint

表级别的唯一约束。

定义单列或复合唯一约束。对于简单的单列约束，将unique=True添加到Column定义中相当于未命名的单列 UniqueConstraint 的简写等效形式。

成员

init(), argument_for(), columns, contains_column(), copy(), ddl_if(), dialect_kwargs, dialect_options, info, kwargs

类签名

类sqlalchemy.schema.UniqueConstraint (sqlalchemy.schema.ColumnCollectionConstraint)

method __init__(*columns: _DDLColumnArgument, name: _ConstraintNameArgument = None, deferrable: bool | None = None, initially: str | None = None, info: _InfoType | None = None, _autoattach: bool = True, _column_flag: bool = False, _gather_expressions: List[_DDLColumnArgument] | None = None, **dialect_kw: Any) → None

继承自 sqlalchemy.schema.ColumnCollectionConstraint.__init__ 方法的 ColumnCollectionConstraint

参数：

• *columns – 列名或列对象的序列。
  
• name – 可选，此约束的数据库中的名称。
  
• deferrable – 可选布尔值。 如果设置，为此约束发出 DEFERRABLE 或 NOT DEFERRABLE。
  
• initially – 可选字符串。 如果设置，发出 INITIALLY when 为此约束发出 DDL。
  
• **dialect_kw – 其他关键字参数，包括方言特定参数，将传递给Constraint超类。
  

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 columns: ReadOnlyColumnCollection[str, Column[Any]]

从 ColumnCollectionMixin 的 .columns 属性继承

代表此约束的一组列的 ColumnCollection。

method contains_column(col: Column[Any]) → bool

从 ColumnCollectionConstraint 的 ColumnCollectionConstraint.contains_column() 方法继承

如果此约束包含给定列，则返回 True。

请注意，此对象还包含一个名为.columns的属性，它是 Column 对象的 ColumnCollection。

method copy(*, target_table: Table | None = None, **kw: Any) → ColumnCollectionConstraint

从 ColumnCollectionConstraint 的 ColumnCollectionConstraint.copy() 方法继承

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

method ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

从 HasConditionalDDL 的 HasConditionalDDL.ddl_if() 方法继承

对此模式项目应用条件 DDL 规则。

这些规则的工作方式类似于ExecutableDDLElement.execute_if()可调用对象，额外的特性是在 DDL 编译阶段可以检查条件，例如CreateTable构造中。HasConditionalDDL.ddl_if() 目前也适用于Index构造以及所有Constraint构造。

参数：

• dialect – 方言的字符串名称，或者字符串名称的元组，表示多个方言类型。
  
• callable_ – 一个可调用对象，其构造方式与ExecutableDDLElement.execute_if.callable_中描述的形式相同。
  
• state – 任意对象，如果存在将传递给可调用对象。
  

新版本 2.0。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

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

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

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

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

attribute kwargs

继承自 DialectKWArgs.kwargs 属性的 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

function sqlalchemy.schema.conv(value: str, quote: bool | None = None) → Any

标记一个字符串，指示名称已经通过命名约定转换。

这是一个字符串子类，表示不应再受任何其他命名约定影响的名称。

例如 当我们使用以下命名约定创建 Constraint 时：

m = MetaData(naming_convention={
    "ck": "ck_%(table_name)s_%(constraint_name)s"
})
t = Table('t', m, Column('x', Integer),
                CheckConstraint('x > 5', name='x5'))

上述约束的名称将呈现为 "ck_t_x5"。即，现有名称 x5 被用作命名约定中的 constraint_name 令牌。

在某些情况下，例如在迁移脚本中，我们可能会渲染上述 CheckConstraint 的名称已经被转换了。为了确保名称不会被双重修改，新名称使用 conv() 标记应用。我们可以明确使用如下：

m = MetaData(naming_convention={
    "ck": "ck_%(table_name)s_%(constraint_name)s"
})
t = Table('t', m, Column('x', Integer),
                CheckConstraint('x > 5', name=conv('ck_t_x5')))

在上面的例子中，conv() 标记表示此处的约束名称是最终的，名称将呈现为 "ck_t_x5" 而不是 "ck_t_ck_t_x5"

另请参阅

配置约束命名约定

索引

索引可以匿名创建（使用自动生成的名称 ix_）为单列使用内联 index 关键字，在 Column 上，该关键字也修改了 unique 的用法，将唯一性应用于索引本身，而不是添加一个单独的 UNIQUE 约束。对于具有特定名称或涵盖多个列的索引，请使用 Index 结构，该结构需要一个名称。

下面我们展示了一个具有多个关联 Index 对象的 Table。DDL 为“CREATE INDEX”在表的创建语句之后发布：

metadata_obj = MetaData()
mytable = Table(
    "mytable",
    metadata_obj,
    # an indexed column, with index "ix_mytable_col1"
    Column("col1", Integer, index=True),
    # a uniquely indexed column with index "ix_mytable_col2"
    Column("col2", Integer, index=True, unique=True),
    Column("col3", Integer),
    Column("col4", Integer),
    Column("col5", Integer),
    Column("col6", Integer),
)
# place an index on col3, col4
Index("idx_col34", mytable.c.col3, mytable.c.col4)
# place a unique index on col5, col6
Index("myindex", mytable.c.col5, mytable.c.col6, unique=True)
mytable.create(engine)
CREATE  TABLE  mytable  (
  col1  INTEGER,
  col2  INTEGER,
  col3  INTEGER,
  col4  INTEGER,
  col5  INTEGER,
  col6  INTEGER
)
CREATE  INDEX  ix_mytable_col1  ON  mytable  (col1)
CREATE  UNIQUE  INDEX  ix_mytable_col2  ON  mytable  (col2)
CREATE  UNIQUE  INDEX  myindex  ON  mytable  (col5,  col6)
CREATE  INDEX  idx_col34  ON  mytable  (col3,  col4) 

注意，在上面的示例中，Index 结构是外部创建的，与其对应的表使用 Column 对象直接创建。Index 也支持在 Table 内部“内联”定义，使用字符串名称来标识列：

metadata_obj = MetaData()
mytable = Table(
    "mytable",
    metadata_obj,
    Column("col1", Integer),
    Column("col2", Integer),
    Column("col3", Integer),
    Column("col4", Integer),
    # place an index on col1, col2
    Index("idx_col12", "col1", "col2"),
    # place a unique index on col3, col4
    Index("idx_col34", "col3", "col4", unique=True),
)

Index 对象也支持其自己的 create() 方法：

i = Index("someindex", mytable.c.col5)
i.create(engine)
CREATE  INDEX  someindex  ON  mytable  (col5) 

函数索引

Index 支持 SQL 和函数表达式，与目标后端支持的一样。要针对列使用降序值创建索引，可以使用 ColumnElement.desc() 修改器：

from sqlalchemy import Index
Index("someindex", mytable.c.somecol.desc())

或者使用支持函数索引的后端，比如 PostgreSQL，可以使用 lower() 函数创建“不区分大小写”的索引：

from sqlalchemy import func, Index
Index("someindex", func.lower(mytable.c.somecol))
```### 函数索引
`Index` 支持 SQL 和函数表达式，与目标后端支持的一样。要针对列使用降序值创建索引，可以使用 `ColumnElement.desc()` 修改器：
```py
from sqlalchemy import Index
Index("someindex", mytable.c.somecol.desc())

或者使用支持函数索引的后端，比如 PostgreSQL，可以使用 lower() 函数创建“不区分大小写”的索引：

from sqlalchemy import func, Index
Index("someindex", func.lower(mytable.c.somecol))

索引 API

class sqlalchemy.schema.Index

一个表级索引。

定义一个复合（一个或多个列）索引。

例如：

sometable = Table("sometable", metadata,
                Column("name", String(50)),
                Column("address", String(100))
            )
Index("some_index", sometable.c.name)

对于一个简单的、单列索引，添加 Column 也支持 index=True：

sometable = Table("sometable", metadata,
                Column("name", String(50), index=True)
            )

对于复合索引，可以指定多列：

Index("some_index", sometable.c.name, sometable.c.address)

功能性索引也得到支持，通常通过与绑定到表的Column对象一起使用func构造来实现：

Index("some_index", func.lower(sometable.c.name))

Index也可以手动与Table关联，可以通过内联声明或使用Table.append_constraint()来实现。当使用此方法时，可以将索引列的名称指定为字符串：

Table("sometable", metadata,
                Column("name", String(50)),
                Column("address", String(100)),
                Index("some_index", "name", "address")
        )

要支持此形式中的功能性或基于表达式的索引，可以使用text()构造：

from sqlalchemy import text
Table("sometable", metadata,
                Column("name", String(50)),
                Column("address", String(100)),
                Index("some_index", text("lower(name)"))
        )

另请参阅

索引 - 有关Index的一般信息。

PostgreSQL 特定索引选项 - 适用于Index构造的 PostgreSQL 特定选项。

MySQL / MariaDB 特定索引选项 - MySQL 特定选项适用于Index构造。

集群索引支持 - MSSQL 特定选项适用于Index构造。

成员

init(), argument_for(), create(), ddl_if(), dialect_kwargs, dialect_options, drop(), info, kwargs

类签名

类sqlalchemy.schema.Index (sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.schema.ColumnCollectionMixin, sqlalchemy.schema.HasConditionalDDL, sqlalchemy.schema.SchemaItem)

method __init__(name: str | None, *expressions: _DDLColumnArgument, unique: bool = False, quote: bool | None = None, info: _InfoType | None = None, _table: Table | None = None, _column_flag: bool = False, **dialect_kw: Any) → None

构造一个索引对象。

参数：

• name – 索引的名称
  
• *expressions – 要包含在索引中的列表达式。这些表达式通常是Column的实例，但也可以是最终指向Column的任意 SQL 表达式。
  
• unique=False – 仅限关键字参数；如果为 True，则创建一个唯一索引。
  
• quote=None – 仅限关键字参数；是否对索引的名称应用引号。工作方式与Column.quote相同。
  
• info=None – 可选数据字典，将填充到此对象的SchemaItem.info 属性中。
  
• **dialect_kw – 上述未提及的额外关键字参数是方言特定的，并以_的形式传递。有关个别方言的文档参数的详细信息，请参阅方言的文档。
  

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

对于此 Index，使用给定的 Connection 或 Engine 发出 CREATE 语句以进行连接。

参见

MetaData.create_all()。

method ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

继承自 HasConditionalDDL.ddl_if() 方法 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式类似于 ExecutableDDLElement.execute_if() 可调用对象，其附加功能是可以在 DDL 编译阶段检查条件，例如 CreateTable 构造。HasConditionalDDL.ddl_if() 目前也适用于 Index 构造以及所有 Constraint 构造。

参数：

• dialect - 方言的字符串名称，或一组字符串名称以指示多个方言类型。
  
• callable_ - 使用与 ExecutableDDLElement.execute_if.callable_ 中描述的相同形式构造的可调用对象。
  
• state - 如果存在，将传递给可调用对象的任意对象。
  

从版本 2.0 开始新增。

参见

控制约束和索引的 DDL 生成 - 背景和用法示例

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 进行连接性，为此 Index 发出 DROP 语句。

另请参阅

MetaData.drop_all().

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

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

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

attribute kwargs

继承自 DialectKWArgs.kwargs 属性的 DialectKWArgs。

DialectKWArgs.dialect_kwargs 的同义词。

,

col5 INTEGER,
 col6 INTEGER
 )
 CREATE INDEX ix_mytable_col1 ON mytable (col1)
 CREATE UNIQUE INDEX ix_mytable_col2 ON mytable (col2)
 CREATE UNIQUE INDEX myindex ON mytable (col5, col6)
 CREATE INDEX idx_col34 ON mytable (col3, col4)

注意，在上面的示例中，`Index` 结构是外部创建的，与其对应的表使用 `Column` 对象直接创建。`Index` 也支持在 `Table` 内部“内联”定义，使用字符串名称来标识列：
```py
metadata_obj = MetaData()
mytable = Table(
    "mytable",
    metadata_obj,
    Column("col1", Integer),
    Column("col2", Integer),
    Column("col3", Integer),
    Column("col4", Integer),
    # place an index on col1, col2
    Index("idx_col12", "col1", "col2"),
    # place a unique index on col3, col4
    Index("idx_col34", "col3", "col4", unique=True),
)

Index 对象也支持其自己的 create() 方法：

i = Index("someindex", mytable.c.col5)
i.create(engine)
CREATE  INDEX  someindex  ON  mytable  (col5) 

函数索引

Index 支持 SQL 和函数表达式，与目标后端支持的一样。要针对列使用降序值创建索引，可以使用 ColumnElement.desc() 修改器：

from sqlalchemy import Index
Index("someindex", mytable.c.somecol.desc())

或者使用支持函数索引的后端，比如 PostgreSQL，可以使用 lower() 函数创建“不区分大小写”的索引：

from sqlalchemy import func, Index
Index("someindex", func.lower(mytable.c.somecol))
```### 函数索引
`Index` 支持 SQL 和函数表达式，与目标后端支持的一样。要针对列使用降序值创建索引，可以使用 `ColumnElement.desc()` 修改器：
```py
from sqlalchemy import Index
Index("someindex", mytable.c.somecol.desc())

或者使用支持函数索引的后端，比如 PostgreSQL，可以使用 lower() 函数创建“不区分大小写”的索引：

from sqlalchemy import func, Index
Index("someindex", func.lower(mytable.c.somecol))

索引 API

class sqlalchemy.schema.Index

一个表级索引。

定义一个复合（一个或多个列）索引。

例如：

sometable = Table("sometable", metadata,
                Column("name", String(50)),
                Column("address", String(100))
            )
Index("some_index", sometable.c.name)

对于一个简单的、单列索引，添加 Column 也支持 index=True：

sometable = Table("sometable", metadata,
                Column("name", String(50), index=True)
            )

对于复合索引，可以指定多列：

Index("some_index", sometable.c.name, sometable.c.address)
• 1

功能性索引也得到支持，通常通过与绑定到表的Column对象一起使用func构造来实现：

Index("some_index", func.lower(sometable.c.name))

Index也可以手动与Table关联，可以通过内联声明或使用Table.append_constraint()来实现。当使用此方法时，可以将索引列的名称指定为字符串：

Table("sometable", metadata,
                Column("name", String(50)),
                Column("address", String(100)),
                Index("some_index", "name", "address")
        )

要支持此形式中的功能性或基于表达式的索引，可以使用text()构造：

from sqlalchemy import text
Table("sometable", metadata,
                Column("name", String(50)),
                Column("address", String(100)),
                Index("some_index", text("lower(name)"))
        )

另请参阅

索引 - 有关Index的一般信息。

PostgreSQL 特定索引选项 - 适用于Index构造的 PostgreSQL 特定选项。

MySQL / MariaDB 特定索引选项 - MySQL 特定选项适用于Index构造。

集群索引支持 - MSSQL 特定选项适用于Index构造。

成员

init(), argument_for(), create(), ddl_if(), dialect_kwargs, dialect_options, drop(), info, kwargs

类签名

类sqlalchemy.schema.Index (sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.schema.ColumnCollectionMixin, sqlalchemy.schema.HasConditionalDDL, sqlalchemy.schema.SchemaItem)

method __init__(name: str | None, *expressions: _DDLColumnArgument, unique: bool = False, quote: bool | None = None, info: _InfoType | None = None, _table: Table | None = None, _column_flag: bool = False, **dialect_kw: Any) → None

构造一个索引对象。

参数：

• name – 索引的名称
  
• *expressions – 要包含在索引中的列表达式。这些表达式通常是Column的实例，但也可以是最终指向Column的任意 SQL 表达式。
  
• unique=False – 仅限关键字参数；如果为 True，则创建一个唯一索引。
  
• quote=None – 仅限关键字参数；是否对索引的名称应用引号。工作方式与Column.quote相同。
  
• info=None – 可选数据字典，将填充到此对象的SchemaItem.info 属性中。
  
• **dialect_kw – 上述未提及的额外关键字参数是方言特定的，并以_的形式传递。有关个别方言的文档参数的详细信息，请参阅方言的文档。
  

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

对于此 Index，使用给定的 Connection 或 Engine 发出 CREATE 语句以进行连接。

参见

MetaData.create_all()。

method ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

继承自 HasConditionalDDL.ddl_if() 方法 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式类似于 ExecutableDDLElement.execute_if() 可调用对象，其附加功能是可以在 DDL 编译阶段检查条件，例如 CreateTable 构造。HasConditionalDDL.ddl_if() 目前也适用于 Index 构造以及所有 Constraint 构造。

参数：

• dialect - 方言的字符串名称，或一组字符串名称以指示多个方言类型。
  
• callable_ - 使用与 ExecutableDDLElement.execute_if.callable_ 中描述的相同形式构造的可调用对象。
  
• state - 如果存在，将传递给可调用对象的任意对象。
  

从版本 2.0 开始新增。

参见

控制约束和索引的 DDL 生成 - 背景和用法示例

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 进行连接性，为此 Index 发出 DROP 语句。

另请参阅

MetaData.drop_all().

attribute info

继承自 SchemaItem.info 属性的 SchemaItem

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

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

attribute kwargs

继承自 DialectKWArgs.kwargs 属性的 DialectKWArgs。

DialectKWArgs.dialect_kwargs 的同义词。