<!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>
Query API
—
SQLAlchemy 1.2 Documentation
</title>
<!-- begin iterate through site-imported + 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/changelog.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
<!-- end iterate through site-imported + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<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 1.2 Documentation" href="../index.html" />
<link rel="up" title="Loading Objects" href="loading_objects.html" />
<link rel="next" title="Using the Session" href="session.html" />
<link rel="prev" title="Constructors and Object Initialization" href="constructors.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">1.2.19</span>
| Release Date: April 15, 2019
</div>
<h1>SQLAlchemy 1.2 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 1.2 Documentation</a></h3>
<p id="sidebar-topnav">
<a href="../contents.html">Contents</a> |
<a href="../genindex.html">Index</a>
</p>
<div id="sidebar-search">
<form class="search" action="../search.html" method="get">
<label>
Search terms:
<input type="text" placeholder="search..." name="q" size="12" />
</label>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div id="docs-sidebar">
<div id="sidebar-banner">
</div>
<div id="docs-sidebar-inner">
<h3>
<a href="index.html" title="SQLAlchemy ORM">SQLAlchemy ORM</a>
</h3>
<ul>
<li><span class="link-container"><a class="reference external" href="tutorial.html">Object Relational Tutorial</a></span></li>
<li><span class="link-container"><a class="reference external" href="mapper_config.html">Mapper Configuration</a></span></li>
<li><span class="link-container"><a class="reference external" href="relationships.html">Relationship Configuration</a></span></li>
<li><span class="link-container"><a class="reference external" href="loading_objects.html">Loading Objects</a></span><ul>
<li><span class="link-container"><a class="reference external" href="loading_columns.html">Loading Columns</a></span></li>
<li><span class="link-container"><a class="reference external" href="loading_relationships.html">Relationship Loading Techniques</a></span></li>
<li><span class="link-container"><a class="reference external" href="inheritance_loading.html">Loading Inheritance Hierarchies</a></span></li>
<li><span class="link-container"><a class="reference external" href="constructors.html">Constructors and Object Initialization</a></span></li>
<li class="selected"><span class="link-container"><strong>Query API</strong><a class="paramlink headerlink reference internal" href="#">¶</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#the-query-object">The Query Object</a></span></li>
<li><span class="link-container"><a class="reference external" href="#orm-specific-query-constructs">ORM-Specific Query Constructs</a></span></li>
</ul>
</li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="session.html">Using the Session</a></span></li>
<li><span class="link-container"><a class="reference external" href="extending.html">Events and Internals</a></span></li>
<li><span class="link-container"><a class="reference external" href="extensions/index.html">ORM Extensions</a></span></li>
<li><span class="link-container"><a class="reference external" href="examples.html">ORM Examples</a></span></li>
</ul>
</div>
</div>
</div>
<div id="docs-body" class="withsidebar" >
<span class="target" id="module-sqlalchemy.orm"></span><div class="section" id="query-api">
<span id="query-api-toplevel"></span><h1>Query API<a class="headerlink" href="#query-api" title="Permalink to this headline">¶</a></h1>
<p>This section presents the API reference for the ORM <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object. For a walkthrough
of how to use this object, see <a class="reference internal" href="tutorial.html"><span class="std std-ref">Object Relational Tutorial</span></a>.</p>
<div class="section" id="the-query-object">
<h2>The Query Object<a class="headerlink" href="#the-query-object" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> is produced in terms of a given <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>, using the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.query" title="sqlalchemy.orm.session.Session.query"><code class="xref py py-meth docutils literal notranslate"><span class="pre">query()</span></code></a> method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">SomeMappedClass</span><span class="p">)</span></pre></div>
</div>
<p>Following is the full interface for the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object.</p>
<dl class="class">
<dt id="sqlalchemy.orm.query.Query">
<em class="property">class </em><code class="descclassname">sqlalchemy.orm.query.</code><code class="descname">Query</code><span class="sig-paren">(</span><em>entities</em>, <em>session=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query" title="Permalink to this definition">¶</a></dt>
<dd><p>ORM-level SQL construction object.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> is the source of all SELECT statements generated by the
ORM, both those formulated by end-user query operations as well as by
high level internal operations such as related collection loading. It
features a generative interface whereby successive calls return a new
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object, a copy of the former with additional
criteria and options associated with it.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> objects are normally initially generated using the
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.query" title="sqlalchemy.orm.session.Session.query"><code class="xref py py-meth docutils literal notranslate"><span class="pre">query()</span></code></a> method of <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>, and in
less common cases by instantiating the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> directly and
associating with a <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> using the <a class="reference internal" href="#sqlalchemy.orm.query.Query.with_session" title="sqlalchemy.orm.query.Query.with_session"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_session()</span></code></a>
method.</p>
<p>For a full walkthrough of <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> usage, see the
<a class="reference internal" href="tutorial.html"><span class="std std-ref">Object Relational Tutorial</span></a>.</p>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>entities</em>, <em>session=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> directly.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">Query</span><span class="p">([</span><span class="n">User</span><span class="p">,</span> <span class="n">Address</span><span class="p">],</span> <span class="n">session</span><span class="o">=</span><span class="n">some_session</span><span class="p">)</span></pre></div>
</div>
<p>The above is equivalent to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">some_session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">Address</span><span class="p">)</span></pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.orm.query.Query.params.entities"></span><strong>entities</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.params.entities">¶</a> – a sequence of entities and/or SQL expressions.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.params.session"></span><strong>session</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.params.session">¶</a> – a <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> with which the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>
will be associated. Optional; a <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> can be associated
with a <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> generatively via the
<a class="reference internal" href="#sqlalchemy.orm.query.Query.with_session" title="sqlalchemy.orm.query.Query.with_session"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_session()</span></code></a> method as well.</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.query" title="sqlalchemy.orm.session.Session.query"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.query()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.with_session" title="sqlalchemy.orm.query.Query.with_session"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_session()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.add_column">
<code class="descname">add_column</code><span class="sig-paren">(</span><em>column</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.add_column" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a column expression to the list of result columns to be
returned.</p>
<p>Pending deprecation: <a class="reference internal" href="#sqlalchemy.orm.query.Query.add_column" title="sqlalchemy.orm.query.Query.add_column"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_column()</span></code></a> will be superseded by
<a class="reference internal" href="#sqlalchemy.orm.query.Query.add_columns" title="sqlalchemy.orm.query.Query.add_columns"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_columns()</span></code></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.add_columns">
<code class="descname">add_columns</code><span class="sig-paren">(</span><em>*column</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.add_columns" title="Permalink to this definition">¶</a></dt>
<dd><p>Add one or more column expressions to the list
of result columns to be returned.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.add_entity">
<code class="descname">add_entity</code><span class="sig-paren">(</span><em>entity</em>, <em>alias=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.add_entity" title="Permalink to this definition">¶</a></dt>
<dd><p>add a mapped entity to the list of result columns
to be returned.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.all">
<code class="descname">all</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.all" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the results represented by this <code class="docutils literal notranslate"><span class="pre">Query</span></code> as a list.</p>
<p>This results in an execution of the underlying query.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.as_scalar">
<code class="descname">as_scalar</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.as_scalar" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the full SELECT statement represented by this
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>, converted to a scalar subquery.</p>
<p>Analogous to <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.SelectBase.as_scalar" title="sqlalchemy.sql.expression.SelectBase.as_scalar"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sqlalchemy.sql.expression.SelectBase.as_scalar()</span></code></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.autoflush">
<code class="descname">autoflush</code><span class="sig-paren">(</span><em>setting</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.autoflush" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a Query with a specific ‘autoflush’ setting.</p>
<p>Note that a Session with autoflush=False will
not autoflush, even if this flag is set to True at the
Query level. Therefore this flag is usually used only
to disable autoflush for a specific Query.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Query.column_descriptions">
<code class="descname">column_descriptions</code><a class="headerlink" href="#sqlalchemy.orm.query.Query.column_descriptions" title="Permalink to this definition">¶</a></dt>
<dd><p>Return metadata about the columns which would be
returned by this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>.</p>
<p>Format is a list of dictionaries:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">user_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">'user2'</span><span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">user_alias</span><span class="p">)</span>
<span class="c1"># this expression:</span>
<span class="n">q</span><span class="o">.</span><span class="n">column_descriptions</span>
<span class="c1"># would return:</span>
<span class="p">[</span>
<span class="p">{</span>
<span class="s1">'name'</span><span class="p">:</span><span class="s1">'User'</span><span class="p">,</span>
<span class="s1">'type'</span><span class="p">:</span><span class="n">User</span><span class="p">,</span>
<span class="s1">'aliased'</span><span class="p">:</span><span class="kc">False</span><span class="p">,</span>
<span class="s1">'expr'</span><span class="p">:</span><span class="n">User</span><span class="p">,</span>
<span class="s1">'entity'</span><span class="p">:</span> <span class="n">User</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="s1">'name'</span><span class="p">:</span><span class="s1">'id'</span><span class="p">,</span>
<span class="s1">'type'</span><span class="p">:</span><span class="n">Integer</span><span class="p">(),</span>
<span class="s1">'aliased'</span><span class="p">:</span><span class="kc">False</span><span class="p">,</span>
<span class="s1">'expr'</span><span class="p">:</span><span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">,</span>
<span class="s1">'entity'</span><span class="p">:</span> <span class="n">User</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="s1">'name'</span><span class="p">:</span><span class="s1">'user2'</span><span class="p">,</span>
<span class="s1">'type'</span><span class="p">:</span><span class="n">User</span><span class="p">,</span>
<span class="s1">'aliased'</span><span class="p">:</span><span class="kc">True</span><span class="p">,</span>
<span class="s1">'expr'</span><span class="p">:</span><span class="n">user_alias</span><span class="p">,</span>
<span class="s1">'entity'</span><span class="p">:</span> <span class="n">user_alias</span>
<span class="p">}</span>
<span class="p">]</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.correlate">
<code class="descname">correlate</code><span class="sig-paren">(</span><em>*args</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.correlate" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> construct which will correlate the given
FROM clauses to that of an enclosing <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> or
<a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select()</span></code></a>.</p>
<p>The method here accepts mapped classes, <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> constructs,
and <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><code class="xref py py-func docutils literal notranslate"><span class="pre">mapper()</span></code></a> constructs as arguments, which are resolved into
expression constructs, in addition to appropriate expression
constructs.</p>
<p>The correlation arguments are ultimately passed to
<a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Select.correlate" title="sqlalchemy.sql.expression.Select.correlate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Select.correlate()</span></code></a> after coercion to expression constructs.</p>
<p>The correlation arguments take effect in such cases
as when <a class="reference internal" href="#sqlalchemy.orm.query.Query.from_self" title="sqlalchemy.orm.query.Query.from_self"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.from_self()</span></code></a> is used, or when
a subquery as returned by <a class="reference internal" href="#sqlalchemy.orm.query.Query.subquery" title="sqlalchemy.orm.query.Query.subquery"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.subquery()</span></code></a> is
embedded in another <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select()</span></code></a> construct.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.count">
<code class="descname">count</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.count" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a count of rows this Query would return.</p>
<p>This generates the SQL for this Query as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">count</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="n">AS</span> <span class="n">count_1</span> <span class="n">FROM</span> <span class="p">(</span>
<span class="n">SELECT</span> <span class="o"><</span><span class="n">rest</span> <span class="n">of</span> <span class="n">query</span> <span class="n">follows</span><span class="o">...></span>
<span class="p">)</span> <span class="n">AS</span> <span class="n">anon_1</span></pre></div>
</div>
<p>For fine grained control over specific columns
to count, to skip the usage of a subquery or
otherwise control of the FROM clause,
or to use other aggregate functions,
use <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><code class="xref py py-attr docutils literal notranslate"><span class="pre">func</span></code></a>
expressions in conjunction
with <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.query" title="sqlalchemy.orm.session.Session.query"><code class="xref py py-meth docutils literal notranslate"><span class="pre">query()</span></code></a>, i.e.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">func</span>
<span class="c1"># count User records, without</span>
<span class="c1"># using a subquery.</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">))</span>
<span class="c1"># return count of user "id" grouped</span>
<span class="c1"># by "name"</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">))</span><span class="o">.</span>\
<span class="n">group_by</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">distinct</span>
<span class="c1"># count distinct "name" values</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">distinct</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="p">)))</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.cte">
<code class="descname">cte</code><span class="sig-paren">(</span><em>name=None</em>, <em>recursive=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.cte" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the full SELECT statement represented by this
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> represented as a common table expression (CTE).</p>
<p>Parameters and usage are the same as those of the
<a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.SelectBase.cte" title="sqlalchemy.sql.expression.SelectBase.cte"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SelectBase.cte()</span></code></a> method; see that method for
further details.</p>
<p>Here is the <a class="reference external" href="http://www.postgresql.org/docs/8.4/static/queries-with.html">PostgreSQL WITH
RECURSIVE example</a>.
Note that, in this example, the <code class="docutils literal notranslate"><span class="pre">included_parts</span></code> cte and the
<code class="docutils literal notranslate"><span class="pre">incl_alias</span></code> alias of it are Core selectables, which
means the columns are accessed via the <code class="docutils literal notranslate"><span class="pre">.c.</span></code> attribute. The
<code class="docutils literal notranslate"><span class="pre">parts_alias</span></code> object is an <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.aliased()</span></code></a> instance of the
<code class="docutils literal notranslate"><span class="pre">Part</span></code> entity, so column-mapped attributes are available
directly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="k">import</span> <span class="n">aliased</span>
<span class="k">class</span> <span class="nc">Part</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'part'</span>
<span class="n">part</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">sub_part</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">quantity</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">)</span>
<span class="n">included_parts</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span>
<span class="n">Part</span><span class="o">.</span><span class="n">sub_part</span><span class="p">,</span>
<span class="n">Part</span><span class="o">.</span><span class="n">part</span><span class="p">,</span>
<span class="n">Part</span><span class="o">.</span><span class="n">quantity</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Part</span><span class="o">.</span><span class="n">part</span><span class="o">==</span><span class="s2">"our part"</span><span class="p">)</span><span class="o">.</span>\
<span class="n">cte</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">"included_parts"</span><span class="p">,</span> <span class="n">recursive</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">incl_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">included_parts</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s2">"pr"</span><span class="p">)</span>
<span class="n">parts_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">Part</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s2">"p"</span><span class="p">)</span>
<span class="n">included_parts</span> <span class="o">=</span> <span class="n">included_parts</span><span class="o">.</span><span class="n">union_all</span><span class="p">(</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span>
<span class="n">parts_alias</span><span class="o">.</span><span class="n">sub_part</span><span class="p">,</span>
<span class="n">parts_alias</span><span class="o">.</span><span class="n">part</span><span class="p">,</span>
<span class="n">parts_alias</span><span class="o">.</span><span class="n">quantity</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">parts_alias</span><span class="o">.</span><span class="n">part</span><span class="o">==</span><span class="n">incl_alias</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">sub_part</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span>
<span class="n">included_parts</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">sub_part</span><span class="p">,</span>
<span class="n">func</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">included_parts</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">quantity</span><span class="p">)</span><span class="o">.</span>
<span class="n">label</span><span class="p">(</span><span class="s1">'total_quantity'</span><span class="p">)</span>
<span class="p">)</span><span class="o">.</span>\
<span class="n">group_by</span><span class="p">(</span><span class="n">included_parts</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">sub_part</span><span class="p">)</span></pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.HasCTE.cte" title="sqlalchemy.sql.expression.HasCTE.cte"><code class="xref py py-meth docutils literal notranslate"><span class="pre">HasCTE.cte()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.delete">
<code class="descname">delete</code><span class="sig-paren">(</span><em>synchronize_session='evaluate'</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.delete" title="Permalink to this definition">¶</a></dt>
<dd><p>Perform a bulk delete query.</p>
<p>Deletes rows matched by this query from the database.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">age</span> <span class="o">==</span> <span class="mi">25</span><span class="p">)</span><span class="o">.</span>\
<span class="n">delete</span><span class="p">(</span><span class="n">synchronize_session</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">age</span> <span class="o">==</span> <span class="mi">25</span><span class="p">)</span><span class="o">.</span>\
<span class="n">delete</span><span class="p">(</span><span class="n">synchronize_session</span><span class="o">=</span><span class="s1">'evaluate'</span><span class="p">)</span></pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.query.Query.delete" title="sqlalchemy.orm.query.Query.delete"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.delete()</span></code></a> method is a “bulk” operation,
which bypasses ORM unit-of-work automation in favor of greater
performance. <strong>Please read all caveats and warnings below.</strong></p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.orm.query.Query.delete.params.synchronize_session"></span><strong>synchronize_session</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.delete.params.synchronize_session">¶</a> – <p>chooses the strategy for the removal of
matched objects from the session. Valid values are:</p>
<p><code class="docutils literal notranslate"><span class="pre">False</span></code> - don’t synchronize the session. This option is the most
efficient and is reliable once the session is expired, which
typically occurs after a commit(), or explicitly using
expire_all(). Before the expiration, objects may still remain in
the session which were in fact deleted which can lead to confusing
results if they are accessed via get() or already loaded
collections.</p>
<p><code class="docutils literal notranslate"><span class="pre">'fetch'</span></code> - performs a select query before the delete to find
objects that are matched by the delete query and need to be
removed from the session. Matched objects are removed from the
session.</p>
<p><code class="docutils literal notranslate"><span class="pre">'evaluate'</span></code> - Evaluate the query’s criteria in Python straight
on the objects in the session. If evaluation of the criteria isn’t
implemented, an error is raised.</p>
<p>The expression evaluator currently doesn’t account for differing
string collations between the database and Python.</p>
</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>the count of rows matched as returned by the database’s
“row count” feature.</p>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p><strong>Additional Caveats for bulk query deletes</strong></p>
<ul>
<li><p>This method does <strong>not work for joined
inheritance mappings</strong>, since the <strong>multiple table
deletes are not supported by SQL</strong> as well as that the
<strong>join condition of an inheritance mapper is not
automatically rendered</strong>. Care must be taken in any
multiple-table delete to first accommodate via some other means
how the related table will be deleted, as well as to
explicitly include the joining
condition between those tables, even in mappings where
this is normally automatic. E.g. if a class <code class="docutils literal notranslate"><span class="pre">Engineer</span></code>
subclasses <code class="docutils literal notranslate"><span class="pre">Employee</span></code>, a DELETE against the <code class="docutils literal notranslate"><span class="pre">Employee</span></code>
table would look like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Engineer</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Engineer</span><span class="o">.</span><span class="n">id</span> <span class="o">==</span> <span class="n">Employee</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Employee</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'dilbert'</span><span class="p">)</span><span class="o">.</span>\
<span class="n">delete</span><span class="p">()</span></pre></div>
</div>
<p>However the above SQL will not delete from the Engineer table,
unless an ON DELETE CASCADE rule is established in the database
to handle it.</p>
<p>Short story, <strong>do not use this method for joined inheritance
mappings unless you have taken the additional steps to make
this feasible</strong>.</p>
</li>
<li><p>The polymorphic identity WHERE criteria is <strong>not</strong> included
for single- or
joined- table updates - this must be added <strong>manually</strong> even
for single table inheritance.</p></li>
<li><p>The method does <strong>not</strong> offer in-Python cascading of
relationships - it is assumed that ON DELETE CASCADE/SET
NULL/etc. is configured for any foreign key references
which require it, otherwise the database may emit an
integrity violation if foreign key references are being
enforced.</p>
<p>After the DELETE, dependent objects in the
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> which were impacted by an ON DELETE
may not contain the current state, or may have been
deleted. This issue is resolved once the
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> is expired, which normally occurs upon
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.commit()</span></code></a> or can be forced by using
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire_all" title="sqlalchemy.orm.session.Session.expire_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.expire_all()</span></code></a>. Accessing an expired
object whose row has been deleted will invoke a SELECT
to locate the row; when the row is not found, an
<a class="reference internal" href="exceptions.html#sqlalchemy.orm.exc.ObjectDeletedError" title="sqlalchemy.orm.exc.ObjectDeletedError"><code class="xref py py-class docutils literal notranslate"><span class="pre">ObjectDeletedError</span></code></a> is
raised.</p>
</li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">'fetch'</span></code> strategy results in an additional
SELECT statement emitted and will significantly reduce
performance.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">'evaluate'</span></code> strategy performs a scan of
all matching objects within the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>; if the
contents of the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> are expired, such as
via a proceeding <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.commit()</span></code></a> call, <strong>this will
result in SELECT queries emitted for every matching object</strong>.</p></li>
<li><p>The <a class="reference internal" href="events.html#sqlalchemy.orm.events.MapperEvents.before_delete" title="sqlalchemy.orm.events.MapperEvents.before_delete"><code class="xref py py-meth docutils literal notranslate"><span class="pre">MapperEvents.before_delete()</span></code></a> and
<a class="reference internal" href="events.html#sqlalchemy.orm.events.MapperEvents.after_delete" title="sqlalchemy.orm.events.MapperEvents.after_delete"><code class="xref py py-meth docutils literal notranslate"><span class="pre">MapperEvents.after_delete()</span></code></a>
events <strong>are not invoked</strong> from this method. Instead, the
<a class="reference internal" href="events.html#sqlalchemy.orm.events.SessionEvents.after_bulk_delete" title="sqlalchemy.orm.events.SessionEvents.after_bulk_delete"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SessionEvents.after_bulk_delete()</span></code></a> method is provided to
act upon a mass DELETE of entity rows.</p></li>
</ul>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.update" title="sqlalchemy.orm.query.Query.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.update()</span></code></a></p>
<p><a class="reference internal" href="../core/tutorial.html#inserts-and-updates"><span class="std std-ref">Inserts, Updates and Deletes</span></a> - Core SQL tutorial</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.distinct">
<code class="descname">distinct</code><span class="sig-paren">(</span><em>*criterion</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.distinct" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply a <code class="docutils literal notranslate"><span class="pre">DISTINCT</span></code> to the query and return the newly resulting
<code class="docutils literal notranslate"><span class="pre">Query</span></code>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.query.Query.distinct" title="sqlalchemy.orm.query.Query.distinct"><code class="xref py py-meth docutils literal notranslate"><span class="pre">distinct()</span></code></a> call includes logic that will automatically
add columns from the ORDER BY of the query to the columns
clause of the SELECT statement, to satisfy the common need
of the database backend that ORDER BY columns be part of the
SELECT list when DISTINCT is used. These columns <em>are not</em>
added to the list of columns actually fetched by the
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>, however, so would not affect results.
The columns are passed through when using the
<a class="reference internal" href="#sqlalchemy.orm.query.Query.statement" title="sqlalchemy.orm.query.Query.statement"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Query.statement</span></code></a> accessor, however.</p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.orm.query.Query.distinct.params.*expr"></span><strong>*expr</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.distinct.params.*expr">¶</a> – optional column expressions. When present,
the PostgreSQL dialect will render a <code class="docutils literal notranslate"><span class="pre">DISTINCT</span> <span class="pre">ON</span> <span class="pre">(<expressions>>)</span></code>
construct.</p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.enable_assertions">
<code class="descname">enable_assertions</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.enable_assertions" title="Permalink to this definition">¶</a></dt>
<dd><p>Control whether assertions are generated.</p>
<p>When set to False, the returned Query will
not assert its state before certain operations,
including that LIMIT/OFFSET has not been applied
when filter() is called, no criterion exists
when get() is called, and no “from_statement()”
exists when filter()/order_by()/group_by() etc.
is called. This more permissive mode is used by
custom Query subclasses to specify criterion or
other modifiers outside of the usual usage patterns.</p>
<p>Care should be taken to ensure that the usage
pattern is even possible. A statement applied
by from_statement() will override any criterion
set by filter() or order_by(), for example.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.enable_eagerloads">
<code class="descname">enable_eagerloads</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.enable_eagerloads" title="Permalink to this definition">¶</a></dt>
<dd><p>Control whether or not eager joins and subqueries are
rendered.</p>
<p>When set to False, the returned Query will not render
eager joins regardless of <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.joinedload" title="sqlalchemy.orm.joinedload"><code class="xref py py-func docutils literal notranslate"><span class="pre">joinedload()</span></code></a>,
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.subqueryload" title="sqlalchemy.orm.subqueryload"><code class="xref py py-func docutils literal notranslate"><span class="pre">subqueryload()</span></code></a> options
or mapper-level <code class="docutils literal notranslate"><span class="pre">lazy='joined'</span></code>/<code class="docutils literal notranslate"><span class="pre">lazy='subquery'</span></code>
configurations.</p>
<p>This is used primarily when nesting the Query’s
statement into a subquery or other
selectable, or when using <a class="reference internal" href="#sqlalchemy.orm.query.Query.yield_per" title="sqlalchemy.orm.query.Query.yield_per"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.yield_per()</span></code></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.except_">
<code class="descname">except_</code><span class="sig-paren">(</span><em>*q</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.except_" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an EXCEPT of this Query against one or more queries.</p>
<p>Works the same way as <a class="reference internal" href="#sqlalchemy.orm.query.Query.union" title="sqlalchemy.orm.query.Query.union"><code class="xref py py-meth docutils literal notranslate"><span class="pre">union()</span></code></a>. See
that method for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.except_all">
<code class="descname">except_all</code><span class="sig-paren">(</span><em>*q</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.except_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an EXCEPT ALL of this Query against one or more queries.</p>
<p>Works the same way as <a class="reference internal" href="#sqlalchemy.orm.query.Query.union" title="sqlalchemy.orm.query.Query.union"><code class="xref py py-meth docutils literal notranslate"><span class="pre">union()</span></code></a>. See
that method for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.execution_options">
<code class="descname">execution_options</code><span class="sig-paren">(</span><em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.execution_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Set non-SQL options which take effect during execution.</p>
<p>The options are the same as those accepted by
<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection.execution_options" title="sqlalchemy.engine.Connection.execution_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Connection.execution_options()</span></code></a>.</p>
<p>Note that the <code class="docutils literal notranslate"><span class="pre">stream_results</span></code> execution option is enabled
automatically if the <a class="reference internal" href="#sqlalchemy.orm.query.Query.yield_per" title="sqlalchemy.orm.query.Query.yield_per"><code class="xref py py-meth docutils literal notranslate"><span class="pre">yield_per()</span></code></a>
method is used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.exists">
<code class="descname">exists</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.exists" title="Permalink to this definition">¶</a></dt>
<dd><p>A convenience method that turns a query into an EXISTS subquery
of the form EXISTS (SELECT 1 FROM … WHERE …).</p>
<p>e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'fred'</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">q</span><span class="o">.</span><span class="n">exists</span><span class="p">())</span></pre></div>
</div>
<p>Producing SQL similar to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">EXISTS</span> <span class="p">(</span>
<span class="n">SELECT</span> <span class="mi">1</span> <span class="n">FROM</span> <span class="n">users</span> <span class="n">WHERE</span> <span class="n">users</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="p">:</span><span class="n">name_1</span>
<span class="p">)</span> <span class="n">AS</span> <span class="n">anon_1</span></pre></div>
</div>
<p>The EXISTS construct is usually used in the WHERE clause:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">q</span><span class="o">.</span><span class="n">exists</span><span class="p">())</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span></pre></div>
</div>
<p>Note that some databases such as SQL Server don’t allow an
EXISTS expression to be present in the columns clause of a
SELECT. To select a simple boolean value based on the exists
as a WHERE, use <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.literal" title="sqlalchemy.sql.expression.literal"><code class="xref py py-func docutils literal notranslate"><span class="pre">literal()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">literal</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">literal</span><span class="p">(</span><span class="kc">True</span><span class="p">))</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">q</span><span class="o">.</span><span class="n">exists</span><span class="p">())</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.filter">
<code class="descname">filter</code><span class="sig-paren">(</span><em>*criterion</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.filter" title="Permalink to this definition">¶</a></dt>
<dd><p>apply the given filtering criterion to a copy
of this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>, using SQL expressions.</p>
<p>e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">MyClass</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">MyClass</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'some name'</span><span class="p">)</span></pre></div>
</div>
<p>Multiple criteria may be specified as comma separated; the effect
is that they will be joined together using the <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><code class="xref py py-func docutils literal notranslate"><span class="pre">and_()</span></code></a>
function:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">MyClass</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">MyClass</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'some name'</span><span class="p">,</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">id</span> <span class="o">></span> <span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>The criterion is any SQL expression object applicable to the
WHERE clause of a select. String expressions are coerced
into SQL expression constructs via the <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><code class="xref py py-func docutils literal notranslate"><span class="pre">text()</span></code></a> construct.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.filter_by" title="sqlalchemy.orm.query.Query.filter_by"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.filter_by()</span></code></a> - filter on keyword expressions.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.filter_by">
<code class="descname">filter_by</code><span class="sig-paren">(</span><em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.filter_by" title="Permalink to this definition">¶</a></dt>
<dd><p>apply the given filtering criterion to a copy
of this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>, using keyword expressions.</p>
<p>e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">MyClass</span><span class="p">)</span><span class="o">.</span><span class="n">filter_by</span><span class="p">(</span><span class="n">name</span> <span class="o">=</span> <span class="s1">'some name'</span><span class="p">)</span></pre></div>
</div>
<p>Multiple criteria may be specified as comma separated; the effect
is that they will be joined together using the <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><code class="xref py py-func docutils literal notranslate"><span class="pre">and_()</span></code></a>
function:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">MyClass</span><span class="p">)</span><span class="o">.</span>\
<span class="n">filter_by</span><span class="p">(</span><span class="n">name</span> <span class="o">=</span> <span class="s1">'some name'</span><span class="p">,</span> <span class="nb">id</span> <span class="o">=</span> <span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>The keyword expressions are extracted from the primary
entity of the query, or the last entity that was the
target of a call to <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.join()</span></code></a>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.filter" title="sqlalchemy.orm.query.Query.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.filter()</span></code></a> - filter on SQL expressions.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.first">
<code class="descname">first</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.first" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the first result of this <code class="docutils literal notranslate"><span class="pre">Query</span></code> or
None if the result doesn’t contain any row.</p>
<p>first() applies a limit of one within the generated SQL, so that
only one primary entity row is generated on the server side
(note this may consist of multiple result rows if join-loaded
collections are present).</p>
<p>Calling <a class="reference internal" href="#sqlalchemy.orm.query.Query.first" title="sqlalchemy.orm.query.Query.first"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.first()</span></code></a> results in an execution of the underlying
query.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.one" title="sqlalchemy.orm.query.Query.one"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.one()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.one_or_none" title="sqlalchemy.orm.query.Query.one_or_none"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.one_or_none()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.from_self">
<code class="descname">from_self</code><span class="sig-paren">(</span><em>*entities</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.from_self" title="Permalink to this definition">¶</a></dt>
<dd><p>return a Query that selects from this Query’s
SELECT statement.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.from_self" title="sqlalchemy.orm.query.Query.from_self"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.from_self()</span></code></a> essentially turns the SELECT statement
into a SELECT of itself. Given a query such as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'e%'</span><span class="p">))</span></pre></div>
</div>
<p>Given the <a class="reference internal" href="#sqlalchemy.orm.query.Query.from_self" title="sqlalchemy.orm.query.Query.from_self"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.from_self()</span></code></a> version:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'e%'</span><span class="p">))</span><span class="o">.</span><span class="n">from_self</span><span class="p">()</span></pre></div>
</div>
<p>This query renders as:</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">SELECT</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">user_id</span> <span class="k">AS</span> <span class="n">anon_1_user_id</span><span class="p">,</span>
<span class="n">anon_1</span><span class="p">.</span><span class="n">user_name</span> <span class="k">AS</span> <span class="n">anon_1_user_name</span>
<span class="k">FROM</span> <span class="p">(</span><span class="k">SELECT</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">user_id</span><span class="p">,</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">user_name</span>
<span class="k">FROM</span> <span class="ss">"user"</span>
<span class="k">WHERE</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">LIKE</span> <span class="p">:</span><span class="n">name_1</span><span class="p">)</span> <span class="k">AS</span> <span class="n">anon_1</span></pre></div>
</div>
<p>There are lots of cases where <a class="reference internal" href="#sqlalchemy.orm.query.Query.from_self" title="sqlalchemy.orm.query.Query.from_self"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.from_self()</span></code></a> may be useful.
A simple one is where above, we may want to apply a row LIMIT to
the set of user objects we query against, and then apply additional
joins against that row-limited set:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'e%'</span><span class="p">))</span><span class="o">.</span>\
<span class="n">limit</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="n">from_self</span><span class="p">()</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'q%'</span><span class="p">))</span></pre></div>
</div>
<p>The above query joins to the <code class="docutils literal notranslate"><span class="pre">Address</span></code> entity but only against the
first five results of the <code class="docutils literal notranslate"><span class="pre">User</span></code> query:</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">SELECT</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">user_id</span> <span class="k">AS</span> <span class="n">anon_1_user_id</span><span class="p">,</span>
<span class="n">anon_1</span><span class="p">.</span><span class="n">user_name</span> <span class="k">AS</span> <span class="n">anon_1_user_name</span>
<span class="k">FROM</span> <span class="p">(</span><span class="k">SELECT</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">user_id</span><span class="p">,</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">user_name</span>
<span class="k">FROM</span> <span class="ss">"user"</span>
<span class="k">WHERE</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">LIKE</span> <span class="p">:</span><span class="n">name_1</span>
<span class="k">LIMIT</span> <span class="p">:</span><span class="n">param_1</span><span class="p">)</span> <span class="k">AS</span> <span class="n">anon_1</span>
<span class="k">JOIN</span> <span class="n">address</span> <span class="k">ON</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">user_id</span> <span class="o">=</span> <span class="n">address</span><span class="p">.</span><span class="n">user_id</span>
<span class="k">WHERE</span> <span class="n">address</span><span class="p">.</span><span class="n">email</span> <span class="k">LIKE</span> <span class="p">:</span><span class="n">email_1</span></pre></div>
</div>
<p><strong>Automatic Aliasing</strong></p>
<p>Another key behavior of <a class="reference internal" href="#sqlalchemy.orm.query.Query.from_self" title="sqlalchemy.orm.query.Query.from_self"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.from_self()</span></code></a> is that it applies
<strong>automatic aliasing</strong> to the entities inside the subquery, when
they are referenced on the outside. Above, if we continue to
refer to the <code class="docutils literal notranslate"><span class="pre">User</span></code> entity without any additional aliasing applied
to it, those references wil be in terms of the subquery:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'e%'</span><span class="p">))</span><span class="o">.</span>\
<span class="n">limit</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="n">from_self</span><span class="p">()</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'q%'</span><span class="p">))</span><span class="o">.</span>\
<span class="n">order_by</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="p">)</span></pre></div>
</div>
<p>The ORDER BY against <code class="docutils literal notranslate"><span class="pre">User.name</span></code> is aliased to be in terms of the
inner subquery:</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">SELECT</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">user_id</span> <span class="k">AS</span> <span class="n">anon_1_user_id</span><span class="p">,</span>
<span class="n">anon_1</span><span class="p">.</span><span class="n">user_name</span> <span class="k">AS</span> <span class="n">anon_1_user_name</span>
<span class="k">FROM</span> <span class="p">(</span><span class="k">SELECT</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">user_id</span><span class="p">,</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">user_name</span>
<span class="k">FROM</span> <span class="ss">"user"</span>
<span class="k">WHERE</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">LIKE</span> <span class="p">:</span><span class="n">name_1</span>
<span class="k">LIMIT</span> <span class="p">:</span><span class="n">param_1</span><span class="p">)</span> <span class="k">AS</span> <span class="n">anon_1</span>
<span class="k">JOIN</span> <span class="n">address</span> <span class="k">ON</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">user_id</span> <span class="o">=</span> <span class="n">address</span><span class="p">.</span><span class="n">user_id</span>
<span class="k">WHERE</span> <span class="n">address</span><span class="p">.</span><span class="n">email</span> <span class="k">LIKE</span> <span class="p">:</span><span class="n">email_1</span> <span class="k">ORDER</span> <span class="k">BY</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">user_name</span></pre></div>
</div>
<p>The automatic aliasing feature only works in a <strong>limited</strong> way,
for simple filters and orderings. More ambitious constructions
such as referring to the entity in joins should prefer to use
explicit subquery objects, typically making use of the
<a class="reference internal" href="#sqlalchemy.orm.query.Query.subquery" title="sqlalchemy.orm.query.Query.subquery"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.subquery()</span></code></a> method to produce an explicit subquery object.
Always test the structure of queries by viewing the SQL to ensure
a particular structure does what’s expected!</p>
<p><strong>Changing the Entities</strong></p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.from_self" title="sqlalchemy.orm.query.Query.from_self"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.from_self()</span></code></a> also includes the ability to modify what
columns are being queried. In our example, we want <code class="docutils literal notranslate"><span class="pre">User.id</span></code>
to be queried by the inner query, so that we can join to the
<code class="docutils literal notranslate"><span class="pre">Address</span></code> entity on the outside, but we only wanted the outer
query to return the <code class="docutils literal notranslate"><span class="pre">Address.email</span></code> column:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'e%'</span><span class="p">))</span><span class="o">.</span>\
<span class="n">limit</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="n">from_self</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'q%'</span><span class="p">))</span></pre></div>
</div>
<p>yielding:</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">SELECT</span> <span class="n">address</span><span class="p">.</span><span class="n">email</span> <span class="k">AS</span> <span class="n">address_email</span>
<span class="k">FROM</span> <span class="p">(</span><span class="k">SELECT</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">user_id</span><span class="p">,</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">user_name</span>
<span class="k">FROM</span> <span class="ss">"user"</span>
<span class="k">WHERE</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">LIKE</span> <span class="p">:</span><span class="n">name_1</span>
<span class="k">LIMIT</span> <span class="p">:</span><span class="n">param_1</span><span class="p">)</span> <span class="k">AS</span> <span class="n">anon_1</span>
<span class="k">JOIN</span> <span class="n">address</span> <span class="k">ON</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">user_id</span> <span class="o">=</span> <span class="n">address</span><span class="p">.</span><span class="n">user_id</span>
<span class="k">WHERE</span> <span class="n">address</span><span class="p">.</span><span class="n">email</span> <span class="k">LIKE</span> <span class="p">:</span><span class="n">email_1</span></pre></div>
</div>
<p><strong>Looking out for Inner / Outer Columns</strong></p>
<p>Keep in mind that when referring to columns that originate from
inside the subquery, we need to ensure they are present in the
columns clause of the subquery itself; this is an ordinary aspect of
SQL. For example, if we wanted to load from a joined entity inside
the subquery using <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.contains_eager" title="sqlalchemy.orm.contains_eager"><code class="xref py py-func docutils literal notranslate"><span class="pre">contains_eager()</span></code></a>, we need to add those
columns. Below illustrates a join of <code class="docutils literal notranslate"><span class="pre">Address</span></code> to <code class="docutils literal notranslate"><span class="pre">User</span></code>,
then a subquery, and then we’d like <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.contains_eager" title="sqlalchemy.orm.contains_eager"><code class="xref py py-func docutils literal notranslate"><span class="pre">contains_eager()</span></code></a> to access
the <code class="docutils literal notranslate"><span class="pre">User</span></code> columns:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Address</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">user</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'e%'</span><span class="p">))</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">q</span><span class="o">.</span><span class="n">add_entity</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">from_self</span><span class="p">()</span><span class="o">.</span>\
<span class="n">options</span><span class="p">(</span><span class="n">contains_eager</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">user</span><span class="p">))</span></pre></div>
</div>
<p>We use <a class="reference internal" href="#sqlalchemy.orm.query.Query.add_entity" title="sqlalchemy.orm.query.Query.add_entity"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.add_entity()</span></code></a> above <strong>before</strong> we call
<a class="reference internal" href="#sqlalchemy.orm.query.Query.from_self" title="sqlalchemy.orm.query.Query.from_self"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.from_self()</span></code></a> so that the <code class="docutils literal notranslate"><span class="pre">User</span></code> columns are present
in the inner subquery, so that they are available to the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.contains_eager" title="sqlalchemy.orm.contains_eager"><code class="xref py py-func docutils literal notranslate"><span class="pre">contains_eager()</span></code></a> modifier we are using on the outside,
producing:</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">SELECT</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">address_id</span> <span class="k">AS</span> <span class="n">anon_1_address_id</span><span class="p">,</span>
<span class="n">anon_1</span><span class="p">.</span><span class="n">address_email</span> <span class="k">AS</span> <span class="n">anon_1_address_email</span><span class="p">,</span>
<span class="n">anon_1</span><span class="p">.</span><span class="n">address_user_id</span> <span class="k">AS</span> <span class="n">anon_1_address_user_id</span><span class="p">,</span>
<span class="n">anon_1</span><span class="p">.</span><span class="n">user_id</span> <span class="k">AS</span> <span class="n">anon_1_user_id</span><span class="p">,</span>
<span class="n">anon_1</span><span class="p">.</span><span class="n">user_name</span> <span class="k">AS</span> <span class="n">anon_1_user_name</span>
<span class="k">FROM</span> <span class="p">(</span>
<span class="k">SELECT</span> <span class="n">address</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">address_id</span><span class="p">,</span>
<span class="n">address</span><span class="p">.</span><span class="n">email</span> <span class="k">AS</span> <span class="n">address_email</span><span class="p">,</span>
<span class="n">address</span><span class="p">.</span><span class="n">user_id</span> <span class="k">AS</span> <span class="n">address_user_id</span><span class="p">,</span>
<span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">user_id</span><span class="p">,</span>
<span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">user_name</span>
<span class="k">FROM</span> <span class="n">address</span> <span class="k">JOIN</span> <span class="ss">"user"</span> <span class="k">ON</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="o">=</span> <span class="n">address</span><span class="p">.</span><span class="n">user_id</span>
<span class="k">WHERE</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">LIKE</span> <span class="p">:</span><span class="n">name_1</span><span class="p">)</span> <span class="k">AS</span> <span class="n">anon_1</span></pre></div>
</div>
<p>If we didn’t call <code class="docutils literal notranslate"><span class="pre">add_entity(User)</span></code>, but still asked
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.contains_eager" title="sqlalchemy.orm.contains_eager"><code class="xref py py-func docutils literal notranslate"><span class="pre">contains_eager()</span></code></a> to load the <code class="docutils literal notranslate"><span class="pre">User</span></code> entity, it would be
forced to add the table on the outside without the correct
join criteria - note the <code class="docutils literal notranslate"><span class="pre">anon1,</span> <span class="pre">"user"</span></code> phrase at
the end:</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="c1">-- incorrect query</span>
<span class="k">SELECT</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">address_id</span> <span class="k">AS</span> <span class="n">anon_1_address_id</span><span class="p">,</span>
<span class="n">anon_1</span><span class="p">.</span><span class="n">address_email</span> <span class="k">AS</span> <span class="n">anon_1_address_email</span><span class="p">,</span>
<span class="n">anon_1</span><span class="p">.</span><span class="n">address_user_id</span> <span class="k">AS</span> <span class="n">anon_1_address_user_id</span><span class="p">,</span>
<span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">user_id</span><span class="p">,</span>
<span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">user_name</span>
<span class="k">FROM</span> <span class="p">(</span>
<span class="k">SELECT</span> <span class="n">address</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">address_id</span><span class="p">,</span>
<span class="n">address</span><span class="p">.</span><span class="n">email</span> <span class="k">AS</span> <span class="n">address_email</span><span class="p">,</span>
<span class="n">address</span><span class="p">.</span><span class="n">user_id</span> <span class="k">AS</span> <span class="n">address_user_id</span>
<span class="k">FROM</span> <span class="n">address</span> <span class="k">JOIN</span> <span class="ss">"user"</span> <span class="k">ON</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="o">=</span> <span class="n">address</span><span class="p">.</span><span class="n">user_id</span>
<span class="k">WHERE</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">LIKE</span> <span class="p">:</span><span class="n">name_1</span><span class="p">)</span> <span class="k">AS</span> <span class="n">anon_1</span><span class="p">,</span> <span class="ss">"user"</span></pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.orm.query.Query.from_self.params.*entities"></span><strong>*entities</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.from_self.params.*entities">¶</a> – optional list of entities which will replace
those being selected.</p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.from_statement">
<code class="descname">from_statement</code><span class="sig-paren">(</span><em>statement</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.from_statement" title="Permalink to this definition">¶</a></dt>
<dd><p>Execute the given SELECT statement and return results.</p>
<p>This method bypasses all internal statement compilation, and the
statement is executed without modification.</p>
<p>The statement is typically either a <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><code class="xref py py-func docutils literal notranslate"><span class="pre">text()</span></code></a>
or <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select()</span></code></a> construct, and should return the set
of columns
appropriate to the entity class represented by this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="tutorial.html#orm-tutorial-literal-sql"><span class="std std-ref">Using Textual SQL</span></a> - usage examples in the
ORM tutorial</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.get">
<code class="descname">get</code><span class="sig-paren">(</span><em>ident</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an instance based on the given primary key identifier,
or <code class="docutils literal notranslate"><span class="pre">None</span></code> if not found.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">my_user</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
<span class="n">some_object</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">VersionedFoo</span><span class="p">)</span><span class="o">.</span><span class="n">get</span><span class="p">((</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">))</span></pre></div>
</div>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.get" title="sqlalchemy.orm.query.Query.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> is special in that it provides direct
access to the identity map of the owning <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>.
If the given primary key identifier is present
in the local identity map, the object is returned
directly from this collection and no SQL is emitted,
unless the object has been marked fully expired.
If not present,
a SELECT is performed in order to locate the object.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.get" title="sqlalchemy.orm.query.Query.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> also will perform a check if
the object is present in the identity map and
marked as expired - a SELECT
is emitted to refresh the object as well as to
ensure that the row is still present.
If not, <a class="reference internal" href="exceptions.html#sqlalchemy.orm.exc.ObjectDeletedError" title="sqlalchemy.orm.exc.ObjectDeletedError"><code class="xref py py-class docutils literal notranslate"><span class="pre">ObjectDeletedError</span></code></a> is raised.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.get" title="sqlalchemy.orm.query.Query.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> is only used to return a single
mapped instance, not multiple instances or
individual column constructs, and strictly
on a single primary key value. The originating
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> must be constructed in this way,
i.e. against a single mapped entity,
with no additional filtering criterion. Loading
options via <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">options()</span></code></a> may be applied
however, and will be used if the object is not
yet locally present.</p>
<p>A lazy-loading, many-to-one attribute configured
by <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>, using a simple
foreign-key-to-primary-key criterion, will also use an
operation equivalent to <a class="reference internal" href="#sqlalchemy.orm.query.Query.get" title="sqlalchemy.orm.query.Query.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> in order to retrieve
the target value from the local identity map
before querying the database. See <a class="reference internal" href="loading_relationships.html"><span class="doc">Relationship Loading Techniques</span></a>
for further details on relationship loading.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.orm.query.Query.get.params.ident"></span><strong>ident</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.get.params.ident">¶</a> – A scalar or tuple value representing
the primary key. For a composite primary key,
the order of identifiers corresponds in most cases
to that of the mapped <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> object’s
primary key columns. For a <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><code class="xref py py-func docutils literal notranslate"><span class="pre">mapper()</span></code></a> that
was given the <code class="docutils literal notranslate"><span class="pre">primary</span> <span class="pre">key</span></code> argument during
construction, the order of identifiers corresponds
to the elements present in this collection.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>The object instance, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.group_by">
<code class="descname">group_by</code><span class="sig-paren">(</span><em>*criterion</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.group_by" title="Permalink to this definition">¶</a></dt>
<dd><p>apply one or more GROUP BY criterion to the query and return
the newly resulting <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a></p>
<p>All existing GROUP BY settings can be suppressed by
passing <code class="docutils literal notranslate"><span class="pre">None</span></code> - this will suppress any GROUP BY configured
on mappers as well.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1: </span>GROUP BY can be cancelled by passing None,
in the same way as ORDER BY.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.having">
<code class="descname">having</code><span class="sig-paren">(</span><em>criterion</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.having" title="Permalink to this definition">¶</a></dt>
<dd><p>apply a HAVING criterion to the query and return the
newly resulting <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.having" title="sqlalchemy.orm.query.Query.having"><code class="xref py py-meth docutils literal notranslate"><span class="pre">having()</span></code></a> is used in conjunction with
<a class="reference internal" href="#sqlalchemy.orm.query.Query.group_by" title="sqlalchemy.orm.query.Query.group_by"><code class="xref py py-meth docutils literal notranslate"><span class="pre">group_by()</span></code></a>.</p>
<p>HAVING criterion makes it possible to use filters on aggregate
functions like COUNT, SUM, AVG, MAX, and MIN, eg.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span><span class="o">.</span>\
<span class="n">group_by</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span>\
<span class="n">having</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">id</span><span class="p">)</span> <span class="o">></span> <span class="mi">2</span><span class="p">)</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.instances">
<code class="descname">instances</code><span class="sig-paren">(</span><em>cursor</em>, <em>_Query__context=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.instances" title="Permalink to this definition">¶</a></dt>
<dd><p>Given a ResultProxy cursor as returned by connection.execute(),
return an ORM result as an iterator.</p>
<p>e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">result</span> <span class="o">=</span> <span class="n">engine</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">"select * from users"</span><span class="p">)</span>
<span class="k">for</span> <span class="n">u</span> <span class="ow">in</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">instances</span><span class="p">(</span><span class="n">result</span><span class="p">):</span>
<span class="nb">print</span> <span class="n">u</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.intersect">
<code class="descname">intersect</code><span class="sig-paren">(</span><em>*q</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.intersect" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an INTERSECT of this Query against one or more queries.</p>
<p>Works the same way as <a class="reference internal" href="#sqlalchemy.orm.query.Query.union" title="sqlalchemy.orm.query.Query.union"><code class="xref py py-meth docutils literal notranslate"><span class="pre">union()</span></code></a>. See
that method for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.intersect_all">
<code class="descname">intersect_all</code><span class="sig-paren">(</span><em>*q</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.intersect_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an INTERSECT ALL of this Query against one or more queries.</p>
<p>Works the same way as <a class="reference internal" href="#sqlalchemy.orm.query.Query.union" title="sqlalchemy.orm.query.Query.union"><code class="xref py py-meth docutils literal notranslate"><span class="pre">union()</span></code></a>. See
that method for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.join">
<code class="descname">join</code><span class="sig-paren">(</span><em>*props</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.join" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a SQL JOIN against this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object’s criterion
and apply generatively, returning the newly resulting <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>.</p>
<p><strong>Simple Relationship Joins</strong></p>
<p>Consider a mapping between two classes <code class="docutils literal notranslate"><span class="pre">User</span></code> and <code class="docutils literal notranslate"><span class="pre">Address</span></code>,
with a relationship <code class="docutils literal notranslate"><span class="pre">User.addresses</span></code> representing a collection
of <code class="docutils literal notranslate"><span class="pre">Address</span></code> objects associated with each <code class="docutils literal notranslate"><span class="pre">User</span></code>. The most
common usage of <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> is to create a JOIN along this
relationship, using the <code class="docutils literal notranslate"><span class="pre">User.addresses</span></code> attribute as an indicator
for how this should occur:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span></pre></div>
</div>
<p>Where above, the call to <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> along <code class="docutils literal notranslate"><span class="pre">User.addresses</span></code>
will result in SQL equivalent to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">user</span><span class="o">.*</span> <span class="n">FROM</span> <span class="n">user</span> <span class="n">JOIN</span> <span class="n">address</span> <span class="n">ON</span> <span class="n">user</span><span class="o">.</span><span class="n">id</span> <span class="o">=</span> <span class="n">address</span><span class="o">.</span><span class="n">user_id</span></pre></div>
</div>
<p>In the above example we refer to <code class="docutils literal notranslate"><span class="pre">User.addresses</span></code> as passed to
<a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> as the <em>on clause</em>, that is, it indicates
how the “ON” portion of the JOIN should be constructed. For a
single-entity query such as the one above (i.e. we start by selecting
only from <code class="docutils literal notranslate"><span class="pre">User</span></code> and nothing else), the relationship can also be
specified by its string name:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s2">"addresses"</span><span class="p">)</span></pre></div>
</div>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> can also accommodate multiple
“on clause” arguments to produce a chain of joins, such as below
where a join across four related entities is constructed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s2">"orders"</span><span class="p">,</span> <span class="s2">"items"</span><span class="p">,</span> <span class="s2">"keywords"</span><span class="p">)</span></pre></div>
</div>
<p>The above would be shorthand for three separate calls to
<a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a>, each using an explicit attribute to indicate
the source entity:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">orders</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">Order</span><span class="o">.</span><span class="n">items</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">Item</span><span class="o">.</span><span class="n">keywords</span><span class="p">)</span></pre></div>
</div>
<p><strong>Joins to a Target Entity or Selectable</strong></p>
<p>A second form of <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> allows any mapped entity
or core selectable construct as a target. In this usage,
<a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> will attempt
to create a JOIN along the natural foreign key relationship between
two entities:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">Address</span><span class="p">)</span></pre></div>
</div>
<p>The above calling form of <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> will raise an error if
either there are no foreign keys between the two entities, or if
there are multiple foreign key linkages between them. In the
above calling form, <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> is called upon to
create the “on clause” automatically for us. The target can
be any mapped entity or selectable, such as a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">addresses_table</span><span class="p">)</span></pre></div>
</div>
<p><strong>Joins to a Target with an ON Clause</strong></p>
<p>The third calling form allows both the target entity as well
as the ON clause to be passed explicitly. Suppose for
example we wanted to join to <code class="docutils literal notranslate"><span class="pre">Address</span></code> twice, using
an alias the second time. We use <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a>
to create a distinct alias of <code class="docutils literal notranslate"><span class="pre">Address</span></code>, and join
to it using the <code class="docutils literal notranslate"><span class="pre">target,</span> <span class="pre">onclause</span></code> form, so that the
alias can be specified explicitly as the target along with
the relationship to instruct how the ON clause should proceed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">a_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">Address</span><span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">a_alias</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email_address</span><span class="o">==</span><span class="s1">'ed@foo.com'</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">a_alias</span><span class="o">.</span><span class="n">email_address</span><span class="o">==</span><span class="s1">'ed@bar.com'</span><span class="p">)</span></pre></div>
</div>
<p>Where above, the generated SQL would be similar to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">user</span><span class="o">.*</span> <span class="n">FROM</span> <span class="n">user</span>
<span class="n">JOIN</span> <span class="n">address</span> <span class="n">ON</span> <span class="n">user</span><span class="o">.</span><span class="n">id</span> <span class="o">=</span> <span class="n">address</span><span class="o">.</span><span class="n">user_id</span>
<span class="n">JOIN</span> <span class="n">address</span> <span class="n">AS</span> <span class="n">address_1</span> <span class="n">ON</span> <span class="n">user</span><span class="o">.</span><span class="n">id</span><span class="o">=</span><span class="n">address_1</span><span class="o">.</span><span class="n">user_id</span>
<span class="n">WHERE</span> <span class="n">address</span><span class="o">.</span><span class="n">email_address</span> <span class="o">=</span> <span class="p">:</span><span class="n">email_address_1</span>
<span class="n">AND</span> <span class="n">address_1</span><span class="o">.</span><span class="n">email_address</span> <span class="o">=</span> <span class="p">:</span><span class="n">email_address_2</span></pre></div>
</div>
<p>The two-argument calling form of <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a>
also allows us to construct arbitrary joins with SQL-oriented
“on clause” expressions, not relying upon configured relationships
at all. Any SQL expression can be passed as the ON clause
when using the two-argument form, which should refer to the target
entity in some way as well as an applicable source entity:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">Address</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="n">Address</span><span class="o">.</span><span class="n">user_id</span><span class="p">)</span></pre></div>
</div>
<p><strong>Advanced Join Targeting and Adaption</strong></p>
<p>There is a lot of flexibility in what the “target” can be when using
<a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a>. As noted previously, it also accepts
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> constructs and other selectables such as
<a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.alias" title="sqlalchemy.sql.expression.alias"><code class="xref py py-func docutils literal notranslate"><span class="pre">alias()</span></code></a> and <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select()</span></code></a> constructs, with either the one
or two-argument forms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">addresses_q</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">Address</span><span class="o">.</span><span class="n">user_id</span><span class="p">])</span><span class="o">.</span>\
<span class="n">where</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email_address</span><span class="o">.</span><span class="n">endswith</span><span class="p">(</span><span class="s2">"@bar.com"</span><span class="p">))</span><span class="o">.</span>\
<span class="n">alias</span><span class="p">()</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">addresses_q</span><span class="p">,</span> <span class="n">addresses_q</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">User</span><span class="o">.</span><span class="n">id</span><span class="p">)</span></pre></div>
</div>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> also features the ability to <em>adapt</em> a
<a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-meth docutils literal notranslate"><span class="pre">relationship()</span></code></a> -driven ON clause to the target
selectable. Below we construct a JOIN from <code class="docutils literal notranslate"><span class="pre">User</span></code> to a subquery
against <code class="docutils literal notranslate"><span class="pre">Address</span></code>, allowing the relationship denoted by
<code class="docutils literal notranslate"><span class="pre">User.addresses</span></code> to <em>adapt</em> itself to the altered target:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">address_subq</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Address</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email_address</span> <span class="o">==</span> <span class="s1">'ed@foo.com'</span><span class="p">)</span><span class="o">.</span>\
<span class="n">subquery</span><span class="p">()</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">address_subq</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span></pre></div>
</div>
<p>Producing SQL similar to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">user</span><span class="o">.*</span> <span class="n">FROM</span> <span class="n">user</span>
<span class="n">JOIN</span> <span class="p">(</span>
<span class="n">SELECT</span> <span class="n">address</span><span class="o">.</span><span class="n">id</span> <span class="n">AS</span> <span class="nb">id</span><span class="p">,</span>
<span class="n">address</span><span class="o">.</span><span class="n">user_id</span> <span class="n">AS</span> <span class="n">user_id</span><span class="p">,</span>
<span class="n">address</span><span class="o">.</span><span class="n">email_address</span> <span class="n">AS</span> <span class="n">email_address</span>
<span class="n">FROM</span> <span class="n">address</span>
<span class="n">WHERE</span> <span class="n">address</span><span class="o">.</span><span class="n">email_address</span> <span class="o">=</span> <span class="p">:</span><span class="n">email_address_1</span>
<span class="p">)</span> <span class="n">AS</span> <span class="n">anon_1</span> <span class="n">ON</span> <span class="n">user</span><span class="o">.</span><span class="n">id</span> <span class="o">=</span> <span class="n">anon_1</span><span class="o">.</span><span class="n">user_id</span></pre></div>
</div>
<p>The above form allows one to fall back onto an explicit ON
clause at any time:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">address_subq</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="n">address_subq</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">user_id</span><span class="p">)</span></pre></div>
</div>
<p><strong>Controlling what to Join From</strong></p>
<p>While <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> exclusively deals with the “right”
side of the JOIN, we can also control the “left” side, in those
cases where it’s needed, using <a class="reference internal" href="#sqlalchemy.orm.query.Query.select_from" title="sqlalchemy.orm.query.Query.select_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">select_from()</span></code></a>.
Below we construct a query against <code class="docutils literal notranslate"><span class="pre">Address</span></code> but can still
make usage of <code class="docutils literal notranslate"><span class="pre">User.addresses</span></code> as our ON clause by instructing
the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> to select first from the <code class="docutils literal notranslate"><span class="pre">User</span></code>
entity:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Address</span><span class="p">)</span><span class="o">.</span><span class="n">select_from</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'ed'</span><span class="p">)</span></pre></div>
</div>
<p>Which will produce SQL similar to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">address</span><span class="o">.*</span> <span class="n">FROM</span> <span class="n">user</span>
<span class="n">JOIN</span> <span class="n">address</span> <span class="n">ON</span> <span class="n">user</span><span class="o">.</span><span class="n">id</span><span class="o">=</span><span class="n">address</span><span class="o">.</span><span class="n">user_id</span>
<span class="n">WHERE</span> <span class="n">user</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="p">:</span><span class="n">name_1</span></pre></div>
</div>
<p><strong>Constructing Aliases Anonymously</strong></p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> can construct anonymous aliases
using the <code class="docutils literal notranslate"><span class="pre">aliased=True</span></code> flag. This feature is useful
when a query is being joined algorithmically, such as
when querying self-referentially to an arbitrary depth:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Node</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="s2">"children"</span><span class="p">,</span> <span class="s2">"children"</span><span class="p">,</span> <span class="n">aliased</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span></pre></div>
</div>
<p>When <code class="docutils literal notranslate"><span class="pre">aliased=True</span></code> is used, the actual “alias” construct
is not explicitly available. To work with it, methods such as
<a class="reference internal" href="#sqlalchemy.orm.query.Query.filter" title="sqlalchemy.orm.query.Query.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.filter()</span></code></a> will adapt the incoming entity to
the last join point:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Node</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="s2">"children"</span><span class="p">,</span> <span class="s2">"children"</span><span class="p">,</span> <span class="n">aliased</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Node</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'grandchild 1'</span><span class="p">)</span></pre></div>
</div>
<p>When using automatic aliasing, the <code class="docutils literal notranslate"><span class="pre">from_joinpoint=True</span></code>
argument can allow a multi-node join to be broken into
multiple calls to <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a>, so that
each path along the way can be further filtered:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Node</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="s2">"children"</span><span class="p">,</span> <span class="n">aliased</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Node</span><span class="o">.</span><span class="n">name</span><span class="o">=</span><span class="s1">'child 1'</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="s2">"children"</span><span class="p">,</span> <span class="n">aliased</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">from_joinpoint</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Node</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'grandchild 1'</span><span class="p">)</span></pre></div>
</div>
<p>The filtering aliases above can then be reset back to the
original <code class="docutils literal notranslate"><span class="pre">Node</span></code> entity using <a class="reference internal" href="#sqlalchemy.orm.query.Query.reset_joinpoint" title="sqlalchemy.orm.query.Query.reset_joinpoint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">reset_joinpoint()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Node</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="s2">"children"</span><span class="p">,</span> <span class="s2">"children"</span><span class="p">,</span> <span class="n">aliased</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Node</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'grandchild 1'</span><span class="p">)</span><span class="o">.</span>\
<span class="n">reset_joinpoint</span><span class="p">()</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Node</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'parent 1)</span></pre></div>
</div>
<p>For an example of <code class="docutils literal notranslate"><span class="pre">aliased=True</span></code>, see the distribution
example <a class="reference internal" href="examples.html#examples-xmlpersistence"><span class="std std-ref">XML Persistence</span></a> which illustrates
an XPath-like query system using algorithmic joins.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.orm.query.Query.join.params.*props"></span><strong>*props</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.join.params.*props">¶</a> – A collection of one or more join conditions,
each consisting of a relationship-bound attribute or string
relationship name representing an “on clause”, or a single
target entity, or a tuple in the form of <code class="docutils literal notranslate"><span class="pre">(target,</span> <span class="pre">onclause)</span></code>.
A special two-argument calling form of the form <code class="docutils literal notranslate"><span class="pre">target,</span> <span class="pre">onclause</span></code>
is also accepted.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.join.params.aliased"></span><strong>aliased=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.join.params.aliased">¶</a> – If True, indicate that the JOIN target should be
anonymously aliased. Subsequent calls to <a class="reference internal" href="#sqlalchemy.orm.query.Query.filter" title="sqlalchemy.orm.query.Query.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">filter()</span></code></a>
and similar will adapt the incoming criterion to the target
alias, until <a class="reference internal" href="#sqlalchemy.orm.query.Query.reset_joinpoint" title="sqlalchemy.orm.query.Query.reset_joinpoint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">reset_joinpoint()</span></code></a> is called.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.join.params.isouter"></span><strong>isouter=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.join.params.isouter">¶</a> – <p>If True, the join used will be a left outer join,
just as if the <a class="reference internal" href="#sqlalchemy.orm.query.Query.outerjoin" title="sqlalchemy.orm.query.Query.outerjoin"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.outerjoin()</span></code></a> method were called. This
flag is here to maintain consistency with the same flag as accepted
by <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.FromClause.join" title="sqlalchemy.sql.expression.FromClause.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">FromClause.join()</span></code></a> and other Core constructs.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.0.</span></p>
</div>
</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.join.params.full"></span><strong>full=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.join.params.full">¶</a> – <p>render FULL OUTER JOIN; implies <code class="docutils literal notranslate"><span class="pre">isouter</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.1.</span></p>
</div>
</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.join.params.from_joinpoint"></span><strong>from_joinpoint=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.join.params.from_joinpoint">¶</a> – When using <code class="docutils literal notranslate"><span class="pre">aliased=True</span></code>, a setting
of True here will cause the join to be from the most recent
joined target, rather than starting back from the original
FROM clauses of the query.</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="tutorial.html#ormtutorial-joins"><span class="std std-ref">Querying with Joins</span></a> in the ORM tutorial.</p>
<p><a class="reference internal" href="inheritance.html"><span class="std std-ref">Mapping Class Inheritance Hierarchies</span></a> for details on how
<a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> is used for inheritance relationships.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.join" title="sqlalchemy.orm.join"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.join()</span></code></a> - a standalone ORM-level join function,
used internally by <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.join()</span></code></a>, which in previous
SQLAlchemy versions was the primary ORM-level joining interface.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.label">
<code class="descname">label</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.label" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the full SELECT statement represented by this
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>, converted
to a scalar subquery with a label of the given name.</p>
<p>Analogous to <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.SelectBase.label" title="sqlalchemy.sql.expression.SelectBase.label"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sqlalchemy.sql.expression.SelectBase.label()</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Query.lazy_loaded_from">
<code class="descname">lazy_loaded_from</code><em class="property"> = None</em><a class="headerlink" href="#sqlalchemy.orm.query.Query.lazy_loaded_from" title="Permalink to this definition">¶</a></dt>
<dd><p>An <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><code class="xref py py-class docutils literal notranslate"><span class="pre">InstanceState</span></code></a> that is using this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> for a
lazy load operation.</p>
<p>This can be used for extensions like the horizontal sharding extension
as well as event handlers and custom mapper options to determine
when a query is being used to lazy load a relationship on an object.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.2.9.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.limit">
<code class="descname">limit</code><span class="sig-paren">(</span><em>limit</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.limit" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply a <code class="docutils literal notranslate"><span class="pre">LIMIT</span></code> to the query and return the newly resulting
<code class="docutils literal notranslate"><span class="pre">Query</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.merge_result">
<code class="descname">merge_result</code><span class="sig-paren">(</span><em>iterator</em>, <em>load=True</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.merge_result" title="Permalink to this definition">¶</a></dt>
<dd><p>Merge a result into this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object’s Session.</p>
<p>Given an iterator returned by a <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> of the same structure
as this one, return an identical iterator of results, with all mapped
instances merged into the session using <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.merge()</span></code></a>. This
is an optimized method which will merge all mapped instances,
preserving the structure of the result rows and unmapped columns with
less method overhead than that of calling <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.merge()</span></code></a>
explicitly for each value.</p>
<p>The structure of the results is determined based on the column list of
this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> - if these do not correspond, unchecked errors
will occur.</p>
<p>The ‘load’ argument is the same as that of <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.merge()</span></code></a>.</p>
<p>For an example of how <a class="reference internal" href="#sqlalchemy.orm.query.Query.merge_result" title="sqlalchemy.orm.query.Query.merge_result"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge_result()</span></code></a> is used, see
the source code for the example <a class="reference internal" href="examples.html#examples-caching"><span class="std std-ref">Dogpile Caching</span></a>, where
<a class="reference internal" href="#sqlalchemy.orm.query.Query.merge_result" title="sqlalchemy.orm.query.Query.merge_result"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge_result()</span></code></a> is used to efficiently restore state
from a cache back into a target <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.offset">
<code class="descname">offset</code><span class="sig-paren">(</span><em>offset</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.offset" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply an <code class="docutils literal notranslate"><span class="pre">OFFSET</span></code> to the query and return the newly resulting
<code class="docutils literal notranslate"><span class="pre">Query</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.one">
<code class="descname">one</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.one" title="Permalink to this definition">¶</a></dt>
<dd><p>Return exactly one result or raise an exception.</p>
<p>Raises <code class="docutils literal notranslate"><span class="pre">sqlalchemy.orm.exc.NoResultFound</span></code> if the query selects
no rows. Raises <code class="docutils literal notranslate"><span class="pre">sqlalchemy.orm.exc.MultipleResultsFound</span></code>
if multiple object identities are returned, or if multiple
rows are returned for a query that returns only scalar values
as opposed to full identity-mapped entities.</p>
<p>Calling <a class="reference internal" href="#sqlalchemy.orm.query.Query.one" title="sqlalchemy.orm.query.Query.one"><code class="xref py py-meth docutils literal notranslate"><span class="pre">one()</span></code></a> results in an execution of the underlying query.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.first" title="sqlalchemy.orm.query.Query.first"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.first()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.one_or_none" title="sqlalchemy.orm.query.Query.one_or_none"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.one_or_none()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.one_or_none">
<code class="descname">one_or_none</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.one_or_none" title="Permalink to this definition">¶</a></dt>
<dd><p>Return at most one result or raise an exception.</p>
<p>Returns <code class="docutils literal notranslate"><span class="pre">None</span></code> if the query selects
no rows. Raises <code class="docutils literal notranslate"><span class="pre">sqlalchemy.orm.exc.MultipleResultsFound</span></code>
if multiple object identities are returned, or if multiple
rows are returned for a query that returns only scalar values
as opposed to full identity-mapped entities.</p>
<p>Calling <a class="reference internal" href="#sqlalchemy.orm.query.Query.one_or_none" title="sqlalchemy.orm.query.Query.one_or_none"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.one_or_none()</span></code></a> results in an execution of the
underlying query.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.9: </span>Added <a class="reference internal" href="#sqlalchemy.orm.query.Query.one_or_none" title="sqlalchemy.orm.query.Query.one_or_none"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.one_or_none()</span></code></a></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.first" title="sqlalchemy.orm.query.Query.first"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.first()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.one" title="sqlalchemy.orm.query.Query.one"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.one()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.only_return_tuples">
<code class="descname">only_return_tuples</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.only_return_tuples" title="Permalink to this definition">¶</a></dt>
<dd><dl class="simple">
<dt>When set to True, the query results will always be a tuple,</dt><dd><p>specifically for single element queries. The default is False.</p>
</dd>
</dl>
<p>. .. versionadded:: 1.2.5</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.options">
<code class="descname">options</code><span class="sig-paren">(</span><em>*args</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.options" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new Query object, applying the given list of
mapper options.</p>
<p>Most supplied options regard changing how column- and
relationship-mapped attributes are loaded. See the sections
<a class="reference internal" href="loading_columns.html#deferred"><span class="std std-ref">Deferred Column Loading</span></a> and <a class="reference internal" href="loading_relationships.html"><span class="doc">Relationship Loading Techniques</span></a> for reference
documentation.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.order_by">
<code class="descname">order_by</code><span class="sig-paren">(</span><em>*criterion</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.order_by" title="Permalink to this definition">¶</a></dt>
<dd><p>apply one or more ORDER BY criterion to the query and return
the newly resulting <code class="docutils literal notranslate"><span class="pre">Query</span></code></p>
<p>All existing ORDER BY settings can be suppressed by
passing <code class="docutils literal notranslate"><span class="pre">None</span></code> - this will suppress any ordering configured
on the <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><code class="xref py py-func docutils literal notranslate"><span class="pre">mapper()</span></code></a> object using the deprecated
<a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.order_by" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.order_by</span></code></a> parameter.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.outerjoin">
<code class="descname">outerjoin</code><span class="sig-paren">(</span><em>*props</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.outerjoin" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a left outer join against this <code class="docutils literal notranslate"><span class="pre">Query</span></code> object’s criterion
and apply generatively, returning the newly resulting <code class="docutils literal notranslate"><span class="pre">Query</span></code>.</p>
<p>Usage is the same as the <code class="docutils literal notranslate"><span class="pre">join()</span></code> method.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.params">
<code class="descname">params</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.params" title="Permalink to this definition">¶</a></dt>
<dd><p>add values for bind parameters which may have been
specified in filter().</p>
<p>parameters may be specified using **kwargs, or optionally a single
dictionary as the first positional argument. The reason for both is
that **kwargs is convenient, however some parameter dictionaries
contain unicode keys in which case **kwargs cannot be used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.populate_existing">
<code class="descname">populate_existing</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.populate_existing" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> that will expire and refresh all instances
as they are loaded, or reused from the current <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.populate_existing" title="sqlalchemy.orm.query.Query.populate_existing"><code class="xref py py-meth docutils literal notranslate"><span class="pre">populate_existing()</span></code></a> does not improve behavior when
the ORM is used normally - the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> object’s usual
behavior of maintaining a transaction and expiring all attributes
after rollback or commit handles object state automatically.
This method is not intended for general use.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.prefix_with">
<code class="descname">prefix_with</code><span class="sig-paren">(</span><em>*prefixes</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.prefix_with" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply the prefixes to the query and return the newly resulting
<code class="docutils literal notranslate"><span class="pre">Query</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.orm.query.Query.prefix_with.params.*prefixes"></span><strong>*prefixes</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.prefix_with.params.*prefixes">¶</a> – optional prefixes, typically strings,
not using any commas. In particular is useful for MySQL keywords.</p>
</dd>
</dl>
<p>e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">query</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="o">.</span>\
<span class="n">prefix_with</span><span class="p">(</span><span class="s1">'HIGH_PRIORITY'</span><span class="p">)</span><span class="o">.</span>\
<span class="n">prefix_with</span><span class="p">(</span><span class="s1">'SQL_SMALL_RESULT'</span><span class="p">,</span> <span class="s1">'ALL'</span><span class="p">)</span></pre></div>
</div>
<p>Would render:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">HIGH_PRIORITY</span> <span class="n">SQL_SMALL_RESULT</span> <span class="n">ALL</span> <span class="n">users</span><span class="o">.</span><span class="n">name</span> <span class="n">AS</span> <span class="n">users_name</span>
<span class="n">FROM</span> <span class="n">users</span></pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.HasPrefixes.prefix_with" title="sqlalchemy.sql.expression.HasPrefixes.prefix_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">HasPrefixes.prefix_with()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.reset_joinpoint">
<code class="descname">reset_joinpoint</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.reset_joinpoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>, where the “join point” has
been reset back to the base FROM entities of the query.</p>
<p>This method is usually used in conjunction with the
<code class="docutils literal notranslate"><span class="pre">aliased=True</span></code> feature of the <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a>
method. See the example in <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a> for how
this is used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.scalar">
<code class="descname">scalar</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.scalar" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the first element of the first result or None
if no rows present. If multiple rows are returned,
raises MultipleResultsFound.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Item</span><span class="p">)</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
<span class="go"><Item></span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Item</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
<span class="go">1</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Item</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Item</span><span class="o">.</span><span class="n">id</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
<span class="go">None</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Item</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">Item</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
<span class="go">1</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">Parent</span><span class="o">.</span><span class="n">id</span><span class="p">))</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
<span class="go">20</span></pre></div>
</div>
<p>This results in an execution of the underlying query.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.select_entity_from">
<code class="descname">select_entity_from</code><span class="sig-paren">(</span><em>from_obj</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.select_entity_from" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the FROM clause of this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> to a
core selectable, applying it as a replacement FROM clause
for corresponding mapped entities.</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from" title="sqlalchemy.orm.query.Query.select_entity_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_entity_from()</span></code></a> method supplies an alternative
approach to the use case of applying an <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> construct
explicitly throughout a query. Instead of referring to the
<a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> construct explicitly,
<a class="reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from" title="sqlalchemy.orm.query.Query.select_entity_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_entity_from()</span></code></a> automatically <em>adapts</em> all
occurrences of the entity to the target selectable.</p>
<p>Given a case for <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> such as selecting <code class="docutils literal notranslate"><span class="pre">User</span></code>
objects from a SELECT statement:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">select_stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">User</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">id</span> <span class="o">==</span> <span class="mi">7</span><span class="p">)</span>
<span class="n">user_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">select_stmt</span><span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">user_alias</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">user_alias</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'ed'</span><span class="p">)</span></pre></div>
</div>
<p>Above, we apply the <code class="docutils literal notranslate"><span class="pre">user_alias</span></code> object explicitly throughout the
query. When it’s not feasible for <code class="docutils literal notranslate"><span class="pre">user_alias</span></code> to be referenced
explicitly in many places, <a class="reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from" title="sqlalchemy.orm.query.Query.select_entity_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_entity_from()</span></code></a> may be
used at the start of the query to adapt the existing <code class="docutils literal notranslate"><span class="pre">User</span></code> entity:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">select_entity_from</span><span class="p">(</span><span class="n">select_stmt</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'ed'</span><span class="p">)</span></pre></div>
</div>
<p>Above, the generated SQL will show that the <code class="docutils literal notranslate"><span class="pre">User</span></code> entity is
adapted to our statement, even in the case of the WHERE clause:</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">SELECT</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">anon_1_id</span><span class="p">,</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">anon_1_name</span>
<span class="k">FROM</span> <span class="p">(</span><span class="k">SELECT</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">id</span><span class="p">,</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">name</span>
<span class="k">FROM</span> <span class="ss">"user"</span>
<span class="k">WHERE</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="o">=</span> <span class="p">:</span><span class="n">id_1</span><span class="p">)</span> <span class="k">AS</span> <span class="n">anon_1</span>
<span class="k">WHERE</span> <span class="n">anon_1</span><span class="p">.</span><span class="n">name</span> <span class="o">=</span> <span class="p">:</span><span class="n">name_1</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from" title="sqlalchemy.orm.query.Query.select_entity_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_entity_from()</span></code></a> method is similar to the
<a class="reference internal" href="#sqlalchemy.orm.query.Query.select_from" title="sqlalchemy.orm.query.Query.select_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_from()</span></code></a> method, in that it sets the FROM clause
of the query. The difference is that it additionally applies
adaptation to the other parts of the query that refer to the
primary entity. If above we had used <a class="reference internal" href="#sqlalchemy.orm.query.Query.select_from" title="sqlalchemy.orm.query.Query.select_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_from()</span></code></a>
instead, the SQL generated would have been:</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="c1">-- uses plain select_from(), not select_entity_from()</span>
<span class="k">SELECT</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">user_id</span><span class="p">,</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">user_name</span>
<span class="k">FROM</span> <span class="ss">"user"</span><span class="p">,</span> <span class="p">(</span><span class="k">SELECT</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">id</span><span class="p">,</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">name</span>
<span class="k">FROM</span> <span class="ss">"user"</span>
<span class="k">WHERE</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">id</span> <span class="o">=</span> <span class="p">:</span><span class="n">id_1</span><span class="p">)</span> <span class="k">AS</span> <span class="n">anon_1</span>
<span class="k">WHERE</span> <span class="ss">"user"</span><span class="p">.</span><span class="n">name</span> <span class="o">=</span> <span class="p">:</span><span class="n">name_1</span></pre></div>
</div>
<p>To supply textual SQL to the <a class="reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from" title="sqlalchemy.orm.query.Query.select_entity_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_entity_from()</span></code></a> method,
we can make use of the <a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><code class="xref py py-func docutils literal notranslate"><span class="pre">text()</span></code></a> construct. However, the
<a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><code class="xref py py-func docutils literal notranslate"><span class="pre">text()</span></code></a> construct needs to be aligned with the columns of our
entity, which is achieved by making use of the
<a class="reference internal" href="../core/sqlelement.html#sqlalchemy.sql.expression.TextClause.columns" title="sqlalchemy.sql.expression.TextClause.columns"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TextClause.columns()</span></code></a> method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">text_stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s2">"select id, name from user"</span><span class="p">)</span><span class="o">.</span><span class="n">columns</span><span class="p">(</span>
<span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">select_entity_from</span><span class="p">(</span><span class="n">text_stmt</span><span class="p">)</span></pre></div>
</div>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from" title="sqlalchemy.orm.query.Query.select_entity_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_entity_from()</span></code></a> itself accepts an <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a>
object, so that the special options of <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> such as
<a class="reference internal" href="#sqlalchemy.orm.aliased.params.adapt_on_names" title="sqlalchemy.orm.aliased"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">aliased.adapt_on_names</span></code></a> may be used within the
scope of the <a class="reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from" title="sqlalchemy.orm.query.Query.select_entity_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_entity_from()</span></code></a> method’s adaptation
services. Suppose
a view <code class="docutils literal notranslate"><span class="pre">user_view</span></code> also returns rows from <code class="docutils literal notranslate"><span class="pre">user</span></code>. If
we reflect this view into a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>, this view has no
relationship to the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> to which we are mapped, however
we can use name matching to select from it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">user_view</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s1">'user_view'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span>
<span class="n">autoload_with</span><span class="o">=</span><span class="n">engine</span><span class="p">)</span>
<span class="n">user_view_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span>
<span class="n">User</span><span class="p">,</span> <span class="n">user_view</span><span class="p">,</span> <span class="n">adapt_on_names</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">select_entity_from</span><span class="p">(</span><span class="n">user_view_alias</span><span class="p">)</span><span class="o">.</span>\
<span class="n">order_by</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="p">)</span></pre></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.1.7: </span>The <a class="reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from" title="sqlalchemy.orm.query.Query.select_entity_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_entity_from()</span></code></a>
method now accepts an <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> object as an alternative
to a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.FromClause" title="sqlalchemy.sql.expression.FromClause"><code class="xref py py-class docutils literal notranslate"><span class="pre">FromClause</span></code></a> object.</p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.orm.query.Query.select_entity_from.params.from_obj"></span><strong>from_obj</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from.params.from_obj">¶</a> – a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.FromClause" title="sqlalchemy.sql.expression.FromClause"><code class="xref py py-class docutils literal notranslate"><span class="pre">FromClause</span></code></a> object that will replace
the FROM clause of this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>. It also may be an instance
of <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a>.</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.select_from" title="sqlalchemy.orm.query.Query.select_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_from()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.select_from">
<code class="descname">select_from</code><span class="sig-paren">(</span><em>*from_obj</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.select_from" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the FROM clause of this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> explicitly.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.select_from" title="sqlalchemy.orm.query.Query.select_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_from()</span></code></a> is often used in conjunction with
<a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.join()</span></code></a> in order to control which entity is selected
from on the “left” side of the join.</p>
<p>The entity or selectable object here effectively replaces the
“left edge” of any calls to <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a>, when no
joinpoint is otherwise established - usually, the default “join
point” is the leftmost entity in the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object’s
list of entities to be selected.</p>
<p>A typical example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Address</span><span class="p">)</span><span class="o">.</span><span class="n">select_from</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'ed'</span><span class="p">)</span></pre></div>
</div>
<p>Which produces SQL equivalent to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">address</span><span class="o">.*</span> <span class="n">FROM</span> <span class="n">user</span>
<span class="n">JOIN</span> <span class="n">address</span> <span class="n">ON</span> <span class="n">user</span><span class="o">.</span><span class="n">id</span><span class="o">=</span><span class="n">address</span><span class="o">.</span><span class="n">user_id</span>
<span class="n">WHERE</span> <span class="n">user</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="p">:</span><span class="n">name_1</span></pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.orm.query.Query.select_from.params.*from_obj"></span><strong>*from_obj</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.select_from.params.*from_obj">¶</a> – collection of one or more entities to apply
to the FROM clause. Entities can be mapped classes,
<a class="reference internal" href="#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedClass</span></code></a> objects, <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mapper</span></code></a> objects
as well as core <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.FromClause" title="sqlalchemy.sql.expression.FromClause"><code class="xref py py-class docutils literal notranslate"><span class="pre">FromClause</span></code></a> elements like subqueries.</p>
</dd>
</dl>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 0.9: </span>This method no longer applies the given FROM object
to be the selectable from which matching entities
select from; the <a class="reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from" title="sqlalchemy.orm.query.Query.select_entity_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">select_entity_from()</span></code></a> method
now accomplishes this. See that method for a description
of this behavior.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">join()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.select_entity_from" title="sqlalchemy.orm.query.Query.select_entity_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_entity_from()</span></code></a></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Query.selectable">
<code class="descname">selectable</code><a class="headerlink" href="#sqlalchemy.orm.query.Query.selectable" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Select" title="sqlalchemy.sql.expression.Select"><code class="xref py py-class docutils literal notranslate"><span class="pre">Select</span></code></a> object emitted by this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>.</p>
<p>Used for <a class="reference internal" href="../core/inspection.html#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><code class="xref py py-func docutils literal notranslate"><span class="pre">inspect()</span></code></a> compatibility, this is equivalent to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">query</span><span class="o">.</span><span class="n">enable_eagerloads</span><span class="p">(</span><span class="kc">False</span><span class="p">)</span><span class="o">.</span><span class="n">with_labels</span><span class="p">()</span><span class="o">.</span><span class="n">statement</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.slice">
<code class="descname">slice</code><span class="sig-paren">(</span><em>start</em>, <em>stop</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.slice" title="Permalink to this definition">¶</a></dt>
<dd><p>Computes the “slice” of the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> represented by
the given indices and returns the resulting <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>.</p>
<p>The start and stop indices behave like the argument to Python’s
built-in <code class="xref py py-func docutils literal notranslate"><span class="pre">range()</span></code> function. This method provides an
alternative to using <code class="docutils literal notranslate"><span class="pre">LIMIT</span></code>/<code class="docutils literal notranslate"><span class="pre">OFFSET</span></code> to get a slice of the
query.</p>
<p>For example,</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span><span class="n">slice</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span></pre></div>
</div>
<p>renders as</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">SELECT</span> <span class="n">users</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">users_id</span><span class="p">,</span>
<span class="n">users</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">users_name</span>
<span class="k">FROM</span> <span class="n">users</span> <span class="k">ORDER</span> <span class="k">BY</span> <span class="n">users</span><span class="p">.</span><span class="n">id</span>
<span class="k">LIMIT</span> <span class="o">?</span> <span class="k">OFFSET</span> <span class="o">?</span>
<span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span></pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.limit" title="sqlalchemy.orm.query.Query.limit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.limit()</span></code></a></p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.offset" title="sqlalchemy.orm.query.Query.offset"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.offset()</span></code></a></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Query.statement">
<code class="descname">statement</code><a class="headerlink" href="#sqlalchemy.orm.query.Query.statement" title="Permalink to this definition">¶</a></dt>
<dd><p>The full SELECT statement represented by this Query.</p>
<p>The statement by default will not have disambiguating labels
applied to the construct unless with_labels(True) is called
first.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.subquery">
<code class="descname">subquery</code><span class="sig-paren">(</span><em>name=None</em>, <em>with_labels=False</em>, <em>reduce_columns=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.subquery" title="Permalink to this definition">¶</a></dt>
<dd><p>return the full SELECT statement represented by
this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>, embedded within an <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><code class="xref py py-class docutils literal notranslate"><span class="pre">Alias</span></code></a>.</p>
<p>Eager JOIN generation within the query is disabled.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.orm.query.Query.subquery.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.subquery.params.name">¶</a> – string name to be assigned as the alias;
this is passed through to <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.FromClause.alias" title="sqlalchemy.sql.expression.FromClause.alias"><code class="xref py py-meth docutils literal notranslate"><span class="pre">FromClause.alias()</span></code></a>.
If <code class="docutils literal notranslate"><span class="pre">None</span></code>, a name will be deterministically generated
at compile time.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.subquery.params.with_labels"></span><strong>with_labels</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.subquery.params.with_labels">¶</a> – if True, <a class="reference internal" href="#sqlalchemy.orm.query.Query.with_labels" title="sqlalchemy.orm.query.Query.with_labels"><code class="xref py py-meth docutils literal notranslate"><span class="pre">with_labels()</span></code></a> will be called
on the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> first to apply table-qualified labels
to all columns.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.subquery.params.reduce_columns"></span><strong>reduce_columns</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.subquery.params.reduce_columns">¶</a> – if True, <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Select.reduce_columns" title="sqlalchemy.sql.expression.Select.reduce_columns"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Select.reduce_columns()</span></code></a> will
be called on the resulting <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select()</span></code></a> construct,
to remove same-named columns where one also refers to the other
via foreign key or WHERE clause equivalence.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.suffix_with">
<code class="descname">suffix_with</code><span class="sig-paren">(</span><em>*suffixes</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.suffix_with" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply the suffix to the query and return the newly resulting
<code class="docutils literal notranslate"><span class="pre">Query</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.orm.query.Query.suffix_with.params.*suffixes"></span><strong>*suffixes</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.suffix_with.params.*suffixes">¶</a> – optional suffixes, typically strings,
not using any commas.</p>
</dd>
</dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.0.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.prefix_with" title="sqlalchemy.orm.query.Query.prefix_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.prefix_with()</span></code></a></p>
<p><a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.HasSuffixes.suffix_with" title="sqlalchemy.sql.expression.HasSuffixes.suffix_with"><code class="xref py py-meth docutils literal notranslate"><span class="pre">HasSuffixes.suffix_with()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.union">
<code class="descname">union</code><span class="sig-paren">(</span><em>*q</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.union" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a UNION of this Query against one or more queries.</p>
<p>e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q1</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">SomeClass</span><span class="o">.</span><span class="n">foo</span><span class="o">==</span><span class="s1">'bar'</span><span class="p">)</span>
<span class="n">q2</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">SomeClass</span><span class="o">.</span><span class="n">bar</span><span class="o">==</span><span class="s1">'foo'</span><span class="p">)</span>
<span class="n">q3</span> <span class="o">=</span> <span class="n">q1</span><span class="o">.</span><span class="n">union</span><span class="p">(</span><span class="n">q2</span><span class="p">)</span></pre></div>
</div>
<p>The method accepts multiple Query objects so as to control
the level of nesting. A series of <code class="docutils literal notranslate"><span class="pre">union()</span></code> calls such as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">x</span><span class="o">.</span><span class="n">union</span><span class="p">(</span><span class="n">y</span><span class="p">)</span><span class="o">.</span><span class="n">union</span><span class="p">(</span><span class="n">z</span><span class="p">)</span><span class="o">.</span><span class="n">all</span><span class="p">()</span></pre></div>
</div>
<p>will nest on each <code class="docutils literal notranslate"><span class="pre">union()</span></code>, and produces:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">*</span> <span class="n">FROM</span> <span class="p">(</span><span class="n">SELECT</span> <span class="o">*</span> <span class="n">FROM</span> <span class="p">(</span><span class="n">SELECT</span> <span class="o">*</span> <span class="n">FROM</span> <span class="n">X</span> <span class="n">UNION</span>
<span class="n">SELECT</span> <span class="o">*</span> <span class="n">FROM</span> <span class="n">y</span><span class="p">)</span> <span class="n">UNION</span> <span class="n">SELECT</span> <span class="o">*</span> <span class="n">FROM</span> <span class="n">Z</span><span class="p">)</span></pre></div>
</div>
<p>Whereas:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">x</span><span class="o">.</span><span class="n">union</span><span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">z</span><span class="p">)</span><span class="o">.</span><span class="n">all</span><span class="p">()</span></pre></div>
</div>
<p>produces:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="o">*</span> <span class="n">FROM</span> <span class="p">(</span><span class="n">SELECT</span> <span class="o">*</span> <span class="n">FROM</span> <span class="n">X</span> <span class="n">UNION</span> <span class="n">SELECT</span> <span class="o">*</span> <span class="n">FROM</span> <span class="n">y</span> <span class="n">UNION</span>
<span class="n">SELECT</span> <span class="o">*</span> <span class="n">FROM</span> <span class="n">Z</span><span class="p">)</span></pre></div>
</div>
<p>Note that many database backends do not allow ORDER BY to
be rendered on a query called within UNION, EXCEPT, etc.
To disable all ORDER BY clauses including those configured
on mappers, issue <code class="docutils literal notranslate"><span class="pre">query.order_by(None)</span></code> - the resulting
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object will not render ORDER BY within
its SELECT statement.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.union_all">
<code class="descname">union_all</code><span class="sig-paren">(</span><em>*q</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.union_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a UNION ALL of this Query against one or more queries.</p>
<p>Works the same way as <a class="reference internal" href="#sqlalchemy.orm.query.Query.union" title="sqlalchemy.orm.query.Query.union"><code class="xref py py-meth docutils literal notranslate"><span class="pre">union()</span></code></a>. See
that method for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.update">
<code class="descname">update</code><span class="sig-paren">(</span><em>values</em>, <em>synchronize_session='evaluate'</em>, <em>update_args=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.update" title="Permalink to this definition">¶</a></dt>
<dd><p>Perform a bulk update query.</p>
<p>Updates rows matched by this query in the database.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">age</span> <span class="o">==</span> <span class="mi">25</span><span class="p">)</span><span class="o">.</span>\
<span class="n">update</span><span class="p">({</span><span class="n">User</span><span class="o">.</span><span class="n">age</span><span class="p">:</span> <span class="n">User</span><span class="o">.</span><span class="n">age</span> <span class="o">-</span> <span class="mi">10</span><span class="p">},</span> <span class="n">synchronize_session</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">age</span> <span class="o">==</span> <span class="mi">25</span><span class="p">)</span><span class="o">.</span>\
<span class="n">update</span><span class="p">({</span><span class="s2">"age"</span><span class="p">:</span> <span class="n">User</span><span class="o">.</span><span class="n">age</span> <span class="o">-</span> <span class="mi">10</span><span class="p">},</span> <span class="n">synchronize_session</span><span class="o">=</span><span class="s1">'evaluate'</span><span class="p">)</span></pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.query.Query.update" title="sqlalchemy.orm.query.Query.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.update()</span></code></a> method is a “bulk” operation,
which bypasses ORM unit-of-work automation in favor of greater
performance. <strong>Please read all caveats and warnings below.</strong></p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.orm.query.Query.update.params.values"></span><strong>values</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.update.params.values">¶</a> – <p>a dictionary with attributes names, or alternatively
mapped attributes or SQL expressions, as keys, and literal
values or sql expressions as values. If <a class="reference internal" href="../core/tutorial.html#updates-order-parameters"><span class="std std-ref">parameter-ordered
mode</span></a> is desired, the values can be
passed as a list of 2-tuples;
this requires that the
<a class="reference internal" href="../core/dml.html#sqlalchemy.sql.expression.update.params.preserve_parameter_order" title="sqlalchemy.sql.expression.update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">preserve_parameter_order</span></code></a>
flag is passed to the <a class="reference internal" href="#sqlalchemy.orm.query.Query.update.params.update_args" title="sqlalchemy.orm.query.Query.update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">Query.update.update_args</span></code></a> dictionary
as well.</p>
<blockquote>
<div><div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.0.0: </span>- string names in the values dictionary
are now resolved against the mapped entity; previously, these
strings were passed as literal column names with no mapper-level
translation.</p>
</div>
</div></blockquote>
</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.update.params.synchronize_session"></span><strong>synchronize_session</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.update.params.synchronize_session">¶</a> – <p>chooses the strategy to update the
attributes on objects in the session. Valid values are:</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">False</span></code> - don’t synchronize the session. This option is the most
efficient and is reliable once the session is expired, which
typically occurs after a commit(), or explicitly using
expire_all(). Before the expiration, updated objects may still
remain in the session with stale values on their attributes, which
can lead to confusing results.</p>
<p><code class="docutils literal notranslate"><span class="pre">'fetch'</span></code> - performs a select query before the update to find
objects that are matched by the update query. The updated
attributes are expired on matched objects.</p>
<p><code class="docutils literal notranslate"><span class="pre">'evaluate'</span></code> - Evaluate the Query’s criteria in Python straight
on the objects in the session. If evaluation of the criteria isn’t
implemented, an exception is raised.</p>
<p>The expression evaluator currently doesn’t account for differing
string collations between the database and Python.</p>
</div></blockquote>
</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.update.params.update_args"></span><strong>update_args</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.update.params.update_args">¶</a> – <p>Optional dictionary, if present will be passed
to the underlying <a class="reference internal" href="../core/dml.html#sqlalchemy.sql.expression.update" title="sqlalchemy.sql.expression.update"><code class="xref py py-func docutils literal notranslate"><span class="pre">update()</span></code></a> construct as the <code class="docutils literal notranslate"><span class="pre">**kw</span></code> for
the object. May be used to pass dialect-specific arguments such
as <code class="docutils literal notranslate"><span class="pre">mysql_limit</span></code>, as well as other special arguments such as
<a class="reference internal" href="../core/dml.html#sqlalchemy.sql.expression.update.params.preserve_parameter_order" title="sqlalchemy.sql.expression.update"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">preserve_parameter_order</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.0.</span></p>
</div>
</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>the count of rows matched as returned by the database’s
“row count” feature.</p>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p><strong>Additional Caveats for bulk query updates</strong></p>
<ul>
<li><p>The method does <strong>not</strong> offer in-Python cascading of
relationships - it is assumed that ON UPDATE CASCADE is
configured for any foreign key references which require
it, otherwise the database may emit an integrity
violation if foreign key references are being enforced.</p>
<p>After the UPDATE, dependent objects in the
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> which were impacted by an ON UPDATE
CASCADE may not contain the current state; this issue is
resolved once the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> is expired, which
normally occurs upon <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.commit()</span></code></a> or can be
forced by using <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire_all" title="sqlalchemy.orm.session.Session.expire_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.expire_all()</span></code></a>.</p>
</li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">'fetch'</span></code> strategy results in an additional
SELECT statement emitted and will significantly reduce
performance.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">'evaluate'</span></code> strategy performs a scan of
all matching objects within the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>; if the
contents of the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> are expired, such as
via a proceeding <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.commit()</span></code></a> call, <strong>this will
result in SELECT queries emitted for every matching object</strong>.</p></li>
<li><p>The method supports multiple table updates, as detailed
in <a class="reference internal" href="../core/tutorial.html#multi-table-updates"><span class="std std-ref">Multiple Table Updates</span></a>, and this behavior does
extend to support updates of joined-inheritance and
other multiple table mappings. However, the <strong>join
condition of an inheritance mapper is not
automatically rendered</strong>. Care must be taken in any
multiple-table update to explicitly include the joining
condition between those tables, even in mappings where
this is normally automatic. E.g. if a class <code class="docutils literal notranslate"><span class="pre">Engineer</span></code>
subclasses <code class="docutils literal notranslate"><span class="pre">Employee</span></code>, an UPDATE of the <code class="docutils literal notranslate"><span class="pre">Engineer</span></code>
local table using criteria against the <code class="docutils literal notranslate"><span class="pre">Employee</span></code>
local table might look like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Engineer</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Engineer</span><span class="o">.</span><span class="n">id</span> <span class="o">==</span> <span class="n">Employee</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Employee</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'dilbert'</span><span class="p">)</span><span class="o">.</span>\
<span class="n">update</span><span class="p">({</span><span class="s2">"engineer_type"</span><span class="p">:</span> <span class="s2">"programmer"</span><span class="p">})</span></pre></div>
</div>
</li>
<li><p>The polymorphic identity WHERE criteria is <strong>not</strong> included
for single- or
joined- table updates - this must be added <strong>manually</strong>, even
for single table inheritance.</p></li>
<li><p>The <a class="reference internal" href="events.html#sqlalchemy.orm.events.MapperEvents.before_update" title="sqlalchemy.orm.events.MapperEvents.before_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">MapperEvents.before_update()</span></code></a> and
<a class="reference internal" href="events.html#sqlalchemy.orm.events.MapperEvents.after_update" title="sqlalchemy.orm.events.MapperEvents.after_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">MapperEvents.after_update()</span></code></a>
events <strong>are not invoked from this method</strong>. Instead, the
<a class="reference internal" href="events.html#sqlalchemy.orm.events.SessionEvents.after_bulk_update" title="sqlalchemy.orm.events.SessionEvents.after_bulk_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SessionEvents.after_bulk_update()</span></code></a> method is provided to
act upon a mass UPDATE of entity rows.</p></li>
</ul>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.delete" title="sqlalchemy.orm.query.Query.delete"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.delete()</span></code></a></p>
<p><a class="reference internal" href="../core/tutorial.html#inserts-and-updates"><span class="std std-ref">Inserts, Updates and Deletes</span></a> - Core SQL tutorial</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.value">
<code class="descname">value</code><span class="sig-paren">(</span><em>column</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.value" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a scalar result corresponding to the given
column expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.values">
<code class="descname">values</code><span class="sig-paren">(</span><em>*columns</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.values" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an iterator yielding result tuples corresponding
to the given list of columns</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Query.whereclause">
<code class="descname">whereclause</code><a class="headerlink" href="#sqlalchemy.orm.query.Query.whereclause" title="Permalink to this definition">¶</a></dt>
<dd><p>A readonly attribute which returns the current WHERE criterion for
this Query.</p>
<p>This returned value is a SQL expression construct, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if no
criterion has been established.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_entities">
<code class="descname">with_entities</code><span class="sig-paren">(</span><em>*entities</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_entities" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> replacing the SELECT list with the
given entities.</p>
<p>e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Users, filtered on some arbitrary criterion</span>
<span class="c1"># and then ordered by related email address</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">address</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s1">'</span><span class="si">%e</span><span class="s1">d%'</span><span class="p">))</span><span class="o">.</span>\
<span class="n">order_by</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email</span><span class="p">)</span>
<span class="c1"># given *only* User.id==5, Address.email, and 'q', what</span>
<span class="c1"># would the *next* User in the result be ?</span>
<span class="n">subq</span> <span class="o">=</span> <span class="n">q</span><span class="o">.</span><span class="n">with_entities</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email</span><span class="p">)</span><span class="o">.</span>\
<span class="n">order_by</span><span class="p">(</span><span class="kc">None</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">User</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">subquery</span><span class="p">()</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">q</span><span class="o">.</span><span class="n">join</span><span class="p">((</span><span class="n">subq</span><span class="p">,</span> <span class="n">subq</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">email</span> <span class="o"><</span> <span class="n">Address</span><span class="o">.</span><span class="n">email</span><span class="p">))</span><span class="o">.</span>\
<span class="n">limit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_for_update">
<code class="descname">with_for_update</code><span class="sig-paren">(</span><em>read=False</em>, <em>nowait=False</em>, <em>of=None</em>, <em>skip_locked=False</em>, <em>key_share=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_for_update" title="Permalink to this definition">¶</a></dt>
<dd><p>return a new <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> with the specified options for the
<code class="docutils literal notranslate"><span class="pre">FOR</span> <span class="pre">UPDATE</span></code> clause.</p>
<p>The behavior of this method is identical to that of
<code class="xref py py-meth docutils literal notranslate"><span class="pre">SelectBase.with_for_update()</span></code>. When called with no arguments,
the resulting <code class="docutils literal notranslate"><span class="pre">SELECT</span></code> statement will have a <code class="docutils literal notranslate"><span class="pre">FOR</span> <span class="pre">UPDATE</span></code> clause
appended. When additional arguments are specified, backend-specific
options such as <code class="docutils literal notranslate"><span class="pre">FOR</span> <span class="pre">UPDATE</span> <span class="pre">NOWAIT</span></code> or <code class="docutils literal notranslate"><span class="pre">LOCK</span> <span class="pre">IN</span> <span class="pre">SHARE</span> <span class="pre">MODE</span></code>
can take effect.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">with_for_update</span><span class="p">(</span><span class="n">nowait</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">of</span><span class="o">=</span><span class="n">User</span><span class="p">)</span></pre></div>
</div>
<p>The above query on a PostgreSQL backend will render like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SELECT</span> <span class="n">users</span><span class="o">.</span><span class="n">id</span> <span class="n">AS</span> <span class="n">users_id</span> <span class="n">FROM</span> <span class="n">users</span> <span class="n">FOR</span> <span class="n">UPDATE</span> <span class="n">OF</span> <span class="n">users</span> <span class="n">NOWAIT</span></pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.0: </span><a class="reference internal" href="#sqlalchemy.orm.query.Query.with_for_update" title="sqlalchemy.orm.query.Query.with_for_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_for_update()</span></code></a> supersedes
the <a class="reference internal" href="#sqlalchemy.orm.query.Query.with_lockmode" title="sqlalchemy.orm.query.Query.with_lockmode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_lockmode()</span></code></a> method.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.GenerativeSelect.with_for_update" title="sqlalchemy.sql.expression.GenerativeSelect.with_for_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">GenerativeSelect.with_for_update()</span></code></a> - Core level method with
full argument and behavioral description.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_hint">
<code class="descname">with_hint</code><span class="sig-paren">(</span><em>selectable</em>, <em>text</em>, <em>dialect_name='*'</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_hint" title="Permalink to this definition">¶</a></dt>
<dd><p>Add an indexing or other executional context
hint for the given entity or selectable to
this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>.</p>
<p>Functionality is passed straight through to
<a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Select.with_hint" title="sqlalchemy.sql.expression.Select.with_hint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">with_hint()</span></code></a>,
with the addition that <code class="docutils literal notranslate"><span class="pre">selectable</span></code> can be a
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>, <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><code class="xref py py-class docutils literal notranslate"><span class="pre">Alias</span></code></a>, or ORM entity / mapped class
/etc.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.with_statement_hint" title="sqlalchemy.orm.query.Query.with_statement_hint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_statement_hint()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_labels">
<code class="descname">with_labels</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_labels" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply column labels to the return value of Query.statement.</p>
<p>Indicates that this Query’s <cite>statement</cite> accessor should return
a SELECT statement that applies labels to all columns in the
form <tablename>_<columnname>; this is commonly used to
disambiguate columns from multiple tables which have the same
name.</p>
<p>When the <cite>Query</cite> actually issues SQL to load rows, it always
uses column labeling.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.query.Query.with_labels" title="sqlalchemy.orm.query.Query.with_labels"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_labels()</span></code></a> method <em>only</em> applies
the output of <a class="reference internal" href="#sqlalchemy.orm.query.Query.statement" title="sqlalchemy.orm.query.Query.statement"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Query.statement</span></code></a>, and <em>not</em> to any of
the result-row invoking systems of <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> itself, e.g.
<a class="reference internal" href="#sqlalchemy.orm.query.Query.first" title="sqlalchemy.orm.query.Query.first"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.first()</span></code></a>, <a class="reference internal" href="#sqlalchemy.orm.query.Query.all" title="sqlalchemy.orm.query.Query.all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.all()</span></code></a>, etc. To execute
a query using <a class="reference internal" href="#sqlalchemy.orm.query.Query.with_labels" title="sqlalchemy.orm.query.Query.with_labels"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_labels()</span></code></a>, invoke the
<a class="reference internal" href="#sqlalchemy.orm.query.Query.statement" title="sqlalchemy.orm.query.Query.statement"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Query.statement</span></code></a> using <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.execute" title="sqlalchemy.orm.session.Session.execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.execute()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">result</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">query</span><span class="o">.</span><span class="n">with_labels</span><span class="p">()</span><span class="o">.</span><span class="n">statement</span><span class="p">)</span></pre></div>
</div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_lockmode">
<code class="descname">with_lockmode</code><span class="sig-paren">(</span><em>mode</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_lockmode" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object with the specified “locking mode”,
which essentially refers to the <code class="docutils literal notranslate"><span class="pre">FOR</span> <span class="pre">UPDATE</span></code> clause.</p>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 0.9: </span>The <a class="reference internal" href="#sqlalchemy.orm.query.Query.with_lockmode" title="sqlalchemy.orm.query.Query.with_lockmode"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_lockmode()</span></code></a> method is deprecated and will
be removed in a future release. Please refer to
<a class="reference internal" href="#sqlalchemy.orm.query.Query.with_for_update" title="sqlalchemy.orm.query.Query.with_for_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_for_update()</span></code></a>.</p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><span class="target" id="sqlalchemy.orm.query.Query.with_lockmode.params.mode"></span><strong>mode</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.with_lockmode.params.mode">¶</a> – <p>a string representing the desired locking mode.
Valid values are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">None</span></code> - translates to no lockmode</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">'update'</span></code> - translates to <code class="docutils literal notranslate"><span class="pre">FOR</span> <span class="pre">UPDATE</span></code>
(standard SQL, supported by most dialects)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">'update_nowait'</span></code> - translates to <code class="docutils literal notranslate"><span class="pre">FOR</span> <span class="pre">UPDATE</span> <span class="pre">NOWAIT</span></code>
(supported by Oracle, PostgreSQL 8.1 upwards)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">'read'</span></code> - translates to <code class="docutils literal notranslate"><span class="pre">LOCK</span> <span class="pre">IN</span> <span class="pre">SHARE</span> <span class="pre">MODE</span></code> (for MySQL),
and <code class="docutils literal notranslate"><span class="pre">FOR</span> <span class="pre">SHARE</span></code> (for PostgreSQL)</p></li>
</ul>
</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.with_for_update" title="sqlalchemy.orm.query.Query.with_for_update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_for_update()</span></code></a> - improved API for
specifying the <code class="docutils literal notranslate"><span class="pre">FOR</span> <span class="pre">UPDATE</span></code> clause.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_parent">
<code class="descname">with_parent</code><span class="sig-paren">(</span><em>instance</em>, <em>property=None</em>, <em>from_entity=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_parent" title="Permalink to this definition">¶</a></dt>
<dd><p>Add filtering criterion that relates the given instance
to a child object or collection, using its attribute state
as well as an established <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>
configuration.</p>
<p>The method uses the <a class="reference internal" href="#sqlalchemy.orm.with_parent" title="sqlalchemy.orm.with_parent"><code class="xref py py-func docutils literal notranslate"><span class="pre">with_parent()</span></code></a> function to generate
the clause, the result of which is passed to <a class="reference internal" href="#sqlalchemy.orm.query.Query.filter" title="sqlalchemy.orm.query.Query.filter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.filter()</span></code></a>.</p>
<p>Parameters are the same as <a class="reference internal" href="#sqlalchemy.orm.with_parent" title="sqlalchemy.orm.with_parent"><code class="xref py py-func docutils literal notranslate"><span class="pre">with_parent()</span></code></a>, with the exception
that the given property can be None, in which case a search is
performed against this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object’s target mapper.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.orm.query.Query.with_parent.params.instance"></span><strong>instance</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.with_parent.params.instance">¶</a> – An instance which has some <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.with_parent.params.property"></span><strong>property</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.with_parent.params.property">¶</a> – String property name, or class-bound attribute, which indicates
what relationship from the instance should be used to reconcile the
parent/child relationship.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Query.with_parent.params.from_entity"></span><strong>from_entity</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Query.with_parent.params.from_entity">¶</a> – Entity in which to consider as the left side. This defaults to the
“zero” entity of the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> itself.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_polymorphic">
<code class="descname">with_polymorphic</code><span class="sig-paren">(</span><em>cls_or_mappers</em>, <em>selectable=None</em>, <em>polymorphic_on=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_polymorphic" title="Permalink to this definition">¶</a></dt>
<dd><p>Load columns for inheriting classes.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.with_polymorphic" title="sqlalchemy.orm.query.Query.with_polymorphic"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_polymorphic()</span></code></a> applies transformations
to the “main” mapped class represented by this <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>.
The “main” mapped class here means the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>
object’s first argument is a full class, i.e.
<code class="docutils literal notranslate"><span class="pre">session.query(SomeClass)</span></code>. These transformations allow additional
tables to be present in the FROM clause so that columns for a
joined-inheritance subclass are available in the query, both for the
purposes of load-time efficiency as well as the ability to use
these columns at query time.</p>
<p>See the documentation section <a class="reference internal" href="inheritance_loading.html#with-polymorphic"><span class="std std-ref">Using with_polymorphic</span></a> for
details on how this method is used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_session">
<code class="descname">with_session</code><span class="sig-paren">(</span><em>session</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_session" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> that will use the given <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>.</p>
<p>While the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object is normally instantiated using the
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.query" title="sqlalchemy.orm.session.Session.query"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.query()</span></code></a> method, it is legal to build the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>
directly without necessarily using a <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>. Such a
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object, or any <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> already associated
with a different <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>, can produce a new <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>
object associated with a target session using this method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="k">import</span> <span class="n">Query</span>
<span class="n">query</span> <span class="o">=</span> <span class="n">Query</span><span class="p">([</span><span class="n">MyClass</span><span class="p">])</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">MyClass</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="n">result</span> <span class="o">=</span> <span class="n">query</span><span class="o">.</span><span class="n">with_session</span><span class="p">(</span><span class="n">my_session</span><span class="p">)</span><span class="o">.</span><span class="n">one</span><span class="p">()</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_statement_hint">
<code class="descname">with_statement_hint</code><span class="sig-paren">(</span><em>text</em>, <em>dialect_name='*'</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_statement_hint" title="Permalink to this definition">¶</a></dt>
<dd><p>add a statement hint to this <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Select" title="sqlalchemy.sql.expression.Select"><code class="xref py py-class docutils literal notranslate"><span class="pre">Select</span></code></a>.</p>
<p>This method is similar to <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Select.with_hint" title="sqlalchemy.sql.expression.Select.with_hint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Select.with_hint()</span></code></a> except that
it does not require an individual table, and instead applies to the
statement as a whole.</p>
<p>This feature calls down into <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Select.with_statement_hint" title="sqlalchemy.sql.expression.Select.with_statement_hint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Select.with_statement_hint()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.0.0.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.with_hint" title="sqlalchemy.orm.query.Query.with_hint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.with_hint()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_transformation">
<code class="descname">with_transformation</code><span class="sig-paren">(</span><em>fn</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_transformation" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object transformed by
the given function.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">filter_something</span><span class="p">(</span><span class="n">criterion</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">transform</span><span class="p">(</span><span class="n">q</span><span class="p">):</span>
<span class="k">return</span> <span class="n">q</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">criterion</span><span class="p">)</span>
<span class="k">return</span> <span class="n">transform</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">q</span><span class="o">.</span><span class="n">with_transformation</span><span class="p">(</span><span class="n">filter_something</span><span class="p">(</span><span class="n">x</span><span class="o">==</span><span class="mi">5</span><span class="p">))</span></pre></div>
</div>
<p>This allows ad-hoc recipes to be created for <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>
objects. See the example at <a class="reference internal" href="extensions/hybrid.html#hybrid-transformers"><span class="std std-ref">Building Transformers</span></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.yield_per">
<code class="descname">yield_per</code><span class="sig-paren">(</span><em>count</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Query.yield_per" title="Permalink to this definition">¶</a></dt>
<dd><p>Yield only <code class="docutils literal notranslate"><span class="pre">count</span></code> rows at a time.</p>
<p>The purpose of this method is when fetching very large result sets
(> 10K rows), to batch results in sub-collections and yield them
out partially, so that the Python interpreter doesn’t need to declare
very large areas of memory which is both time consuming and leads
to excessive memory use. The performance from fetching hundreds of
thousands of rows can often double when a suitable yield-per setting
(e.g. approximately 1000) is used, even with DBAPIs that buffer
rows (which are most).</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.query.Query.yield_per" title="sqlalchemy.orm.query.Query.yield_per"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.yield_per()</span></code></a> method <strong>is not compatible
subqueryload eager loading or joinedload eager loading when
using collections</strong>. It is potentially compatible with “select in”
eager loading, <strong>provided the database driver supports multiple,
independent cursors</strong> (pysqlite and psycopg2 are known to work,
MySQL and SQL Server ODBC drivers do not).</p>
<p>Therefore in some cases, it may be helpful to disable
eager loads, either unconditionally with
<a class="reference internal" href="#sqlalchemy.orm.query.Query.enable_eagerloads" title="sqlalchemy.orm.query.Query.enable_eagerloads"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.enable_eagerloads()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Object</span><span class="p">)</span><span class="o">.</span><span class="n">yield_per</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span><span class="o">.</span><span class="n">enable_eagerloads</span><span class="p">(</span><span class="kc">False</span><span class="p">)</span></pre></div>
</div>
<p>Or more selectively using <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.lazyload" title="sqlalchemy.orm.lazyload"><code class="xref py py-func docutils literal notranslate"><span class="pre">lazyload()</span></code></a>; such as with
an asterisk to specify the default loader scheme:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">q</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Object</span><span class="p">)</span><span class="o">.</span><span class="n">yield_per</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span><span class="o">.</span>\
<span class="n">options</span><span class="p">(</span><span class="n">lazyload</span><span class="p">(</span><span class="s1">'*'</span><span class="p">),</span> <span class="n">joinedload</span><span class="p">(</span><span class="n">Object</span><span class="o">.</span><span class="n">some_related</span><span class="p">))</span></pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Use this method with caution; if the same instance is
present in more than one batch of rows, end-user changes
to attributes will be overwritten.</p>
<p>In particular, it’s usually impossible to use this setting
with eagerly loaded collections (i.e. any lazy=’joined’ or
‘subquery’) since those collections will be cleared for a
new load when encountered in a subsequent result batch.
In the case of ‘subquery’ loading, the full result for all
rows is fetched which generally defeats the purpose of
<a class="reference internal" href="#sqlalchemy.orm.query.Query.yield_per" title="sqlalchemy.orm.query.Query.yield_per"><code class="xref py py-meth docutils literal notranslate"><span class="pre">yield_per()</span></code></a>.</p>
<p>Also note that while
<a class="reference internal" href="#sqlalchemy.orm.query.Query.yield_per" title="sqlalchemy.orm.query.Query.yield_per"><code class="xref py py-meth docutils literal notranslate"><span class="pre">yield_per()</span></code></a> will set the
<code class="docutils literal notranslate"><span class="pre">stream_results</span></code> execution option to True, currently
this is only understood by
<a class="reference internal" href="../dialects/postgresql.html#module-sqlalchemy.dialects.postgresql.psycopg2" title="sqlalchemy.dialects.postgresql.psycopg2"><code class="xref py py-mod docutils literal notranslate"><span class="pre">psycopg2</span></code></a>,
<a class="reference internal" href="../dialects/mysql.html#module-sqlalchemy.dialects.mysql.mysqldb" title="sqlalchemy.dialects.mysql.mysqldb"><code class="xref py py-mod docutils literal notranslate"><span class="pre">mysqldb</span></code></a> and
<a class="reference internal" href="../dialects/mysql.html#module-sqlalchemy.dialects.mysql.pymysql" title="sqlalchemy.dialects.mysql.pymysql"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pymysql</span></code></a> dialects
which will stream results using server side cursors
instead of pre-buffer all rows for this query. Other
DBAPIs <strong>pre-buffer all rows</strong> before making them
available. The memory use of raw database rows is much less
than that of an ORM-mapped object, but should still be taken into
consideration when benchmarking.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query.enable_eagerloads" title="sqlalchemy.orm.query.Query.enable_eagerloads"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.enable_eagerloads()</span></code></a></p>
</div>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="orm-specific-query-constructs">
<h2>ORM-Specific Query Constructs<a class="headerlink" href="#orm-specific-query-constructs" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="sqlalchemy.orm.aliased">
<code class="descclassname">sqlalchemy.orm.</code><code class="descname">aliased</code><span class="sig-paren">(</span><em>element</em>, <em>alias=None</em>, <em>name=None</em>, <em>flat=False</em>, <em>adapt_on_names=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.aliased" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an alias of the given element, usually an <a class="reference internal" href="#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedClass</span></code></a>
instance.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">my_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">MyClass</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">MyClass</span><span class="p">,</span> <span class="n">my_alias</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">MyClass</span><span class="o">.</span><span class="n">id</span> <span class="o">></span> <span class="n">my_alias</span><span class="o">.</span><span class="n">id</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> function is used to create an ad-hoc mapping
of a mapped class to a new selectable. By default, a selectable
is generated from the normally mapped selectable (typically a
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>) using the <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.FromClause.alias" title="sqlalchemy.sql.expression.FromClause.alias"><code class="xref py py-meth docutils literal notranslate"><span class="pre">FromClause.alias()</span></code></a> method.
However, <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> can also be used to link the class to
a new <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select()</span></code></a> statement. Also, the <a class="reference internal" href="inheritance_loading.html#sqlalchemy.orm.with_polymorphic" title="sqlalchemy.orm.with_polymorphic"><code class="xref py py-func docutils literal notranslate"><span class="pre">with_polymorphic()</span></code></a>
function is a variant of <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> that is intended to specify
a so-called “polymorphic selectable”, that corresponds to the union
of several joined-inheritance subclasses at once.</p>
<p>For convenience, the <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> function also accepts plain
<a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.FromClause" title="sqlalchemy.sql.expression.FromClause"><code class="xref py py-class docutils literal notranslate"><span class="pre">FromClause</span></code></a> constructs, such as a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> or
<a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select()</span></code></a> construct. In those cases, the <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.FromClause.alias" title="sqlalchemy.sql.expression.FromClause.alias"><code class="xref py py-meth docutils literal notranslate"><span class="pre">FromClause.alias()</span></code></a>
method is called on the object and the new <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><code class="xref py py-class docutils literal notranslate"><span class="pre">Alias</span></code></a> object
returned. The returned <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><code class="xref py py-class docutils literal notranslate"><span class="pre">Alias</span></code></a> is not ORM-mapped in this case.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.orm.aliased.params.element"></span><strong>element</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.aliased.params.element">¶</a> – element to be aliased. Is normally a mapped class,
but for convenience can also be a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.FromClause" title="sqlalchemy.sql.expression.FromClause"><code class="xref py py-class docutils literal notranslate"><span class="pre">FromClause</span></code></a> element.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.aliased.params.alias"></span><strong>alias</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.aliased.params.alias">¶</a> – Optional selectable unit to map the element to. This should
normally be a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><code class="xref py py-class docutils literal notranslate"><span class="pre">Alias</span></code></a> object corresponding to the <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>
to which the class is mapped, or to a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select()</span></code></a> construct that
is compatible with the mapping. By default, a simple anonymous
alias of the mapped table is generated.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.aliased.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.aliased.params.name">¶</a> – optional string name to use for the alias, if not specified
by the <code class="docutils literal notranslate"><span class="pre">alias</span></code> parameter. The name, among other things, forms the
attribute name that will be accessible via tuples returned by a
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.aliased.params.flat"></span><strong>flat</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.aliased.params.flat">¶</a> – <p>Boolean, will be passed through to the
<a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.FromClause.alias" title="sqlalchemy.sql.expression.FromClause.alias"><code class="xref py py-meth docutils literal notranslate"><span class="pre">FromClause.alias()</span></code></a> call so that aliases of <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Join" title="sqlalchemy.sql.expression.Join"><code class="xref py py-class docutils literal notranslate"><span class="pre">Join</span></code></a> objects
don’t include an enclosing SELECT. This can lead to more efficient
queries in many circumstances. A JOIN against a nested JOIN will be
rewritten as a JOIN against an aliased SELECT subquery on backends that
don’t support this syntax.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.0.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Join.alias" title="sqlalchemy.sql.expression.Join.alias"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Join.alias()</span></code></a></p>
</div>
</p></li>
<li><p><span class="target" id="sqlalchemy.orm.aliased.params.adapt_on_names"></span><strong>adapt_on_names</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.aliased.params.adapt_on_names">¶</a> – <p>if True, more liberal “matching” will be used when
mapping the mapped columns of the ORM entity to those of the
given selectable - a name-based match will be performed if the
given selectable doesn’t otherwise have a column that corresponds
to one on the entity. The use case for this is when associating
an entity with some derived selectable such as one that uses
aggregate functions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">UnitPrice</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'unit_price'</span>
<span class="o">...</span>
<span class="n">unit_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">)</span>
<span class="n">price</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Numeric</span><span class="p">)</span>
<span class="n">aggregated_unit_price</span> <span class="o">=</span> <span class="n">Session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span>
<span class="n">func</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">UnitPrice</span><span class="o">.</span><span class="n">price</span><span class="p">)</span><span class="o">.</span><span class="n">label</span><span class="p">(</span><span class="s1">'price'</span><span class="p">)</span>
<span class="p">)</span><span class="o">.</span><span class="n">group_by</span><span class="p">(</span><span class="n">UnitPrice</span><span class="o">.</span><span class="n">unit_id</span><span class="p">)</span><span class="o">.</span><span class="n">subquery</span><span class="p">()</span>
<span class="n">aggregated_unit_price</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">UnitPrice</span><span class="p">,</span>
<span class="n">alias</span><span class="o">=</span><span class="n">aggregated_unit_price</span><span class="p">,</span> <span class="n">adapt_on_names</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span></pre></div>
</div>
<p>Above, functions on <code class="docutils literal notranslate"><span class="pre">aggregated_unit_price</span></code> which refer to
<code class="docutils literal notranslate"><span class="pre">.price</span></code> will return the
<code class="docutils literal notranslate"><span class="pre">func.sum(UnitPrice.price).label('price')</span></code> column, as it is
matched on the name “price”. Ordinarily, the “price” function
wouldn’t have any “column correspondence” to the actual
<code class="docutils literal notranslate"><span class="pre">UnitPrice.price</span></code> column as it is not a proxy of the original.</p>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.orm.util.AliasedClass">
<em class="property">class </em><code class="descclassname">sqlalchemy.orm.util.</code><code class="descname">AliasedClass</code><span class="sig-paren">(</span><em>cls</em>, <em>alias=None</em>, <em>name=None</em>, <em>flat=False</em>, <em>adapt_on_names=False</em>, <em>with_polymorphic_mappers=()</em>, <em>with_polymorphic_discriminator=None</em>, <em>base_alias=None</em>, <em>use_mapper_path=False</em>, <em>represents_outer_join=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.util.AliasedClass" title="Permalink to this definition">¶</a></dt>
<dd><p>Represents an “aliased” form of a mapped class for usage with Query.</p>
<p>The ORM equivalent of a <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.alias" title="sqlalchemy.sql.expression.alias"><code class="xref py py-func docutils literal notranslate"><span class="pre">sqlalchemy.sql.expression.alias()</span></code></a>
construct, this object mimics the mapped class using a
__getattr__ scheme and maintains a reference to a
real <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><code class="xref py py-class docutils literal notranslate"><span class="pre">Alias</span></code></a> object.</p>
<p>Usage is via the <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.aliased()</span></code></a> function, or alternatively
via the <a class="reference internal" href="inheritance_loading.html#sqlalchemy.orm.with_polymorphic" title="sqlalchemy.orm.with_polymorphic"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.with_polymorphic()</span></code></a> function.</p>
<p>Usage example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># find all pairs of users with the same name</span>
<span class="n">user_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">User</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">user_alias</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">((</span><span class="n">user_alias</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">id</span> <span class="o">></span> <span class="n">user_alias</span><span class="o">.</span><span class="n">id</span><span class="p">))</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="o">==</span><span class="n">user_alias</span><span class="o">.</span><span class="n">name</span><span class="p">)</span></pre></div>
</div>
<p>The resulting object is an instance of <a class="reference internal" href="#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedClass</span></code></a>.
This object implements an attribute scheme which produces the
same attribute and method interface as the original mapped
class, allowing <a class="reference internal" href="#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedClass</span></code></a> to be compatible
with any attribute technique which works on the original class,
including hybrid attributes (see <a class="reference internal" href="extensions/hybrid.html"><span class="std std-ref">Hybrid Attributes</span></a>).</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedClass</span></code></a> can be inspected for its underlying
<a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mapper</span></code></a>, aliased selectable, and other information
using <a class="reference internal" href="../core/inspection.html#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><code class="xref py py-func docutils literal notranslate"><span class="pre">inspect()</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">inspect</span>
<span class="n">my_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">MyClass</span><span class="p">)</span>
<span class="n">insp</span> <span class="o">=</span> <span class="n">inspect</span><span class="p">(</span><span class="n">my_alias</span><span class="p">)</span></pre></div>
</div>
<p>The resulting inspection object is an instance of <a class="reference internal" href="#sqlalchemy.orm.util.AliasedInsp" title="sqlalchemy.orm.util.AliasedInsp"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedInsp</span></code></a>.</p>
<p>See <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><code class="xref py py-func docutils literal notranslate"><span class="pre">aliased()</span></code></a> and <a class="reference internal" href="inheritance_loading.html#sqlalchemy.orm.with_polymorphic" title="sqlalchemy.orm.with_polymorphic"><code class="xref py py-func docutils literal notranslate"><span class="pre">with_polymorphic()</span></code></a> for construction
argument descriptions.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.orm.util.AliasedInsp">
<em class="property">class </em><code class="descclassname">sqlalchemy.orm.util.</code><code class="descname">AliasedInsp</code><span class="sig-paren">(</span><em>entity</em>, <em>mapper</em>, <em>selectable</em>, <em>name</em>, <em>with_polymorphic_mappers</em>, <em>polymorphic_on</em>, <em>_base_alias</em>, <em>_use_mapper_path</em>, <em>adapt_on_names</em>, <em>represents_outer_join</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.util.AliasedInsp" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="internals.html#sqlalchemy.orm.base.InspectionAttr" title="sqlalchemy.orm.base.InspectionAttr"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.orm.base.InspectionAttr</span></code></a></p>
<p>Provide an inspection interface for an
<a class="reference internal" href="#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedClass</span></code></a> object.</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.util.AliasedInsp" title="sqlalchemy.orm.util.AliasedInsp"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedInsp</span></code></a> object is returned
given an <a class="reference internal" href="#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedClass</span></code></a> using the
<a class="reference internal" href="../core/inspection.html#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><code class="xref py py-func docutils literal notranslate"><span class="pre">inspect()</span></code></a> function:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">inspect</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="k">import</span> <span class="n">aliased</span>
<span class="n">my_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">MyMappedClass</span><span class="p">)</span>
<span class="n">insp</span> <span class="o">=</span> <span class="n">inspect</span><span class="p">(</span><span class="n">my_alias</span><span class="p">)</span></pre></div>
</div>
<p>Attributes on <a class="reference internal" href="#sqlalchemy.orm.util.AliasedInsp" title="sqlalchemy.orm.util.AliasedInsp"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedInsp</span></code></a>
include:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">entity</span></code> - the <a class="reference internal" href="#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedClass</span></code></a> represented.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mapper</span></code> - the <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mapper</span></code></a> mapping the underlying class.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">selectable</span></code> - the <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><code class="xref py py-class docutils literal notranslate"><span class="pre">Alias</span></code></a> construct which ultimately
represents an aliased <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a> or <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.Select" title="sqlalchemy.sql.expression.Select"><code class="xref py py-class docutils literal notranslate"><span class="pre">Select</span></code></a>
construct.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">name</span></code> - the name of the alias. Also is used as the attribute
name when returned in a result tuple from <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">with_polymorphic_mappers</span></code> - collection of <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mapper</span></code></a> objects
indicating all those mappers expressed in the select construct
for the <a class="reference internal" href="#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedClass</span></code></a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">polymorphic_on</span></code> - an alternate column or SQL expression which
will be used as the “discriminator” for a polymorphic load.</p></li>
</ul>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="../core/inspection.html"><span class="std std-ref">Runtime Inspection API</span></a></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.orm.query.Bundle">
<em class="property">class </em><code class="descclassname">sqlalchemy.orm.query.</code><code class="descname">Bundle</code><span class="sig-paren">(</span><em>name</em>, <em>*exprs</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Bundle" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="internals.html#sqlalchemy.orm.base.InspectionAttr" title="sqlalchemy.orm.base.InspectionAttr"><code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.orm.base.InspectionAttr</span></code></a></p>
<p>A grouping of SQL expressions that are returned by a <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>
under one namespace.</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.query.Bundle" title="sqlalchemy.orm.query.Bundle"><code class="xref py py-class docutils literal notranslate"><span class="pre">Bundle</span></code></a> essentially allows nesting of the tuple-based
results returned by a column-oriented <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object. It also
is extensible via simple subclassing, where the primary capability
to override is that of how the set of expressions should be returned,
allowing post-processing as well as custom return types, without
involving ORM identity-mapped classes.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.9.0.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="loading_columns.html#bundles"><span class="std std-ref">Column Bundles</span></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.orm.query.Bundle.__init__">
<code class="descname">__init__</code><span class="sig-paren">(</span><em>name</em>, <em>*exprs</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Bundle.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.orm.query.Bundle" title="sqlalchemy.orm.query.Bundle"><code class="xref py py-class docutils literal notranslate"><span class="pre">Bundle</span></code></a>.</p>
<p>e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bn</span> <span class="o">=</span> <span class="n">Bundle</span><span class="p">(</span><span class="s2">"mybundle"</span><span class="p">,</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">x</span><span class="p">,</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">y</span><span class="p">)</span>
<span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">bn</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span>
<span class="n">bn</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="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">bn</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">y</span> <span class="o">==</span> <span class="mi">4</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="o">.</span><span class="n">mybundle</span><span class="o">.</span><span class="n">x</span><span class="p">,</span> <span class="n">row</span><span class="o">.</span><span class="n">mybundle</span><span class="o">.</span><span class="n">y</span><span class="p">)</span></pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.orm.query.Bundle.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Bundle.params.name">¶</a> – name of the bundle.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Bundle.params.*exprs"></span><strong>*exprs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Bundle.params.*exprs">¶</a> – columns or SQL expressions comprising the bundle.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.query.Bundle.params.single_entity"></span><strong>single_entity=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.query.Bundle.params.single_entity">¶</a> – if True, rows for this <a class="reference internal" href="#sqlalchemy.orm.query.Bundle" title="sqlalchemy.orm.query.Bundle"><code class="xref py py-class docutils literal notranslate"><span class="pre">Bundle</span></code></a>
can be returned as a “single entity” outside of any enclosing tuple
in the same manner as a mapped entity.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Bundle.c">
<code class="descname">c</code><em class="property"> = None</em><a class="headerlink" href="#sqlalchemy.orm.query.Bundle.c" title="Permalink to this definition">¶</a></dt>
<dd><p>An alias for <a class="reference internal" href="#sqlalchemy.orm.query.Bundle.columns" title="sqlalchemy.orm.query.Bundle.columns"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Bundle.columns</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Bundle.columns">
<code class="descname">columns</code><em class="property"> = None</em><a class="headerlink" href="#sqlalchemy.orm.query.Bundle.columns" title="Permalink to this definition">¶</a></dt>
<dd><p>A namespace of SQL expressions referred to by this <a class="reference internal" href="#sqlalchemy.orm.query.Bundle" title="sqlalchemy.orm.query.Bundle"><code class="xref py py-class docutils literal notranslate"><span class="pre">Bundle</span></code></a>.</p>
<blockquote>
<div><p>e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bn</span> <span class="o">=</span> <span class="n">Bundle</span><span class="p">(</span><span class="s2">"mybundle"</span><span class="p">,</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">x</span><span class="p">,</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">y</span><span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">bn</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">bn</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></pre></div>
</div>
<p>Nesting of bundles is also supported:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">b1</span> <span class="o">=</span> <span class="n">Bundle</span><span class="p">(</span><span class="s2">"b1"</span><span class="p">,</span>
<span class="n">Bundle</span><span class="p">(</span><span class="s1">'b2'</span><span class="p">,</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">a</span><span class="p">,</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">b</span><span class="p">),</span>
<span class="n">Bundle</span><span class="p">(</span><span class="s1">'b3'</span><span class="p">,</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">x</span><span class="p">,</span> <span class="n">MyClass</span><span class="o">.</span><span class="n">y</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">b1</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span>
<span class="n">b1</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">b2</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">a</span> <span class="o">==</span> <span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">b1</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">b3</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">y</span> <span class="o">==</span> <span class="mi">9</span><span class="p">)</span></pre></div>
</div>
</div></blockquote>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Bundle.c" title="sqlalchemy.orm.query.Bundle.c"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Bundle.c</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Bundle.create_row_processor">
<code class="descname">create_row_processor</code><span class="sig-paren">(</span><em>query</em>, <em>procs</em>, <em>labels</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Bundle.create_row_processor" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce the “row processing” function for this <a class="reference internal" href="#sqlalchemy.orm.query.Bundle" title="sqlalchemy.orm.query.Bundle"><code class="xref py py-class docutils literal notranslate"><span class="pre">Bundle</span></code></a>.</p>
<p>May be overridden by subclasses.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="loading_columns.html#bundles"><span class="std std-ref">Column Bundles</span></a> - includes an example of subclassing.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Bundle.label">
<code class="descname">label</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.query.Bundle.label" title="Permalink to this definition">¶</a></dt>
<dd><p>Provide a copy of this <a class="reference internal" href="#sqlalchemy.orm.query.Bundle" title="sqlalchemy.orm.query.Bundle"><code class="xref py py-class docutils literal notranslate"><span class="pre">Bundle</span></code></a> passing a new label.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Bundle.single_entity">
<code class="descname">single_entity</code><em class="property"> = False</em><a class="headerlink" href="#sqlalchemy.orm.query.Bundle.single_entity" title="Permalink to this definition">¶</a></dt>
<dd><p>If True, queries for a single Bundle will be returned as a single
entity, rather than an element within a keyed tuple.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.util.KeyedTuple">
<em class="property">class </em><code class="descclassname">sqlalchemy.util.</code><code class="descname">KeyedTuple</code><a class="headerlink" href="#sqlalchemy.util.KeyedTuple" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.util._collections.AbstractKeyedTuple</span></code></p>
<p><code class="docutils literal notranslate"><span class="pre">tuple</span></code> subclass that adds labeled names.</p>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">k</span> <span class="o">=</span> <span class="n">KeyedTuple</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">labels</span><span class="o">=</span><span class="p">[</span><span class="s2">"one"</span><span class="p">,</span> <span class="s2">"two"</span><span class="p">,</span> <span class="s2">"three"</span><span class="p">])</span>
<span class="gp">>>> </span><span class="n">k</span><span class="o">.</span><span class="n">one</span>
<span class="go">1</span>
<span class="gp">>>> </span><span class="n">k</span><span class="o">.</span><span class="n">two</span>
<span class="go">2</span></pre></div>
</div>
<p>Result rows returned by <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> that contain multiple
ORM entities and/or column expressions make use of this
class to return rows.</p>
<p>The <a class="reference internal" href="#sqlalchemy.util.KeyedTuple" title="sqlalchemy.util.KeyedTuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">KeyedTuple</span></code></a> exhibits similar behavior to the
<code class="docutils literal notranslate"><span class="pre">collections.namedtuple()</span></code> construct provided in the Python
standard library, however is architected very differently.
Unlike <code class="docutils literal notranslate"><span class="pre">collections.namedtuple()</span></code>, <a class="reference internal" href="#sqlalchemy.util.KeyedTuple" title="sqlalchemy.util.KeyedTuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">KeyedTuple</span></code></a> is
does not rely on creation of custom subtypes in order to represent
a new series of keys, instead each <a class="reference internal" href="#sqlalchemy.util.KeyedTuple" title="sqlalchemy.util.KeyedTuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">KeyedTuple</span></code></a> instance
receives its list of keys in place. The subtype approach
of <code class="docutils literal notranslate"><span class="pre">collections.namedtuple()</span></code> introduces significant complexity
and performance overhead, which is not necessary for the
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> object’s use case.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="tutorial.html#ormtutorial-querying"><span class="std std-ref">Querying</span></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.util.KeyedTuple._asdict">
<code class="descname">_asdict</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.util.KeyedTuple._asdict" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the contents of this <a class="reference internal" href="#sqlalchemy.util.KeyedTuple" title="sqlalchemy.util.KeyedTuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">KeyedTuple</span></code></a> as a dictionary.</p>
<p>This method provides compatibility with <code class="docutils literal notranslate"><span class="pre">collections.namedtuple()</span></code>,
with the exception that the dictionary returned is <strong>not</strong> ordered.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.util.KeyedTuple._fields">
<code class="descname">_fields</code><a class="headerlink" href="#sqlalchemy.util.KeyedTuple._fields" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a tuple of string key names for this <a class="reference internal" href="#sqlalchemy.util.KeyedTuple" title="sqlalchemy.util.KeyedTuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">KeyedTuple</span></code></a>.</p>
<p>This method provides compatibility with <code class="docutils literal notranslate"><span class="pre">collections.namedtuple()</span></code>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.util.KeyedTuple.keys" title="sqlalchemy.util.KeyedTuple.keys"><code class="xref py py-meth docutils literal notranslate"><span class="pre">KeyedTuple.keys()</span></code></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.util.KeyedTuple.keys">
<code class="descname">keys</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.util.KeyedTuple.keys" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member docutils container">
<p><em>inherited from the</em> <code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code> <em>method of</em> <code class="xref py py-class docutils literal notranslate"><span class="pre">AbstractKeyedTuple</span></code></p>
</div>
<p>Return a list of string key names for this <a class="reference internal" href="#sqlalchemy.util.KeyedTuple" title="sqlalchemy.util.KeyedTuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">KeyedTuple</span></code></a>.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.util.KeyedTuple._fields" title="sqlalchemy.util.KeyedTuple._fields"><code class="xref py py-attr docutils literal notranslate"><span class="pre">KeyedTuple._fields</span></code></a></p>
</div>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.orm.strategy_options.Load">
<em class="property">class </em><code class="descclassname">sqlalchemy.orm.strategy_options.</code><code class="descname">Load</code><span class="sig-paren">(</span><em>entity</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.sql.expression.Generative</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">sqlalchemy.orm.interfaces.MapperOption</span></code></p>
<p>Represents loader options which modify the state of a
<a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> in order to affect how various mapped attributes are
loaded.</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object is in most cases used implicitly behind the
scenes when one makes use of a query option like <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.joinedload" title="sqlalchemy.orm.joinedload"><code class="xref py py-func docutils literal notranslate"><span class="pre">joinedload()</span></code></a>,
<a class="reference internal" href="loading_columns.html#sqlalchemy.orm.defer" title="sqlalchemy.orm.defer"><code class="xref py py-func docutils literal notranslate"><span class="pre">defer()</span></code></a>, or similar. However, the <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object
can also be used directly, and in some cases can be useful.</p>
<p>To use <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> directly, instantiate it with the target mapped
class as the argument. This style of usage is
useful when dealing with a <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> that has multiple entities:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">myopt</span> <span class="o">=</span> <span class="n">Load</span><span class="p">(</span><span class="n">MyClass</span><span class="p">)</span><span class="o">.</span><span class="n">joinedload</span><span class="p">(</span><span class="s2">"widgets"</span><span class="p">)</span></pre></div>
</div>
<p>The above <code class="docutils literal notranslate"><span class="pre">myopt</span></code> can now be used with <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.options()</span></code></a>, where it
will only take effect for the <code class="docutils literal notranslate"><span class="pre">MyClass</span></code> entity:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">MyClass</span><span class="p">,</span> <span class="n">MyOtherClass</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">myopt</span><span class="p">)</span></pre></div>
</div>
<p>One case where <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> is useful as public API is when specifying
“wildcard” options that only take effect for a certain class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Order</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">Load</span><span class="p">(</span><span class="n">Order</span><span class="p">)</span><span class="o">.</span><span class="n">lazyload</span><span class="p">(</span><span class="s1">'*'</span><span class="p">))</span></pre></div>
</div>
<p>Above, all relationships on <code class="docutils literal notranslate"><span class="pre">Order</span></code> will be lazy-loaded, but other
attributes on those descendant objects will load using their normal
loader strategy.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="loading_relationships.html"><span class="std std-ref">Relationship Loading Techniques</span></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.baked_lazyload">
<code class="descname">baked_lazyload</code><span class="sig-paren">(</span><em>attr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.baked_lazyload" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<code class="xref py py-func docutils literal notranslate"><span class="pre">orm.baked_lazyload()</span></code> option applied.</p>
<p>See <code class="xref py py-func docutils literal notranslate"><span class="pre">orm.baked_lazyload()</span></code> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.contains_eager">
<code class="descname">contains_eager</code><span class="sig-paren">(</span><em>attr</em>, <em>alias=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.contains_eager" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.contains_eager" title="sqlalchemy.orm.contains_eager"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.contains_eager()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.contains_eager" title="sqlalchemy.orm.contains_eager"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.contains_eager()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.defaultload">
<code class="descname">defaultload</code><span class="sig-paren">(</span><em>attr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.defaultload" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.defaultload" title="sqlalchemy.orm.defaultload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.defaultload()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.defaultload" title="sqlalchemy.orm.defaultload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.defaultload()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.defer">
<code class="descname">defer</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.defer" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_columns.html#sqlalchemy.orm.defer" title="sqlalchemy.orm.defer"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.defer()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_columns.html#sqlalchemy.orm.defer" title="sqlalchemy.orm.defer"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.defer()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.immediateload">
<code class="descname">immediateload</code><span class="sig-paren">(</span><em>attr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.immediateload" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.immediateload" title="sqlalchemy.orm.immediateload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.immediateload()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.immediateload" title="sqlalchemy.orm.immediateload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.immediateload()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.joinedload">
<code class="descname">joinedload</code><span class="sig-paren">(</span><em>attr</em>, <em>innerjoin=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.joinedload" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.joinedload" title="sqlalchemy.orm.joinedload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.joinedload()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.joinedload" title="sqlalchemy.orm.joinedload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.joinedload()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.lazyload">
<code class="descname">lazyload</code><span class="sig-paren">(</span><em>attr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.lazyload" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.lazyload" title="sqlalchemy.orm.lazyload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.lazyload()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.lazyload" title="sqlalchemy.orm.lazyload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.lazyload()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.load_only">
<code class="descname">load_only</code><span class="sig-paren">(</span><em>*attrs</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.load_only" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_columns.html#sqlalchemy.orm.load_only" title="sqlalchemy.orm.load_only"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.load_only()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_columns.html#sqlalchemy.orm.load_only" title="sqlalchemy.orm.load_only"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.load_only()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.noload">
<code class="descname">noload</code><span class="sig-paren">(</span><em>attr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.noload" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.noload" title="sqlalchemy.orm.noload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.noload()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.noload" title="sqlalchemy.orm.noload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.noload()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.process_query">
<code class="descname">process_query</code><span class="sig-paren">(</span><em>query</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.process_query" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply a modification to the given <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.process_query_conditionally">
<code class="descname">process_query_conditionally</code><span class="sig-paren">(</span><em>query</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.process_query_conditionally" title="Permalink to this definition">¶</a></dt>
<dd><p>same as process_query(), except that this option may not
apply to the given query.</p>
<p>This is typically used during a lazy load or scalar refresh
operation to propagate options stated in the original Query to the
new Query being used for the load. It occurs for those options that
specify propagate_to_loaders=True.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.raiseload">
<code class="descname">raiseload</code><span class="sig-paren">(</span><em>attr</em>, <em>sql_only=False</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.raiseload" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.raiseload" title="sqlalchemy.orm.raiseload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.raiseload()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.raiseload" title="sqlalchemy.orm.raiseload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.raiseload()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.selectin_polymorphic">
<code class="descname">selectin_polymorphic</code><span class="sig-paren">(</span><em>classes</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.selectin_polymorphic" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="inheritance_loading.html#sqlalchemy.orm.selectin_polymorphic" title="sqlalchemy.orm.selectin_polymorphic"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.selectin_polymorphic()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="inheritance_loading.html#sqlalchemy.orm.selectin_polymorphic" title="sqlalchemy.orm.selectin_polymorphic"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.selectin_polymorphic()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.selectinload">
<code class="descname">selectinload</code><span class="sig-paren">(</span><em>attr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.selectinload" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.selectinload" title="sqlalchemy.orm.selectinload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.selectinload()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.selectinload" title="sqlalchemy.orm.selectinload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.selectinload()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.subqueryload">
<code class="descname">subqueryload</code><span class="sig-paren">(</span><em>attr</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.subqueryload" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.subqueryload" title="sqlalchemy.orm.subqueryload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.subqueryload()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_relationships.html#sqlalchemy.orm.subqueryload" title="sqlalchemy.orm.subqueryload"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.subqueryload()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.undefer">
<code class="descname">undefer</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.undefer" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_columns.html#sqlalchemy.orm.undefer" title="sqlalchemy.orm.undefer"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.undefer()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_columns.html#sqlalchemy.orm.undefer" title="sqlalchemy.orm.undefer"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.undefer()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.undefer_group">
<code class="descname">undefer_group</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.undefer_group" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_columns.html#sqlalchemy.orm.undefer_group" title="sqlalchemy.orm.undefer_group"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.undefer_group()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_columns.html#sqlalchemy.orm.undefer_group" title="sqlalchemy.orm.undefer_group"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.undefer_group()</span></code></a> for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.strategy_options.Load.with_expression">
<code class="descname">with_expression</code><span class="sig-paren">(</span><em>key</em>, <em>expression</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.strategy_options.Load.with_expression" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a new <a class="reference internal" href="#sqlalchemy.orm.strategy_options.Load" title="sqlalchemy.orm.strategy_options.Load"><code class="xref py py-class docutils literal notranslate"><span class="pre">Load</span></code></a> object with the
<a class="reference internal" href="loading_columns.html#sqlalchemy.orm.with_expression" title="sqlalchemy.orm.with_expression"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.with_expression()</span></code></a> option applied.</p>
<p>See <a class="reference internal" href="loading_columns.html#sqlalchemy.orm.with_expression" title="sqlalchemy.orm.with_expression"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.with_expression()</span></code></a> for usage examples.</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.join">
<code class="descclassname">sqlalchemy.orm.</code><code class="descname">join</code><span class="sig-paren">(</span><em>left</em>, <em>right</em>, <em>onclause=None</em>, <em>isouter=False</em>, <em>full=False</em>, <em>join_to_left=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.join" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an inner join between left and right clauses.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.join" title="sqlalchemy.orm.join"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.join()</span></code></a> is an extension to the core join interface
provided by <a class="reference internal" href="../core/selectable.html#sqlalchemy.sql.expression.join" title="sqlalchemy.sql.expression.join"><code class="xref py py-func docutils literal notranslate"><span class="pre">sql.expression.join()</span></code></a>, where the
left and right selectables may be not only core selectable
objects such as <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><code class="xref py py-class docutils literal notranslate"><span class="pre">Table</span></code></a>, but also mapped classes or
<a class="reference internal" href="#sqlalchemy.orm.util.AliasedClass" title="sqlalchemy.orm.util.AliasedClass"><code class="xref py py-class docutils literal notranslate"><span class="pre">AliasedClass</span></code></a> instances. The “on” clause can
be a SQL expression, or an attribute or string name
referencing a configured <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.join" title="sqlalchemy.orm.join"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.join()</span></code></a> is not commonly needed in modern usage,
as its functionality is encapsulated within that of the
<a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.join()</span></code></a> method, which features a
significant amount of automation beyond <a class="reference internal" href="#sqlalchemy.orm.join" title="sqlalchemy.orm.join"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.join()</span></code></a>
by itself. Explicit usage of <a class="reference internal" href="#sqlalchemy.orm.join" title="sqlalchemy.orm.join"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.join()</span></code></a>
with <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> involves usage of the
<a class="reference internal" href="#sqlalchemy.orm.query.Query.select_from" title="sqlalchemy.orm.query.Query.select_from"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.select_from()</span></code></a> method, as in:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="k">import</span> <span class="n">join</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">select_from</span><span class="p">(</span><span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">Address</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">))</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email_address</span><span class="o">==</span><span class="s1">'foo@bar.com'</span><span class="p">)</span></pre></div>
</div>
<p>In modern SQLAlchemy the above join can be written more
succinctly as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">addresses</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">Address</span><span class="o">.</span><span class="n">email_address</span><span class="o">==</span><span class="s1">'foo@bar.com'</span><span class="p">)</span></pre></div>
</div>
<p>See <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Query.join()</span></code></a> for information on modern usage
of ORM level joins.</p>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 0.8: </span>the <code class="docutils literal notranslate"><span class="pre">join_to_left</span></code> parameter is deprecated, and will be removed
in a future release. The parameter has no effect.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.outerjoin">
<code class="descclassname">sqlalchemy.orm.</code><code class="descname">outerjoin</code><span class="sig-paren">(</span><em>left</em>, <em>right</em>, <em>onclause=None</em>, <em>full=False</em>, <em>join_to_left=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.outerjoin" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a left outer join between left and right clauses.</p>
<p>This is the “outer join” version of the <a class="reference internal" href="#sqlalchemy.orm.join" title="sqlalchemy.orm.join"><code class="xref py py-func docutils literal notranslate"><span class="pre">orm.join()</span></code></a> function,
featuring the same behavior except that an OUTER JOIN is generated.
See that function’s documentation for other usage details.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.with_parent">
<code class="descclassname">sqlalchemy.orm.</code><code class="descname">with_parent</code><span class="sig-paren">(</span><em>instance</em>, <em>prop</em>, <em>from_entity=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.with_parent" title="Permalink to this definition">¶</a></dt>
<dd><p>Create filtering criterion that relates this query’s primary entity
to the given related instance, using established <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>
configuration.</p>
<p>The SQL rendered is the same as that rendered when a lazy loader
would fire off from the given parent on that attribute, meaning
that the appropriate state is taken from the parent object in
Python without the need to render joins to the parent table
in the rendered statement.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><span class="target" id="sqlalchemy.orm.with_parent.params.instance"></span><strong>instance</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.with_parent.params.instance">¶</a> – An instance which has some <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.with_parent.params.property"></span><strong>property</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.with_parent.params.property">¶</a> – String property name, or class-bound attribute, which indicates
what relationship from the instance should be used to reconcile the
parent/child relationship.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.with_parent.params.from_entity"></span><strong>from_entity</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.with_parent.params.from_entity">¶</a> – <p>Entity in which to consider as the left side. This defaults to the
“zero” entity of the <a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a> itself.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.2.</span></p>
</div>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links, withsidebar">
Previous:
<a href="constructors.html" title="previous chapter">Constructors and Object Initialization</a>
Next:
<a href="session.html" title="next chapter">Using the Session</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2019, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
</div>
</div>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.2.19',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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>
<script type="text/javascript" src="../_static/language_data.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>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
b0b6ffab06cbeede296e36ce94734bf8
>
files
>
858
