插入、更新、删除

INSERT，UPDATE和DELETE语句建立在从UpdateBase开始的层次结构上。Insert和Update构建了基于中间值ValuesBase的构建。

sqlalchemy.sql.expression.delete(table, whereclause=None, bind=None, returning=None, prefixes=None, **dialect_kw)

构建删除对象.

类似的功能可以通过Table上的delete()方法获得。

参数：
  • 表 - 从中​​删除行的表。
  • whereclause – A ClauseElement describing the WHERE condition of the DELETE statement. 请注意，可以使用where()生成方法。

也可以看看

Deletes - SQL表达式教程

sqlalchemy.sql.expression.insert(table, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, **dialect_kw)

构建插入对象.

类似的功能可以通过 insert() 方法 得到.

参数：
  • table – TableClause 是插入的主题
  • values – collection of values to be inserted; see Insert.values() for a description of allowed formats here. 完全可以省略；根据传递给Connection.execute()的参数，Insert构造也将在执行时动态呈现VALUES子句。
  • inline – if True, no attempt will be made to retrieve the SQL-generated default values to be provided within the statement; in particular, this allows SQL expressions to be rendered ‘inline’ within the statement without the need to pre-execute them beforehand; for backends that support “returning”, this turns off the “implicit returning” feature for the statement.

如果同时存在值和编译时绑定参数，则编译时绑定参数将基于每个键覆盖值中指定的信息。

值中的键可以是Column对象或它们的字符串标识符。每个键可以引用以下之一：

如果指定了引用此INSERT语句表的SELECT语句，则该语句将与INSERT语句关联。

也可以看看

Insert Expressions - SQL表达式教程

Inserts, Updates and Deletes - SQL表达式教程

sqlalchemy.sql.expression.update(table, whereclause=None, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, preserve_parameter_order=False, **dialect_kw)

构建一个Update对象。

例如。：

from sqlalchemy import update

stmt = update(users).where(users.c.id==5).\
        values(name='user #5')

类似的功能可以通过Table中的update()方法来使用：

stmt = users.update().\
            where(users.c.id==5).\
            values(name='user #5')
参数：
  • table – A Table object representing the database table to be updated.
  • whereclause -

    可选SQL表达式，用于描述UPDATE语句的WHERE条件。现代应用程序可能更喜欢使用生成的where()方法来指定WHERE子句。

    WHERE子句可以引用多个表。对于支持这种情况的数据库，将生成一个UPDATE FROM子句，或者在MySQL上执行多表更新。该语句将在不支持多表更新语句的数据库上失败。引用WHERE子句中其他表的SQL标准方法是使用相关子查询：

    users.update().values(name='ed').where(
        users.c.name==select([addresses.c.email_address]).\
                    where(addresses.c.user_id==users.c.id).\
                    as_scalar()
        )

    Changed in version 0.7.4: The WHERE clause can refer to multiple tables.

  • 值 -

    可选字典，它指定UPDATE的SET条件。如果保留为None，则在执行和/或编译语句期间，根据传递给语句的那些参数确定SET条件。当没有任何参数的独立编译时，SET子句为所有列生成。

    现代应用程序可能更喜欢使用生成的Update.values()方法来设置UPDATE语句的值。

  • inline – if True, SQL defaults present on Column objects via the default keyword will be compiled ‘inline’ into the statement and not pre-executed. 这意味着它们的值在从ResultProxy.last_updated_params()返回的字典中不可用。
  • preserve_parameter_order -

    如果为True，则更新语句预期仅通过Update.values()方法接收参数，并且它们必须作为Python list呈现的UPDATE语句将为维持此顺序的每个引用列发出SET子句。

    版本1.0.10中的新功能

    也可以看看

    Parameter-Ordered Updates - preserve_parameter_order标志的完整示例

如果values和编译时绑定参数均存在，则编译时绑定参数将基于每个键覆盖values中指定的信息。

values中的键可以是Column对象或它们的字符串标识符（特别是Column的“键”，通常但不一定等同于其名称”）。通常，这里使用的Column对象应该是要更新的表的目标Table的一部分。但是，在使用MySQL时，多表UPDATE语句可以引用来自WHERE子句中引用的任何表的列。

在values中引用的值通常是：

当在update()结构的values子句中结合select()结构时，由select()表示的子查询应该是相关到父表，即提供将子查询内部的表链接到正在更新的外部表的准则：

users.update().values(
        name=select([addresses.c.email_address]).\
                where(addresses.c.user_id==users.c.id).\
                as_scalar()
    )

也可以看看

Inserts, Updates and Deletes - SQL表达式语言教程

class sqlalchemy.sql.expression.Delete(table, whereclause=None, bind=None, returning=None, prefixes=None, **dialect_kw)

基础：sqlalchemy.sql.expression.UpdateBase

表示一个DELETE构造。

使用delete()函数创建Delete对象。

__init__(table, whereclause=None, bind=None, returning=None, prefixes=None, **dialect_kw)

构建一个新的Delete对象。

这个构造函数被镜像为公共API函数；有关完整的用法和参数说明，请参阅delete()。

argument_for （ dialect_name，argument_name，默认 ） ¶ T6>
inherited from the argument_for() method of DialectKWArgs

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

例如。：

Index.argument_for("mydialect", "length", None)

some_index = Index('a', 'b', mydialect_length=5)

The DialectKWArgs.argument_for() method is a per-argument way adding extra arguments to the DefaultDialect.construct_arguments dictionary. 这本词典提供了代表方言的各种模式层次结构所接受的参数名称列表。

新方言通常应该一次性将该字典指定为方言类的数据成员。用于临时添加参数名称的用例通常用于最终用户代码，该代码也使用了使用额外参数的自定义编译方案。

参数：
  • dialect_name – name of a dialect. The dialect must be locatable, else a NoSuchModuleError is raised. 该方言还必须包含一个现有的DefaultDialect.construct_arguments集合，指示它参与关键字参数验证和默认系统，否则引发ArgumentError。如果方言不包括这个集合，那么任何关键字参数都可以代表这个方言指定。所有包含在SQLAlchemy中的方言都包含这个集合，但是对于第三方方言，支持可能会有所不同。
  • argument_name - 参数的名称。
  • 默认 - 参数的默认值。

版本0.9.4中的新功能

结合 T0> ¶ T1>
继承自 bind 属性 UpdateBase

返回与此UpdateBase或与之关联的Table的“绑定”。

比较 （ 其他，** kw ） t5 >
inherited from the compare() method of ClauseElement

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

子类应该覆盖默认行为，这是一种直接的身份比较。

** kw是由subclass compare()方法消耗的参数，可用于修改比较条件。（请参阅ColumnElement）

编译 （ bind = None，dialect = None，** kw ） T5> ¶ T6>
inherited from the compile() method of ClauseElement

编译这个SQL表达式。

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

参数：
  • bind – An Engine or Connection from which a Compiled will be acquired. 这个参数优先于这个ClauseElement的绑定引擎，如果有的话。
  • column_keys – Used for INSERT and UPDATE statements, a list of column names which should be present in the VALUES clause of the compiled statement. 如果None，则呈现目标表格对象中的所有列。
  • dialect – A Dialect instance from which a Compiled will be acquired. 该参数优先于bind参数以及ClauseElement的绑定引擎（如果有的话）。
  • inline – Used for INSERT statements, for a dialect which does not support inline retrieval of newly generated primary key columns, will force the expression used to create the new primary key value to be rendered inline within the INSERT statement’s VALUES clause. 这通常是指序列执行，但也可能指与主键Column关联的任何服务器端默认生成函数。
  • compile_kwargs -

    在所有“访问”方法中将传递给编译器的附加参数的可选字典。例如，这允许将自定义标志传递给自定义编译构造。它也用于传递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})

    版本0.9.0中的新功能

也可以看看

How do I render SQL expressions as strings, possibly with bound parameters inlined?

cte(name=None, recursive=False)
继承自 cte() 方法 HasCTE

返回一个新的CTE或公共表表达式实例。

公用表表达式是一种SQL标准，通过使用一个名为“WITH”的子句，SELECT语句可以使用与主语句一起指定的次要语句。有关UNION的特殊语义也可用于允许“递归”查询，其中SELECT语句可以在先前已选择的一组行上进行绘制。

CTE也可以应用于DML构造对某些数据库的UPDATE，INSERT和DELETE，与RETURNING一起作为CTE行的来源以及CTE行的使用者。

SQLAlchemy将CTE对象检测为与Alias对象类似的对象，作为要传递到语句的FROM子句的特殊元素以及顶部的WITH子句的声明。

在版本1.1中进行了更改：添加了对CTE，CTE添加到UPDATE / INSERT / DELETE的UPDATE / INSERT / DELETE的支持。

参数：
  • name – name given to the common table expression. 像_FromClause.alias()一样，名称可以保留为None，在这种情况下，查询编译时将使用匿名符号。
  • recursive – if True, will render WITH RECURSIVE. 递归公用表表达式旨在与UNION ALL结合使用，以便从已选择的行中派生行。

以下示例包含两篇来自Postgresql的文档，位于http://www.postgresql.org/docs/current/static/queries-with.html以及其他示例。

例1，非递归：

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select([
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ]).group_by(orders.c.region).cte("regional_sales")


top_regions = select([regional_sales.c.region]).\
        where(
            regional_sales.c.total_sales >
            select([
                func.sum(regional_sales.c.total_sales)/10
            ])
        ).cte("top_regions")

statement = select([
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ]).where(orders.c.region.in_(
        select([top_regions.c.region])
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

例2，与RECURSIVE：

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select([
                    parts.c.sub_part,
                    parts.c.part,
                    parts.c.quantity]).\
                    where(parts.c.part=='our part').\
                    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select([
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ]).
        where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select([
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ]).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

例3，使用带CTE的UPDATE和INSERT的upsert：

orders = table(
    'orders',
    column('region'),
    column('amount'),
    column('product'),
    column('quantity')
)

upsert = (
    orders.update()
    .where(orders.c.region == 'Region1')
    .values(amount=1.0, product='Product1', quantity=1)
    .returning(*(orders.c._all_columns)).cte('upsert'))

insert = orders.insert().from_select(
    orders.c.keys(),
    select([
        literal('Region1'), literal(1.0),
        literal('Product1'), literal(1)
    ).where(exists(upsert.select()))
)

connection.execute(insert)

也可以看看

orm.query.Query.cte() - HasCTE.cte()的ORM版本。

dialect_kwargs T0> ¶ T1>
继承自 dialect_kwargs 属性 DialectKWArgs

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

这些参数在它们的原始<dialect>_<kwarg>格式中呈现。只包括实际通过的论点；不同于DialectKWArgs.dialect_options集合，其中包含此方言已知的所有选项，包括默认值。

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

版本0.9.2中的新功能

在版本0.9.4中更改： DialectKWArgs.dialect_kwargs集合现在可写入。

也可以看看

DialectKWArgs.dialect_options - nested dictionary form

dialect_options T0> ¶ T1>
继承自 dialect_options 属性 DialectKWArgs

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

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

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

版本0.9.2中的新功能

也可以看看

DialectKWArgs.dialect_kwargs - flat dictionary form

执行 tt> （ * multiparams，** params ） T5>
继承自 execute() 方法 Executable

编译并执行Executable。

execution_options T0> （ T1> **千瓦 T2> ） T3> ¶ T4>
继承自 execution_options() 方法 tt> Executable

为执行期间生效的语句设置非SQL选项。

执行选项可以在每个语句或每个Connection的基础上设置。此外，Engine和ORM Query对象提供对执行选项的访问，而这些执行选项在连接时进行配置。

execution_options()方法是生成的。返回此语句的新实例，其中包含以下选项：

statement = select([table.c.x, table.c.y])
statement = statement.execution_options(autocommit=True)

请注意，只有一部分可能的执行选项可以应用于语句 - 这些选项包括“autocommit”和“stream_results”，但不包括“isolation_level”或“c​​ompiled_cache”。有关可能的选项的完整列表，请参阅Connection.execution_options()。

也可以看看

Connection.execution_options()

Query.execution_options()

kwargs T0> ¶ T1>
继承自 kwargs 属性 DialectKWArgs

DialectKWArgs.dialect_kwargs的同义词。

params(*arg, **kw)
inherited from the params() method of UpdateBase

设置语句的参数。

此方法在基类上引发NotImplementedError，并由ValuesBase覆盖，以提供UPDATE和INSERT的SET / VALUES子句。

prefix_with （ * expr，** kw ） T5>
继承自 prefix_with() 方法 HasPrefixes

在语句关键字后添加一个或多个表达式，即SELECT，INSERT，UPDATE或DELETE。生成。

这用于支持后端特定的前缀关键字，例如由MySQL提供的前缀关键字。

例如。：

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

可以通过多次调用prefix_with()来指定多个前缀。

参数：
  • *expr – textual or ClauseElement construct which will be rendered following the INSERT, UPDATE, or DELETE keyword.
  • ** kw - 接受单个关键字'dialect'。这是一个可选的字符串方言名称，它将限制将该前缀的呈现仅限于该方言。
返回 T0> （ T1> * COLS T2> ） T3> ¶ T4>
inherited from the returning() method of UpdateBase

在此语句中添加一个RETURNING或等同的子句。

例如。：

stmt = table.update().\
          where(table.c.data == 'value').\
          values(status='X').\
          returning(table.c.server_flag,
                    table.c.updated_timestamp)

for server_flag, updated_timestamp in connection.execute(stmt):
    print(server_flag, updated_timestamp)

给定的列表达式集合应该从作为INSERT，UPDATE或DELETE目标的表中派生。虽然Column对象是典型的，但元素也可以是表达式：

stmt = table.insert().returning(
    (table.c.first_name + " " + table.c.last_name).
    label('fullname'))

编译后，将在语句中呈现RETURNING子句或数据库等效项。对于INSERT和UPDATE，这些值是新插入/更新的值。对于DELETE，这些值是那些被删除的行。

执行时，要返回的列的值通过结果集可用，并可以使用ResultProxy.fetchone()和类似的方法进行迭代。对于本身不支持返回值的DBAPI（即cx_oracle），SQLAlchemy将在结果级接近此行为，以便提供合理的行为中立性。

请注意，并非所有数据库/ DBAPI都支持RETURNING。对于不支持的后端，编译和/或执行时会引发异常。对于那些支持它的人来说，后端的功能差异很大，包括对executemany()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明，以确定RETURNING的可用性。

也可以看看

ValuesBase.return_defaults() - 针对单个行INSERT或UPDATE的高效获取服务器端默认值和触发器的一种替代方法。

标量 （ * multiparams，** params ） T5>
inherited from the scalar() method of Executable

编译并执行此Executable，返回结果的标量表示。

self_group T0> （ T1> 针对=无 T2> ） T3> ¶ T4>
inherited from the self_group() method of ClauseElement

对这个ClauseElement应用“分组”。

子类重写此方法以返回“分组”结构，即括号。In particular it’s used by “binary” expressions to provide a grouping around themselves when placed into a larger expression, as well as by select() constructs when placed into the FROM clause of another select(). （请注意，通常应使用Select.alias()方法创建子查询，因为许多平台需要命名嵌套的SELECT语句）。

由于表达式组合在一起，所以self_group()的应用程序是自动的 - 最终用户代码不需要直接使用此方法。Note that SQLAlchemy’s clause constructs take operator precedence into account - so parenthesis might not be needed, for example, in an expression like x OR (y AND z) - AND takes precedence over OR.

ClauseElement的base self_group()方法仅返回self。

unique_params （ * optionaldict，** kwargs ） T5>
inherited from the unique_params() method of ClauseElement

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

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

其中 T0> （ T1> whereclause T2> ） T3> ¶ T4>

将给定的WHERE子句添加到新返回的删除结构中。

with_hint(text, selectable=None, dialect_name='*')
继承自 with_hint() 方法 UpdateBase

为这个INSERT / UPDATE / DELETE语句添加一个表提示给单个表。

注意

UpdateBase.with_hint() currently applies only to Microsoft SQL Server. 对于MySQL INSERT / UPDATE / DELETE提示，请使用UpdateBase.prefix_with()。

The text of the hint is rendered in the appropriate location for the database backend in use, relative to the Table that is the subject of this statement, or optionally to that of the given Table passed as the selectable argument.

The dialect_name option will limit the rendering of a particular hint to a particular backend. 例如，添加仅对SQL Server有效的提示：

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")

New in version 0.7.6.

参数：
  • 文本 - 提示的文本。
  • selectable – optional Table that specifies an element of the FROM clause within an UPDATE or DELETE to be the subject of the hint - applies only to certain backends.
  • dialect_name – defaults to *, if specified as the name of a particular dialect, will apply these hints only when that dialect is in use.
class sqlalchemy.sql.expression.Insert(table, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, **dialect_kw)

基础：sqlalchemy.sql.expression.ValuesBase

表示一个INSERT构造。

Insert对象是使用insert()函数创建的。

也可以看看

Insert Expressions

__init__(table, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, **dialect_kw)

构建一个新的Insert对象。

这个构造函数被镜像为公共API函数；有关完整的用法和参数说明，请参阅insert()。

argument_for （ dialect_name，argument_name，默认 ） ¶ T6>
inherited from the argument_for() method of DialectKWArgs

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

例如。：

Index.argument_for("mydialect", "length", None)

some_index = Index('a', 'b', mydialect_length=5)

The DialectKWArgs.argument_for() method is a per-argument way adding extra arguments to the DefaultDialect.construct_arguments dictionary. 这本词典提供了代表方言的各种模式层次结构所接受的参数名称列表。

新方言通常应该一次性将该字典指定为方言类的数据成员。用于临时添加参数名称的用例通常用于最终用户代码，该代码也使用了使用额外参数的自定义编译方案。

参数：
  • dialect_name – name of a dialect. The dialect must be locatable, else a NoSuchModuleError is raised. 该方言还必须包含一个现有的DefaultDialect.construct_arguments集合，指示它参与关键字参数验证和默认系统，否则引发ArgumentError。如果方言不包括这个集合，那么任何关键字参数都可以代表这个方言指定。所有包含在SQLAlchemy中的方言都包含这个集合，但是对于第三方方言，支持可能会有所不同。
  • argument_name - 参数的名称。
  • 默认 - 参数的默认值。

版本0.9.4中的新功能

结合 T0> ¶ T1>
继承自 bind 属性 UpdateBase

返回与此UpdateBase或与之关联的Table的“绑定”。

比较 （ 其他，** kw ） t5 >
inherited from the compare() method of ClauseElement

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

子类应该覆盖默认行为，这是一种直接的身份比较。

** kw是由subclass compare()方法消耗的参数，可用于修改比较条件。（请参阅ColumnElement）

编译 （ bind = None，dialect = None，** kw ） T5> ¶ T6>
inherited from the compile() method of ClauseElement

编译这个SQL表达式。

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

参数：
  • bind – An Engine or Connection from which a Compiled will be acquired. 这个参数优先于这个ClauseElement的绑定引擎，如果有的话。
  • column_keys – Used for INSERT and UPDATE statements, a list of column names which should be present in the VALUES clause of the compiled statement. 如果None，则呈现目标表格对象中的所有列。
  • dialect – A Dialect instance from which a Compiled will be acquired. 该参数优先于bind参数以及ClauseElement的绑定引擎（如果有的话）。
  • inline – Used for INSERT statements, for a dialect which does not support inline retrieval of newly generated primary key columns, will force the expression used to create the new primary key value to be rendered inline within the INSERT statement’s VALUES clause. 这通常是指序列执行，但也可能指与主键Column关联的任何服务器端默认生成函数。
  • compile_kwargs -

    在所有“访问”方法中将传递给编译器的附加参数的可选字典。例如，这允许将自定义标志传递给自定义编译构造。它也用于传递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})

    版本0.9.0中的新功能

也可以看看

How do I render SQL expressions as strings, possibly with bound parameters inlined?

cte(name=None, recursive=False)
继承自 cte() 方法 HasCTE

返回一个新的CTE或公共表表达式实例。

公用表表达式是一种SQL标准，通过使用一个名为“WITH”的子句，SELECT语句可以使用与主语句一起指定的次要语句。有关UNION的特殊语义也可用于允许“递归”查询，其中SELECT语句可以在先前已选择的一组行上进行绘制。

CTE也可以应用于DML构造对某些数据库的UPDATE，INSERT和DELETE，与RETURNING一起作为CTE行的来源以及CTE行的使用者。

SQLAlchemy将CTE对象检测为与Alias对象类似的对象，作为要传递到语句的FROM子句的特殊元素以及顶部的WITH子句的声明。

在版本1.1中进行了更改：添加了对CTE，CTE添加到UPDATE / INSERT / DELETE的UPDATE / INSERT / DELETE的支持。

参数：
  • name – name given to the common table expression. 像_FromClause.alias()一样，名称可以保留为None，在这种情况下，查询编译时将使用匿名符号。
  • recursive – if True, will render WITH RECURSIVE. 递归公用表表达式旨在与UNION ALL结合使用，以便从已选择的行中派生行。

以下示例包含两篇来自Postgresql的文档，位于http://www.postgresql.org/docs/current/static/queries-with.html以及其他示例。

例1，非递归：

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select([
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ]).group_by(orders.c.region).cte("regional_sales")


top_regions = select([regional_sales.c.region]).\
        where(
            regional_sales.c.total_sales >
            select([
                func.sum(regional_sales.c.total_sales)/10
            ])
        ).cte("top_regions")

statement = select([
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ]).where(orders.c.region.in_(
        select([top_regions.c.region])
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

例2，与RECURSIVE：

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select([
                    parts.c.sub_part,
                    parts.c.part,
                    parts.c.quantity]).\
                    where(parts.c.part=='our part').\
                    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select([
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ]).
        where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select([
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ]).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

例3，使用带CTE的UPDATE和INSERT的upsert：

orders = table(
    'orders',
    column('region'),
    column('amount'),
    column('product'),
    column('quantity')
)

upsert = (
    orders.update()
    .where(orders.c.region == 'Region1')
    .values(amount=1.0, product='Product1', quantity=1)
    .returning(*(orders.c._all_columns)).cte('upsert'))

insert = orders.insert().from_select(
    orders.c.keys(),
    select([
        literal('Region1'), literal(1.0),
        literal('Product1'), literal(1)
    ).where(exists(upsert.select()))
)

connection.execute(insert)

也可以看看

orm.query.Query.cte() - HasCTE.cte()的ORM版本。

dialect_kwargs T0> ¶ T1>
继承自 dialect_kwargs 属性 DialectKWArgs

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

这些参数在它们的原始<dialect>_<kwarg>格式中呈现。只包括实际通过的论点；不同于DialectKWArgs.dialect_options集合，其中包含此方言已知的所有选项，包括默认值。

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

版本0.9.2中的新功能

在版本0.9.4中更改： DialectKWArgs.dialect_kwargs集合现在可写入。

也可以看看

DialectKWArgs.dialect_options - nested dictionary form

dialect_options T0> ¶ T1>
继承自 dialect_options 属性 DialectKWArgs

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

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

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

版本0.9.2中的新功能

也可以看看

DialectKWArgs.dialect_kwargs - flat dictionary form

执行 tt> （ * multiparams，** params ） T5>
继承自 execute() 方法 Executable

编译并执行Executable。

execution_options T0> （ T1> **千瓦 T2> ） T3> ¶ T4>
继承自 execution_options() 方法 tt> Executable

为执行期间生效的语句设置非SQL选项。

执行选项可以在每个语句或每个Connection的基础上设置。此外，Engine和ORM Query对象提供对执行选项的访问，而这些执行选项在连接时进行配置。

execution_options()方法是生成的。返回此语句的新实例，其中包含以下选项：

statement = select([table.c.x, table.c.y])
statement = statement.execution_options(autocommit=True)

请注意，只有一部分可能的执行选项可以应用于语句 - 这些选项包括“autocommit”和“stream_results”，但不包括“isolation_level”或“c​​ompiled_cache”。有关可能的选项的完整列表，请参阅Connection.execution_options()。

也可以看看

Connection.execution_options()

Query.execution_options()

from_select(names, select, include_defaults=True)

返回一个代表INSERT ... FROM SELECT语句的新Insert结构。

例如。：

sel = select([table1.c.a, table1.c.b]).where(table1.c.c > 5)
ins = table2.insert().from_select(['a', 'b'], sel)
参数：
  • names – a sequence of string column names or Column objects representing the target columns.
  • select – a select() construct, FromClause or other construct which resolves into a FromClause, such as an ORM Query object, etc. 从此FROM子句返回的列的顺序应与作为names参数发送的列顺序相对应；虽然在传递到数据库之前没有检查过，但是如果这些列列表不一致，数据库通常会引发异常。
  • include_defaults -

    如果为True，则在名称列表中未指定的Column对象（如Column Insert/Update Defaults中所述）指定的非服务器默认值和SQL表达式将呈现到INSERT和SELECT语句中，以便这些值也包含在要插入的数据中。

    注意

    一个使用Python可调用函数的Python方面的默认值只会在整个语句中调用一次，而不是每行。

    版本1.0.0中的新增功能： - Insert.from_select()现在将Python端和SQL表达式列默认值显示为SELECT语句中的列，否则不包含在列表中列名称。

在版本1.0.0中更改：使用FROM SELECT的INSERT意味着insert.inline标志设置为True，表示该语句不会尝试获取“最后插入的主键“或其他默认值。该语句处理任意数量的行，因此ResultProxy.inserted_primary_key访问器不适用。

0.8.3版本中的新功能

kwargs T0> ¶ T1>
继承自 kwargs 属性 DialectKWArgs

DialectKWArgs.dialect_kwargs的同义词。

params(*arg, **kw)
inherited from the params() method of UpdateBase

设置语句的参数。

此方法在基类上引发NotImplementedError，并由ValuesBase覆盖，以提供UPDATE和INSERT的SET / VALUES子句。

prefix_with （ * expr，** kw ） T5>
继承自 prefix_with() 方法 HasPrefixes

在语句关键字后添加一个或多个表达式，即SELECT，INSERT，UPDATE或DELETE。生成。

这用于支持后端特定的前缀关键字，例如由MySQL提供的前缀关键字。

例如。：

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

可以通过多次调用prefix_with()来指定多个前缀。

参数：
  • *expr – textual or ClauseElement construct which will be rendered following the INSERT, UPDATE, or DELETE keyword.
  • ** kw - 接受单个关键字'dialect'。这是一个可选的字符串方言名称，它将限制将该前缀的呈现仅限于该方言。
return_defaults T0> （ T1> * COLS T2> ） T3> ¶ T4>
继承自 return_defaults() 方法ValuesBase

利用RETURNING子句获取服务器端表达式和默认值。

例如。：

stmt = table.insert().values(data='newdata').return_defaults()

result = connection.execute(stmt)

server_created_at = result.returned_defaults['created_at']

当用于支持RETURNING的后端时，如果不同时使用UpdateBase.returning()，则由SQL表达式或server-side-default生成的所有列值将被添加到任何现有的RETURNING子句中。然后，使用ResultProxy.returned_defaults存取器作为字典，结果可以在结果上使用列值，该值指的是键入Column对象及其.key

这种方法与UpdateBase.returning()不同之处在于：

  1. ValuesBase.return_defaults()仅用于与一行匹配的INSERT或UPDATE语句。尽管一般意义上的RETURNING构造支持多行UPDATE或DELETE语句的多行，或者对于返回多行的INSERT的特殊情况（例如，来自SELECT，多值VALUES子句的INSERT），ValuesBase.return_defaults()仅用于“ORM样式”单行INSERT / UPDATE语句。当使用ValuesBase.return_defaults()时，语句返回的行也会隐式消耗。By contrast, UpdateBase.returning() leaves the RETURNING result-set intact with a collection of any number of rows.
  2. 它与现有逻辑兼容，以获取自动生成的主键值，也称为“隐式返回”。支持RETURNING的后端将自动使用RETURNING来获取新生成的主键值；而UpdateBase.returning()方法绕过了这种行为，ValuesBase.return_defaults()保持不变。
  3. 它可以被称为反对任何后端。不支持RETURNING的后端将跳过功能的使用，而不是引发异常。ResultProxy.returned_defaults的返回值将为None

ValuesBase.return_defaults() is used by the ORM to provide an efficient implementation for the eager_defaults feature of mapper().

参数：cols – optional list of column key names or Column objects. 如果省略，则服务器上评估的所有列表达式都将添加到返回列表中。

版本0.9.0中的新功能

也可以看看

UpdateBase.returning()

ResultProxy.returned_defaults

返回 T0> （ T1> * COLS T2> ） T3> ¶ T4>
inherited from the returning() method of UpdateBase

在此语句中添加一个RETURNING或等同的子句。

例如。：

stmt = table.update().\
          where(table.c.data == 'value').\
          values(status='X').\
          returning(table.c.server_flag,
                    table.c.updated_timestamp)

for server_flag, updated_timestamp in connection.execute(stmt):
    print(server_flag, updated_timestamp)

给定的列表达式集合应该从作为INSERT，UPDATE或DELETE目标的表中派生。虽然Column对象是典型的，但元素也可以是表达式：

stmt = table.insert().returning(
    (table.c.first_name + " " + table.c.last_name).
    label('fullname'))

编译后，将在语句中呈现RETURNING子句或数据库等效项。对于INSERT和UPDATE，这些值是新插入/更新的值。对于DELETE，这些值是那些被删除的行。

执行时，要返回的列的值通过结果集可用，并可以使用ResultProxy.fetchone()和类似的方法进行迭代。对于本身不支持返回值的DBAPI（即cx_oracle），SQLAlchemy将在结果级接近此行为，以便提供合理的行为中立性。

请注意，并非所有数据库/ DBAPI都支持RETURNING。对于不支持的后端，编译和/或执行时会引发异常。对于那些支持它的人来说，后端的功能差异很大，包括对executemany()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明，以确定RETURNING的可用性。

也可以看看

ValuesBase.return_defaults() - 针对单个行INSERT或UPDATE的高效获取服务器端默认值和触发器的一种替代方法。

标量 （ * multiparams，** params ） T5>
inherited from the scalar() method of Executable

编译并执行此Executable，返回结果的标量表示。

self_group T0> （ T1> 针对=无 T2> ） T3> ¶ T4>
inherited from the self_group() method of ClauseElement

对这个ClauseElement应用“分组”。

子类重写此方法以返回“分组”结构，即括号。In particular it’s used by “binary” expressions to provide a grouping around themselves when placed into a larger expression, as well as by select() constructs when placed into the FROM clause of another select(). （请注意，通常应使用Select.alias()方法创建子查询，因为许多平台需要命名嵌套的SELECT语句）。

由于表达式组合在一起，所以self_group()的应用程序是自动的 - 最终用户代码不需要直接使用此方法。Note that SQLAlchemy’s clause constructs take operator precedence into account - so parenthesis might not be needed, for example, in an expression like x OR (y AND z) - AND takes precedence over OR.

ClauseElement的base self_group()方法仅返回self。

unique_params （ * optionaldict，** kwargs ） T5>
inherited from the unique_params() method of ClauseElement

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

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

值 （ * args，** kwargs ） T5>
inherited from the values() method of ValuesBase

为INSERT语句指定一个固定的VALUES子句，或者为UPDATE指定一个SET子句。

Note that the Insert and Update constructs support per-execution time formatting of the VALUES and/or SET clauses, based on the arguments passed to Connection.execute(). 但是，可以使用ValuesBase.values()方法将特定的一组参数“修复”到语句中。

多次调用ValuesBase.values()将产生一个新的结构，每个结构都修改参数列表以包含发送的新参数。在单个参数字典的典型情况下，新传递的键将替换以前构造中的相同键。在基于列表的“多值”结构的情况下，每个新的值列表都被扩展到现有的值列表中。

参数：
  • ** kwargs -

    键值对表示映射到要呈现到VALUES或SET子句中的值的Column的字符串键：

    users.insert().values(name="some name")

users.update().where(users.c.id==5).values(name="some name")
  • * args -

    作为传递键/值参数的替代方法，字典，元组或字典或元组列表可以作为单个位置参数传递，以形成语句的VALUES或SET子句。接受的表单根据是Insert还是Update结构而有所不同。

    对于Insert或Update结构，可以传递单个字典，其工作方式与kwargs表单相同：

    users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})

    对于任何一种形式，但对于Insert构造更典型，也接受包含表中每列的条目的元组：

    users.insert().values((5, "some name"))

    Insert结构还支持传递字典或全表元组列表，这些元组在服务器上将呈现不太常见的“多值”SQL语法 - 后端支持此语法，如SQLite，Postgresql，MySQL，但不一定是其他的：

    users.insert().values([
                    {"name": "some name"},
                    {"name": "some other name"},
                    {"name": "yet another name"},
                ])

    上面的表单将呈现多个VALUES语句，类似于：

    INSERT INTO users (name) VALUES
                (:name_1),
                (:name_2),
                (:name_3)

    It is essential to note that passing multiple values is NOT the same as using traditional executemany() form. 上面的语法是不常用的特殊语法。要针对多行发出INSERT语句，常规方法是将多个值列表传递给Connection.execute()方法，该方法由所有数据库后端支持，并且通常对于非常高效的大量的参数。

    也可以看看

    Executing Multiple Statements - 介绍用于INSERT和其他语句的多参数集调用的传统Core方法。

    版本1.0.0中已更改：使用多个VALUES子句（即使是长度为1的列表）的INSERT意味着Insert.inline标志设置为True，表明该语句不会尝试获取“最后插入的主键”或其他默认值。该语句处理任意数量的行，因此ResultProxy.inserted_primary_key访问器不适用。

    在1.0.0版本中已更改：多值插入现在支持具有Python侧缺省值和可调参数的列，方式与“executemany”调用方式相同；可调用的是每行调用的。对于其他细节，当使用多值插入时，请参阅Python-side defaults invoked for each row invidually when using a multivalued insert

    Update结构支持一个特殊的形式，它是一个2元组的列表，当提供的时候必须和preserve_parameter_order参数一起传递。这种形式导致UPDATE语句使用Update.values()给出的参数顺序来呈现SET子句，而不是Table中给出的列的顺序。

    版本1.0.10中的新增功能： - 通过preserve_parameter_order标志增加了对参数排序的UPDATE语句的支持。

    也可以看看

    Parameter-Ordered Updates - preserve_parameter_order标志的完整示例

也可以看看

Inserts, Updates and Deletes - SQL表达式语言教程

insert() - 产生一个INSERT语句

update() - 产生一个UPDATE语句

with_hint(text, selectable=None, dialect_name='*')
继承自 with_hint() 方法 UpdateBase

为这个INSERT / UPDATE / DELETE语句添加一个表提示给单个表。

注意

UpdateBase.with_hint() currently applies only to Microsoft SQL Server. 对于MySQL INSERT / UPDATE / DELETE提示，请使用UpdateBase.prefix_with()。

The text of the hint is rendered in the appropriate location for the database backend in use, relative to the Table that is the subject of this statement, or optionally to that of the given Table passed as the selectable argument.

The dialect_name option will limit the rendering of a particular hint to a particular backend. 例如，添加仅对SQL Server有效的提示：

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")

New in version 0.7.6.

参数：
  • 文本 - 提示的文本。
  • selectable – optional Table that specifies an element of the FROM clause within an UPDATE or DELETE to be the subject of the hint - applies only to certain backends.
  • dialect_name – defaults to *, if specified as the name of a particular dialect, will apply these hints only when that dialect is in use.
class sqlalchemy.sql.expression.Update(table, whereclause=None, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, preserve_parameter_order=False, **dialect_kw)

基础：sqlalchemy.sql.expression.ValuesBase

表示更新构造。

Update对象是使用update()函数创建的。

__init__(table, whereclause=None, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, preserve_parameter_order=False, **dialect_kw)

构建一个新的Update对象。

这个构造函数被镜像为公共API函数；有关完整的用法和参数说明，请参阅update()。

argument_for （ dialect_name，argument_name，默认 ） ¶ T6>
inherited from the argument_for() method of DialectKWArgs

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

例如。：

Index.argument_for("mydialect", "length", None)

some_index = Index('a', 'b', mydialect_length=5)

The DialectKWArgs.argument_for() method is a per-argument way adding extra arguments to the DefaultDialect.construct_arguments dictionary. 这本词典提供了代表方言的各种模式层次结构所接受的参数名称列表。

新方言通常应该一次性将该字典指定为方言类的数据成员。用于临时添加参数名称的用例通常用于最终用户代码，该代码也使用了使用额外参数的自定义编译方案。

参数：
  • dialect_name – name of a dialect. The dialect must be locatable, else a NoSuchModuleError is raised. 该方言还必须包含一个现有的DefaultDialect.construct_arguments集合，指示它参与关键字参数验证和默认系统，否则引发ArgumentError。如果方言不包括这个集合，那么任何关键字参数都可以代表这个方言指定。所有包含在SQLAlchemy中的方言都包含这个集合，但是对于第三方方言，支持可能会有所不同。
  • argument_name - 参数的名称。
  • 默认 - 参数的默认值。

版本0.9.4中的新功能

结合 T0> ¶ T1>
继承自 bind 属性 UpdateBase

返回与此UpdateBase或与之关联的Table的“绑定”。

比较 （ 其他，** kw ） t5 >
inherited from the compare() method of ClauseElement

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

子类应该覆盖默认行为，这是一种直接的身份比较。

** kw是由subclass compare()方法消耗的参数，可用于修改比较条件。（请参阅ColumnElement）

编译 （ bind = None，dialect = None，** kw ） T5> ¶ T6>
inherited from the compile() method of ClauseElement

编译这个SQL表达式。

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

参数：
  • bind – An Engine or Connection from which a Compiled will be acquired. 这个参数优先于这个ClauseElement的绑定引擎，如果有的话。
  • column_keys – Used for INSERT and UPDATE statements, a list of column names which should be present in the VALUES clause of the compiled statement. 如果None，则呈现目标表格对象中的所有列。
  • dialect – A Dialect instance from which a Compiled will be acquired. 该参数优先于bind参数以及ClauseElement的绑定引擎（如果有的话）。
  • inline – Used for INSERT statements, for a dialect which does not support inline retrieval of newly generated primary key columns, will force the expression used to create the new primary key value to be rendered inline within the INSERT statement’s VALUES clause. 这通常是指序列执行，但也可能指与主键Column关联的任何服务器端默认生成函数。
  • compile_kwargs -

    在所有“访问”方法中将传递给编译器的附加参数的可选字典。例如，这允许将自定义标志传递给自定义编译构造。它也用于传递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})

    版本0.9.0中的新功能

也可以看看

How do I render SQL expressions as strings, possibly with bound parameters inlined?

cte(name=None, recursive=False)
继承自 cte() 方法 HasCTE

返回一个新的CTE或公共表表达式实例。

公用表表达式是一种SQL标准，通过使用一个名为“WITH”的子句，SELECT语句可以使用与主语句一起指定的次要语句。有关UNION的特殊语义也可用于允许“递归”查询，其中SELECT语句可以在先前已选择的一组行上进行绘制。

CTE也可以应用于DML构造对某些数据库的UPDATE，INSERT和DELETE，与RETURNING一起作为CTE行的来源以及CTE行的使用者。

SQLAlchemy将CTE对象检测为与Alias对象类似的对象，作为要传递到语句的FROM子句的特殊元素以及顶部的WITH子句的声明。

在版本1.1中进行了更改：添加了对CTE，CTE添加到UPDATE / INSERT / DELETE的UPDATE / INSERT / DELETE的支持。

参数：
  • name – name given to the common table expression. 像_FromClause.alias()一样，名称可以保留为None，在这种情况下，查询编译时将使用匿名符号。
  • recursive – if True, will render WITH RECURSIVE. 递归公用表表达式旨在与UNION ALL结合使用，以便从已选择的行中派生行。

以下示例包含两篇来自Postgresql的文档，位于http://www.postgresql.org/docs/current/static/queries-with.html以及其他示例。

例1，非递归：

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select([
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ]).group_by(orders.c.region).cte("regional_sales")


top_regions = select([regional_sales.c.region]).\
        where(
            regional_sales.c.total_sales >
            select([
                func.sum(regional_sales.c.total_sales)/10
            ])
        ).cte("top_regions")

statement = select([
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ]).where(orders.c.region.in_(
        select([top_regions.c.region])
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

例2，与RECURSIVE：

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select([
                    parts.c.sub_part,
                    parts.c.part,
                    parts.c.quantity]).\
                    where(parts.c.part=='our part').\
                    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select([
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ]).
        where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select([
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ]).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

例3，使用带CTE的UPDATE和INSERT的upsert：

orders = table(
    'orders',
    column('region'),
    column('amount'),
    column('product'),
    column('quantity')
)

upsert = (
    orders.update()
    .where(orders.c.region == 'Region1')
    .values(amount=1.0, product='Product1', quantity=1)
    .returning(*(orders.c._all_columns)).cte('upsert'))

insert = orders.insert().from_select(
    orders.c.keys(),
    select([
        literal('Region1'), literal(1.0),
        literal('Product1'), literal(1)
    ).where(exists(upsert.select()))
)

connection.execute(insert)

也可以看看

orm.query.Query.cte() - HasCTE.cte()的ORM版本。

dialect_kwargs T0> ¶ T1>
继承自 dialect_kwargs 属性 DialectKWArgs

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

这些参数在它们的原始<dialect>_<kwarg>格式中呈现。只包括实际通过的论点；不同于DialectKWArgs.dialect_options集合，其中包含此方言已知的所有选项，包括默认值。

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

版本0.9.2中的新功能

在版本0.9.4中更改： DialectKWArgs.dialect_kwargs集合现在可写入。

也可以看看

DialectKWArgs.dialect_options - nested dictionary form

dialect_options T0> ¶ T1>
继承自 dialect_options 属性 DialectKWArgs

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

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

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

版本0.9.2中的新功能

也可以看看

DialectKWArgs.dialect_kwargs - flat dictionary form

执行 tt> （ * multiparams，** params ） T5>
继承自 execute() 方法 Executable

编译并执行Executable。

execution_options T0> （ T1> **千瓦 T2> ） T3> ¶ T4>
继承自 execution_options() 方法 tt> Executable

为执行期间生效的语句设置非SQL选项。

执行选项可以在每个语句或每个Connection的基础上设置。此外，Engine和ORM Query对象提供对执行选项的访问，而这些执行选项在连接时进行配置。

execution_options()方法是生成的。返回此语句的新实例，其中包含以下选项：

statement = select([table.c.x, table.c.y])
statement = statement.execution_options(autocommit=True)

请注意，只有一部分可能的执行选项可以应用于语句 - 这些选项包括“autocommit”和“stream_results”，但不包括“isolation_level”或“c​​ompiled_cache”。有关可能的选项的完整列表，请参阅Connection.execution_options()。

也可以看看

Connection.execution_options()

Query.execution_options()

kwargs T0> ¶ T1>
继承自 kwargs 属性 DialectKWArgs

DialectKWArgs.dialect_kwargs的同义词。

params(*arg, **kw)
inherited from the params() method of UpdateBase

设置语句的参数。

此方法在基类上引发NotImplementedError，并由ValuesBase覆盖，以提供UPDATE和INSERT的SET / VALUES子句。

prefix_with （ * expr，** kw ） T5>
继承自 prefix_with() 方法 HasPrefixes

在语句关键字后添加一个或多个表达式，即SELECT，INSERT，UPDATE或DELETE。生成。

这用于支持后端特定的前缀关键字，例如由MySQL提供的前缀关键字。

例如。：

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

可以通过多次调用prefix_with()来指定多个前缀。

参数：
  • *expr – textual or ClauseElement construct which will be rendered following the INSERT, UPDATE, or DELETE keyword.
  • ** kw - 接受单个关键字'dialect'。这是一个可选的字符串方言名称，它将限制将该前缀的呈现仅限于该方言。
return_defaults T0> （ T1> * COLS T2> ） T3> ¶ T4>
继承自 return_defaults() 方法ValuesBase

利用RETURNING子句获取服务器端表达式和默认值。

例如。：

stmt = table.insert().values(data='newdata').return_defaults()

result = connection.execute(stmt)

server_created_at = result.returned_defaults['created_at']

当用于支持RETURNING的后端时，如果不同时使用UpdateBase.returning()，则由SQL表达式或server-side-default生成的所有列值将被添加到任何现有的RETURNING子句中。然后，使用ResultProxy.returned_defaults存取器作为字典，结果可以在结果上使用列值，该值指的是键入Column对象及其.key

这种方法与UpdateBase.returning()不同之处在于：

  1. ValuesBase.return_defaults()仅用于与一行匹配的INSERT或UPDATE语句。尽管一般意义上的RETURNING构造支持多行UPDATE或DELETE语句的多行，或者对于返回多行的INSERT的特殊情况（例如，来自SELECT，多值VALUES子句的INSERT），ValuesBase.return_defaults()仅用于“ORM样式”单行INSERT / UPDATE语句。当使用ValuesBase.return_defaults()时，语句返回的行也会隐式消耗。By contrast, UpdateBase.returning() leaves the RETURNING result-set intact with a collection of any number of rows.
  2. 它与现有逻辑兼容，以获取自动生成的主键值，也称为“隐式返回”。支持RETURNING的后端将自动使用RETURNING来获取新生成的主键值；而UpdateBase.returning()方法绕过了这种行为，ValuesBase.return_defaults()保持不变。
  3. 它可以被称为反对任何后端。不支持RETURNING的后端将跳过功能的使用，而不是引发异常。ResultProxy.returned_defaults的返回值将为None

ValuesBase.return_defaults() is used by the ORM to provide an efficient implementation for the eager_defaults feature of mapper().

参数：cols – optional list of column key names or Column objects. 如果省略，则服务器上评估的所有列表达式都将添加到返回列表中。

版本0.9.0中的新功能

也可以看看

UpdateBase.returning()

ResultProxy.returned_defaults

返回 T0> （ T1> * COLS T2> ） T3> ¶ T4>
inherited from the returning() method of UpdateBase

在此语句中添加一个RETURNING或等同的子句。

例如。：

stmt = table.update().\
          where(table.c.data == 'value').\
          values(status='X').\
          returning(table.c.server_flag,
                    table.c.updated_timestamp)

for server_flag, updated_timestamp in connection.execute(stmt):
    print(server_flag, updated_timestamp)

给定的列表达式集合应该从作为INSERT，UPDATE或DELETE目标的表中派生。虽然Column对象是典型的，但元素也可以是表达式：

stmt = table.insert().returning(
    (table.c.first_name + " " + table.c.last_name).
    label('fullname'))

编译后，将在语句中呈现RETURNING子句或数据库等效项。对于INSERT和UPDATE，这些值是新插入/更新的值。对于DELETE，这些值是那些被删除的行。

执行时，要返回的列的值通过结果集可用，并可以使用ResultProxy.fetchone()和类似的方法进行迭代。对于本身不支持返回值的DBAPI（即cx_oracle），SQLAlchemy将在结果级接近此行为，以便提供合理的行为中立性。

请注意，并非所有数据库/ DBAPI都支持RETURNING。对于不支持的后端，编译和/或执行时会引发异常。对于那些支持它的人来说，后端的功能差异很大，包括对executemany()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明，以确定RETURNING的可用性。

也可以看看

ValuesBase.return_defaults() - 针对单个行INSERT或UPDATE的高效获取服务器端默认值和触发器的一种替代方法。

标量 （ * multiparams，** params ） T5>
inherited from the scalar() method of Executable

编译并执行此Executable，返回结果的标量表示。

self_group T0> （ T1> 针对=无 T2> ） T3> ¶ T4>
inherited from the self_group() method of ClauseElement

对这个ClauseElement应用“分组”。

子类重写此方法以返回“分组”结构，即括号。In particular it’s used by “binary” expressions to provide a grouping around themselves when placed into a larger expression, as well as by select() constructs when placed into the FROM clause of another select(). （请注意，通常应使用Select.alias()方法创建子查询，因为许多平台需要命名嵌套的SELECT语句）。

由于表达式组合在一起，所以self_group()的应用程序是自动的 - 最终用户代码不需要直接使用此方法。Note that SQLAlchemy’s clause constructs take operator precedence into account - so parenthesis might not be needed, for example, in an expression like x OR (y AND z) - AND takes precedence over OR.

ClauseElement的base self_group()方法仅返回self。

unique_params （ * optionaldict，** kwargs ） T5>
inherited from the unique_params() method of ClauseElement

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

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

值 （ * args，** kwargs ） T5>
inherited from the values() method of ValuesBase

为INSERT语句指定一个固定的VALUES子句，或者为UPDATE指定一个SET子句。

Note that the Insert and Update constructs support per-execution time formatting of the VALUES and/or SET clauses, based on the arguments passed to Connection.execute(). 但是，可以使用ValuesBase.values()方法将特定的一组参数“修复”到语句中。

多次调用ValuesBase.values()将产生一个新的结构，每个结构都修改参数列表以包含发送的新参数。在单个参数字典的典型情况下，新传递的键将替换以前构造中的相同键。在基于列表的“多值”结构的情况下，每个新的值列表都被扩展到现有的值列表中。

参数：
  • ** kwargs -

    键值对表示映射到要呈现到VALUES或SET子句中的值的Column的字符串键：

    users.insert().values(name="some name")

users.update().where(users.c.id==5).values(name="some name")
  • * args -

    作为传递键/值参数的替代方法，字典，元组或字典或元组列表可以作为单个位置参数传递，以形成语句的VALUES或SET子句。接受的表单根据是Insert还是Update结构而有所不同。

    对于Insert或Update结构，可以传递单个字典，其工作方式与kwargs表单相同：

    users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})

    对于任何一种形式，但对于Insert构造更典型，也接受包含表中每列的条目的元组：

    users.insert().values((5, "some name"))

    Insert结构还支持传递字典或全表元组列表，这些元组在服务器上将呈现不太常见的“多值”SQL语法 - 后端支持此语法，如SQLite，Postgresql，MySQL，但不一定是其他的：

    users.insert().values([
                    {"name": "some name"},
                    {"name": "some other name"},
                    {"name": "yet another name"},
                ])

    上面的表单将呈现多个VALUES语句，类似于：

    INSERT INTO users (name) VALUES
                (:name_1),
                (:name_2),
                (:name_3)

    It is essential to note that passing multiple values is NOT the same as using traditional executemany() form. 上面的语法是不常用的特殊语法。要针对多行发出INSERT语句，常规方法是将多个值列表传递给Connection.execute()方法，该方法由所有数据库后端支持，并且通常对于非常高效的大量的参数。

    也可以看看

    Executing Multiple Statements - 介绍用于INSERT和其他语句的多参数集调用的传统Core方法。

    版本1.0.0中已更改：使用多个VALUES子句（即使是长度为1的列表）的INSERT意味着Insert.inline标志设置为True，表明该语句不会尝试获取“最后插入的主键”或其他默认值。该语句处理任意数量的行，因此ResultProxy.inserted_primary_key访问器不适用。

    在1.0.0版本中已更改：多值插入现在支持具有Python侧缺省值和可调参数的列，方式与“executemany”调用方式相同；可调用的是每行调用的。对于其他细节，当使用多值插入时，请参阅Python-side defaults invoked for each row invidually when using a multivalued insert

    Update结构支持一个特殊的形式，它是一个2元组的列表，当提供的时候必须和preserve_parameter_order参数一起传递。这种形式导致UPDATE语句使用Update.values()给出的参数顺序来呈现SET子句，而不是Table中给出的列的顺序。

    版本1.0.10中的新增功能： - 通过preserve_parameter_order标志增加了对参数排序的UPDATE语句的支持。

    也可以看看

    Parameter-Ordered Updates - preserve_parameter_order标志的完整示例

也可以看看

Inserts, Updates and Deletes - SQL表达式语言教程

insert() - 产生一个INSERT语句

update() - 产生一个UPDATE语句

其中 T0> （ T1> whereclause T2> ） T3> ¶ T4>

返回一个新的update()构造，将给定的表达式添加到其WHERE子句中，通过AND连接到现有子句（如果有的话）。

with_hint(text, selectable=None, dialect_name='*')
继承自 with_hint() 方法 UpdateBase

为这个INSERT / UPDATE / DELETE语句添加一个表提示给单个表。

注意

UpdateBase.with_hint() currently applies only to Microsoft SQL Server. 对于MySQL INSERT / UPDATE / DELETE提示，请使用UpdateBase.prefix_with()。

The text of the hint is rendered in the appropriate location for the database backend in use, relative to the Table that is the subject of this statement, or optionally to that of the given Table passed as the selectable argument.

The dialect_name option will limit the rendering of a particular hint to a particular backend. 例如，添加仅对SQL Server有效的提示：

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")

New in version 0.7.6.

参数：
  • 文本 - 提示的文本。
  • selectable – optional Table that specifies an element of the FROM clause within an UPDATE or DELETE to be the subject of the hint - applies only to certain backends.
  • dialect_name – defaults to *, if specified as the name of a particular dialect, will apply these hints only when that dialect is in use.
class sqlalchemy.sql.expression。 UpdateBase

基础：sqlalchemy.sql.expression.HasCTE，sqlalchemy.sql.base.DialectKWArgs，sqlalchemy.sql.expression.HasPrefixes，sqlalchemy.sql.expression.Executable，sqlalchemy.sql.expression.ClauseElement

为INSERT，UPDATE和DELETE语句形成基础。

__初始化__ T0> ¶ T1>
继承自 __init__ 属性 object

x .__ init __（...）初始化x；请参阅帮助（类型（x））进行签名

argument_for （ dialect_name，argument_name，默认 ） ¶ T6>
inherited from the argument_for() method of DialectKWArgs

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

例如。：

Index.argument_for("mydialect", "length", None)

some_index = Index('a', 'b', mydialect_length=5)

The DialectKWArgs.argument_for() method is a per-argument way adding extra arguments to the DefaultDialect.construct_arguments dictionary. 这本词典提供了代表方言的各种模式层次结构所接受的参数名称列表。

新方言通常应该一次性将该字典指定为方言类的数据成员。用于临时添加参数名称的用例通常用于最终用户代码，该代码也使用了使用额外参数的自定义编译方案。

参数：
  • dialect_name – name of a dialect. The dialect must be locatable, else a NoSuchModuleError is raised. 该方言还必须包含一个现有的DefaultDialect.construct_arguments集合，指示它参与关键字参数验证和默认系统，否则引发ArgumentError。如果方言不包括这个集合，那么任何关键字参数都可以代表这个方言指定。所有包含在SQLAlchemy中的方言都包含这个集合，但是对于第三方方言，支持可能会有所不同。
  • argument_name - 参数的名称。
  • 默认 - 参数的默认值。

版本0.9.4中的新功能

结合 T0> ¶ T1>

返回与此UpdateBase或与之关联的Table的“绑定”。

比较 （ 其他，** kw ） t5 >
inherited from the compare() method of ClauseElement

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

子类应该覆盖默认行为，这是一种直接的身份比较。

** kw是由subclass compare()方法消耗的参数，可用于修改比较条件。（请参阅ColumnElement）

编译 （ bind = None，dialect = None，** kw ） T5> ¶ T6>
inherited from the compile() method of ClauseElement

编译这个SQL表达式。

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

参数：
  • bind – An Engine or Connection from which a Compiled will be acquired. 这个参数优先于这个ClauseElement的绑定引擎，如果有的话。
  • column_keys – Used for INSERT and UPDATE statements, a list of column names which should be present in the VALUES clause of the compiled statement. 如果None，则呈现目标表格对象中的所有列。
  • dialect – A Dialect instance from which a Compiled will be acquired. 该参数优先于bind参数以及ClauseElement的绑定引擎（如果有的话）。
  • inline – Used for INSERT statements, for a dialect which does not support inline retrieval of newly generated primary key columns, will force the expression used to create the new primary key value to be rendered inline within the INSERT statement’s VALUES clause. 这通常是指序列执行，但也可能指与主键Column关联的任何服务器端默认生成函数。
  • compile_kwargs -

    在所有“访问”方法中将传递给编译器的附加参数的可选字典。例如，这允许将自定义标志传递给自定义编译构造。它也用于传递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})

    版本0.9.0中的新功能

也可以看看

How do I render SQL expressions as strings, possibly with bound parameters inlined?

cte(name=None, recursive=False)
继承自 cte() 方法 HasCTE

返回一个新的CTE或公共表表达式实例。

公用表表达式是一种SQL标准，通过使用一个名为“WITH”的子句，SELECT语句可以使用与主语句一起指定的次要语句。有关UNION的特殊语义也可用于允许“递归”查询，其中SELECT语句可以在先前已选择的一组行上进行绘制。

CTE也可以应用于DML构造对某些数据库的UPDATE，INSERT和DELETE，与RETURNING一起作为CTE行的来源以及CTE行的使用者。

SQLAlchemy将CTE对象检测为与Alias对象类似的对象，作为要传递到语句的FROM子句的特殊元素以及顶部的WITH子句的声明。

在版本1.1中进行了更改：添加了对CTE，CTE添加到UPDATE / INSERT / DELETE的UPDATE / INSERT / DELETE的支持。

参数：
  • name – name given to the common table expression. 像_FromClause.alias()一样，名称可以保留为None，在这种情况下，查询编译时将使用匿名符号。
  • recursive – if True, will render WITH RECURSIVE. 递归公用表表达式旨在与UNION ALL结合使用，以便从已选择的行中派生行。

以下示例包含两篇来自Postgresql的文档，位于http://www.postgresql.org/docs/current/static/queries-with.html以及其他示例。

例1，非递归：

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select([
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ]).group_by(orders.c.region).cte("regional_sales")


top_regions = select([regional_sales.c.region]).\
        where(
            regional_sales.c.total_sales >
            select([
                func.sum(regional_sales.c.total_sales)/10
            ])
        ).cte("top_regions")

statement = select([
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ]).where(orders.c.region.in_(
        select([top_regions.c.region])
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

例2，与RECURSIVE：

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select([
                    parts.c.sub_part,
                    parts.c.part,
                    parts.c.quantity]).\
                    where(parts.c.part=='our part').\
                    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select([
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ]).
        where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select([
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ]).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

例3，使用带CTE的UPDATE和INSERT的upsert：

orders = table(
    'orders',
    column('region'),
    column('amount'),
    column('product'),
    column('quantity')
)

upsert = (
    orders.update()
    .where(orders.c.region == 'Region1')
    .values(amount=1.0, product='Product1', quantity=1)
    .returning(*(orders.c._all_columns)).cte('upsert'))

insert = orders.insert().from_select(
    orders.c.keys(),
    select([
        literal('Region1'), literal(1.0),
        literal('Product1'), literal(1)
    ).where(exists(upsert.select()))
)

connection.execute(insert)

也可以看看

orm.query.Query.cte() - HasCTE.cte()的ORM版本。

dialect_kwargs T0> ¶ T1>
继承自 dialect_kwargs 属性 DialectKWArgs

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

这些参数在它们的原始<dialect>_<kwarg>格式中呈现。只包括实际通过的论点；不同于DialectKWArgs.dialect_options集合，其中包含此方言已知的所有选项，包括默认值。

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

版本0.9.2中的新功能

在版本0.9.4中更改： DialectKWArgs.dialect_kwargs集合现在可写入。

也可以看看

DialectKWArgs.dialect_options - nested dictionary form

dialect_options T0> ¶ T1>
继承自 dialect_options 属性 DialectKWArgs

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

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

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

版本0.9.2中的新功能

也可以看看

DialectKWArgs.dialect_kwargs - flat dictionary form

执行 tt> （ * multiparams，** params ） T5>
继承自 execute() 方法 Executable

编译并执行Executable。

execution_options T0> （ T1> **千瓦 T2> ） T3> ¶ T4>
继承自 execution_options() 方法 tt> Executable

为执行期间生效的语句设置非SQL选项。

执行选项可以在每个语句或每个Connection的基础上设置。此外，Engine和ORM Query对象提供对执行选项的访问，而这些执行选项在连接时进行配置。

execution_options()方法是生成的。返回此语句的新实例，其中包含以下选项：

statement = select([table.c.x, table.c.y])
statement = statement.execution_options(autocommit=True)

请注意，只有一部分可能的执行选项可以应用于语句 - 这些选项包括“autocommit”和“stream_results”，但不包括“isolation_level”或“c​​ompiled_cache”。有关可能的选项的完整列表，请参阅Connection.execution_options()。

也可以看看

Connection.execution_options()

Query.execution_options()

get_children T0> （ T1> ** kwargs T2> ） T3> ¶ T4>
inherited from the get_children() method of ClauseElement

返回这个ClauseElement的直接子元素。

这用于访问遍历。

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

kwargs T0> ¶ T1>
继承自 kwargs 属性 DialectKWArgs

DialectKWArgs.dialect_kwargs的同义词。

params(*arg, **kw)

设置语句的参数。

此方法在基类上引发NotImplementedError，并由ValuesBase覆盖，以提供UPDATE和INSERT的SET / VALUES子句。

prefix_with （ * expr，** kw ） T5>
继承自 prefix_with() 方法 HasPrefixes

在语句关键字后添加一个或多个表达式，即SELECT，INSERT，UPDATE或DELETE。生成。

这用于支持后端特定的前缀关键字，例如由MySQL提供的前缀关键字。

例如。：

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

可以通过多次调用prefix_with()来指定多个前缀。

参数：
  • *expr – textual or ClauseElement construct which will be rendered following the INSERT, UPDATE, or DELETE keyword.
  • ** kw - 接受单个关键字'dialect'。这是一个可选的字符串方言名称，它将限制将该前缀的呈现仅限于该方言。
返回 T0> （ T1> * COLS T2> ） T3> ¶ T4>

在此语句中添加一个RETURNING或等同的子句。

例如。：

stmt = table.update().\
          where(table.c.data == 'value').\
          values(status='X').\
          returning(table.c.server_flag,
                    table.c.updated_timestamp)

for server_flag, updated_timestamp in connection.execute(stmt):
    print(server_flag, updated_timestamp)

给定的列表达式集合应该从作为INSERT，UPDATE或DELETE目标的表中派生。虽然Column对象是典型的，但元素也可以是表达式：

stmt = table.insert().returning(
    (table.c.first_name + " " + table.c.last_name).
    label('fullname'))

编译后，将在语句中呈现RETURNING子句或数据库等效项。对于INSERT和UPDATE，这些值是新插入/更新的值。对于DELETE，这些值是那些被删除的行。

执行时，要返回的列的值通过结果集可用，并可以使用ResultProxy.fetchone()和类似的方法进行迭代。对于本身不支持返回值的DBAPI（即cx_oracle），SQLAlchemy将在结果级接近此行为，以便提供合理的行为中立性。

请注意，并非所有数据库/ DBAPI都支持RETURNING。对于不支持的后端，编译和/或执行时会引发异常。对于那些支持它的人来说，后端的功能差异很大，包括对executemany()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明，以确定RETURNING的可用性。

也可以看看

ValuesBase.return_defaults() - 针对单个行INSERT或UPDATE的高效获取服务器端默认值和触发器的一种替代方法。

标量 （ * multiparams，** params ） T5>
inherited from the scalar() method of Executable

编译并执行此Executable，返回结果的标量表示。

self_group T0> （ T1> 针对=无 T2> ） T3> ¶ T4>
inherited from the self_group() method of ClauseElement

对这个ClauseElement应用“分组”。

子类重写此方法以返回“分组”结构，即括号。In particular it’s used by “binary” expressions to provide a grouping around themselves when placed into a larger expression, as well as by select() constructs when placed into the FROM clause of another select(). （请注意，通常应使用Select.alias()方法创建子查询，因为许多平台需要命名嵌套的SELECT语句）。

由于表达式组合在一起，所以self_group()的应用程序是自动的 - 最终用户代码不需要直接使用此方法。Note that SQLAlchemy’s clause constructs take operator precedence into account - so parenthesis might not be needed, for example, in an expression like x OR (y AND z) - AND takes precedence over OR.

ClauseElement的base self_group()方法仅返回self。

unique_params （ * optionaldict，** kwargs ） T5>
inherited from the unique_params() method of ClauseElement

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

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

with_hint(text, selectable=None, dialect_name='*')

为这个INSERT / UPDATE / DELETE语句添加一个表提示给单个表。

注意

UpdateBase.with_hint() currently applies only to Microsoft SQL Server. 对于MySQL INSERT / UPDATE / DELETE提示，请使用UpdateBase.prefix_with()。

The text of the hint is rendered in the appropriate location for the database backend in use, relative to the Table that is the subject of this statement, or optionally to that of the given Table passed as the selectable argument.

The dialect_name option will limit the rendering of a particular hint to a particular backend. 例如，添加仅对SQL Server有效的提示：

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")

New in version 0.7.6.

参数：
  • 文本 - 提示的文本。
  • selectable – optional Table that specifies an element of the FROM clause within an UPDATE or DELETE to be the subject of the hint - applies only to certain backends.
  • dialect_name – defaults to *, if specified as the name of a particular dialect, will apply these hints only when that dialect is in use.
class sqlalchemy.sql.expression.ValuesBase(table, values, prefixes)

基础：sqlalchemy.sql.expression.UpdateBase

提供对ValuesBase.values()到INSERT和UPDATE结构的支持。

return_defaults T0> （ T1> * COLS T2> ） T3> ¶ T4>

利用RETURNING子句获取服务器端表达式和默认值。

例如。：

stmt = table.insert().values(data='newdata').return_defaults()

result = connection.execute(stmt)

server_created_at = result.returned_defaults['created_at']

当用于支持RETURNING的后端时，如果不同时使用UpdateBase.returning()，则由SQL表达式或server-side-default生成的所有列值将被添加到任何现有的RETURNING子句中。然后，使用ResultProxy.returned_defaults存取器作为字典，结果可以在结果上使用列值，该值指的是键入Column对象及其.key

这种方法与UpdateBase.returning()不同之处在于：

  1. ValuesBase.return_defaults()仅用于与一行匹配的INSERT或UPDATE语句。尽管一般意义上的RETURNING构造支持多行UPDATE或DELETE语句的多行，或者对于返回多行的INSERT的特殊情况（例如，来自SELECT，多值VALUES子句的INSERT），ValuesBase.return_defaults()仅用于“ORM样式”单行INSERT / UPDATE语句。当使用ValuesBase.return_defaults()时，语句返回的行也会隐式消耗。By contrast, UpdateBase.returning() leaves the RETURNING result-set intact with a collection of any number of rows.
  2. 它与现有逻辑兼容，以获取自动生成的主键值，也称为“隐式返回”。支持RETURNING的后端将自动使用RETURNING来获取新生成的主键值；而UpdateBase.returning()方法绕过了这种行为，ValuesBase.return_defaults()保持不变。
  3. 它可以被称为反对任何后端。不支持RETURNING的后端将跳过功能的使用，而不是引发异常。ResultProxy.returned_defaults的返回值将为None

ValuesBase.return_defaults() is used by the ORM to provide an efficient implementation for the eager_defaults feature of mapper().

参数：cols – optional list of column key names or Column objects. 如果省略，则服务器上评估的所有列表达式都将添加到返回列表中。

版本0.9.0中的新功能

也可以看看

UpdateBase.returning()

ResultProxy.returned_defaults

值 （ * args，** kwargs ） T5>

为INSERT语句指定一个固定的VALUES子句，或者为UPDATE指定一个SET子句。

Note that the Insert and Update constructs support per-execution time formatting of the VALUES and/or SET clauses, based on the arguments passed to Connection.execute(). 但是，可以使用ValuesBase.values()方法将特定的一组参数“修复”到语句中。

多次调用ValuesBase.values()将产生一个新的结构，每个结构都修改参数列表以包含发送的新参数。在单个参数字典的典型情况下，新传递的键将替换以前构造中的相同键。在基于列表的“多值”结构的情况下，每个新的值列表都被扩展到现有的值列表中。

参数：
  • ** kwargs -

    键值对表示映射到要呈现到VALUES或SET子句中的值的Column的字符串键：

    users.insert().values(name="some name")

users.update().where(users.c.id==5).values(name="some name")
  • * args -

    作为传递键/值参数的替代方法，字典，元组或字典或元组列表可以作为单个位置参数传递，以形成语句的VALUES或SET子句。接受的表单根据是Insert还是Update结构而有所不同。

    对于Insert或Update结构，可以传递单个字典，其工作方式与kwargs表单相同：

    users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})

    对于任何一种形式，但对于Insert构造更典型，也接受包含表中每列的条目的元组：

    users.insert().values((5, "some name"))

    Insert结构还支持传递字典或全表元组列表，这些元组在服务器上将呈现不太常见的“多值”SQL语法 - 后端支持此语法，如SQLite，Postgresql，MySQL，但不一定是其他的：

    users.insert().values([
                    {"name": "some name"},
                    {"name": "some other name"},
                    {"name": "yet another name"},
                ])

    上面的表单将呈现多个VALUES语句，类似于：

    INSERT INTO users (name) VALUES
                (:name_1),
                (:name_2),
                (:name_3)

    It is essential to note that passing multiple values is NOT the same as using traditional executemany() form. 上面的语法是不常用的特殊语法。要针对多行发出INSERT语句，常规方法是将多个值列表传递给Connection.execute()方法，该方法由所有数据库后端支持，并且通常对于非常高效的大量的参数。

    也可以看看

    Executing Multiple Statements - 介绍用于INSERT和其他语句的多参数集调用的传统Core方法。

    版本1.0.0中已更改：使用多个VALUES子句（即使是长度为1的列表）的INSERT意味着Insert.inline标志设置为True，表明该语句不会尝试获取“最后插入的主键”或其他默认值。该语句处理任意数量的行，因此ResultProxy.inserted_primary_key访问器不适用。

    在1.0.0版本中已更改：多值插入现在支持具有Python侧缺省值和可调参数的列，方式与“executemany”调用方式相同；可调用的是每行调用的。对于其他细节，当使用多值插入时，请参阅Python-side defaults invoked for each row invidually when using a multivalued insert

    Update结构支持一个特殊的形式，它是一个2元组的列表，当提供的时候必须和preserve_parameter_order参数一起传递。这种形式导致UPDATE语句使用Update.values()给出的参数顺序来呈现SET子句，而不是Table中给出的列的顺序。

    版本1.0.10中的新增功能： - 通过preserve_parameter_order标志增加了对参数排序的UPDATE语句的支持。

    也可以看看

    Parameter-Ordered Updates - preserve_parameter_order标志的完整示例

也可以看看

Inserts, Updates and Deletes - SQL表达式语言教程

insert() - 产生一个INSERT语句

update() - 产生一个UPDATE语句