版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

插入、更新、删除

INSERT,UPDATE和DELETE语句建立在从UpdateBase开始的层次上。InsertUpdate在中间值ValuesBase上构建。

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

构建删除对象.

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

参数:
  • table – The table to delete rows from.
  • 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() 方法 得到.

参数:
  • tableTableClause 是插入的主题
  • values – collection of values to be inserted; see Insert.values() for a description of allowed formats here. 完全可以省略;一个Insert结构也将根据传递给Connection.execute()的参数在执行时动态地呈现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对象或其字符串标识符。每个密钥可以引用以下之一:

  • 文字数据值(即字符串,数字等));
  • 一个Column对象;
  • 一个SELECT语句。

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

也可以看看

Insert Expressions - SQL Expression Tutorial

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 -

    描述UPDATE语句的WHERE条件的可选SQL表达式。现代应用程序可能更喜欢使用生成的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()
            )

    在0.7.4版中更改: WHERE子句可以引用多个表。

  • -

    可选字典,指定UPDATESET条件。如果保留为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中引用的值通常是:

  • 文字数据值(即字符串,数字等)
  • a SQL expression, such as a related Column, a scalar-returning select() construct, etc.

当在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, default)
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. The dialect must also include an existing DefaultDialect.construct_arguments collection, indicating that it participates in the keyword-argument validation and default system, else ArgumentError is raised. 如果方言不包括这个集合,那么任何关键字参数都可以代表这个方言指定。所有包含在SQLAlchemy中的方言都包括这个集合,但是对于第三方方言,支持可能会有所不同。
  • 参数名称 - 参数的名称。
  • 默认 - 参数的默认值。

版本0.9.4中的新功能

结合 T0> ¶ T1>
inherited from the bind attribute of UpdateBase

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

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

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

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

** kw是由subclass compare()方法消耗的参数,可以用来修改比较条件。(请参见ColumnElement

编译 tt> bind = Nonedialect = 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中新增。

cte(name=None, recursive=False)
inherited from the cte() method of HasCTE

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

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

CTE也可以应用于DML构造在某些数据库上的UPDATE,INSERT和DELETE,当与RETURNING结合使用时,它们都是CTE行的来源,同时也是CTE行的使用者。

SQLAlchemy将CTE对象(与Alias对象的处理方式类似)视为要传递到语句的FROM子句的特殊元素,以及顶部的WITH子句的声明。

在版本1.1中改变:增加了对UPDATE / INSERT / DELETE的支持,因为CTE,CTE添加到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,一个使用UPDATE和INSERT和CTE的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>格式中呈现。Only arguments that were actually passed are included; unlike the DialectKWArgs.dialect_options collection, which contains all options known by this dialect including defaults.

收藏也是可写的;键被接受为形式<dialect>_<kwarg>,其中值将被组合到选项列表中。

版本0.9.2中的新功能

在版本0.9.4中更改: DialectKWArgs.dialect_kwargs集合现在是可写的。

也可以看看

DialectKWArgs.dialect_options - nested dictionary form

dialect_options T0> ¶ T1>
inherited from the dialect_options attribute of DialectKWArgs

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

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

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

版本0.9.2中的新功能

也可以看看

DialectKWArgs.dialect_kwargs - flat dictionary form

execute(*multiparams, **params)
继承自 execute() 方法 Executable

编译并执行这个Executable

execution_options T0> ( T1> **千瓦 T2> ) T3> ¶ T4>
inherited from the execution_options() method of 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()

kwargs T0> ¶ T1>
inherited from the kwargs attribute of DialectKWArgs

A synonym for DialectKWArgs.dialect_kwargs.

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

设置语句的参数。

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

prefix_with * expr** kw T5>
inherited from the prefix_with() method of 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()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明,以确定返回的可用性。

也可以看看

ValuesBase.return_defaults() - an alternative method tailored towards efficient fetching of server-side defaults and triggers for single-row INSERTs or UPDATEs.

标量 * 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='*')
inherited from the with_hint() method of 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构造。

The Insert object is created using the insert() function.

也可以看看

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, default)
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. The dialect must also include an existing DefaultDialect.construct_arguments collection, indicating that it participates in the keyword-argument validation and default system, else ArgumentError is raised. 如果方言不包括这个集合,那么任何关键字参数都可以代表这个方言指定。所有包含在SQLAlchemy中的方言都包括这个集合,但是对于第三方方言,支持可能会有所不同。
  • 参数名称 - 参数的名称。
  • 默认 - 参数的默认值。

版本0.9.4中的新功能

结合 T0> ¶ T1>
inherited from the bind attribute of UpdateBase

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

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

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

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

** kw是由subclass compare()方法消耗的参数,可以用来修改比较条件。(请参见ColumnElement

编译 tt> bind = Nonedialect = 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中新增。

cte(name=None, recursive=False)
inherited from the cte() method of HasCTE

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

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

CTE也可以应用于DML构造在某些数据库上的UPDATE,INSERT和DELETE,当与RETURNING结合使用时,它们都是CTE行的来源,同时也是CTE行的使用者。

SQLAlchemy将CTE对象(与Alias对象的处理方式类似)视为要传递到语句的FROM子句的特殊元素,以及顶部的WITH子句的声明。

在版本1.1中改变:增加了对UPDATE / INSERT / DELETE的支持,因为CTE,CTE添加到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,一个使用UPDATE和INSERT和CTE的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>格式中呈现。Only arguments that were actually passed are included; unlike the DialectKWArgs.dialect_options collection, which contains all options known by this dialect including defaults.

收藏也是可写的;键被接受为形式<dialect>_<kwarg>,其中值将被组合到选项列表中。

版本0.9.2中的新功能

在版本0.9.4中更改: DialectKWArgs.dialect_kwargs集合现在是可写的。

也可以看看

DialectKWArgs.dialect_options - nested dictionary form

dialect_options T0> ¶ T1>
inherited from the dialect_options attribute of DialectKWArgs

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

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

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

版本0.9.2中的新功能

也可以看看

DialectKWArgs.dialect_kwargs - flat dictionary form

execute(*multiparams, **params)
继承自 execute() 方法 Executable

编译并执行这个Executable

execution_options T0> ( T1> **千瓦 T2> ) T3> ¶ T4>
inherited from the execution_options() method of 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()

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表达式列的默认值呈现给SELECT语句中的列,否则列表中不包括列名称。

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

0.8.3版本中的新功能

kwargs T0> ¶ T1>
inherited from the kwargs attribute of DialectKWArgs

A synonym for DialectKWArgs.dialect_kwargs.

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

设置语句的参数。

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

prefix_with * expr** kw T5>
inherited from the prefix_with() method of 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>
inherited from the return_defaults() method of 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 - 列键名称的可选列表或Column对象。如果省略,则服务器上评估的所有列表达式都将添加到返回列表中。

版本0.9.0中新增。

返回 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()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明,以确定返回的可用性。

也可以看看

ValuesBase.return_defaults() - an alternative method tailored towards efficient fetching of server-side defaults and triggers for single-row INSERTs or UPDATEs.

标量 * 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子句。接受的表单根据是否为InsertUpdate结构而有所不同。

    对于InsertUpdate结构,可以传递单个字典,其工作方式与kwargs表单相同:

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

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

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

    The Insert construct also supports being passed a list of dictionaries or full-table-tuples, which on the server will render the less common SQL syntax of “multiple values” - this syntax is supported on backends such as SQLite, Postgresql, MySQL, but not necessarily others:

    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() - produce an INSERT statement

update() - 产生一个UPDATE语句

with_hint(text, selectable=None, dialect_name='*')
inherited from the with_hint() method of 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, default)
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. The dialect must also include an existing DefaultDialect.construct_arguments collection, indicating that it participates in the keyword-argument validation and default system, else ArgumentError is raised. 如果方言不包括这个集合,那么任何关键字参数都可以代表这个方言指定。所有包含在SQLAlchemy中的方言都包括这个集合,但是对于第三方方言,支持可能会有所不同。
  • 参数名称 - 参数的名称。
  • 默认 - 参数的默认值。

版本0.9.4中的新功能

结合 T0> ¶ T1>
inherited from the bind attribute of UpdateBase

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

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

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

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

** kw是由subclass compare()方法消耗的参数,可以用来修改比较条件。(请参见ColumnElement

编译 tt> bind = Nonedialect = 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中新增。

cte(name=None, recursive=False)
inherited from the cte() method of HasCTE

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

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

CTE也可以应用于DML构造在某些数据库上的UPDATE,INSERT和DELETE,当与RETURNING结合使用时,它们都是CTE行的来源,同时也是CTE行的使用者。

SQLAlchemy将CTE对象(与Alias对象的处理方式类似)视为要传递到语句的FROM子句的特殊元素,以及顶部的WITH子句的声明。

在版本1.1中改变:增加了对UPDATE / INSERT / DELETE的支持,因为CTE,CTE添加到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,一个使用UPDATE和INSERT和CTE的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>格式中呈现。Only arguments that were actually passed are included; unlike the DialectKWArgs.dialect_options collection, which contains all options known by this dialect including defaults.

收藏也是可写的;键被接受为形式<dialect>_<kwarg>,其中值将被组合到选项列表中。

版本0.9.2中的新功能

在版本0.9.4中更改: DialectKWArgs.dialect_kwargs集合现在是可写的。

也可以看看

DialectKWArgs.dialect_options - nested dictionary form

dialect_options T0> ¶ T1>
inherited from the dialect_options attribute of DialectKWArgs

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

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

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

版本0.9.2中的新功能

也可以看看

DialectKWArgs.dialect_kwargs - flat dictionary form

execute(*multiparams, **params)
继承自 execute() 方法 Executable

编译并执行这个Executable

execution_options T0> ( T1> **千瓦 T2> ) T3> ¶ T4>
inherited from the execution_options() method of 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()

kwargs T0> ¶ T1>
inherited from the kwargs attribute of DialectKWArgs

A synonym for DialectKWArgs.dialect_kwargs.

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

设置语句的参数。

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

prefix_with * expr** kw T5>
inherited from the prefix_with() method of 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>
inherited from the return_defaults() method of 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 - 列键名称的可选列表或Column对象。如果省略,则服务器上评估的所有列表达式都将添加到返回列表中。

版本0.9.0中新增。

返回 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()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明,以确定返回的可用性。

也可以看看

ValuesBase.return_defaults() - an alternative method tailored towards efficient fetching of server-side defaults and triggers for single-row INSERTs or UPDATEs.

标量 * 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子句。接受的表单根据是否为InsertUpdate结构而有所不同。

    对于InsertUpdate结构,可以传递单个字典,其工作方式与kwargs表单相同:

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

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

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

    The Insert construct also supports being passed a list of dictionaries or full-table-tuples, which on the server will render the less common SQL syntax of “multiple values” - this syntax is supported on backends such as SQLite, Postgresql, MySQL, but not necessarily others:

    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() - produce an INSERT statement

update() - 产生一个UPDATE语句

其中 T0> ( T1> whereclause T2> ) T3> ¶ T4>

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

with_hint(text, selectable=None, dialect_name='*')
inherited from the with_hint() method of 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.HasCTEsqlalchemy.sql.base.DialectKWArgssqlalchemy.sql.expression.HasPrefixessqlalchemy.sql.expression.Executablesqlalchemy.sql.expression.ClauseElement

形成INSERTUPDATEDELETE语句的基础。

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(类型(x))进行签名

argument_for(dialect_name, argument_name, default)
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. The dialect must also include an existing DefaultDialect.construct_arguments collection, indicating that it participates in the keyword-argument validation and default system, else ArgumentError is raised. 如果方言不包括这个集合,那么任何关键字参数都可以代表这个方言指定。所有包含在SQLAlchemy中的方言都包括这个集合,但是对于第三方方言,支持可能会有所不同。
  • 参数名称 - 参数的名称。
  • 默认 - 参数的默认值。

版本0.9.4中的新功能

结合 T0> ¶ T1>

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

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

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

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

** kw是由subclass compare()方法消耗的参数,可以用来修改比较条件。(请参见ColumnElement

编译 tt> bind = Nonedialect = 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中新增。

cte(name=None, recursive=False)
inherited from the cte() method of HasCTE

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

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

CTE也可以应用于DML构造在某些数据库上的UPDATE,INSERT和DELETE,当与RETURNING结合使用时,它们都是CTE行的来源,同时也是CTE行的使用者。

SQLAlchemy将CTE对象(与Alias对象的处理方式类似)视为要传递到语句的FROM子句的特殊元素,以及顶部的WITH子句的声明。

在版本1.1中改变:增加了对UPDATE / INSERT / DELETE的支持,因为CTE,CTE添加到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,一个使用UPDATE和INSERT和CTE的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>格式中呈现。Only arguments that were actually passed are included; unlike the DialectKWArgs.dialect_options collection, which contains all options known by this dialect including defaults.

收藏也是可写的;键被接受为形式<dialect>_<kwarg>,其中值将被组合到选项列表中。

版本0.9.2中的新功能

在版本0.9.4中更改: DialectKWArgs.dialect_kwargs集合现在是可写的。

也可以看看

DialectKWArgs.dialect_options - nested dictionary form

dialect_options T0> ¶ T1>
inherited from the dialect_options attribute of DialectKWArgs

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

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

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

版本0.9.2中的新功能

也可以看看

DialectKWArgs.dialect_kwargs - flat dictionary form

execute(*multiparams, **params)
继承自 execute() 方法 Executable

编译并执行这个Executable

execution_options T0> ( T1> **千瓦 T2> ) T3> ¶ T4>
inherited from the execution_options() method of 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()

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

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

这用于访问遍历。

** kwargs可能包含标志,这些标志会改变返回的集合,例如为了减少较大的遍历而返回一个项目的子集,或者从不同的上下文中返回子项目(比如模式级集合而不是子句-水平)。

kwargs T0> ¶ T1>
inherited from the kwargs attribute of DialectKWArgs

A synonym for DialectKWArgs.dialect_kwargs.

params * arg** kw T5>

设置语句的参数。

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

prefix_with * expr** kw T5>
inherited from the prefix_with() method of 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()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明,以确定返回的可用性。

也可以看看

ValuesBase.return_defaults() - an alternative method tailored towards efficient fetching of server-side defaults and triggers for single-row INSERTs or UPDATEs.

标量 * 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 - 列键名称的可选列表或Column对象。如果省略,则服务器上评估的所有列表达式都将添加到返回列表中。

版本0.9.0中新增。

* 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子句。接受的表单根据是否为InsertUpdate结构而有所不同。

    对于InsertUpdate结构,可以传递单个字典,其工作方式与kwargs表单相同:

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

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

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

    The Insert construct also supports being passed a list of dictionaries or full-table-tuples, which on the server will render the less common SQL syntax of “multiple values” - this syntax is supported on backends such as SQLite, Postgresql, MySQL, but not necessarily others:

    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() - produce an INSERT statement

update() - 产生一个UPDATE语句