File: dml.html

package info (click to toggle)
sqlalchemy 0.9.8%2Bdfsg-0.1
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd
size: 23,952 kB
ctags: 24,534
sloc: python: 152,282; ansic: 1,346; makefile: 257; xml: 17
file content (2643 lines) | stat: -rw-r--r-- 287,818 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        
        <title>
            
    
                Insert, Updates, Deletes
             &mdash;
    SQLAlchemy 0.9 Documentation

        </title>

        
            <!-- begin iterate through SQLA + sphinx environment css_files -->
                <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
                <link rel="stylesheet" href="../_static/docs.css" type="text/css" />
                <link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
                <link rel="stylesheet" href="../_static/changelog.css" type="text/css" />
            <!-- end iterate through SQLA + sphinx environment css_files -->
        

        

    

    <!-- begin layout.mako headers -->

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '../',
          VERSION:     '0.9.8',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: '.html'
      };
    </script>

    <!-- begin iterate through sphinx environment script_files -->
        <script type="text/javascript" src="../_static/jquery.js"></script>
        <script type="text/javascript" src="../_static/underscore.js"></script>
        <script type="text/javascript" src="../_static/doctools.js"></script>
    <!-- end iterate through sphinx environment script_files -->

    <script type="text/javascript" src="../_static/detectmobile.js"></script>
    <script type="text/javascript" src="../_static/init.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
        <link rel="copyright" title="Copyright" href="../copyright.html" />
    <link rel="top" title="SQLAlchemy 0.9 Documentation" href="../index.html" />
        <link rel="up" title="SQL Statements and Expressions API" href="expression_api.html" />
        <link rel="next" title="SQL and Generic Functions" href="functions.html" />
        <link rel="prev" title="Selectables, Tables, FROM objects" href="selectable.html" />
    <!-- end layout.mako headers -->


    </head>
    <body>
        















<div id="docs-container">





<div id="docs-top-navigation-container" class="body-background">
<div id="docs-header">
    <div id="docs-version-header">
        Release: <span class="version-num">0.9.8</span> | Release Date: October 13, 2014
    </div>

    <h1>SQLAlchemy 0.9 Documentation</h1>

</div>
</div>

<div id="docs-body-container">

    <div id="fixed-sidebar" class="withsidebar">


        <div id="docs-sidebar-popout">
            <h3><a href="../index.html">SQLAlchemy 0.9 Documentation</a></h3>

            <p id="sidebar-paginate">
                    <a href="expression_api.html" title="SQL Statements and Expressions API">Up</a> |

                    <a href="selectable.html" title="Selectables, Tables, FROM objects">Prev</a> |
                    <a href="functions.html" title="SQL and Generic Functions">Next</a>
            </p>

            <p id="sidebar-topnav">
                <a href="../index.html">Contents</a> |
                <a href="../genindex.html">Index</a>
            </p>

            <div id="sidebar-search">
                <form class="search" action="../search.html" method="get">
                  <input type="text" name="q" size="12" /> <input type="submit" value="Search" />
                  <input type="hidden" name="check_keywords" value="yes" />
                  <input type="hidden" name="area" value="default" />
                </form>
            </div>

        </div>

        <div id="docs-sidebar">

        <h3><a href="#">            
                Insert, Updates, Deletes
            
        </a></h3>
        <ul>
<li><a class="reference internal" href="#">Insert, Updates, Deletes</a></li>
</ul>




        </div>

    </div>

    

    <div id="docs-body" class="withsidebar" >
        
<div class="section" id="insert-updates-deletes">
<h1>Insert, Updates, Deletes<a class="headerlink" href="#insert-updates-deletes" title="Permalink to this headline">¶</a></h1>
<p>INSERT, UPDATE and DELETE statements build on a hierarchy starting
with <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a>.   The <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update</span></tt></a>
constructs build on the intermediary <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">ValuesBase</span></tt></a>.</p>
<span class="target" id="module-sqlalchemy.sql.expression"></span><dl class="function">
<dt id="sqlalchemy.sql.expression.delete">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">delete</tt><big>(</big><em>table</em>, <em>whereclause=None</em>, <em>bind=None</em>, <em>returning=None</em>, <em>prefixes=None</em>, <em>**dialect_kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.delete" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct <a class="reference internal" href="#sqlalchemy.sql.expression.Delete" title="sqlalchemy.sql.expression.Delete"><tt class="xref py py-class docutils literal"><span class="pre">Delete</span></tt></a> object.</p>
<p>Similar functionality is available via the
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.TableClause.delete" title="sqlalchemy.sql.expression.TableClause.delete"><tt class="xref py py-meth docutils literal"><span class="pre">delete()</span></tt></a> method on
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.delete.params.table"></span><strong>table</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.delete.params.table">¶</a> &#8211; The table to delete rows from.</li>
<li><span class="target" id="sqlalchemy.sql.expression.delete.params.whereclause"></span><strong>whereclause</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.delete.params.whereclause">¶</a> &#8211; A <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a> describing the <tt class="docutils literal"><span class="pre">WHERE</span></tt>
condition of the <tt class="docutils literal"><span class="pre">DELETE</span></tt> statement. Note that the
<a class="reference internal" href="#sqlalchemy.sql.expression.Delete.where" title="sqlalchemy.sql.expression.Delete.where"><tt class="xref py py-meth docutils literal"><span class="pre">where()</span></tt></a> generative method may be used instead.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="tutorial.html#deletes"><em>Deletes</em></a> - SQL Expression Tutorial</p>
</div>
</dd></dl>

<dl class="function">
<dt id="sqlalchemy.sql.expression.insert">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">insert</tt><big>(</big><em>table</em>, <em>values=None</em>, <em>inline=False</em>, <em>bind=None</em>, <em>prefixes=None</em>, <em>returning=None</em>, <em>return_defaults=False</em>, <em>**dialect_kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.insert" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct an <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> object.</p>
<p>Similar functionality is available via the
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.TableClause.insert" title="sqlalchemy.sql.expression.TableClause.insert"><tt class="xref py py-meth docutils literal"><span class="pre">insert()</span></tt></a> method on
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.insert.params.table"></span><strong>table</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.insert.params.table">¶</a> &#8211; <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.TableClause" title="sqlalchemy.sql.expression.TableClause"><tt class="xref py py-class docutils literal"><span class="pre">TableClause</span></tt></a> which is the subject of the
insert.</li>
<li><span class="target" id="sqlalchemy.sql.expression.insert.params.values"></span><strong>values</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.insert.params.values">¶</a> &#8211; collection of values to be inserted; see
<a class="reference internal" href="#sqlalchemy.sql.expression.Insert.values" title="sqlalchemy.sql.expression.Insert.values"><tt class="xref py py-meth docutils literal"><span class="pre">Insert.values()</span></tt></a> for a description of allowed formats here.
Can be omitted entirely; a <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> construct will also
dynamically render the VALUES clause at execution time based on
the parameters passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>.</li>
<li><span class="target" id="sqlalchemy.sql.expression.insert.params.inline"></span><strong>inline</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.insert.params.inline">¶</a> &#8211; if True, SQL defaults will be compiled &#8216;inline&#8217; into
the statement and not pre-executed.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>If both <cite>values</cite> and compile-time bind parameters are present, the
compile-time bind parameters override the information specified
within <cite>values</cite> on a per-key basis.</p>
<p>The keys within <cite>values</cite> can be either
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> objects or their string
identifiers. Each key may reference one of:</p>
<ul class="simple">
<li>a literal data value (i.e. string, number, etc.);</li>
<li>a Column object;</li>
<li>a SELECT statement.</li>
</ul>
<p>If a <tt class="docutils literal"><span class="pre">SELECT</span></tt> statement is specified which references this
<tt class="docutils literal"><span class="pre">INSERT</span></tt> statement&#8217;s table, the statement will be correlated
against the <tt class="docutils literal"><span class="pre">INSERT</span></tt> statement.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="tutorial.html#coretutorial-insert-expressions"><em>Insert Expressions</em></a> - SQL Expression Tutorial</p>
<p class="last"><a class="reference internal" href="tutorial.html#inserts-and-updates"><em>Inserts, Updates and Deletes</em></a> - SQL Expression Tutorial</p>
</div>
</dd></dl>

<dl class="function">
<dt id="sqlalchemy.sql.expression.update">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">update</tt><big>(</big><em>table</em>, <em>whereclause=None</em>, <em>values=None</em>, <em>inline=False</em>, <em>bind=None</em>, <em>prefixes=None</em>, <em>returning=None</em>, <em>return_defaults=False</em>, <em>**dialect_kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.update" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct an <a class="reference internal" href="#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update</span></tt></a> object.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">update</span>

<span class="n">stmt</span> <span class="o">=</span> <span class="n">update</span><span class="p">(</span><span class="n">users</span><span class="p">)</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">users</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span>\
        <span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;user #5&#39;</span><span class="p">)</span></pre></div>
</div>
<p>Similar functionality is available via the
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.TableClause.update" title="sqlalchemy.sql.expression.TableClause.update"><tt class="xref py py-meth docutils literal"><span class="pre">update()</span></tt></a> method on
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">users</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span>\
            <span class="n">where</span><span class="p">(</span><span class="n">users</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span>\
            <span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;user #5&#39;</span><span class="p">)</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.update.params.table"></span><strong>table</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.update.params.table">¶</a> &#8211; A <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> object representing the database
table to be updated.</li>
<li><span class="target" id="sqlalchemy.sql.expression.update.params.whereclause"></span><strong>whereclause</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.update.params.whereclause">¶</a> &#8211; <p>Optional SQL expression describing the <tt class="docutils literal"><span class="pre">WHERE</span></tt>
condition of the <tt class="docutils literal"><span class="pre">UPDATE</span></tt> statement.   Modern applications
may prefer to use the generative <a class="reference internal" href="#sqlalchemy.sql.expression.Update.where" title="sqlalchemy.sql.expression.Update.where"><tt class="xref py py-meth docutils literal"><span class="pre">where()</span></tt></a>
method to specify the <tt class="docutils literal"><span class="pre">WHERE</span></tt> clause.</p>
<p>The WHERE clause can refer to multiple tables.
For databases which support this, an <tt class="docutils literal"><span class="pre">UPDATE</span> <span class="pre">FROM</span></tt> clause will
be generated, or on MySQL, a multi-table update.  The statement
will fail on databases that don&#8217;t have support for multi-table
update statements.  A SQL-standard method of referring to
additional tables in the WHERE clause is to use a correlated
subquery:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&#39;ed&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">where</span><span class="p">(</span>
        <span class="n">users</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="o">==</span><span class="n">select</span><span class="p">([</span><span class="n">addresses</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">email_address</span><span class="p">])</span><span class="o">.</span>\
                    <span class="n">where</span><span class="p">(</span><span class="n">addresses</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">user_id</span><span class="o">==</span><span class="n">users</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span>\
                    <span class="n">as_scalar</span><span class="p">()</span>
        <span class="p">)</span></pre></div>
</div>
<div class="versionchanged">
<p><span>Changed in version 0.7.4: </span>The WHERE clause can refer to multiple tables.</p>
</div>
</li>
<li><span class="target" id="sqlalchemy.sql.expression.update.params.values"></span><strong>values</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.update.params.values">¶</a> &#8211; <p>Optional dictionary which specifies the <tt class="docutils literal"><span class="pre">SET</span></tt> conditions of the
<tt class="docutils literal"><span class="pre">UPDATE</span></tt>.  If left as <tt class="docutils literal"><span class="pre">None</span></tt>, the <tt class="docutils literal"><span class="pre">SET</span></tt>
conditions are determined from those parameters passed to the
statement during the execution and/or compilation of the
statement.   When compiled standalone without any parameters,
the <tt class="docutils literal"><span class="pre">SET</span></tt> clause generates for all columns.</p>
<p>Modern applications may prefer to use the generative
<a class="reference internal" href="#sqlalchemy.sql.expression.Update.values" title="sqlalchemy.sql.expression.Update.values"><tt class="xref py py-meth docutils literal"><span class="pre">Update.values()</span></tt></a> method to set the values of the
UPDATE statement.</p>
</li>
<li><span class="target" id="sqlalchemy.sql.expression.update.params.inline"></span><strong>inline</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.update.params.inline">¶</a> &#8211; 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 &#8216;inline&#8217; within the
statement without the need to pre-execute them beforehand; for
backends that support &#8220;returning&#8221;, this turns off the &#8220;implicit
returning&#8221; feature for the statement.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>If both <tt class="docutils literal"><span class="pre">values</span></tt> and compile-time bind parameters are present, the
compile-time bind parameters override the information specified
within <tt class="docutils literal"><span class="pre">values</span></tt> on a per-key basis.</p>
<p>The keys within <tt class="docutils literal"><span class="pre">values</span></tt> can be either <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>
objects or their string identifiers (specifically the &#8220;key&#8221; of the
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>, normally but not necessarily equivalent to
its &#8220;name&#8221;).  Normally, the
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> objects used here are expected to be
part of the target <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> that is the table
to be updated.  However when using MySQL, a multiple-table
UPDATE statement can refer to columns from any of
the tables referred to in the WHERE clause.</p>
<p>The values referred to in <tt class="docutils literal"><span class="pre">values</span></tt> are typically:</p>
<ul class="simple">
<li>a literal data value (i.e. string, number, etc.)</li>
<li>a SQL expression, such as a related <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>,
a scalar-returning <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> construct,
etc.</li>
</ul>
<p>When combining <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> constructs within the values
clause of an <a class="reference internal" href="#sqlalchemy.sql.expression.update" title="sqlalchemy.sql.expression.update"><tt class="xref py py-func docutils literal"><span class="pre">update()</span></tt></a> construct,
the subquery represented by the <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> should be
<em>correlated</em> to the parent table, that is, providing criterion
which links the table inside the subquery to the outer table
being updated:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">(</span>
        <span class="n">name</span><span class="o">=</span><span class="n">select</span><span class="p">([</span><span class="n">addresses</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">email_address</span><span class="p">])</span><span class="o">.</span>\
                <span class="n">where</span><span class="p">(</span><span class="n">addresses</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">user_id</span><span class="o">==</span><span class="n">users</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span>\
                <span class="n">as_scalar</span><span class="p">()</span>
    <span class="p">)</span></pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="tutorial.html#inserts-and-updates"><em>Inserts, Updates and Deletes</em></a> - SQL Expression
Language Tutorial</p>
</div>
</dd></dl>

<dl class="class">
<dt id="sqlalchemy.sql.expression.Delete">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">Delete</tt><big>(</big><em>table</em>, <em>whereclause=None</em>, <em>bind=None</em>, <em>returning=None</em>, <em>prefixes=None</em>, <em>**dialect_kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.UpdateBase</span></tt></a></p>
<p>Represent a DELETE construct.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.Delete" title="sqlalchemy.sql.expression.Delete"><tt class="xref py py-class docutils literal"><span class="pre">Delete</span></tt></a> object is created using the <a class="reference internal" href="#sqlalchemy.sql.expression.delete" title="sqlalchemy.sql.expression.delete"><tt class="xref py py-func docutils literal"><span class="pre">delete()</span></tt></a>
function.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.__init__">
<tt class="descname">__init__</tt><big>(</big><em>table</em>, <em>whereclause=None</em>, <em>bind=None</em>, <em>returning=None</em>, <em>prefixes=None</em>, <em>**dialect_kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.Delete" title="sqlalchemy.sql.expression.Delete"><tt class="xref py py-class docutils literal"><span class="pre">Delete</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.delete" title="sqlalchemy.sql.expression.delete"><tt class="xref py py-func docutils literal"><span class="pre">delete()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>

<dl class="classmethod">
<dt id="sqlalchemy.sql.expression.Delete.argument_for">
<em class="property">classmethod </em><tt class="descname">argument_for</tt><big>(</big><em>dialect_name</em>, <em>argument_name</em>, <em>default</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.argument_for" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.argument_for" title="sqlalchemy.sql.base.DialectKWArgs.argument_for"><tt class="xref py py-meth docutils literal"><span class="pre">argument_for()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>Add a new kind of dialect-specific keyword argument for this class.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Index</span><span class="o">.</span><span class="n">argument_for</span><span class="p">(</span><span class="s">&quot;mydialect&quot;</span><span class="p">,</span> <span class="s">&quot;length&quot;</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>

<span class="n">some_index</span> <span class="o">=</span> <span class="n">Index</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">,</span> <span class="s">&#39;b&#39;</span><span class="p">,</span> <span class="n">mydialect_length</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.argument_for" title="sqlalchemy.sql.base.DialectKWArgs.argument_for"><tt class="xref py py-meth docutils literal"><span class="pre">DialectKWArgs.argument_for()</span></tt></a> method is a per-argument
way adding extra arguments to the
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> dictionary. This
dictionary provides a list of argument names accepted by various
schema-level constructs on behalf of a dialect.</p>
<p>New dialects should typically specify this dictionary all at once as a
data member of the dialect class.  The use case for ad-hoc addition of
argument names is typically for end-user code that is also using
a custom compilation scheme which consumes the additional arguments.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Delete.argument_for.params.dialect_name"></span><strong>dialect_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.argument_for.params.dialect_name">¶</a> &#8211; name of a dialect.  The dialect must be
locatable, else a <tt class="xref py py-class docutils literal"><span class="pre">NoSuchModuleError</span></tt> is raised.   The
dialect must also include an existing
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> collection, indicating
that it participates in the keyword-argument validation and default
system, else <tt class="xref py py-class docutils literal"><span class="pre">ArgumentError</span></tt> is raised.  If the dialect does
not include this collection, then any keyword argument can be
specified on behalf of this dialect already.  All dialects packaged
within SQLAlchemy include this collection, however for third party
dialects, support may vary.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Delete.argument_for.params.argument_name"></span><strong>argument_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.argument_for.params.argument_name">¶</a> &#8211; name of the parameter.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Delete.argument_for.params.default"></span><strong>default</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.argument_for.params.default">¶</a> &#8211; default value of the parameter.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.9.4.</span></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Delete.bind">
<tt class="descname">bind</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.bind" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.bind" title="sqlalchemy.sql.expression.UpdateBase.bind"><tt class="xref py py-attr docutils literal"><span class="pre">bind</span></tt></a> <em>attribute of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Return a &#8216;bind&#8217; linked to this <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a>
or a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> associated with it.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.compare">
<tt class="descname">compare</tt><big>(</big><em>other</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.compare" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.compare" title="sqlalchemy.sql.expression.ClauseElement.compare"><tt class="xref py py-meth docutils literal"><span class="pre">compare()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Compare this ClauseElement to the given ClauseElement.</p>
<p>Subclasses should override the default behavior, which is a
straight identity comparison.</p>
<p>**kw are arguments consumed by subclass compare() methods and
may be used to modify the criteria for comparison.
(see <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>)</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.compile">
<tt class="descname">compile</tt><big>(</big><em>bind=None</em>, <em>dialect=None</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.compile" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.compile" title="sqlalchemy.sql.expression.ClauseElement.compile"><tt class="xref py py-meth docutils literal"><span class="pre">compile()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Compile this SQL expression.</p>
<p>The return value is a <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object.
Calling <tt class="docutils literal"><span class="pre">str()</span></tt> or <tt class="docutils literal"><span class="pre">unicode()</span></tt> on the returned value will yield a
string representation of the result. The
<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object also can return a
dictionary of bind parameter names and values
using the <tt class="docutils literal"><span class="pre">params</span></tt> accessor.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Delete.compile.params.bind"></span><strong>bind</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.compile.params.bind">¶</a> &#8211; An <tt class="docutils literal"><span class="pre">Engine</span></tt> or <tt class="docutils literal"><span class="pre">Connection</span></tt> from which a
<tt class="docutils literal"><span class="pre">Compiled</span></tt> will be acquired. This argument takes precedence over
this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>&#8216;s bound engine, if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Delete.compile.params.column_keys"></span><strong>column_keys</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.compile.params.column_keys">¶</a> &#8211; Used for INSERT and UPDATE statements, a list of
column names which should be present in the VALUES clause of the
compiled statement. If <tt class="docutils literal"><span class="pre">None</span></tt>, all columns from the target table
object are rendered.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Delete.compile.params.dialect"></span><strong>dialect</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.compile.params.dialect">¶</a> &#8211; A <tt class="docutils literal"><span class="pre">Dialect</span></tt> instance from which a <tt class="docutils literal"><span class="pre">Compiled</span></tt>
will be acquired. This argument takes precedence over the <cite>bind</cite>
argument as well as this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>&#8216;s bound engine,
if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Delete.compile.params.inline"></span><strong>inline</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.compile.params.inline">¶</a> &#8211; 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&#8217;s
VALUES clause. This typically refers to Sequence execution but may
also refer to any server-side default generation function
associated with a primary key <cite>Column</cite>.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Delete.compile.params.compile_kwargs"></span><strong>compile_kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.compile.params.compile_kwargs">¶</a> &#8211; <p>optional dictionary of additional parameters
that will be passed through to the compiler within all &#8220;visit&#8221;
methods.  This allows any custom flag to be passed through to
a custom compilation construct, for example.  It is also used
for the case of passing the <tt class="docutils literal"><span class="pre">literal_binds</span></tt> flag through:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">table</span><span class="p">,</span> <span class="n">column</span><span class="p">,</span> <span class="n">select</span>

<span class="n">t</span> <span class="o">=</span> <span class="n">table</span><span class="p">(</span><span class="s">&#39;t&#39;</span><span class="p">,</span> <span class="n">column</span><span class="p">(</span><span class="s">&#39;x&#39;</span><span class="p">))</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span> <span class="o">==</span> <span class="mi">5</span><span class="p">)</span>

<span class="k">print</span> <span class="n">s</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">compile_kwargs</span><span class="o">=</span><span class="p">{</span><span class="s">&quot;literal_binds&quot;</span><span class="p">:</span> <span class="bp">True</span><span class="p">})</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.0.</span></p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../faq.html#faq-sql-expression-string"><em>How do I render SQL expressions as strings, possibly with bound parameters inlined?</em></a></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Delete.dialect_kwargs">
<tt class="descname">dialect_kwargs</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.dialect_kwargs" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">dialect_kwargs</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A collection of keyword arguments specified as dialect-specific
options to this construct.</p>
<p>The arguments are present here in their original <tt class="docutils literal"><span class="pre">&lt;dialect&gt;_&lt;kwarg&gt;</span></tt>
format.  Only arguments that were actually passed are included;
unlike the <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_options</span></tt></a> collection, which
contains all options known by this dialect including defaults.</p>
<p>The collection is also writable; keys are accepted of the
form <tt class="docutils literal"><span class="pre">&lt;dialect&gt;_&lt;kwarg&gt;</span></tt> where the value will be assembled
into the list of options.</p>
<div class="versionadded">
<p><span>New in version 0.9.2.</span></p>
</div>
<div class="versionchanged">
<p><span>Changed in version 0.9.4: </span>The <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a>
collection is now writable.</p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_options</span></tt></a> - nested dictionary form</p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Delete.dialect_options">
<tt class="descname">dialect_options</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.dialect_options" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">dialect_options</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A collection of keyword arguments specified as dialect-specific
options to this construct.</p>
<p>This is a two-level nested registry, keyed to <tt class="docutils literal"><span class="pre">&lt;dialect_name&gt;</span></tt>
and <tt class="docutils literal"><span class="pre">&lt;argument_name&gt;</span></tt>.  For example, the <tt class="docutils literal"><span class="pre">postgresql_where</span></tt>
argument would be locatable as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">arg</span> <span class="o">=</span> <span class="n">my_object</span><span class="o">.</span><span class="n">dialect_options</span><span class="p">[</span><span class="s">&#39;postgresql&#39;</span><span class="p">][</span><span class="s">&#39;where&#39;</span><span class="p">]</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.2.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a> - flat dictionary form</p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.execute">
<tt class="descname">execute</tt><big>(</big><em>*multiparams</em>, <em>**params</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.execute" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.execute" title="sqlalchemy.sql.expression.Executable.execute"><tt class="xref py py-meth docutils literal"><span class="pre">execute()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Compile and execute this <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.execution_options">
<tt class="descname">execution_options</tt><big>(</big><em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.execution_options" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.execution_options" title="sqlalchemy.sql.expression.Executable.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">execution_options()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Set non-SQL options for the statement which take effect during
execution.</p>
<p>Execution options can be set on a per-statement or
per <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> basis.   Additionally, the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> and ORM <a class="reference internal" href="../orm/query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> objects provide
access to execution options which they in turn configure upon
connections.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.Delete.execution_options" title="sqlalchemy.sql.expression.Delete.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">execution_options()</span></tt></a> method is generative.  A new
instance of this statement is returned that contains the options:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">statement</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">,</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">y</span><span class="p">])</span>
<span class="n">statement</span> <span class="o">=</span> <span class="n">statement</span><span class="o">.</span><span class="n">execution_options</span><span class="p">(</span><span class="n">autocommit</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span></pre></div>
</div>
<p>Note that only a subset of possible execution options can be applied
to a statement - these include &#8220;autocommit&#8221; and &#8220;stream_results&#8221;,
but not &#8220;isolation_level&#8221; or &#8220;compiled_cache&#8221;.
See <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execution_options()</span></tt></a> for a full list of
possible options.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execution_options()</span></tt></a></p>
<p class="last"><a class="reference internal" href="../orm/query.html#sqlalchemy.orm.query.Query.execution_options" title="sqlalchemy.orm.query.Query.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Query.execution_options()</span></tt></a></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Delete.kwargs">
<tt class="descname">kwargs</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.kwargs" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.kwargs" title="sqlalchemy.sql.base.DialectKWArgs.kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">kwargs</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A synonym for <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.params">
<tt class="descname">params</tt><big>(</big><em>*arg</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.params" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.params" title="sqlalchemy.sql.expression.UpdateBase.params"><tt class="xref py py-meth docutils literal"><span class="pre">params()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Set the parameters for the statement.</p>
<p>This method raises <tt class="docutils literal"><span class="pre">NotImplementedError</span></tt> on the base class,
and is overridden by <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">ValuesBase</span></tt></a> to provide the
SET/VALUES clause of UPDATE and INSERT.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.prefix_with">
<tt class="descname">prefix_with</tt><big>(</big><em>*expr</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.prefix_with" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.HasPrefixes.prefix_with" title="sqlalchemy.sql.expression.HasPrefixes.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">prefix_with()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.HasPrefixes" title="sqlalchemy.sql.expression.HasPrefixes"><tt class="xref py py-class docutils literal"><span class="pre">HasPrefixes</span></tt></a></div>
<p>Add one or more expressions following the statement keyword, i.e.
SELECT, INSERT, UPDATE, or DELETE. Generative.</p>
<p>This is used to support backend-specific prefix keywords such as those
provided by MySQL.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">prefix_with</span><span class="p">(</span><span class="s">&quot;LOW_PRIORITY&quot;</span><span class="p">,</span> <span class="n">dialect</span><span class="o">=</span><span class="s">&quot;mysql&quot;</span><span class="p">)</span></pre></div>
</div>
<p>Multiple prefixes can be specified by multiple calls
to <a class="reference internal" href="#sqlalchemy.sql.expression.Delete.prefix_with" title="sqlalchemy.sql.expression.Delete.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">prefix_with()</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Delete.prefix_with.params.*expr"></span><strong>*expr</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.prefix_with.params.*expr">¶</a> &#8211; textual or <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a> construct which
will be rendered following the INSERT, UPDATE, or DELETE
keyword.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Delete.prefix_with.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.prefix_with.params.**kw">¶</a> &#8211; A single keyword &#8216;dialect&#8217; is accepted.  This is an
optional string dialect name which will
limit rendering of this prefix to only that dialect.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.returning">
<tt class="descname">returning</tt><big>(</big><em>*cols</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.returning" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">returning()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Add a <a class="reference internal" href="../glossary.html#term-returning"><em class="xref std std-term">RETURNING</em></a> or equivalent clause to this statement.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span>\
          <span class="n">where</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span> <span class="o">==</span> <span class="s">&#39;value&#39;</span><span class="p">)</span><span class="o">.</span>\
          <span class="n">values</span><span class="p">(</span><span class="n">status</span><span class="o">=</span><span class="s">&#39;X&#39;</span><span class="p">)</span><span class="o">.</span>\
          <span class="n">returning</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">server_flag</span><span class="p">,</span>
                    <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">updated_timestamp</span><span class="p">)</span>

<span class="k">for</span> <span class="n">server_flag</span><span class="p">,</span> <span class="n">updated_timestamp</span> <span class="ow">in</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">server_flag</span><span class="p">,</span> <span class="n">updated_timestamp</span><span class="p">)</span></pre></div>
</div>
<p>The given collection of column expressions should be derived from
the table that is
the target of the INSERT, UPDATE, or DELETE.  While <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>
objects are typical, the elements can also be expressions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">returning</span><span class="p">(</span>
    <span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">first_name</span> <span class="o">+</span> <span class="s">&quot; &quot;</span> <span class="o">+</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">last_name</span><span class="p">)</span><span class="o">.</span>
    <span class="n">label</span><span class="p">(</span><span class="s">&#39;fullname&#39;</span><span class="p">))</span></pre></div>
</div>
<p>Upon compilation, a RETURNING clause, or database equivalent,
will be rendered within the statement.   For INSERT and UPDATE,
the values are the newly inserted/updated values.  For DELETE,
the values are those of the rows which were deleted.</p>
<p>Upon execution, the values of the columns to be returned are made
available via the result set and can be iterated using
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.fetchone" title="sqlalchemy.engine.ResultProxy.fetchone"><tt class="xref py py-meth docutils literal"><span class="pre">ResultProxy.fetchone()</span></tt></a> and similar.   For DBAPIs which do not
natively support returning values (i.e. cx_oracle), SQLAlchemy will
approximate this behavior at the result level so that a reasonable
amount of behavioral neutrality is provided.</p>
<p>Note that not all databases/DBAPIs
support RETURNING.   For those backends with no support,
an exception is raised upon compilation and/or execution.
For those who do support it, the functionality across backends
varies greatly, including restrictions on executemany()
and other statements which return multiple rows. Please
read the documentation notes for the database in use in
order to determine the availability of RETURNING.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> - an alternative method tailored
towards efficient fetching of server-side defaults and triggers
for single-row INSERTs or UPDATEs.</p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.scalar">
<tt class="descname">scalar</tt><big>(</big><em>*multiparams</em>, <em>**params</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.scalar" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.scalar" title="sqlalchemy.sql.expression.Executable.scalar"><tt class="xref py py-meth docutils literal"><span class="pre">scalar()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Compile and execute this <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a>, returning the
result&#8217;s scalar representation.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.self_group">
<tt class="descname">self_group</tt><big>(</big><em>against=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.self_group" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.self_group" title="sqlalchemy.sql.expression.ClauseElement.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Apply a &#8216;grouping&#8217; to this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>.</p>
<p>This method is overridden by subclasses to return a
&#8220;grouping&#8221; construct, i.e. parenthesis.   In particular
it&#8217;s used by &#8220;binary&#8221; expressions to provide a grouping
around themselves when placed into a larger expression,
as well as by <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> constructs when placed into
the FROM clause of another <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a>.  (Note that
subqueries should be normally created using the
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.alias" title="sqlalchemy.sql.expression.Select.alias"><tt class="xref py py-meth docutils literal"><span class="pre">Select.alias()</span></tt></a> method, as many platforms require
nested SELECT statements to be named).</p>
<p>As expressions are composed together, the application of
<a class="reference internal" href="#sqlalchemy.sql.expression.Delete.self_group" title="sqlalchemy.sql.expression.Delete.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> is automatic - end-user code should never
need to use this method directly.  Note that SQLAlchemy&#8217;s
clause constructs take operator precedence into account -
so parenthesis might not be needed, for example, in
an expression like <tt class="docutils literal"><span class="pre">x</span> <span class="pre">OR</span> <span class="pre">(y</span> <span class="pre">AND</span> <span class="pre">z)</span></tt> - AND takes precedence
over OR.</p>
<p>The base <a class="reference internal" href="#sqlalchemy.sql.expression.Delete.self_group" title="sqlalchemy.sql.expression.Delete.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> method of <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>
just returns self.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.unique_params">
<tt class="descname">unique_params</tt><big>(</big><em>*optionaldict</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.unique_params" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.unique_params" title="sqlalchemy.sql.expression.ClauseElement.unique_params"><tt class="xref py py-meth docutils literal"><span class="pre">unique_params()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Return a copy with <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> elements replaced.</p>
<p>Same functionality as <tt class="docutils literal"><span class="pre">params()</span></tt>, except adds <cite>unique=True</cite>
to affected bind parameters so that multiple statements can be
used.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.where">
<tt class="descname">where</tt><big>(</big><em>whereclause</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.where" title="Permalink to this definition">¶</a></dt>
<dd><p>Add the given WHERE clause to a newly returned delete construct.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Delete.with_hint">
<tt class="descname">with_hint</tt><big>(</big><em>text</em>, <em>selectable=None</em>, <em>dialect_name='*'</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Delete.with_hint" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.with_hint" title="sqlalchemy.sql.expression.UpdateBase.with_hint"><tt class="xref py py-meth docutils literal"><span class="pre">with_hint()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Add a table hint for a single table to this
INSERT/UPDATE/DELETE statement.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.with_hint" title="sqlalchemy.sql.expression.UpdateBase.with_hint"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.with_hint()</span></tt></a> currently applies only to
Microsoft SQL Server.  For MySQL INSERT/UPDATE/DELETE hints, use
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.prefix_with" title="sqlalchemy.sql.expression.UpdateBase.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.prefix_with()</span></tt></a>.</p>
</div>
<p>The text of the hint is rendered in the appropriate
location for the database backend in use, relative
to the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> that is the subject of this
statement, or optionally to that of the given
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> passed as the <tt class="docutils literal"><span class="pre">selectable</span></tt> argument.</p>
<p>The <tt class="docutils literal"><span class="pre">dialect_name</span></tt> option will limit the rendering of a particular
hint to a particular backend. Such as, to add a hint
that only takes effect for SQL Server:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mytable</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">with_hint</span><span class="p">(</span><span class="s">&quot;WITH (PAGLOCK)&quot;</span><span class="p">,</span> <span class="n">dialect_name</span><span class="o">=</span><span class="s">&quot;mssql&quot;</span><span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.7.6.</span></p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Delete.with_hint.params.text"></span><strong>text</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.with_hint.params.text">¶</a> &#8211; Text of the hint.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Delete.with_hint.params.selectable"></span><strong>selectable</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.with_hint.params.selectable">¶</a> &#8211; optional <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> 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.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Delete.with_hint.params.dialect_name"></span><strong>dialect_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Delete.with_hint.params.dialect_name">¶</a> &#8211; defaults to <tt class="docutils literal"><span class="pre">*</span></tt>, if specified as the name
of a particular dialect, will apply these hints only when
that dialect is in use.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.sql.expression.Insert">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">Insert</tt><big>(</big><em>table</em>, <em>values=None</em>, <em>inline=False</em>, <em>bind=None</em>, <em>prefixes=None</em>, <em>returning=None</em>, <em>return_defaults=False</em>, <em>**dialect_kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ValuesBase</span></tt></a></p>
<p>Represent an INSERT construct.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> object is created using the
<a class="reference internal" href="#sqlalchemy.sql.expression.insert" title="sqlalchemy.sql.expression.insert"><tt class="xref py py-func docutils literal"><span class="pre">insert()</span></tt></a> function.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="tutorial.html#coretutorial-insert-expressions"><em>Insert Expressions</em></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.__init__">
<tt class="descname">__init__</tt><big>(</big><em>table</em>, <em>values=None</em>, <em>inline=False</em>, <em>bind=None</em>, <em>prefixes=None</em>, <em>returning=None</em>, <em>return_defaults=False</em>, <em>**dialect_kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.insert" title="sqlalchemy.sql.expression.insert"><tt class="xref py py-func docutils literal"><span class="pre">insert()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>

<dl class="classmethod">
<dt id="sqlalchemy.sql.expression.Insert.argument_for">
<em class="property">classmethod </em><tt class="descname">argument_for</tt><big>(</big><em>dialect_name</em>, <em>argument_name</em>, <em>default</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.argument_for" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.argument_for" title="sqlalchemy.sql.base.DialectKWArgs.argument_for"><tt class="xref py py-meth docutils literal"><span class="pre">argument_for()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>Add a new kind of dialect-specific keyword argument for this class.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Index</span><span class="o">.</span><span class="n">argument_for</span><span class="p">(</span><span class="s">&quot;mydialect&quot;</span><span class="p">,</span> <span class="s">&quot;length&quot;</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>

<span class="n">some_index</span> <span class="o">=</span> <span class="n">Index</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">,</span> <span class="s">&#39;b&#39;</span><span class="p">,</span> <span class="n">mydialect_length</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.argument_for" title="sqlalchemy.sql.base.DialectKWArgs.argument_for"><tt class="xref py py-meth docutils literal"><span class="pre">DialectKWArgs.argument_for()</span></tt></a> method is a per-argument
way adding extra arguments to the
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> dictionary. This
dictionary provides a list of argument names accepted by various
schema-level constructs on behalf of a dialect.</p>
<p>New dialects should typically specify this dictionary all at once as a
data member of the dialect class.  The use case for ad-hoc addition of
argument names is typically for end-user code that is also using
a custom compilation scheme which consumes the additional arguments.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Insert.argument_for.params.dialect_name"></span><strong>dialect_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.argument_for.params.dialect_name">¶</a> &#8211; name of a dialect.  The dialect must be
locatable, else a <tt class="xref py py-class docutils literal"><span class="pre">NoSuchModuleError</span></tt> is raised.   The
dialect must also include an existing
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> collection, indicating
that it participates in the keyword-argument validation and default
system, else <tt class="xref py py-class docutils literal"><span class="pre">ArgumentError</span></tt> is raised.  If the dialect does
not include this collection, then any keyword argument can be
specified on behalf of this dialect already.  All dialects packaged
within SQLAlchemy include this collection, however for third party
dialects, support may vary.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.argument_for.params.argument_name"></span><strong>argument_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.argument_for.params.argument_name">¶</a> &#8211; name of the parameter.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.argument_for.params.default"></span><strong>default</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.argument_for.params.default">¶</a> &#8211; default value of the parameter.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.9.4.</span></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Insert.bind">
<tt class="descname">bind</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.bind" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.bind" title="sqlalchemy.sql.expression.UpdateBase.bind"><tt class="xref py py-attr docutils literal"><span class="pre">bind</span></tt></a> <em>attribute of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Return a &#8216;bind&#8217; linked to this <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a>
or a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> associated with it.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.compare">
<tt class="descname">compare</tt><big>(</big><em>other</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.compare" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.compare" title="sqlalchemy.sql.expression.ClauseElement.compare"><tt class="xref py py-meth docutils literal"><span class="pre">compare()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Compare this ClauseElement to the given ClauseElement.</p>
<p>Subclasses should override the default behavior, which is a
straight identity comparison.</p>
<p>**kw are arguments consumed by subclass compare() methods and
may be used to modify the criteria for comparison.
(see <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>)</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.compile">
<tt class="descname">compile</tt><big>(</big><em>bind=None</em>, <em>dialect=None</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.compile" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.compile" title="sqlalchemy.sql.expression.ClauseElement.compile"><tt class="xref py py-meth docutils literal"><span class="pre">compile()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Compile this SQL expression.</p>
<p>The return value is a <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object.
Calling <tt class="docutils literal"><span class="pre">str()</span></tt> or <tt class="docutils literal"><span class="pre">unicode()</span></tt> on the returned value will yield a
string representation of the result. The
<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object also can return a
dictionary of bind parameter names and values
using the <tt class="docutils literal"><span class="pre">params</span></tt> accessor.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Insert.compile.params.bind"></span><strong>bind</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.compile.params.bind">¶</a> &#8211; An <tt class="docutils literal"><span class="pre">Engine</span></tt> or <tt class="docutils literal"><span class="pre">Connection</span></tt> from which a
<tt class="docutils literal"><span class="pre">Compiled</span></tt> will be acquired. This argument takes precedence over
this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>&#8216;s bound engine, if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.compile.params.column_keys"></span><strong>column_keys</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.compile.params.column_keys">¶</a> &#8211; Used for INSERT and UPDATE statements, a list of
column names which should be present in the VALUES clause of the
compiled statement. If <tt class="docutils literal"><span class="pre">None</span></tt>, all columns from the target table
object are rendered.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.compile.params.dialect"></span><strong>dialect</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.compile.params.dialect">¶</a> &#8211; A <tt class="docutils literal"><span class="pre">Dialect</span></tt> instance from which a <tt class="docutils literal"><span class="pre">Compiled</span></tt>
will be acquired. This argument takes precedence over the <cite>bind</cite>
argument as well as this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>&#8216;s bound engine,
if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.compile.params.inline"></span><strong>inline</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.compile.params.inline">¶</a> &#8211; 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&#8217;s
VALUES clause. This typically refers to Sequence execution but may
also refer to any server-side default generation function
associated with a primary key <cite>Column</cite>.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.compile.params.compile_kwargs"></span><strong>compile_kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.compile.params.compile_kwargs">¶</a> &#8211; <p>optional dictionary of additional parameters
that will be passed through to the compiler within all &#8220;visit&#8221;
methods.  This allows any custom flag to be passed through to
a custom compilation construct, for example.  It is also used
for the case of passing the <tt class="docutils literal"><span class="pre">literal_binds</span></tt> flag through:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">table</span><span class="p">,</span> <span class="n">column</span><span class="p">,</span> <span class="n">select</span>

<span class="n">t</span> <span class="o">=</span> <span class="n">table</span><span class="p">(</span><span class="s">&#39;t&#39;</span><span class="p">,</span> <span class="n">column</span><span class="p">(</span><span class="s">&#39;x&#39;</span><span class="p">))</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span> <span class="o">==</span> <span class="mi">5</span><span class="p">)</span>

<span class="k">print</span> <span class="n">s</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">compile_kwargs</span><span class="o">=</span><span class="p">{</span><span class="s">&quot;literal_binds&quot;</span><span class="p">:</span> <span class="bp">True</span><span class="p">})</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.0.</span></p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../faq.html#faq-sql-expression-string"><em>How do I render SQL expressions as strings, possibly with bound parameters inlined?</em></a></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Insert.dialect_kwargs">
<tt class="descname">dialect_kwargs</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.dialect_kwargs" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">dialect_kwargs</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A collection of keyword arguments specified as dialect-specific
options to this construct.</p>
<p>The arguments are present here in their original <tt class="docutils literal"><span class="pre">&lt;dialect&gt;_&lt;kwarg&gt;</span></tt>
format.  Only arguments that were actually passed are included;
unlike the <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_options</span></tt></a> collection, which
contains all options known by this dialect including defaults.</p>
<p>The collection is also writable; keys are accepted of the
form <tt class="docutils literal"><span class="pre">&lt;dialect&gt;_&lt;kwarg&gt;</span></tt> where the value will be assembled
into the list of options.</p>
<div class="versionadded">
<p><span>New in version 0.9.2.</span></p>
</div>
<div class="versionchanged">
<p><span>Changed in version 0.9.4: </span>The <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a>
collection is now writable.</p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_options</span></tt></a> - nested dictionary form</p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Insert.dialect_options">
<tt class="descname">dialect_options</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.dialect_options" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">dialect_options</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A collection of keyword arguments specified as dialect-specific
options to this construct.</p>
<p>This is a two-level nested registry, keyed to <tt class="docutils literal"><span class="pre">&lt;dialect_name&gt;</span></tt>
and <tt class="docutils literal"><span class="pre">&lt;argument_name&gt;</span></tt>.  For example, the <tt class="docutils literal"><span class="pre">postgresql_where</span></tt>
argument would be locatable as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">arg</span> <span class="o">=</span> <span class="n">my_object</span><span class="o">.</span><span class="n">dialect_options</span><span class="p">[</span><span class="s">&#39;postgresql&#39;</span><span class="p">][</span><span class="s">&#39;where&#39;</span><span class="p">]</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.2.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a> - flat dictionary form</p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.execute">
<tt class="descname">execute</tt><big>(</big><em>*multiparams</em>, <em>**params</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.execute" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.execute" title="sqlalchemy.sql.expression.Executable.execute"><tt class="xref py py-meth docutils literal"><span class="pre">execute()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Compile and execute this <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.execution_options">
<tt class="descname">execution_options</tt><big>(</big><em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.execution_options" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.execution_options" title="sqlalchemy.sql.expression.Executable.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">execution_options()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Set non-SQL options for the statement which take effect during
execution.</p>
<p>Execution options can be set on a per-statement or
per <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> basis.   Additionally, the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> and ORM <a class="reference internal" href="../orm/query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> objects provide
access to execution options which they in turn configure upon
connections.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.Insert.execution_options" title="sqlalchemy.sql.expression.Insert.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">execution_options()</span></tt></a> method is generative.  A new
instance of this statement is returned that contains the options:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">statement</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">,</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">y</span><span class="p">])</span>
<span class="n">statement</span> <span class="o">=</span> <span class="n">statement</span><span class="o">.</span><span class="n">execution_options</span><span class="p">(</span><span class="n">autocommit</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span></pre></div>
</div>
<p>Note that only a subset of possible execution options can be applied
to a statement - these include &#8220;autocommit&#8221; and &#8220;stream_results&#8221;,
but not &#8220;isolation_level&#8221; or &#8220;compiled_cache&#8221;.
See <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execution_options()</span></tt></a> for a full list of
possible options.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execution_options()</span></tt></a></p>
<p class="last"><a class="reference internal" href="../orm/query.html#sqlalchemy.orm.query.Query.execution_options" title="sqlalchemy.orm.query.Query.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Query.execution_options()</span></tt></a></p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.from_select">
<tt class="descname">from_select</tt><big>(</big><em>names</em>, <em>select</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.from_select" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> construct which represents
an <tt class="docutils literal"><span class="pre">INSERT...FROM</span> <span class="pre">SELECT</span></tt> statement.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">sel</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">table1</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">a</span><span class="p">,</span> <span class="n">table1</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">b</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">table1</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">c</span> <span class="o">&gt;</span> <span class="mi">5</span><span class="p">)</span>
<span class="n">ins</span> <span class="o">=</span> <span class="n">table2</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">from_select</span><span class="p">([</span><span class="s">&#39;a&#39;</span><span class="p">,</span> <span class="s">&#39;b&#39;</span><span class="p">],</span> <span class="n">sel</span><span class="p">)</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Insert.from_select.params.names"></span><strong>names</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.from_select.params.names">¶</a> &#8211; a sequence of string column names or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>
objects representing the target columns.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.from_select.params.select"></span><strong>select</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.from_select.params.select">¶</a> &#8211; a <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> construct, <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.FromClause" title="sqlalchemy.sql.expression.FromClause"><tt class="xref py py-class docutils literal"><span class="pre">FromClause</span></tt></a>
or other construct which resolves into a <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.FromClause" title="sqlalchemy.sql.expression.FromClause"><tt class="xref py py-class docutils literal"><span class="pre">FromClause</span></tt></a>,
such as an ORM <a class="reference internal" href="../orm/query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> object, etc.  The order of
columns returned from this FROM clause should correspond to the
order of columns sent as the <tt class="docutils literal"><span class="pre">names</span></tt> parameter;  while this
is not checked before passing along to the database, the database
would normally raise an exception if these column lists don&#8217;t
correspond.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>The <tt class="docutils literal"><span class="pre">inline=True</span></tt> flag should be set to True when using
backends that support RETURNING, including Postgresql, Oracle,
and SQL Server.   This will prevent the implicit <tt class="docutils literal"><span class="pre">RETURNING</span></tt>
clause from being appended to the statement, which is normally
used to fetch the &#8220;last inserted primary key&#8221; value.  This feature
will raise an error if the statement inserts zero rows, and
on some backends (e.g. Oracle) it will raise an error if the
statement inserts more than one row.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.insert.params.inline" title="sqlalchemy.sql.expression.insert"><tt class="xref py py-paramref docutils literal"><span class="pre">insert.inline</span></tt></a> is set to True as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">sel</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">table1</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">a</span><span class="p">,</span> <span class="n">table1</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">b</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">table1</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">c</span> <span class="o">&gt;</span> <span class="mi">5</span><span class="p">)</span>
<span class="n">ins</span> <span class="o">=</span> <span class="n">table2</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="n">inline</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span><span class="o">.</span><span class="n">from_select</span><span class="p">([</span><span class="s">&#39;a&#39;</span><span class="p">,</span> <span class="s">&#39;b&#39;</span><span class="p">],</span> <span class="n">sel</span><span class="p">)</span></pre></div>
</div>
<p class="last">Version 1.0 of SQLAlchemy will set this flag to True in <strong>all</strong>
cases.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Python-side and SQL function defaults, as described at
<a class="reference internal" href="defaults.html"><em>Column Insert/Update Defaults</em></a>, are <strong>not</strong> automatically
included in the SELECT statement as rendered unless explicitly
added to the statement.  The behavior of automatically rendering
these default values and expressions is available as of SQLAlchemy
version 1.0.0.</p>
</div>
<div class="versionadded">
<p><span>New in version 0.8.3.</span></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Insert.kwargs">
<tt class="descname">kwargs</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.kwargs" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.kwargs" title="sqlalchemy.sql.base.DialectKWArgs.kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">kwargs</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A synonym for <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.params">
<tt class="descname">params</tt><big>(</big><em>*arg</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.params" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.params" title="sqlalchemy.sql.expression.UpdateBase.params"><tt class="xref py py-meth docutils literal"><span class="pre">params()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Set the parameters for the statement.</p>
<p>This method raises <tt class="docutils literal"><span class="pre">NotImplementedError</span></tt> on the base class,
and is overridden by <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">ValuesBase</span></tt></a> to provide the
SET/VALUES clause of UPDATE and INSERT.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.prefix_with">
<tt class="descname">prefix_with</tt><big>(</big><em>*expr</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.prefix_with" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.HasPrefixes.prefix_with" title="sqlalchemy.sql.expression.HasPrefixes.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">prefix_with()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.HasPrefixes" title="sqlalchemy.sql.expression.HasPrefixes"><tt class="xref py py-class docutils literal"><span class="pre">HasPrefixes</span></tt></a></div>
<p>Add one or more expressions following the statement keyword, i.e.
SELECT, INSERT, UPDATE, or DELETE. Generative.</p>
<p>This is used to support backend-specific prefix keywords such as those
provided by MySQL.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">prefix_with</span><span class="p">(</span><span class="s">&quot;LOW_PRIORITY&quot;</span><span class="p">,</span> <span class="n">dialect</span><span class="o">=</span><span class="s">&quot;mysql&quot;</span><span class="p">)</span></pre></div>
</div>
<p>Multiple prefixes can be specified by multiple calls
to <a class="reference internal" href="#sqlalchemy.sql.expression.Insert.prefix_with" title="sqlalchemy.sql.expression.Insert.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">prefix_with()</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Insert.prefix_with.params.*expr"></span><strong>*expr</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.prefix_with.params.*expr">¶</a> &#8211; textual or <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a> construct which
will be rendered following the INSERT, UPDATE, or DELETE
keyword.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.prefix_with.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.prefix_with.params.**kw">¶</a> &#8211; A single keyword &#8216;dialect&#8217; is accepted.  This is an
optional string dialect name which will
limit rendering of this prefix to only that dialect.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.return_defaults">
<tt class="descname">return_defaults</tt><big>(</big><em>*cols</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.return_defaults" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">return_defaults()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">ValuesBase</span></tt></a></div>
<p>Make use of a <a class="reference internal" href="../glossary.html#term-returning"><em class="xref std std-term">RETURNING</em></a> clause for the purpose
of fetching server-side expressions and defaults.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s">&#39;newdata&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">return_defaults</span><span class="p">()</span>

<span class="n">result</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">)</span>

<span class="n">server_created_at</span> <span class="o">=</span> <span class="n">result</span><span class="o">.</span><span class="n">returned_defaults</span><span class="p">[</span><span class="s">&#39;created_at&#39;</span><span class="p">]</span></pre></div>
</div>
<p>When used against a backend that supports RETURNING, all column
values generated by SQL expression or server-side-default will be
added to any existing RETURNING clause, provided that
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> is not used simultaneously.  The column
values will then be available on the result using the
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.returned_defaults" title="sqlalchemy.engine.ResultProxy.returned_defaults"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.returned_defaults</span></tt></a> accessor as a dictionary,
referring to values keyed to the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> object as well as
its <tt class="docutils literal"><span class="pre">.key</span></tt>.</p>
<p>This method differs from <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> in these ways:</p>
<ol class="arabic simple">
<li><a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is only intended for use with
an INSERT or an UPDATE statement that matches exactly one row.
While the RETURNING construct in the general sense supports
multiple rows for a multi-row UPDATE or DELETE statement, or for
special cases of INSERT that return multiple rows (e.g. INSERT from
SELECT, multi-valued VALUES clause),
<a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is intended only for an
&#8220;ORM-style&#8221; single-row INSERT/UPDATE statement.  The row returned
by the statement is also consumed implcitly when
<a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is used.  By contrast,
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> leaves the RETURNING result-set
intact with a collection of any number of rows.</li>
<li>It is compatible with the existing logic to fetch auto-generated
primary key values, also known as &#8220;implicit returning&#8221;.  Backends
that support RETURNING will automatically make use of RETURNING in
order to fetch the value of newly generated primary keys; while the
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> method circumvents this behavior,
<a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> leaves it intact.</li>
<li>It can be called against any backend.  Backends that don&#8217;t support
RETURNING will skip the usage of the feature, rather than raising
an exception.  The return value of
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.returned_defaults" title="sqlalchemy.engine.ResultProxy.returned_defaults"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.returned_defaults</span></tt></a> will be <tt class="docutils literal"><span class="pre">None</span></tt></li>
</ol>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is used by the ORM to provide
an efficient implementation for the <tt class="docutils literal"><span class="pre">eager_defaults</span></tt> feature of
<a class="reference internal" href="../orm/mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.sql.expression.Insert.return_defaults.params.cols"></span><strong>cols</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.return_defaults.params.cols">¶</a> &#8211; optional list of column key names or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>
objects.  If omitted, all column expressions evaulated on the server
are added to the returning list.</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.9.0.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a></p>
<p class="last"><a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.returned_defaults" title="sqlalchemy.engine.ResultProxy.returned_defaults"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.returned_defaults</span></tt></a></p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.returning">
<tt class="descname">returning</tt><big>(</big><em>*cols</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.returning" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">returning()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Add a <a class="reference internal" href="../glossary.html#term-returning"><em class="xref std std-term">RETURNING</em></a> or equivalent clause to this statement.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span>\
          <span class="n">where</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span> <span class="o">==</span> <span class="s">&#39;value&#39;</span><span class="p">)</span><span class="o">.</span>\
          <span class="n">values</span><span class="p">(</span><span class="n">status</span><span class="o">=</span><span class="s">&#39;X&#39;</span><span class="p">)</span><span class="o">.</span>\
          <span class="n">returning</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">server_flag</span><span class="p">,</span>
                    <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">updated_timestamp</span><span class="p">)</span>

<span class="k">for</span> <span class="n">server_flag</span><span class="p">,</span> <span class="n">updated_timestamp</span> <span class="ow">in</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">server_flag</span><span class="p">,</span> <span class="n">updated_timestamp</span><span class="p">)</span></pre></div>
</div>
<p>The given collection of column expressions should be derived from
the table that is
the target of the INSERT, UPDATE, or DELETE.  While <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>
objects are typical, the elements can also be expressions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">returning</span><span class="p">(</span>
    <span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">first_name</span> <span class="o">+</span> <span class="s">&quot; &quot;</span> <span class="o">+</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">last_name</span><span class="p">)</span><span class="o">.</span>
    <span class="n">label</span><span class="p">(</span><span class="s">&#39;fullname&#39;</span><span class="p">))</span></pre></div>
</div>
<p>Upon compilation, a RETURNING clause, or database equivalent,
will be rendered within the statement.   For INSERT and UPDATE,
the values are the newly inserted/updated values.  For DELETE,
the values are those of the rows which were deleted.</p>
<p>Upon execution, the values of the columns to be returned are made
available via the result set and can be iterated using
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.fetchone" title="sqlalchemy.engine.ResultProxy.fetchone"><tt class="xref py py-meth docutils literal"><span class="pre">ResultProxy.fetchone()</span></tt></a> and similar.   For DBAPIs which do not
natively support returning values (i.e. cx_oracle), SQLAlchemy will
approximate this behavior at the result level so that a reasonable
amount of behavioral neutrality is provided.</p>
<p>Note that not all databases/DBAPIs
support RETURNING.   For those backends with no support,
an exception is raised upon compilation and/or execution.
For those who do support it, the functionality across backends
varies greatly, including restrictions on executemany()
and other statements which return multiple rows. Please
read the documentation notes for the database in use in
order to determine the availability of RETURNING.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> - an alternative method tailored
towards efficient fetching of server-side defaults and triggers
for single-row INSERTs or UPDATEs.</p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.scalar">
<tt class="descname">scalar</tt><big>(</big><em>*multiparams</em>, <em>**params</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.scalar" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.scalar" title="sqlalchemy.sql.expression.Executable.scalar"><tt class="xref py py-meth docutils literal"><span class="pre">scalar()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Compile and execute this <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a>, returning the
result&#8217;s scalar representation.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.self_group">
<tt class="descname">self_group</tt><big>(</big><em>against=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.self_group" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.self_group" title="sqlalchemy.sql.expression.ClauseElement.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Apply a &#8216;grouping&#8217; to this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>.</p>
<p>This method is overridden by subclasses to return a
&#8220;grouping&#8221; construct, i.e. parenthesis.   In particular
it&#8217;s used by &#8220;binary&#8221; expressions to provide a grouping
around themselves when placed into a larger expression,
as well as by <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> constructs when placed into
the FROM clause of another <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a>.  (Note that
subqueries should be normally created using the
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.alias" title="sqlalchemy.sql.expression.Select.alias"><tt class="xref py py-meth docutils literal"><span class="pre">Select.alias()</span></tt></a> method, as many platforms require
nested SELECT statements to be named).</p>
<p>As expressions are composed together, the application of
<a class="reference internal" href="#sqlalchemy.sql.expression.Insert.self_group" title="sqlalchemy.sql.expression.Insert.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> is automatic - end-user code should never
need to use this method directly.  Note that SQLAlchemy&#8217;s
clause constructs take operator precedence into account -
so parenthesis might not be needed, for example, in
an expression like <tt class="docutils literal"><span class="pre">x</span> <span class="pre">OR</span> <span class="pre">(y</span> <span class="pre">AND</span> <span class="pre">z)</span></tt> - AND takes precedence
over OR.</p>
<p>The base <a class="reference internal" href="#sqlalchemy.sql.expression.Insert.self_group" title="sqlalchemy.sql.expression.Insert.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> method of <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>
just returns self.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.unique_params">
<tt class="descname">unique_params</tt><big>(</big><em>*optionaldict</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.unique_params" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.unique_params" title="sqlalchemy.sql.expression.ClauseElement.unique_params"><tt class="xref py py-meth docutils literal"><span class="pre">unique_params()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Return a copy with <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> elements replaced.</p>
<p>Same functionality as <tt class="docutils literal"><span class="pre">params()</span></tt>, except adds <cite>unique=True</cite>
to affected bind parameters so that multiple statements can be
used.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.values">
<tt class="descname">values</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.values" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">values()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">ValuesBase</span></tt></a></div>
<p>specify a fixed VALUES clause for an INSERT statement, or the SET
clause for an UPDATE.</p>
<p>Note that the <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update</span></tt></a> constructs support
per-execution time formatting of the VALUES and/or SET clauses,
based on the arguments passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>.
However, the <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> method can be used to &#8220;fix&#8221; a
particular set of parameters into the statement.</p>
<p>Multiple calls to <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> will produce a new
construct, each one with the parameter list modified to include
the new parameters sent.  In the typical case of a single
dictionary of parameters, the newly passed keys will replace
the same keys in the previous construct.  In the case of a list-based
&#8220;multiple values&#8221; construct, each new list of values is extended
onto the existing list of values.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Insert.values.params.**kwargs"></span><strong>**kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.values.params.**kwargs">¶</a> &#8211; <p>key value pairs representing the string key
of a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> mapped to the value to be rendered into the
VALUES or SET clause:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;some name&quot;</span><span class="p">)</span>

<span class="n">users</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">users</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;some name&quot;</span><span class="p">)</span></pre></div>
</div>
</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.values.params.*args"></span><strong>*args</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.values.params.*args">¶</a> &#8211; <p>Alternatively, a dictionary, tuple or list
of dictionaries or tuples can be passed as a single positional
argument in order to form the VALUES or
SET clause of the statement.  The single dictionary form
works the same as the kwargs form:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">({</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;some name&quot;</span><span class="p">})</span></pre></div>
</div>
<p>If a tuple is passed, the tuple should contain the same number
of columns as the target <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">((</span><span class="mi">5</span><span class="p">,</span> <span class="s">&quot;some name&quot;</span><span class="p">))</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> construct also supports multiply-rendered VALUES
construct, for those backends which support this SQL syntax
(SQLite, Postgresql, MySQL).  This mode is indicated by passing a
list of one or more dictionaries/tuples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">([</span>
                    <span class="p">{</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;some name&quot;</span><span class="p">},</span>
                    <span class="p">{</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;some other name&quot;</span><span class="p">},</span>
                    <span class="p">{</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;yet another name&quot;</span><span class="p">},</span>
                <span class="p">])</span></pre></div>
</div>
<p>In the case of an <a class="reference internal" href="#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update</span></tt></a>
construct, only the single dictionary/tuple form is accepted,
else an exception is raised.  It is also an exception case to
attempt to mix the single-/multiple- value styles together,
either through multiple <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> calls
or by sending a list + kwargs at the same time.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Passing a multiple values list is <em>not</em> the same
as passing a multiple values list to the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a> method.  Passing a list of parameter
sets to <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> produces a construct of this
form:</p>
<div class="highlight-python"><pre>INSERT INTO table (col1, col2, col3) VALUES
                (col1_0, col2_0, col3_0),
                (col1_1, col2_1, col3_1),
                ...</pre>
</div>
<p class="last">whereas a multiple list passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>
has the effect of using the DBAPI
<a class="reference external" href="http://www.python.org/dev/peps/pep-0249/#id18">executemany()</a>
method, which provides a high-performance system of invoking
a single-row INSERT statement many times against a series
of parameter sets.   The &#8220;executemany&#8221; style is supported by
all database backends, as it does not depend on a special SQL
syntax.</p>
</div>
<div class="versionadded">
<p><span>New in version 0.8: </span>Support for multiple-VALUES INSERT statements.</p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="tutorial.html#inserts-and-updates"><em>Inserts, Updates and Deletes</em></a> - SQL Expression
Language Tutorial</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.insert" title="sqlalchemy.sql.expression.insert"><tt class="xref py py-func docutils literal"><span class="pre">insert()</span></tt></a> - produce an <tt class="docutils literal"><span class="pre">INSERT</span></tt> statement</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.update" title="sqlalchemy.sql.expression.update"><tt class="xref py py-func docutils literal"><span class="pre">update()</span></tt></a> - produce an <tt class="docutils literal"><span class="pre">UPDATE</span></tt> statement</p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Insert.with_hint">
<tt class="descname">with_hint</tt><big>(</big><em>text</em>, <em>selectable=None</em>, <em>dialect_name='*'</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Insert.with_hint" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.with_hint" title="sqlalchemy.sql.expression.UpdateBase.with_hint"><tt class="xref py py-meth docutils literal"><span class="pre">with_hint()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Add a table hint for a single table to this
INSERT/UPDATE/DELETE statement.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.with_hint" title="sqlalchemy.sql.expression.UpdateBase.with_hint"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.with_hint()</span></tt></a> currently applies only to
Microsoft SQL Server.  For MySQL INSERT/UPDATE/DELETE hints, use
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.prefix_with" title="sqlalchemy.sql.expression.UpdateBase.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.prefix_with()</span></tt></a>.</p>
</div>
<p>The text of the hint is rendered in the appropriate
location for the database backend in use, relative
to the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> that is the subject of this
statement, or optionally to that of the given
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> passed as the <tt class="docutils literal"><span class="pre">selectable</span></tt> argument.</p>
<p>The <tt class="docutils literal"><span class="pre">dialect_name</span></tt> option will limit the rendering of a particular
hint to a particular backend. Such as, to add a hint
that only takes effect for SQL Server:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mytable</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">with_hint</span><span class="p">(</span><span class="s">&quot;WITH (PAGLOCK)&quot;</span><span class="p">,</span> <span class="n">dialect_name</span><span class="o">=</span><span class="s">&quot;mssql&quot;</span><span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.7.6.</span></p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Insert.with_hint.params.text"></span><strong>text</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.with_hint.params.text">¶</a> &#8211; Text of the hint.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.with_hint.params.selectable"></span><strong>selectable</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.with_hint.params.selectable">¶</a> &#8211; optional <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> 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.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Insert.with_hint.params.dialect_name"></span><strong>dialect_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Insert.with_hint.params.dialect_name">¶</a> &#8211; defaults to <tt class="docutils literal"><span class="pre">*</span></tt>, if specified as the name
of a particular dialect, will apply these hints only when
that dialect is in use.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.sql.expression.Update">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">Update</tt><big>(</big><em>table</em>, <em>whereclause=None</em>, <em>values=None</em>, <em>inline=False</em>, <em>bind=None</em>, <em>prefixes=None</em>, <em>returning=None</em>, <em>return_defaults=False</em>, <em>**dialect_kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ValuesBase</span></tt></a></p>
<p>Represent an Update construct.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update</span></tt></a> object is created using the <a class="reference internal" href="#sqlalchemy.sql.expression.update" title="sqlalchemy.sql.expression.update"><tt class="xref py py-func docutils literal"><span class="pre">update()</span></tt></a>
function.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.__init__">
<tt class="descname">__init__</tt><big>(</big><em>table</em>, <em>whereclause=None</em>, <em>values=None</em>, <em>inline=False</em>, <em>bind=None</em>, <em>prefixes=None</em>, <em>returning=None</em>, <em>return_defaults=False</em>, <em>**dialect_kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.update" title="sqlalchemy.sql.expression.update"><tt class="xref py py-func docutils literal"><span class="pre">update()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>

<dl class="classmethod">
<dt id="sqlalchemy.sql.expression.Update.argument_for">
<em class="property">classmethod </em><tt class="descname">argument_for</tt><big>(</big><em>dialect_name</em>, <em>argument_name</em>, <em>default</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.argument_for" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.argument_for" title="sqlalchemy.sql.base.DialectKWArgs.argument_for"><tt class="xref py py-meth docutils literal"><span class="pre">argument_for()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>Add a new kind of dialect-specific keyword argument for this class.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Index</span><span class="o">.</span><span class="n">argument_for</span><span class="p">(</span><span class="s">&quot;mydialect&quot;</span><span class="p">,</span> <span class="s">&quot;length&quot;</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>

<span class="n">some_index</span> <span class="o">=</span> <span class="n">Index</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">,</span> <span class="s">&#39;b&#39;</span><span class="p">,</span> <span class="n">mydialect_length</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.argument_for" title="sqlalchemy.sql.base.DialectKWArgs.argument_for"><tt class="xref py py-meth docutils literal"><span class="pre">DialectKWArgs.argument_for()</span></tt></a> method is a per-argument
way adding extra arguments to the
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> dictionary. This
dictionary provides a list of argument names accepted by various
schema-level constructs on behalf of a dialect.</p>
<p>New dialects should typically specify this dictionary all at once as a
data member of the dialect class.  The use case for ad-hoc addition of
argument names is typically for end-user code that is also using
a custom compilation scheme which consumes the additional arguments.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Update.argument_for.params.dialect_name"></span><strong>dialect_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.argument_for.params.dialect_name">¶</a> &#8211; name of a dialect.  The dialect must be
locatable, else a <tt class="xref py py-class docutils literal"><span class="pre">NoSuchModuleError</span></tt> is raised.   The
dialect must also include an existing
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> collection, indicating
that it participates in the keyword-argument validation and default
system, else <tt class="xref py py-class docutils literal"><span class="pre">ArgumentError</span></tt> is raised.  If the dialect does
not include this collection, then any keyword argument can be
specified on behalf of this dialect already.  All dialects packaged
within SQLAlchemy include this collection, however for third party
dialects, support may vary.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Update.argument_for.params.argument_name"></span><strong>argument_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.argument_for.params.argument_name">¶</a> &#8211; name of the parameter.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Update.argument_for.params.default"></span><strong>default</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.argument_for.params.default">¶</a> &#8211; default value of the parameter.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.9.4.</span></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Update.bind">
<tt class="descname">bind</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Update.bind" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.bind" title="sqlalchemy.sql.expression.UpdateBase.bind"><tt class="xref py py-attr docutils literal"><span class="pre">bind</span></tt></a> <em>attribute of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Return a &#8216;bind&#8217; linked to this <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a>
or a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> associated with it.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.compare">
<tt class="descname">compare</tt><big>(</big><em>other</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.compare" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.compare" title="sqlalchemy.sql.expression.ClauseElement.compare"><tt class="xref py py-meth docutils literal"><span class="pre">compare()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Compare this ClauseElement to the given ClauseElement.</p>
<p>Subclasses should override the default behavior, which is a
straight identity comparison.</p>
<p>**kw are arguments consumed by subclass compare() methods and
may be used to modify the criteria for comparison.
(see <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>)</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.compile">
<tt class="descname">compile</tt><big>(</big><em>bind=None</em>, <em>dialect=None</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.compile" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.compile" title="sqlalchemy.sql.expression.ClauseElement.compile"><tt class="xref py py-meth docutils literal"><span class="pre">compile()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Compile this SQL expression.</p>
<p>The return value is a <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object.
Calling <tt class="docutils literal"><span class="pre">str()</span></tt> or <tt class="docutils literal"><span class="pre">unicode()</span></tt> on the returned value will yield a
string representation of the result. The
<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object also can return a
dictionary of bind parameter names and values
using the <tt class="docutils literal"><span class="pre">params</span></tt> accessor.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Update.compile.params.bind"></span><strong>bind</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.compile.params.bind">¶</a> &#8211; An <tt class="docutils literal"><span class="pre">Engine</span></tt> or <tt class="docutils literal"><span class="pre">Connection</span></tt> from which a
<tt class="docutils literal"><span class="pre">Compiled</span></tt> will be acquired. This argument takes precedence over
this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>&#8216;s bound engine, if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Update.compile.params.column_keys"></span><strong>column_keys</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.compile.params.column_keys">¶</a> &#8211; Used for INSERT and UPDATE statements, a list of
column names which should be present in the VALUES clause of the
compiled statement. If <tt class="docutils literal"><span class="pre">None</span></tt>, all columns from the target table
object are rendered.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Update.compile.params.dialect"></span><strong>dialect</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.compile.params.dialect">¶</a> &#8211; A <tt class="docutils literal"><span class="pre">Dialect</span></tt> instance from which a <tt class="docutils literal"><span class="pre">Compiled</span></tt>
will be acquired. This argument takes precedence over the <cite>bind</cite>
argument as well as this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>&#8216;s bound engine,
if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Update.compile.params.inline"></span><strong>inline</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.compile.params.inline">¶</a> &#8211; 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&#8217;s
VALUES clause. This typically refers to Sequence execution but may
also refer to any server-side default generation function
associated with a primary key <cite>Column</cite>.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Update.compile.params.compile_kwargs"></span><strong>compile_kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.compile.params.compile_kwargs">¶</a> &#8211; <p>optional dictionary of additional parameters
that will be passed through to the compiler within all &#8220;visit&#8221;
methods.  This allows any custom flag to be passed through to
a custom compilation construct, for example.  It is also used
for the case of passing the <tt class="docutils literal"><span class="pre">literal_binds</span></tt> flag through:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">table</span><span class="p">,</span> <span class="n">column</span><span class="p">,</span> <span class="n">select</span>

<span class="n">t</span> <span class="o">=</span> <span class="n">table</span><span class="p">(</span><span class="s">&#39;t&#39;</span><span class="p">,</span> <span class="n">column</span><span class="p">(</span><span class="s">&#39;x&#39;</span><span class="p">))</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span> <span class="o">==</span> <span class="mi">5</span><span class="p">)</span>

<span class="k">print</span> <span class="n">s</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">compile_kwargs</span><span class="o">=</span><span class="p">{</span><span class="s">&quot;literal_binds&quot;</span><span class="p">:</span> <span class="bp">True</span><span class="p">})</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.0.</span></p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../faq.html#faq-sql-expression-string"><em>How do I render SQL expressions as strings, possibly with bound parameters inlined?</em></a></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Update.dialect_kwargs">
<tt class="descname">dialect_kwargs</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Update.dialect_kwargs" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">dialect_kwargs</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A collection of keyword arguments specified as dialect-specific
options to this construct.</p>
<p>The arguments are present here in their original <tt class="docutils literal"><span class="pre">&lt;dialect&gt;_&lt;kwarg&gt;</span></tt>
format.  Only arguments that were actually passed are included;
unlike the <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_options</span></tt></a> collection, which
contains all options known by this dialect including defaults.</p>
<p>The collection is also writable; keys are accepted of the
form <tt class="docutils literal"><span class="pre">&lt;dialect&gt;_&lt;kwarg&gt;</span></tt> where the value will be assembled
into the list of options.</p>
<div class="versionadded">
<p><span>New in version 0.9.2.</span></p>
</div>
<div class="versionchanged">
<p><span>Changed in version 0.9.4: </span>The <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a>
collection is now writable.</p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_options</span></tt></a> - nested dictionary form</p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Update.dialect_options">
<tt class="descname">dialect_options</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Update.dialect_options" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">dialect_options</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A collection of keyword arguments specified as dialect-specific
options to this construct.</p>
<p>This is a two-level nested registry, keyed to <tt class="docutils literal"><span class="pre">&lt;dialect_name&gt;</span></tt>
and <tt class="docutils literal"><span class="pre">&lt;argument_name&gt;</span></tt>.  For example, the <tt class="docutils literal"><span class="pre">postgresql_where</span></tt>
argument would be locatable as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">arg</span> <span class="o">=</span> <span class="n">my_object</span><span class="o">.</span><span class="n">dialect_options</span><span class="p">[</span><span class="s">&#39;postgresql&#39;</span><span class="p">][</span><span class="s">&#39;where&#39;</span><span class="p">]</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.2.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a> - flat dictionary form</p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.execute">
<tt class="descname">execute</tt><big>(</big><em>*multiparams</em>, <em>**params</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.execute" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.execute" title="sqlalchemy.sql.expression.Executable.execute"><tt class="xref py py-meth docutils literal"><span class="pre">execute()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Compile and execute this <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.execution_options">
<tt class="descname">execution_options</tt><big>(</big><em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.execution_options" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.execution_options" title="sqlalchemy.sql.expression.Executable.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">execution_options()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Set non-SQL options for the statement which take effect during
execution.</p>
<p>Execution options can be set on a per-statement or
per <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> basis.   Additionally, the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> and ORM <a class="reference internal" href="../orm/query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> objects provide
access to execution options which they in turn configure upon
connections.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.Update.execution_options" title="sqlalchemy.sql.expression.Update.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">execution_options()</span></tt></a> method is generative.  A new
instance of this statement is returned that contains the options:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">statement</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">,</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">y</span><span class="p">])</span>
<span class="n">statement</span> <span class="o">=</span> <span class="n">statement</span><span class="o">.</span><span class="n">execution_options</span><span class="p">(</span><span class="n">autocommit</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span></pre></div>
</div>
<p>Note that only a subset of possible execution options can be applied
to a statement - these include &#8220;autocommit&#8221; and &#8220;stream_results&#8221;,
but not &#8220;isolation_level&#8221; or &#8220;compiled_cache&#8221;.
See <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execution_options()</span></tt></a> for a full list of
possible options.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execution_options()</span></tt></a></p>
<p class="last"><a class="reference internal" href="../orm/query.html#sqlalchemy.orm.query.Query.execution_options" title="sqlalchemy.orm.query.Query.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Query.execution_options()</span></tt></a></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.Update.kwargs">
<tt class="descname">kwargs</tt><a class="headerlink" href="#sqlalchemy.sql.expression.Update.kwargs" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.kwargs" title="sqlalchemy.sql.base.DialectKWArgs.kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">kwargs</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A synonym for <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.params">
<tt class="descname">params</tt><big>(</big><em>*arg</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.params" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.params" title="sqlalchemy.sql.expression.UpdateBase.params"><tt class="xref py py-meth docutils literal"><span class="pre">params()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Set the parameters for the statement.</p>
<p>This method raises <tt class="docutils literal"><span class="pre">NotImplementedError</span></tt> on the base class,
and is overridden by <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">ValuesBase</span></tt></a> to provide the
SET/VALUES clause of UPDATE and INSERT.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.prefix_with">
<tt class="descname">prefix_with</tt><big>(</big><em>*expr</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.prefix_with" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.HasPrefixes.prefix_with" title="sqlalchemy.sql.expression.HasPrefixes.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">prefix_with()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.HasPrefixes" title="sqlalchemy.sql.expression.HasPrefixes"><tt class="xref py py-class docutils literal"><span class="pre">HasPrefixes</span></tt></a></div>
<p>Add one or more expressions following the statement keyword, i.e.
SELECT, INSERT, UPDATE, or DELETE. Generative.</p>
<p>This is used to support backend-specific prefix keywords such as those
provided by MySQL.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">prefix_with</span><span class="p">(</span><span class="s">&quot;LOW_PRIORITY&quot;</span><span class="p">,</span> <span class="n">dialect</span><span class="o">=</span><span class="s">&quot;mysql&quot;</span><span class="p">)</span></pre></div>
</div>
<p>Multiple prefixes can be specified by multiple calls
to <a class="reference internal" href="#sqlalchemy.sql.expression.Update.prefix_with" title="sqlalchemy.sql.expression.Update.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">prefix_with()</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Update.prefix_with.params.*expr"></span><strong>*expr</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.prefix_with.params.*expr">¶</a> &#8211; textual or <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a> construct which
will be rendered following the INSERT, UPDATE, or DELETE
keyword.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Update.prefix_with.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.prefix_with.params.**kw">¶</a> &#8211; A single keyword &#8216;dialect&#8217; is accepted.  This is an
optional string dialect name which will
limit rendering of this prefix to only that dialect.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.return_defaults">
<tt class="descname">return_defaults</tt><big>(</big><em>*cols</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.return_defaults" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">return_defaults()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">ValuesBase</span></tt></a></div>
<p>Make use of a <a class="reference internal" href="../glossary.html#term-returning"><em class="xref std std-term">RETURNING</em></a> clause for the purpose
of fetching server-side expressions and defaults.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s">&#39;newdata&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">return_defaults</span><span class="p">()</span>

<span class="n">result</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">)</span>

<span class="n">server_created_at</span> <span class="o">=</span> <span class="n">result</span><span class="o">.</span><span class="n">returned_defaults</span><span class="p">[</span><span class="s">&#39;created_at&#39;</span><span class="p">]</span></pre></div>
</div>
<p>When used against a backend that supports RETURNING, all column
values generated by SQL expression or server-side-default will be
added to any existing RETURNING clause, provided that
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> is not used simultaneously.  The column
values will then be available on the result using the
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.returned_defaults" title="sqlalchemy.engine.ResultProxy.returned_defaults"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.returned_defaults</span></tt></a> accessor as a dictionary,
referring to values keyed to the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> object as well as
its <tt class="docutils literal"><span class="pre">.key</span></tt>.</p>
<p>This method differs from <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> in these ways:</p>
<ol class="arabic simple">
<li><a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is only intended for use with
an INSERT or an UPDATE statement that matches exactly one row.
While the RETURNING construct in the general sense supports
multiple rows for a multi-row UPDATE or DELETE statement, or for
special cases of INSERT that return multiple rows (e.g. INSERT from
SELECT, multi-valued VALUES clause),
<a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is intended only for an
&#8220;ORM-style&#8221; single-row INSERT/UPDATE statement.  The row returned
by the statement is also consumed implcitly when
<a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is used.  By contrast,
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> leaves the RETURNING result-set
intact with a collection of any number of rows.</li>
<li>It is compatible with the existing logic to fetch auto-generated
primary key values, also known as &#8220;implicit returning&#8221;.  Backends
that support RETURNING will automatically make use of RETURNING in
order to fetch the value of newly generated primary keys; while the
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> method circumvents this behavior,
<a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> leaves it intact.</li>
<li>It can be called against any backend.  Backends that don&#8217;t support
RETURNING will skip the usage of the feature, rather than raising
an exception.  The return value of
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.returned_defaults" title="sqlalchemy.engine.ResultProxy.returned_defaults"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.returned_defaults</span></tt></a> will be <tt class="docutils literal"><span class="pre">None</span></tt></li>
</ol>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is used by the ORM to provide
an efficient implementation for the <tt class="docutils literal"><span class="pre">eager_defaults</span></tt> feature of
<a class="reference internal" href="../orm/mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.sql.expression.Update.return_defaults.params.cols"></span><strong>cols</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.return_defaults.params.cols">¶</a> &#8211; optional list of column key names or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>
objects.  If omitted, all column expressions evaulated on the server
are added to the returning list.</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.9.0.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a></p>
<p class="last"><a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.returned_defaults" title="sqlalchemy.engine.ResultProxy.returned_defaults"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.returned_defaults</span></tt></a></p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.returning">
<tt class="descname">returning</tt><big>(</big><em>*cols</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.returning" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">returning()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Add a <a class="reference internal" href="../glossary.html#term-returning"><em class="xref std std-term">RETURNING</em></a> or equivalent clause to this statement.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span>\
          <span class="n">where</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span> <span class="o">==</span> <span class="s">&#39;value&#39;</span><span class="p">)</span><span class="o">.</span>\
          <span class="n">values</span><span class="p">(</span><span class="n">status</span><span class="o">=</span><span class="s">&#39;X&#39;</span><span class="p">)</span><span class="o">.</span>\
          <span class="n">returning</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">server_flag</span><span class="p">,</span>
                    <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">updated_timestamp</span><span class="p">)</span>

<span class="k">for</span> <span class="n">server_flag</span><span class="p">,</span> <span class="n">updated_timestamp</span> <span class="ow">in</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">server_flag</span><span class="p">,</span> <span class="n">updated_timestamp</span><span class="p">)</span></pre></div>
</div>
<p>The given collection of column expressions should be derived from
the table that is
the target of the INSERT, UPDATE, or DELETE.  While <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>
objects are typical, the elements can also be expressions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">returning</span><span class="p">(</span>
    <span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">first_name</span> <span class="o">+</span> <span class="s">&quot; &quot;</span> <span class="o">+</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">last_name</span><span class="p">)</span><span class="o">.</span>
    <span class="n">label</span><span class="p">(</span><span class="s">&#39;fullname&#39;</span><span class="p">))</span></pre></div>
</div>
<p>Upon compilation, a RETURNING clause, or database equivalent,
will be rendered within the statement.   For INSERT and UPDATE,
the values are the newly inserted/updated values.  For DELETE,
the values are those of the rows which were deleted.</p>
<p>Upon execution, the values of the columns to be returned are made
available via the result set and can be iterated using
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.fetchone" title="sqlalchemy.engine.ResultProxy.fetchone"><tt class="xref py py-meth docutils literal"><span class="pre">ResultProxy.fetchone()</span></tt></a> and similar.   For DBAPIs which do not
natively support returning values (i.e. cx_oracle), SQLAlchemy will
approximate this behavior at the result level so that a reasonable
amount of behavioral neutrality is provided.</p>
<p>Note that not all databases/DBAPIs
support RETURNING.   For those backends with no support,
an exception is raised upon compilation and/or execution.
For those who do support it, the functionality across backends
varies greatly, including restrictions on executemany()
and other statements which return multiple rows. Please
read the documentation notes for the database in use in
order to determine the availability of RETURNING.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> - an alternative method tailored
towards efficient fetching of server-side defaults and triggers
for single-row INSERTs or UPDATEs.</p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.scalar">
<tt class="descname">scalar</tt><big>(</big><em>*multiparams</em>, <em>**params</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.scalar" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.scalar" title="sqlalchemy.sql.expression.Executable.scalar"><tt class="xref py py-meth docutils literal"><span class="pre">scalar()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Compile and execute this <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a>, returning the
result&#8217;s scalar representation.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.self_group">
<tt class="descname">self_group</tt><big>(</big><em>against=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.self_group" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.self_group" title="sqlalchemy.sql.expression.ClauseElement.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Apply a &#8216;grouping&#8217; to this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>.</p>
<p>This method is overridden by subclasses to return a
&#8220;grouping&#8221; construct, i.e. parenthesis.   In particular
it&#8217;s used by &#8220;binary&#8221; expressions to provide a grouping
around themselves when placed into a larger expression,
as well as by <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> constructs when placed into
the FROM clause of another <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a>.  (Note that
subqueries should be normally created using the
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.alias" title="sqlalchemy.sql.expression.Select.alias"><tt class="xref py py-meth docutils literal"><span class="pre">Select.alias()</span></tt></a> method, as many platforms require
nested SELECT statements to be named).</p>
<p>As expressions are composed together, the application of
<a class="reference internal" href="#sqlalchemy.sql.expression.Update.self_group" title="sqlalchemy.sql.expression.Update.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> is automatic - end-user code should never
need to use this method directly.  Note that SQLAlchemy&#8217;s
clause constructs take operator precedence into account -
so parenthesis might not be needed, for example, in
an expression like <tt class="docutils literal"><span class="pre">x</span> <span class="pre">OR</span> <span class="pre">(y</span> <span class="pre">AND</span> <span class="pre">z)</span></tt> - AND takes precedence
over OR.</p>
<p>The base <a class="reference internal" href="#sqlalchemy.sql.expression.Update.self_group" title="sqlalchemy.sql.expression.Update.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> method of <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>
just returns self.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.unique_params">
<tt class="descname">unique_params</tt><big>(</big><em>*optionaldict</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.unique_params" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.unique_params" title="sqlalchemy.sql.expression.ClauseElement.unique_params"><tt class="xref py py-meth docutils literal"><span class="pre">unique_params()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Return a copy with <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> elements replaced.</p>
<p>Same functionality as <tt class="docutils literal"><span class="pre">params()</span></tt>, except adds <cite>unique=True</cite>
to affected bind parameters so that multiple statements can be
used.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.values">
<tt class="descname">values</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.values" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">values()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">ValuesBase</span></tt></a></div>
<p>specify a fixed VALUES clause for an INSERT statement, or the SET
clause for an UPDATE.</p>
<p>Note that the <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update</span></tt></a> constructs support
per-execution time formatting of the VALUES and/or SET clauses,
based on the arguments passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>.
However, the <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> method can be used to &#8220;fix&#8221; a
particular set of parameters into the statement.</p>
<p>Multiple calls to <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> will produce a new
construct, each one with the parameter list modified to include
the new parameters sent.  In the typical case of a single
dictionary of parameters, the newly passed keys will replace
the same keys in the previous construct.  In the case of a list-based
&#8220;multiple values&#8221; construct, each new list of values is extended
onto the existing list of values.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Update.values.params.**kwargs"></span><strong>**kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.values.params.**kwargs">¶</a> &#8211; <p>key value pairs representing the string key
of a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> mapped to the value to be rendered into the
VALUES or SET clause:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;some name&quot;</span><span class="p">)</span>

<span class="n">users</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">users</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;some name&quot;</span><span class="p">)</span></pre></div>
</div>
</li>
<li><span class="target" id="sqlalchemy.sql.expression.Update.values.params.*args"></span><strong>*args</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.values.params.*args">¶</a> &#8211; <p>Alternatively, a dictionary, tuple or list
of dictionaries or tuples can be passed as a single positional
argument in order to form the VALUES or
SET clause of the statement.  The single dictionary form
works the same as the kwargs form:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">({</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;some name&quot;</span><span class="p">})</span></pre></div>
</div>
<p>If a tuple is passed, the tuple should contain the same number
of columns as the target <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">((</span><span class="mi">5</span><span class="p">,</span> <span class="s">&quot;some name&quot;</span><span class="p">))</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> construct also supports multiply-rendered VALUES
construct, for those backends which support this SQL syntax
(SQLite, Postgresql, MySQL).  This mode is indicated by passing a
list of one or more dictionaries/tuples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">([</span>
                    <span class="p">{</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;some name&quot;</span><span class="p">},</span>
                    <span class="p">{</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;some other name&quot;</span><span class="p">},</span>
                    <span class="p">{</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;yet another name&quot;</span><span class="p">},</span>
                <span class="p">])</span></pre></div>
</div>
<p>In the case of an <a class="reference internal" href="#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update</span></tt></a>
construct, only the single dictionary/tuple form is accepted,
else an exception is raised.  It is also an exception case to
attempt to mix the single-/multiple- value styles together,
either through multiple <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> calls
or by sending a list + kwargs at the same time.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Passing a multiple values list is <em>not</em> the same
as passing a multiple values list to the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a> method.  Passing a list of parameter
sets to <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> produces a construct of this
form:</p>
<div class="highlight-python"><pre>INSERT INTO table (col1, col2, col3) VALUES
                (col1_0, col2_0, col3_0),
                (col1_1, col2_1, col3_1),
                ...</pre>
</div>
<p class="last">whereas a multiple list passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>
has the effect of using the DBAPI
<a class="reference external" href="http://www.python.org/dev/peps/pep-0249/#id18">executemany()</a>
method, which provides a high-performance system of invoking
a single-row INSERT statement many times against a series
of parameter sets.   The &#8220;executemany&#8221; style is supported by
all database backends, as it does not depend on a special SQL
syntax.</p>
</div>
<div class="versionadded">
<p><span>New in version 0.8: </span>Support for multiple-VALUES INSERT statements.</p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="tutorial.html#inserts-and-updates"><em>Inserts, Updates and Deletes</em></a> - SQL Expression
Language Tutorial</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.insert" title="sqlalchemy.sql.expression.insert"><tt class="xref py py-func docutils literal"><span class="pre">insert()</span></tt></a> - produce an <tt class="docutils literal"><span class="pre">INSERT</span></tt> statement</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.update" title="sqlalchemy.sql.expression.update"><tt class="xref py py-func docutils literal"><span class="pre">update()</span></tt></a> - produce an <tt class="docutils literal"><span class="pre">UPDATE</span></tt> statement</p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.where">
<tt class="descname">where</tt><big>(</big><em>whereclause</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.where" title="Permalink to this definition">¶</a></dt>
<dd><p>return a new update() construct with the given expression added to
its WHERE clause, joined to the existing clause via AND, if any.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.Update.with_hint">
<tt class="descname">with_hint</tt><big>(</big><em>text</em>, <em>selectable=None</em>, <em>dialect_name='*'</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Update.with_hint" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.with_hint" title="sqlalchemy.sql.expression.UpdateBase.with_hint"><tt class="xref py py-meth docutils literal"><span class="pre">with_hint()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a></div>
<p>Add a table hint for a single table to this
INSERT/UPDATE/DELETE statement.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.with_hint" title="sqlalchemy.sql.expression.UpdateBase.with_hint"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.with_hint()</span></tt></a> currently applies only to
Microsoft SQL Server.  For MySQL INSERT/UPDATE/DELETE hints, use
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.prefix_with" title="sqlalchemy.sql.expression.UpdateBase.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.prefix_with()</span></tt></a>.</p>
</div>
<p>The text of the hint is rendered in the appropriate
location for the database backend in use, relative
to the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> that is the subject of this
statement, or optionally to that of the given
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> passed as the <tt class="docutils literal"><span class="pre">selectable</span></tt> argument.</p>
<p>The <tt class="docutils literal"><span class="pre">dialect_name</span></tt> option will limit the rendering of a particular
hint to a particular backend. Such as, to add a hint
that only takes effect for SQL Server:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mytable</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">with_hint</span><span class="p">(</span><span class="s">&quot;WITH (PAGLOCK)&quot;</span><span class="p">,</span> <span class="n">dialect_name</span><span class="o">=</span><span class="s">&quot;mssql&quot;</span><span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.7.6.</span></p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.Update.with_hint.params.text"></span><strong>text</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.with_hint.params.text">¶</a> &#8211; Text of the hint.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Update.with_hint.params.selectable"></span><strong>selectable</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.with_hint.params.selectable">¶</a> &#8211; optional <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> 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.</li>
<li><span class="target" id="sqlalchemy.sql.expression.Update.with_hint.params.dialect_name"></span><strong>dialect_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.Update.with_hint.params.dialect_name">¶</a> &#8211; defaults to <tt class="docutils literal"><span class="pre">*</span></tt>, if specified as the name
of a particular dialect, will apply these hints only when
that dialect is in use.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.sql.expression.UpdateBase">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">UpdateBase</tt><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.base.DialectKWArgs</span></tt></a>, <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.HasPrefixes" title="sqlalchemy.sql.expression.HasPrefixes"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.HasPrefixes</span></tt></a>, <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.Executable</span></tt></a>, <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ClauseElement</span></tt></a></p>
<p>Form the base for <tt class="docutils literal"><span class="pre">INSERT</span></tt>, <tt class="docutils literal"><span class="pre">UPDATE</span></tt>, and <tt class="docutils literal"><span class="pre">DELETE</span></tt> statements.</p>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.UpdateBase.__init__">
<tt class="descname">__init__</tt><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.__init__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-attr docutils literal"><span class="pre">__init__</span></tt> <em>attribute of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>x.__init__(...) initializes x; see help(type(x)) for signature</p>
</dd></dl>

<dl class="classmethod">
<dt id="sqlalchemy.sql.expression.UpdateBase.argument_for">
<em class="property">classmethod </em><tt class="descname">argument_for</tt><big>(</big><em>dialect_name</em>, <em>argument_name</em>, <em>default</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.argument_for" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.argument_for" title="sqlalchemy.sql.base.DialectKWArgs.argument_for"><tt class="xref py py-meth docutils literal"><span class="pre">argument_for()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>Add a new kind of dialect-specific keyword argument for this class.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Index</span><span class="o">.</span><span class="n">argument_for</span><span class="p">(</span><span class="s">&quot;mydialect&quot;</span><span class="p">,</span> <span class="s">&quot;length&quot;</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>

<span class="n">some_index</span> <span class="o">=</span> <span class="n">Index</span><span class="p">(</span><span class="s">&#39;a&#39;</span><span class="p">,</span> <span class="s">&#39;b&#39;</span><span class="p">,</span> <span class="n">mydialect_length</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.argument_for" title="sqlalchemy.sql.base.DialectKWArgs.argument_for"><tt class="xref py py-meth docutils literal"><span class="pre">DialectKWArgs.argument_for()</span></tt></a> method is a per-argument
way adding extra arguments to the
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> dictionary. This
dictionary provides a list of argument names accepted by various
schema-level constructs on behalf of a dialect.</p>
<p>New dialects should typically specify this dictionary all at once as a
data member of the dialect class.  The use case for ad-hoc addition of
argument names is typically for end-user code that is also using
a custom compilation scheme which consumes the additional arguments.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.argument_for.params.dialect_name"></span><strong>dialect_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.argument_for.params.dialect_name">¶</a> &#8211; name of a dialect.  The dialect must be
locatable, else a <tt class="xref py py-class docutils literal"><span class="pre">NoSuchModuleError</span></tt> is raised.   The
dialect must also include an existing
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> collection, indicating
that it participates in the keyword-argument validation and default
system, else <tt class="xref py py-class docutils literal"><span class="pre">ArgumentError</span></tt> is raised.  If the dialect does
not include this collection, then any keyword argument can be
specified on behalf of this dialect already.  All dialects packaged
within SQLAlchemy include this collection, however for third party
dialects, support may vary.</li>
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.argument_for.params.argument_name"></span><strong>argument_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.argument_for.params.argument_name">¶</a> &#8211; name of the parameter.</li>
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.argument_for.params.default"></span><strong>default</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.argument_for.params.default">¶</a> &#8211; default value of the parameter.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.9.4.</span></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.UpdateBase.bind">
<tt class="descname">bind</tt><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.bind" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a &#8216;bind&#8217; linked to this <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">UpdateBase</span></tt></a>
or a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> associated with it.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.compare">
<tt class="descname">compare</tt><big>(</big><em>other</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.compare" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.compare" title="sqlalchemy.sql.expression.ClauseElement.compare"><tt class="xref py py-meth docutils literal"><span class="pre">compare()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Compare this ClauseElement to the given ClauseElement.</p>
<p>Subclasses should override the default behavior, which is a
straight identity comparison.</p>
<p>**kw are arguments consumed by subclass compare() methods and
may be used to modify the criteria for comparison.
(see <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>)</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.compile">
<tt class="descname">compile</tt><big>(</big><em>bind=None</em>, <em>dialect=None</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.compile" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.compile" title="sqlalchemy.sql.expression.ClauseElement.compile"><tt class="xref py py-meth docutils literal"><span class="pre">compile()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Compile this SQL expression.</p>
<p>The return value is a <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object.
Calling <tt class="docutils literal"><span class="pre">str()</span></tt> or <tt class="docutils literal"><span class="pre">unicode()</span></tt> on the returned value will yield a
string representation of the result. The
<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object also can return a
dictionary of bind parameter names and values
using the <tt class="docutils literal"><span class="pre">params</span></tt> accessor.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.compile.params.bind"></span><strong>bind</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.compile.params.bind">¶</a> &#8211; An <tt class="docutils literal"><span class="pre">Engine</span></tt> or <tt class="docutils literal"><span class="pre">Connection</span></tt> from which a
<tt class="docutils literal"><span class="pre">Compiled</span></tt> will be acquired. This argument takes precedence over
this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>&#8216;s bound engine, if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.compile.params.column_keys"></span><strong>column_keys</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.compile.params.column_keys">¶</a> &#8211; Used for INSERT and UPDATE statements, a list of
column names which should be present in the VALUES clause of the
compiled statement. If <tt class="docutils literal"><span class="pre">None</span></tt>, all columns from the target table
object are rendered.</li>
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.compile.params.dialect"></span><strong>dialect</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.compile.params.dialect">¶</a> &#8211; A <tt class="docutils literal"><span class="pre">Dialect</span></tt> instance from which a <tt class="docutils literal"><span class="pre">Compiled</span></tt>
will be acquired. This argument takes precedence over the <cite>bind</cite>
argument as well as this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>&#8216;s bound engine,
if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.compile.params.inline"></span><strong>inline</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.compile.params.inline">¶</a> &#8211; 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&#8217;s
VALUES clause. This typically refers to Sequence execution but may
also refer to any server-side default generation function
associated with a primary key <cite>Column</cite>.</li>
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.compile.params.compile_kwargs"></span><strong>compile_kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.compile.params.compile_kwargs">¶</a> &#8211; <p>optional dictionary of additional parameters
that will be passed through to the compiler within all &#8220;visit&#8221;
methods.  This allows any custom flag to be passed through to
a custom compilation construct, for example.  It is also used
for the case of passing the <tt class="docutils literal"><span class="pre">literal_binds</span></tt> flag through:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">table</span><span class="p">,</span> <span class="n">column</span><span class="p">,</span> <span class="n">select</span>

<span class="n">t</span> <span class="o">=</span> <span class="n">table</span><span class="p">(</span><span class="s">&#39;t&#39;</span><span class="p">,</span> <span class="n">column</span><span class="p">(</span><span class="s">&#39;x&#39;</span><span class="p">))</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span> <span class="o">==</span> <span class="mi">5</span><span class="p">)</span>

<span class="k">print</span> <span class="n">s</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">compile_kwargs</span><span class="o">=</span><span class="p">{</span><span class="s">&quot;literal_binds&quot;</span><span class="p">:</span> <span class="bp">True</span><span class="p">})</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.0.</span></p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../faq.html#faq-sql-expression-string"><em>How do I render SQL expressions as strings, possibly with bound parameters inlined?</em></a></p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.UpdateBase.dialect_kwargs">
<tt class="descname">dialect_kwargs</tt><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.dialect_kwargs" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">dialect_kwargs</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A collection of keyword arguments specified as dialect-specific
options to this construct.</p>
<p>The arguments are present here in their original <tt class="docutils literal"><span class="pre">&lt;dialect&gt;_&lt;kwarg&gt;</span></tt>
format.  Only arguments that were actually passed are included;
unlike the <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_options</span></tt></a> collection, which
contains all options known by this dialect including defaults.</p>
<p>The collection is also writable; keys are accepted of the
form <tt class="docutils literal"><span class="pre">&lt;dialect&gt;_&lt;kwarg&gt;</span></tt> where the value will be assembled
into the list of options.</p>
<div class="versionadded">
<p><span>New in version 0.9.2.</span></p>
</div>
<div class="versionchanged">
<p><span>Changed in version 0.9.4: </span>The <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a>
collection is now writable.</p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_options</span></tt></a> - nested dictionary form</p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.UpdateBase.dialect_options">
<tt class="descname">dialect_options</tt><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.dialect_options" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">dialect_options</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A collection of keyword arguments specified as dialect-specific
options to this construct.</p>
<p>This is a two-level nested registry, keyed to <tt class="docutils literal"><span class="pre">&lt;dialect_name&gt;</span></tt>
and <tt class="docutils literal"><span class="pre">&lt;argument_name&gt;</span></tt>.  For example, the <tt class="docutils literal"><span class="pre">postgresql_where</span></tt>
argument would be locatable as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">arg</span> <span class="o">=</span> <span class="n">my_object</span><span class="o">.</span><span class="n">dialect_options</span><span class="p">[</span><span class="s">&#39;postgresql&#39;</span><span class="p">][</span><span class="s">&#39;where&#39;</span><span class="p">]</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.2.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a> - flat dictionary form</p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.execute">
<tt class="descname">execute</tt><big>(</big><em>*multiparams</em>, <em>**params</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.execute" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.execute" title="sqlalchemy.sql.expression.Executable.execute"><tt class="xref py py-meth docutils literal"><span class="pre">execute()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Compile and execute this <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.execution_options">
<tt class="descname">execution_options</tt><big>(</big><em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.execution_options" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.execution_options" title="sqlalchemy.sql.expression.Executable.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">execution_options()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Set non-SQL options for the statement which take effect during
execution.</p>
<p>Execution options can be set on a per-statement or
per <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> basis.   Additionally, the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> and ORM <a class="reference internal" href="../orm/query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> objects provide
access to execution options which they in turn configure upon
connections.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.execution_options" title="sqlalchemy.sql.expression.UpdateBase.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">execution_options()</span></tt></a> method is generative.  A new
instance of this statement is returned that contains the options:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">statement</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">,</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">y</span><span class="p">])</span>
<span class="n">statement</span> <span class="o">=</span> <span class="n">statement</span><span class="o">.</span><span class="n">execution_options</span><span class="p">(</span><span class="n">autocommit</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span></pre></div>
</div>
<p>Note that only a subset of possible execution options can be applied
to a statement - these include &#8220;autocommit&#8221; and &#8220;stream_results&#8221;,
but not &#8220;isolation_level&#8221; or &#8220;compiled_cache&#8221;.
See <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execution_options()</span></tt></a> for a full list of
possible options.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execution_options()</span></tt></a></p>
<p class="last"><a class="reference internal" href="../orm/query.html#sqlalchemy.orm.query.Query.execution_options" title="sqlalchemy.orm.query.Query.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Query.execution_options()</span></tt></a></p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.get_children">
<tt class="descname">get_children</tt><big>(</big><em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.get_children" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.get_children" title="sqlalchemy.sql.expression.ClauseElement.get_children"><tt class="xref py py-meth docutils literal"><span class="pre">get_children()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Return immediate child elements of this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>.</p>
<p>This is used for visit traversal.</p>
<p>**kwargs may contain flags that change the collection that is
returned, for example to return a subset of items in order to
cut down on larger traversals, or to return child items from a
different context (such as schema-level collections instead of
clause-level).</p>
</dd></dl>

<dl class="attribute">
<dt id="sqlalchemy.sql.expression.UpdateBase.kwargs">
<tt class="descname">kwargs</tt><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.kwargs" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.kwargs" title="sqlalchemy.sql.base.DialectKWArgs.kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">kwargs</span></tt></a> <em>attribute of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a></div>
<p>A synonym for <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.params">
<tt class="descname">params</tt><big>(</big><em>*arg</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.params" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the parameters for the statement.</p>
<p>This method raises <tt class="docutils literal"><span class="pre">NotImplementedError</span></tt> on the base class,
and is overridden by <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase" title="sqlalchemy.sql.expression.ValuesBase"><tt class="xref py py-class docutils literal"><span class="pre">ValuesBase</span></tt></a> to provide the
SET/VALUES clause of UPDATE and INSERT.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.prefix_with">
<tt class="descname">prefix_with</tt><big>(</big><em>*expr</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.prefix_with" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.HasPrefixes.prefix_with" title="sqlalchemy.sql.expression.HasPrefixes.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">prefix_with()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.HasPrefixes" title="sqlalchemy.sql.expression.HasPrefixes"><tt class="xref py py-class docutils literal"><span class="pre">HasPrefixes</span></tt></a></div>
<p>Add one or more expressions following the statement keyword, i.e.
SELECT, INSERT, UPDATE, or DELETE. Generative.</p>
<p>This is used to support backend-specific prefix keywords such as those
provided by MySQL.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">prefix_with</span><span class="p">(</span><span class="s">&quot;LOW_PRIORITY&quot;</span><span class="p">,</span> <span class="n">dialect</span><span class="o">=</span><span class="s">&quot;mysql&quot;</span><span class="p">)</span></pre></div>
</div>
<p>Multiple prefixes can be specified by multiple calls
to <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.prefix_with" title="sqlalchemy.sql.expression.UpdateBase.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">prefix_with()</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.prefix_with.params.*expr"></span><strong>*expr</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.prefix_with.params.*expr">¶</a> &#8211; textual or <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a> construct which
will be rendered following the INSERT, UPDATE, or DELETE
keyword.</li>
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.prefix_with.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.prefix_with.params.**kw">¶</a> &#8211; A single keyword &#8216;dialect&#8217; is accepted.  This is an
optional string dialect name which will
limit rendering of this prefix to only that dialect.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.returning">
<tt class="descname">returning</tt><big>(</big><em>*cols</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a <a class="reference internal" href="../glossary.html#term-returning"><em class="xref std std-term">RETURNING</em></a> or equivalent clause to this statement.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span>\
          <span class="n">where</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">data</span> <span class="o">==</span> <span class="s">&#39;value&#39;</span><span class="p">)</span><span class="o">.</span>\
          <span class="n">values</span><span class="p">(</span><span class="n">status</span><span class="o">=</span><span class="s">&#39;X&#39;</span><span class="p">)</span><span class="o">.</span>\
          <span class="n">returning</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">server_flag</span><span class="p">,</span>
                    <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">updated_timestamp</span><span class="p">)</span>

<span class="k">for</span> <span class="n">server_flag</span><span class="p">,</span> <span class="n">updated_timestamp</span> <span class="ow">in</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">server_flag</span><span class="p">,</span> <span class="n">updated_timestamp</span><span class="p">)</span></pre></div>
</div>
<p>The given collection of column expressions should be derived from
the table that is
the target of the INSERT, UPDATE, or DELETE.  While <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>
objects are typical, the elements can also be expressions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">returning</span><span class="p">(</span>
    <span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">first_name</span> <span class="o">+</span> <span class="s">&quot; &quot;</span> <span class="o">+</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">last_name</span><span class="p">)</span><span class="o">.</span>
    <span class="n">label</span><span class="p">(</span><span class="s">&#39;fullname&#39;</span><span class="p">))</span></pre></div>
</div>
<p>Upon compilation, a RETURNING clause, or database equivalent,
will be rendered within the statement.   For INSERT and UPDATE,
the values are the newly inserted/updated values.  For DELETE,
the values are those of the rows which were deleted.</p>
<p>Upon execution, the values of the columns to be returned are made
available via the result set and can be iterated using
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.fetchone" title="sqlalchemy.engine.ResultProxy.fetchone"><tt class="xref py py-meth docutils literal"><span class="pre">ResultProxy.fetchone()</span></tt></a> and similar.   For DBAPIs which do not
natively support returning values (i.e. cx_oracle), SQLAlchemy will
approximate this behavior at the result level so that a reasonable
amount of behavioral neutrality is provided.</p>
<p>Note that not all databases/DBAPIs
support RETURNING.   For those backends with no support,
an exception is raised upon compilation and/or execution.
For those who do support it, the functionality across backends
varies greatly, including restrictions on executemany()
and other statements which return multiple rows. Please
read the documentation notes for the database in use in
order to determine the availability of RETURNING.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> - an alternative method tailored
towards efficient fetching of server-side defaults and triggers
for single-row INSERTs or UPDATEs.</p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.scalar">
<tt class="descname">scalar</tt><big>(</big><em>*multiparams</em>, <em>**params</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.scalar" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.scalar" title="sqlalchemy.sql.expression.Executable.scalar"><tt class="xref py py-meth docutils literal"><span class="pre">scalar()</span></tt></a> <em>method of</em> <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a></div>
<p>Compile and execute this <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a>, returning the
result&#8217;s scalar representation.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.self_group">
<tt class="descname">self_group</tt><big>(</big><em>against=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.self_group" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.self_group" title="sqlalchemy.sql.expression.ClauseElement.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Apply a &#8216;grouping&#8217; to this <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>.</p>
<p>This method is overridden by subclasses to return a
&#8220;grouping&#8221; construct, i.e. parenthesis.   In particular
it&#8217;s used by &#8220;binary&#8221; expressions to provide a grouping
around themselves when placed into a larger expression,
as well as by <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> constructs when placed into
the FROM clause of another <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a>.  (Note that
subqueries should be normally created using the
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.alias" title="sqlalchemy.sql.expression.Select.alias"><tt class="xref py py-meth docutils literal"><span class="pre">Select.alias()</span></tt></a> method, as many platforms require
nested SELECT statements to be named).</p>
<p>As expressions are composed together, the application of
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.self_group" title="sqlalchemy.sql.expression.UpdateBase.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> is automatic - end-user code should never
need to use this method directly.  Note that SQLAlchemy&#8217;s
clause constructs take operator precedence into account -
so parenthesis might not be needed, for example, in
an expression like <tt class="docutils literal"><span class="pre">x</span> <span class="pre">OR</span> <span class="pre">(y</span> <span class="pre">AND</span> <span class="pre">z)</span></tt> - AND takes precedence
over OR.</p>
<p>The base <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.self_group" title="sqlalchemy.sql.expression.UpdateBase.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> method of <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>
just returns self.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.unique_params">
<tt class="descname">unique_params</tt><big>(</big><em>*optionaldict</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.unique_params" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement.unique_params" title="sqlalchemy.sql.expression.ClauseElement.unique_params"><tt class="xref py py-meth docutils literal"><span class="pre">unique_params()</span></tt></a> <em>method of</em> <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Return a copy with <a class="reference internal" href="sqlelement.html#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> elements replaced.</p>
<p>Same functionality as <tt class="docutils literal"><span class="pre">params()</span></tt>, except adds <cite>unique=True</cite>
to affected bind parameters so that multiple statements can be
used.</p>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.UpdateBase.with_hint">
<tt class="descname">with_hint</tt><big>(</big><em>text</em>, <em>selectable=None</em>, <em>dialect_name='*'</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UpdateBase.with_hint" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a table hint for a single table to this
INSERT/UPDATE/DELETE statement.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.with_hint" title="sqlalchemy.sql.expression.UpdateBase.with_hint"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.with_hint()</span></tt></a> currently applies only to
Microsoft SQL Server.  For MySQL INSERT/UPDATE/DELETE hints, use
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.prefix_with" title="sqlalchemy.sql.expression.UpdateBase.prefix_with"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.prefix_with()</span></tt></a>.</p>
</div>
<p>The text of the hint is rendered in the appropriate
location for the database backend in use, relative
to the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> that is the subject of this
statement, or optionally to that of the given
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> passed as the <tt class="docutils literal"><span class="pre">selectable</span></tt> argument.</p>
<p>The <tt class="docutils literal"><span class="pre">dialect_name</span></tt> option will limit the rendering of a particular
hint to a particular backend. Such as, to add a hint
that only takes effect for SQL Server:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mytable</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">with_hint</span><span class="p">(</span><span class="s">&quot;WITH (PAGLOCK)&quot;</span><span class="p">,</span> <span class="n">dialect_name</span><span class="o">=</span><span class="s">&quot;mssql&quot;</span><span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.7.6.</span></p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.with_hint.params.text"></span><strong>text</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.with_hint.params.text">¶</a> &#8211; Text of the hint.</li>
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.with_hint.params.selectable"></span><strong>selectable</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.with_hint.params.selectable">¶</a> &#8211; optional <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> 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.</li>
<li><span class="target" id="sqlalchemy.sql.expression.UpdateBase.with_hint.params.dialect_name"></span><strong>dialect_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.UpdateBase.with_hint.params.dialect_name">¶</a> &#8211; defaults to <tt class="docutils literal"><span class="pre">*</span></tt>, if specified as the name
of a particular dialect, will apply these hints only when
that dialect is in use.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="sqlalchemy.sql.expression.ValuesBase">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">ValuesBase</tt><big>(</big><em>table</em>, <em>values</em>, <em>prefixes</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ValuesBase" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase" title="sqlalchemy.sql.expression.UpdateBase"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.UpdateBase</span></tt></a></p>
<p>Supplies support for <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> to
INSERT and UPDATE constructs.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ValuesBase.return_defaults">
<tt class="descname">return_defaults</tt><big>(</big><em>*cols</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="Permalink to this definition">¶</a></dt>
<dd><p>Make use of a <a class="reference internal" href="../glossary.html#term-returning"><em class="xref std std-term">RETURNING</em></a> clause for the purpose
of fetching server-side expressions and defaults.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">data</span><span class="o">=</span><span class="s">&#39;newdata&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">return_defaults</span><span class="p">()</span>

<span class="n">result</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">)</span>

<span class="n">server_created_at</span> <span class="o">=</span> <span class="n">result</span><span class="o">.</span><span class="n">returned_defaults</span><span class="p">[</span><span class="s">&#39;created_at&#39;</span><span class="p">]</span></pre></div>
</div>
<p>When used against a backend that supports RETURNING, all column
values generated by SQL expression or server-side-default will be
added to any existing RETURNING clause, provided that
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> is not used simultaneously.  The column
values will then be available on the result using the
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.returned_defaults" title="sqlalchemy.engine.ResultProxy.returned_defaults"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.returned_defaults</span></tt></a> accessor as a dictionary,
referring to values keyed to the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> object as well as
its <tt class="docutils literal"><span class="pre">.key</span></tt>.</p>
<p>This method differs from <a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> in these ways:</p>
<ol class="arabic simple">
<li><a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is only intended for use with
an INSERT or an UPDATE statement that matches exactly one row.
While the RETURNING construct in the general sense supports
multiple rows for a multi-row UPDATE or DELETE statement, or for
special cases of INSERT that return multiple rows (e.g. INSERT from
SELECT, multi-valued VALUES clause),
<a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is intended only for an
&#8220;ORM-style&#8221; single-row INSERT/UPDATE statement.  The row returned
by the statement is also consumed implcitly when
<a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is used.  By contrast,
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> leaves the RETURNING result-set
intact with a collection of any number of rows.</li>
<li>It is compatible with the existing logic to fetch auto-generated
primary key values, also known as &#8220;implicit returning&#8221;.  Backends
that support RETURNING will automatically make use of RETURNING in
order to fetch the value of newly generated primary keys; while the
<a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a> method circumvents this behavior,
<a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> leaves it intact.</li>
<li>It can be called against any backend.  Backends that don&#8217;t support
RETURNING will skip the usage of the feature, rather than raising
an exception.  The return value of
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.returned_defaults" title="sqlalchemy.engine.ResultProxy.returned_defaults"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.returned_defaults</span></tt></a> will be <tt class="docutils literal"><span class="pre">None</span></tt></li>
</ol>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults" title="sqlalchemy.sql.expression.ValuesBase.return_defaults"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.return_defaults()</span></tt></a> is used by the ORM to provide
an efficient implementation for the <tt class="docutils literal"><span class="pre">eager_defaults</span></tt> feature of
<a class="reference internal" href="../orm/mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal"><span class="pre">mapper()</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.sql.expression.ValuesBase.return_defaults.params.cols"></span><strong>cols</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ValuesBase.return_defaults.params.cols">¶</a> &#8211; optional list of column key names or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>
objects.  If omitted, all column expressions evaulated on the server
are added to the returning list.</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.9.0.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.UpdateBase.returning" title="sqlalchemy.sql.expression.UpdateBase.returning"><tt class="xref py py-meth docutils literal"><span class="pre">UpdateBase.returning()</span></tt></a></p>
<p class="last"><a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy.returned_defaults" title="sqlalchemy.engine.ResultProxy.returned_defaults"><tt class="xref py py-attr docutils literal"><span class="pre">ResultProxy.returned_defaults</span></tt></a></p>
</div>
</dd></dl>

<dl class="method">
<dt id="sqlalchemy.sql.expression.ValuesBase.values">
<tt class="descname">values</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ValuesBase.values" title="Permalink to this definition">¶</a></dt>
<dd><p>specify a fixed VALUES clause for an INSERT statement, or the SET
clause for an UPDATE.</p>
<p>Note that the <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update</span></tt></a> constructs support
per-execution time formatting of the VALUES and/or SET clauses,
based on the arguments passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>.
However, the <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> method can be used to &#8220;fix&#8221; a
particular set of parameters into the statement.</p>
<p>Multiple calls to <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> will produce a new
construct, each one with the parameter list modified to include
the new parameters sent.  In the typical case of a single
dictionary of parameters, the newly passed keys will replace
the same keys in the previous construct.  In the case of a list-based
&#8220;multiple values&#8221; construct, each new list of values is extended
onto the existing list of values.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.ValuesBase.values.params.**kwargs"></span><strong>**kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values.params.**kwargs">¶</a> &#8211; <p>key value pairs representing the string key
of a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> mapped to the value to be rendered into the
VALUES or SET clause:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;some name&quot;</span><span class="p">)</span>

<span class="n">users</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">users</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="n">values</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;some name&quot;</span><span class="p">)</span></pre></div>
</div>
</li>
<li><span class="target" id="sqlalchemy.sql.expression.ValuesBase.values.params.*args"></span><strong>*args</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values.params.*args">¶</a> &#8211; <p>Alternatively, a dictionary, tuple or list
of dictionaries or tuples can be passed as a single positional
argument in order to form the VALUES or
SET clause of the statement.  The single dictionary form
works the same as the kwargs form:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">({</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;some name&quot;</span><span class="p">})</span></pre></div>
</div>
<p>If a tuple is passed, the tuple should contain the same number
of columns as the target <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">((</span><span class="mi">5</span><span class="p">,</span> <span class="s">&quot;some name&quot;</span><span class="p">))</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> construct also supports multiply-rendered VALUES
construct, for those backends which support this SQL syntax
(SQLite, Postgresql, MySQL).  This mode is indicated by passing a
list of one or more dictionaries/tuples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">users</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span><span class="o">.</span><span class="n">values</span><span class="p">([</span>
                    <span class="p">{</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;some name&quot;</span><span class="p">},</span>
                    <span class="p">{</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;some other name&quot;</span><span class="p">},</span>
                    <span class="p">{</span><span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;yet another name&quot;</span><span class="p">},</span>
                <span class="p">])</span></pre></div>
</div>
<p>In the case of an <a class="reference internal" href="#sqlalchemy.sql.expression.Update" title="sqlalchemy.sql.expression.Update"><tt class="xref py py-class docutils literal"><span class="pre">Update</span></tt></a>
construct, only the single dictionary/tuple form is accepted,
else an exception is raised.  It is also an exception case to
attempt to mix the single-/multiple- value styles together,
either through multiple <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> calls
or by sending a list + kwargs at the same time.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Passing a multiple values list is <em>not</em> the same
as passing a multiple values list to the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a> method.  Passing a list of parameter
sets to <a class="reference internal" href="#sqlalchemy.sql.expression.ValuesBase.values" title="sqlalchemy.sql.expression.ValuesBase.values"><tt class="xref py py-meth docutils literal"><span class="pre">ValuesBase.values()</span></tt></a> produces a construct of this
form:</p>
<div class="highlight-python"><pre>INSERT INTO table (col1, col2, col3) VALUES
                (col1_0, col2_0, col3_0),
                (col1_1, col2_1, col3_1),
                ...</pre>
</div>
<p class="last">whereas a multiple list passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>
has the effect of using the DBAPI
<a class="reference external" href="http://www.python.org/dev/peps/pep-0249/#id18">executemany()</a>
method, which provides a high-performance system of invoking
a single-row INSERT statement many times against a series
of parameter sets.   The &#8220;executemany&#8221; style is supported by
all database backends, as it does not depend on a special SQL
syntax.</p>
</div>
<div class="versionadded">
<p><span>New in version 0.8: </span>Support for multiple-VALUES INSERT statements.</p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="tutorial.html#inserts-and-updates"><em>Inserts, Updates and Deletes</em></a> - SQL Expression
Language Tutorial</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.insert" title="sqlalchemy.sql.expression.insert"><tt class="xref py py-func docutils literal"><span class="pre">insert()</span></tt></a> - produce an <tt class="docutils literal"><span class="pre">INSERT</span></tt> statement</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.update" title="sqlalchemy.sql.expression.update"><tt class="xref py py-func docutils literal"><span class="pre">update()</span></tt></a> - produce an <tt class="docutils literal"><span class="pre">UPDATE</span></tt> statement</p>
</div>
</dd></dl>

</dd></dl>

</div>

    </div>

</div>

<div id="docs-bottom-navigation" class="docs-navigation-links">
        Previous:
        <a href="selectable.html" title="previous chapter">Selectables, Tables, FROM objects</a>
        Next:
        <a href="functions.html" title="next chapter">SQL and Generic Functions</a>

    <div id="docs-copyright">
        &copy; <a href="../copyright.html">Copyright</a> 2007-2014, the SQLAlchemy authors and contributors.
        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.
    </div>
</div>

</div>

        
    </body>
</html>