<!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>
Loading Inheritance Hierarchies
—
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="Constructors and Object Initialization" href="constructors.html" />
<link rel="prev" title="Relationship Loading Techniques" href="loading_relationships.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 class="selected"><span class="link-container"><strong>Loading Inheritance Hierarchies</strong><a class="paramlink headerlink reference internal" href="#">¶</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#using-with-polymorphic">Using with_polymorphic</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#using-aliasing-with-with-polymorphic">Using aliasing with with_polymorphic</a></span></li>
<li><span class="link-container"><a class="reference external" href="#referring-to-specific-subclass-attributes">Referring to Specific Subclass Attributes</a></span></li>
<li><span class="link-container"><a class="reference external" href="#setting-with-polymorphic-at-mapper-configuration-time">Setting with_polymorphic at mapper configuration time</a></span></li>
<li><span class="link-container"><a class="reference external" href="#setting-with-polymorphic-against-a-query">Setting with_polymorphic against a query</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#polymorphic-selectin-loading">Polymorphic Selectin Loading</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#combining-selectin-and-with-polymorphic">Combining selectin and with_polymorphic</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#referring-to-specific-subtypes-on-relationships">Referring to specific subtypes on relationships</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#eager-loading-of-specific-or-polymorphic-subtypes">Eager Loading of Specific or Polymorphic Subtypes</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#loading-objects-with-joined-table-inheritance">Loading objects with joined table inheritance</a></span></li>
<li><span class="link-container"><a class="reference external" href="#loading-objects-with-single-table-inheritance">Loading objects with single table inheritance</a></span></li>
<li><span class="link-container"><a class="reference external" href="#inheritance-loading-api">Inheritance Loading API</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="constructors.html">Constructors and Object Initialization</a></span></li>
<li><span class="link-container"><a class="reference external" href="query.html">Query API</a></span></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" >
<div class="section" id="loading-inheritance-hierarchies">
<span id="inheritance-loading-toplevel"></span><h1>Loading Inheritance Hierarchies<a class="headerlink" href="#loading-inheritance-hierarchies" title="Permalink to this headline">¶</a></h1>
<p>When classes are mapped in inheritance hierarchies using the “joined”,
“single”, or “concrete” table inheritance styles as described at
<a class="reference internal" href="inheritance.html"><span class="std std-ref">Mapping Class Inheritance Hierarchies</span></a>, the usual behavior is that a query for a
particular base class will also yield objects corresponding to subclasses
as well. When a single query is capable of returning a result with
a different class or subclasses per result row, we use the term
“polymorphic loading”.</p>
<p>Within the realm of polymorphic loading, specifically with joined and single
table inheritance, there is an additional problem of which subclass attributes
are to be queried up front, and which are to be loaded later. When an attribute
of a particular subclass is queried up front, we can use it in our query as
something to filter on, and it also will be loaded when we get our objects
back. If it’s not queried up front, it gets loaded later when we first need
to access it. Basic control of this behavior is provided using the
<a class="reference internal" href="#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, as well as two variants, the mapper
configuration <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.with_polymorphic" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.with_polymorphic</span></code></a> in conjunction with
the <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.polymorphic_load" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.polymorphic_load</span></code></a> option, and the <a class="reference internal" href="query.html#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>
-level <a class="reference internal" href="query.html#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> method. The “with_polymorphic” family
each provide a means of specifying which specific subclasses of a particular
base class should be included within a query, which implies what columns and
tables will be available in the SELECT.</p>
<div class="section" id="using-with-polymorphic">
<span id="with-polymorphic"></span><h2>Using with_polymorphic<a class="headerlink" href="#using-with-polymorphic" title="Permalink to this headline">¶</a></h2>
<p>For the following sections, assume the <code class="docutils literal notranslate"><span class="pre">Employee</span></code> / <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> / <code class="docutils literal notranslate"><span class="pre">Manager</span></code>
examples introduced in <a class="reference internal" href="inheritance.html"><span class="std std-ref">Mapping Class Inheritance Hierarchies</span></a>.</p>
<p>Normally, when a <a class="reference internal" href="query.html#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> specifies the base class of an
inheritance hierarchy, only the columns that are local to that base
class are queried:</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">Employee</span><span class="p">)</span><span class="o">.</span><span class="n">all</span><span class="p">()</span></pre></div>
</div>
<p>Above, for both single and joined table inheritance, only the columns
local to <code class="docutils literal notranslate"><span class="pre">Employee</span></code> will be present in the SELECT. We may get back
instances of <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> or <code class="docutils literal notranslate"><span class="pre">Manager</span></code>, however they will not have the
additional attributes loaded until we first access them, at which point a
lazy load is emitted.</p>
<p>Similarly, if we wanted to refer to columns mapped
to <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> or <code class="docutils literal notranslate"><span class="pre">Manager</span></code> in our query that’s against <code class="docutils literal notranslate"><span class="pre">Employee</span></code>,
these columns aren’t available directly in either the single or joined table
inheritance case, since the <code class="docutils literal notranslate"><span class="pre">Employee</span></code> entity does not refer to these columns
(note that for single-table inheritance, this is common if Declarative is used,
but not for a classical mapping).</p>
<p>To solve both of these issues, the <a class="reference internal" href="#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
provides a special <a class="reference internal" href="query.html#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> that represents a range of
columns across subclasses. This object can be used in a <a class="reference internal" href="query.html#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>
like any other alias. When queried, it represents all the columns present in
the classes given:</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">with_polymorphic</span>
<span class="n">eng_plus_manager</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span><span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Engineer</span><span class="p">,</span> <span class="n">Manager</span><span class="p">])</span>
<span class="n">query</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">eng_plus_manager</span><span class="p">)</span></pre></div>
</div>
<p>If the above mapping were using joined table inheritance, the SELECT
statement for the above would be:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><span class="n">query</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<div class='show_sql'>
SELECT employee.id AS employee_id,
engineer.id AS engineer_id,
manager.id AS manager_id,
employee.name AS employee_name,
employee.type AS employee_type,
engineer.engineer_info AS engineer_engineer_info,
manager.manager_data AS manager_manager_data
FROM employee
LEFT OUTER JOIN engineer
ON employee.id = engineer.id
LEFT OUTER JOIN manager
ON employee.id = manager.id
[]</div></pre></div>
</div>
<p>Where above, the additional tables / columns for “engineer” and “manager” are
included. Similar behavior occurs in the case of single table inheritance.</p>
<p><a class="reference internal" href="#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> accepts a single class or
mapper, a list of classes/mappers, or the string <code class="docutils literal notranslate"><span class="pre">'*'</span></code> to indicate all
subclasses:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><span class="c1"># include columns for Engineer</span>
<span class="n">entity</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span><span class="n">Employee</span><span class="p">,</span> <span class="n">Engineer</span><span class="p">)</span>
<span class="c1"># include columns for Engineer, Manager</span>
<span class="n">entity</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span><span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Engineer</span><span class="p">,</span> <span class="n">Manager</span><span class="p">])</span>
<span class="c1"># include columns for all mapped subclasses</span>
<span class="n">entity</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span><span class="n">Employee</span><span class="p">,</span> <span class="s1">'*'</span><span class="p">)</span></pre></div>
</div>
<div class="section" id="using-aliasing-with-with-polymorphic">
<h3>Using aliasing with with_polymorphic<a class="headerlink" href="#using-aliasing-with-with-polymorphic" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="#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 also provides “aliasing” of the
polymorphic selectable itself, meaning, two different <a class="reference internal" href="#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>
entities, referring to the same class hierarchy, can be used together. This
is available using the <a class="reference internal" href="#sqlalchemy.orm.with_polymorphic.params.aliased" title="sqlalchemy.orm.with_polymorphic"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">orm.with_polymorphic.aliased</span></code></a> flag.
For a polymorphic selectable that is across multiple tables, the default behavior
is to wrap the selectable into a subquery. Below we emit a query that will
select for “employee or manager” paired with “employee or engineer” on employees
with the same name:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><span class="n">engineer_employee</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span>
<span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Engineer</span><span class="p">],</span> <span class="n">aliased</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">manager_employee</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span>
<span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Manager</span><span class="p">],</span> <span class="n">aliased</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">engineer_employee</span><span class="p">,</span> <span class="n">manager_employee</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span>
<span class="n">manager_employee</span><span class="p">,</span>
<span class="n">and_</span><span class="p">(</span>
<span class="n">engineer_employee</span><span class="o">.</span><span class="n">id</span> <span class="o">></span> <span class="n">manager_employee</span><span class="o">.</span><span class="n">id</span><span class="p">,</span>
<span class="n">engineer_employee</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="n">manager_employee</span><span class="o">.</span><span class="n">name</span>
<span class="p">)</span>
<span class="p">)</span>
<span class="n">q</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<div class='show_sql'>
SELECT
anon_1.employee_id AS anon_1_employee_id,
anon_1.employee_name AS anon_1_employee_name,
anon_1.employee_type AS anon_1_employee_type,
anon_1.engineer_id AS anon_1_engineer_id,
anon_1.engineer_engineer_name AS anon_1_engineer_engineer_name,
anon_2.employee_id AS anon_2_employee_id,
anon_2.employee_name AS anon_2_employee_name,
anon_2.employee_type AS anon_2_employee_type,
anon_2.manager_id AS anon_2_manager_id,
anon_2.manager_manager_name AS anon_2_manager_manager_name
FROM (
SELECT
employee.id AS employee_id,
employee.name AS employee_name,
employee.type AS employee_type,
engineer.id AS engineer_id,
engineer.engineer_name AS engineer_engineer_name
FROM employee
LEFT OUTER JOIN engineer ON employee.id = engineer.id
) AS anon_1
JOIN (
SELECT
employee.id AS employee_id,
employee.name AS employee_name,
employee.type AS employee_type,
manager.id AS manager_id,
manager.manager_name AS manager_manager_name
FROM employee
LEFT OUTER JOIN manager ON employee.id = manager.id
) AS anon_2
ON anon_1.employee_id > anon_2.employee_id
AND anon_1.employee_name = anon_2.employee_name</div></pre></div>
</div>
<p>The creation of subqueries above is very verbose. While it creates the best
encapsulation of the two distinct queries, it may be inefficient.
<a class="reference internal" href="#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> includes an additional flag to help with this
situation, <a class="reference internal" href="#sqlalchemy.orm.with_polymorphic.params.flat" title="sqlalchemy.orm.with_polymorphic"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">orm.with_polymorphic.flat</span></code></a>, which will “flatten” the
subquery / join combination into straight joins, applying aliasing to the
individual tables instead. Setting <a class="reference internal" href="#sqlalchemy.orm.with_polymorphic.params.flat" title="sqlalchemy.orm.with_polymorphic"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">orm.with_polymorphic.flat</span></code></a>
implies <a class="reference internal" href="#sqlalchemy.orm.with_polymorphic.params.aliased" title="sqlalchemy.orm.with_polymorphic"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">orm.with_polymorphic.aliased</span></code></a>, so only one flag
is necessary:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><span class="n">engineer_employee</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span>
<span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Engineer</span><span class="p">],</span> <span class="n">flat</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">manager_employee</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span>
<span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Manager</span><span class="p">],</span> <span class="n">flat</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">engineer_employee</span><span class="p">,</span> <span class="n">manager_employee</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span>
<span class="n">manager_employee</span><span class="p">,</span>
<span class="n">and_</span><span class="p">(</span>
<span class="n">engineer_employee</span><span class="o">.</span><span class="n">id</span> <span class="o">></span> <span class="n">manager_employee</span><span class="o">.</span><span class="n">id</span><span class="p">,</span>
<span class="n">engineer_employee</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="n">manager_employee</span><span class="o">.</span><span class="n">name</span>
<span class="p">)</span>
<span class="p">)</span>
<span class="n">q</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<div class='show_sql'>
SELECT
employee_1.id AS employee_1_id,
employee_1.name AS employee_1_name,
employee_1.type AS employee_1_type,
engineer_1.id AS engineer_1_id,
engineer_1.engineer_name AS engineer_1_engineer_name,
employee_2.id AS employee_2_id,
employee_2.name AS employee_2_name,
employee_2.type AS employee_2_type,
manager_1.id AS manager_1_id,
manager_1.manager_name AS manager_1_manager_name
FROM employee AS employee_1
LEFT OUTER JOIN engineer AS engineer_1
ON employee_1.id = engineer_1.id
JOIN (
employee AS employee_2
LEFT OUTER JOIN manager AS manager_1
ON employee_2.id = manager_1.id
)
ON employee_1.id > employee_2.id
AND employee_1.name = employee_2.name</div></pre></div>
</div>
<p>Note above, when using <a class="reference internal" href="#sqlalchemy.orm.with_polymorphic.params.flat" title="sqlalchemy.orm.with_polymorphic"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">orm.with_polymorphic.flat</span></code></a>, it is often the
case when used in conjunction with joined table inheritance that we get a
right-nested JOIN in our statement. Some older databases, in particular older
versions of SQLite, may have a problem with this syntax, although virtually all
modern database versions now support this syntax.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <a class="reference internal" href="#sqlalchemy.orm.with_polymorphic.params.flat" title="sqlalchemy.orm.with_polymorphic"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">orm.with_polymorphic.flat</span></code></a> flag only applies to the use
of <code class="xref py py-paramref docutils literal notranslate"><span class="pre">with_polymorphic</span></code> with <strong>joined table inheritance</strong> and when
the <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.with_polymorphic.params.selectable" title="sqlalchemy.orm.query.Query.with_polymorphic"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">with_polymorphic.selectable</span></code></a> argument is <strong>not</strong> used.</p>
</div>
</div>
<div class="section" id="referring-to-specific-subclass-attributes">
<h3>Referring to Specific Subclass Attributes<a class="headerlink" href="#referring-to-specific-subclass-attributes" title="Permalink to this headline">¶</a></h3>
<p>The entity returned by <a class="reference internal" href="#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> is an <a class="reference internal" href="query.html#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, which can be used in a <a class="reference internal" href="query.html#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> like any other alias, including
named attributes for those attributes on the <code class="docutils literal notranslate"><span class="pre">Employee</span></code> class. In our
previous example, <code class="docutils literal notranslate"><span class="pre">eng_plus_manager</span></code> becomes the entity that we use to refer to the
three-way outer join above. It also includes namespaces for each class named
in the list of classes, so that attributes specific to those subclasses can be
called upon as well. The following example illustrates calling upon attributes
specific to <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> as well as <code class="docutils literal notranslate"><span class="pre">Manager</span></code> in terms of <code class="docutils literal notranslate"><span class="pre">eng_plus_manager</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">eng_plus_manager</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span><span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Engineer</span><span class="p">,</span> <span class="n">Manager</span><span class="p">])</span>
<span class="n">query</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">eng_plus_manager</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span>
<span class="n">or_</span><span class="p">(</span>
<span class="n">eng_plus_manager</span><span class="o">.</span><span class="n">Engineer</span><span class="o">.</span><span class="n">engineer_info</span><span class="o">==</span><span class="s1">'x'</span><span class="p">,</span>
<span class="n">eng_plus_manager</span><span class="o">.</span><span class="n">Manager</span><span class="o">.</span><span class="n">manager_data</span><span class="o">==</span><span class="s1">'y'</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="setting-with-polymorphic-at-mapper-configuration-time">
<span id="with-polymorphic-mapper-config"></span><h3>Setting with_polymorphic at mapper configuration time<a class="headerlink" href="#setting-with-polymorphic-at-mapper-configuration-time" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="#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 serves the purpose of allowing
“eager” loading of attributes from subclass tables, as well as the ability
to refer to the attributes from subclass tables at query time. Historically,
the “eager loading” of columns has been the more important part of the
equation. So just as eager loading for relationships can be specified
as a configurational option, the <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.with_polymorphic" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.with_polymorphic</span></code></a>
configuration parameter allows an entity to use a polymorphic load by
default. We can add the parameter to our <code class="docutils literal notranslate"><span class="pre">Employee</span></code> mapping
first introduced at <a class="reference internal" href="inheritance.html#joined-inheritance"><span class="std std-ref">Joined Table Inheritance</span></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Employee</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">'employee'</span>
<span class="nb">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">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">name</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="mi">50</span><span class="p">))</span>
<span class="nb">type</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="mi">50</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'polymorphic_identity'</span><span class="p">:</span><span class="s1">'employee'</span><span class="p">,</span>
<span class="s1">'polymorphic_on'</span><span class="p">:</span><span class="nb">type</span><span class="p">,</span>
<span class="s1">'with_polymorphic'</span><span class="p">:</span> <span class="s1">'*'</span>
<span class="p">}</span></pre></div>
</div>
<p>Above is a common setting for <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.with_polymorphic" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.with_polymorphic</span></code></a>,
which is to indicate an asterisk to load all subclass columns. In the
case of joined table inheritance, this option
should be used sparingly, as it implies that the mapping will always emit
a (often large) series of LEFT OUTER JOIN to many tables, which is not
efficient from a SQL perspective. For single table inheritance, specifying the
asterisk is often a good idea as the load is still against a single table only,
but an additional lazy load of subclass-mapped columns will be prevented.</p>
<p>Using <a class="reference internal" href="#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> or <a class="reference internal" href="query.html#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>
will override the mapper-level <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.with_polymorphic" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.with_polymorphic</span></code></a> setting.</p>
<p>The <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.with_polymorphic" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.with_polymorphic</span></code></a> option also accepts a list of
classes just like <a class="reference internal" href="#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> to polymorphically load among
a subset of classes. However, when using Declarative, providing classes
to this list is not directly possible as the subclasses we’d like to add
are not available yet. Instead, we can specify on each subclass
that they should individually participate in polymorphic loading by
default using the <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.polymorphic_load" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.polymorphic_load</span></code></a> parameter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Engineer</span><span class="p">(</span><span class="n">Employee</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'engineer'</span>
<span class="nb">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">ForeignKey</span><span class="p">(</span><span class="s1">'employee.id'</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">engineer_info</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="mi">50</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'polymorphic_identity'</span><span class="p">:</span><span class="s1">'engineer'</span><span class="p">,</span>
<span class="s1">'polymorphic_load'</span><span class="p">:</span> <span class="s1">'inline'</span>
<span class="p">}</span>
<span class="k">class</span> <span class="nc">Manager</span><span class="p">(</span><span class="n">Employee</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'manager'</span>
<span class="nb">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">ForeignKey</span><span class="p">(</span><span class="s1">'employee.id'</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">manager_data</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="mi">50</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'polymorphic_identity'</span><span class="p">:</span><span class="s1">'manager'</span><span class="p">,</span>
<span class="s1">'polymorphic_load'</span><span class="p">:</span> <span class="s1">'inline'</span>
<span class="p">}</span></pre></div>
</div>
<p>Setting the <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.polymorphic_load" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.polymorphic_load</span></code></a> parameter to the value
<code class="docutils literal notranslate"><span class="pre">"inline"</span></code> means that the <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> and <code class="docutils literal notranslate"><span class="pre">Manager</span></code> classes above
are part of the “polymorphic load” of the base <code class="docutils literal notranslate"><span class="pre">Employee</span></code> class by default,
exactly as though they had been appended to the
<a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.with_polymorphic" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.with_polymorphic</span></code></a> list of classes.</p>
</div>
<div class="section" id="setting-with-polymorphic-against-a-query">
<h3>Setting with_polymorphic against a query<a class="headerlink" href="#setting-with-polymorphic-against-a-query" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="#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 evolved from a query-level
method <a class="reference internal" href="query.html#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>. This method has the same purpose
as <a class="reference internal" href="#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>, except is not as
flexible in its usage patterns in that it only applies to the first entity
of the <a class="reference internal" href="query.html#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 then takes effect for all occurrences of
that entity, so that the entity (and its subclasses) can be referred to
directly, rather than using an alias object. For simple cases it might be
considered to be more succinct:</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">Employee</span><span class="p">)</span><span class="o">.</span>\
<span class="n">with_polymorphic</span><span class="p">([</span><span class="n">Engineer</span><span class="p">,</span> <span class="n">Manager</span><span class="p">])</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span>
<span class="n">or_</span><span class="p">(</span>
<span class="n">Engineer</span><span class="o">.</span><span class="n">engineer_info</span><span class="o">==</span><span class="s1">'w'</span><span class="p">,</span>
<span class="n">Manager</span><span class="o">.</span><span class="n">manager_data</span><span class="o">==</span><span class="s1">'q'</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="query.html#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> method has a more complicated job
than the <a class="reference internal" href="#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, as it needs to correctly
transform entities like <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> and <code class="docutils literal notranslate"><span class="pre">Manager</span></code> appropriately, but
not interfere with other entities. If its flexibility is lacking, switch
to using <a class="reference internal" href="#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>.</p>
</div>
</div>
<div class="section" id="polymorphic-selectin-loading">
<span id="polymorphic-selectin"></span><h2>Polymorphic Selectin Loading<a class="headerlink" href="#polymorphic-selectin-loading" title="Permalink to this headline">¶</a></h2>
<p>An alternative to using the <a class="reference internal" href="#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> family of
functions to “eagerly” load the additional subclasses on an inheritance
mapping, primarily when using joined table inheritance, is to use polymorphic
“selectin” loading. This is an eager loading
feature which works similarly to the <a class="reference internal" href="loading_relationships.html#selectin-eager-loading"><span class="std std-ref">Select IN loading</span></a> feature
of relationship loading. Given our example mapping, we can instruct
a load of <code class="docutils literal notranslate"><span class="pre">Employee</span></code> to emit an extra SELECT per subclass by using
the <a class="reference internal" href="#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> loader option:</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">selectin_polymorphic</span>
<span class="n">query</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">Employee</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span>
<span class="n">selectin_polymorphic</span><span class="p">(</span><span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Manager</span><span class="p">,</span> <span class="n">Engineer</span><span class="p">])</span>
<span class="p">)</span></pre></div>
</div>
<p>When the above query is run, two additional SELECT statements will
be emitted:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><div class='show_sql'>query.all()
SELECT
employee.id AS employee_id,
employee.name AS employee_name,
employee.type AS employee_type
FROM employee
()
SELECT
engineer.id AS engineer_id,
employee.id AS employee_id,
employee.type AS employee_type,
engineer.engineer_name AS engineer_engineer_name
FROM employee JOIN engineer ON employee.id = engineer.id
WHERE employee.id IN (?, ?) ORDER BY employee.id
(1, 2)
SELECT
manager.id AS manager_id,
employee.id AS employee_id,
employee.type AS employee_type,
manager.manager_name AS manager_manager_name
FROM employee JOIN manager ON employee.id = manager.id
WHERE employee.id IN (?) ORDER BY employee.id
(3,)</div></pre></div>
</div>
<p>We can similarly establish the above style of loading to take place
by default by specifying the <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.polymorphic_load" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.polymorphic_load</span></code></a> parameter,
using the value <code class="docutils literal notranslate"><span class="pre">"selectin"</span></code> on a per-subclass basis:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Employee</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">'employee'</span>
<span class="nb">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">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">name</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="mi">50</span><span class="p">))</span>
<span class="nb">type</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="mi">50</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'polymorphic_identity'</span><span class="p">:</span> <span class="s1">'employee'</span><span class="p">,</span>
<span class="s1">'polymorphic_on'</span><span class="p">:</span> <span class="nb">type</span>
<span class="p">}</span>
<span class="k">class</span> <span class="nc">Engineer</span><span class="p">(</span><span class="n">Employee</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'engineer'</span>
<span class="nb">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">ForeignKey</span><span class="p">(</span><span class="s1">'employee.id'</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">engineer_name</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="mi">30</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'polymorphic_load'</span><span class="p">:</span> <span class="s1">'selectin'</span><span class="p">,</span>
<span class="s1">'polymorphic_identity'</span><span class="p">:</span> <span class="s1">'engineer'</span><span class="p">,</span>
<span class="p">}</span>
<span class="k">class</span> <span class="nc">Manager</span><span class="p">(</span><span class="n">Employee</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'manager'</span>
<span class="nb">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">ForeignKey</span><span class="p">(</span><span class="s1">'employee.id'</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">manager_name</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="mi">30</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'polymorphic_load'</span><span class="p">:</span> <span class="s1">'selectin'</span><span class="p">,</span>
<span class="s1">'polymorphic_identity'</span><span class="p">:</span> <span class="s1">'manager'</span><span class="p">,</span>
<span class="p">}</span></pre></div>
</div>
<p>Unlike when using <a class="reference internal" href="#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>, when using the
<a class="reference internal" href="#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> style of loading, we do <strong>not</strong> have the
ability to refer to the <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> or <code class="docutils literal notranslate"><span class="pre">Manager</span></code> entities within our main
query as filter, order by, or other criteria, as these entities are not present
in the initial query that is used to locate results. However, we can apply
loader options that apply towards <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> or <code class="docutils literal notranslate"><span class="pre">Manager</span></code>, which will take
effect when the secondary SELECT is emitted. Below we assume <code class="docutils literal notranslate"><span class="pre">Manager</span></code> has
an additional relationship <code class="docutils literal notranslate"><span class="pre">Manager.paperwork</span></code>, that we’d like to eagerly
load as well. We can use any type of eager loading, such as joined eager
loading via 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">joinedload()</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.orm</span> <span class="k">import</span> <span class="n">joinedload</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="k">import</span> <span class="n">selectin_polymorphic</span>
<span class="n">query</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">Employee</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span>
<span class="n">selectin_polymorphic</span><span class="p">(</span><span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Manager</span><span class="p">,</span> <span class="n">Engineer</span><span class="p">]),</span>
<span class="n">joinedload</span><span class="p">(</span><span class="n">Manager</span><span class="o">.</span><span class="n">paperwork</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Using the query above, we get three SELECT statements emitted, however
the one against <code class="docutils literal notranslate"><span class="pre">Manager</span></code> will be:</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">SELECT</span>
<span class="n">manager</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">manager_id</span><span class="p">,</span>
<span class="n">employee</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">employee_id</span><span class="p">,</span>
<span class="n">employee</span><span class="p">.</span><span class="k">type</span> <span class="k">AS</span> <span class="n">employee_type</span><span class="p">,</span>
<span class="n">manager</span><span class="p">.</span><span class="n">manager_name</span> <span class="k">AS</span> <span class="n">manager_manager_name</span><span class="p">,</span>
<span class="n">paperwork_1</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">paperwork_1_id</span><span class="p">,</span>
<span class="n">paperwork_1</span><span class="p">.</span><span class="n">manager_id</span> <span class="k">AS</span> <span class="n">paperwork_1_manager_id</span><span class="p">,</span>
<span class="n">paperwork_1</span><span class="p">.</span><span class="k">data</span> <span class="k">AS</span> <span class="n">paperwork_1_data</span>
<span class="k">FROM</span> <span class="n">employee</span> <span class="k">JOIN</span> <span class="n">manager</span> <span class="k">ON</span> <span class="n">employee</span><span class="p">.</span><span class="n">id</span> <span class="o">=</span> <span class="n">manager</span><span class="p">.</span><span class="n">id</span>
<span class="k">LEFT</span> <span class="k">OUTER</span> <span class="k">JOIN</span> <span class="n">paperwork</span> <span class="k">AS</span> <span class="n">paperwork_1</span>
<span class="k">ON</span> <span class="n">manager</span><span class="p">.</span><span class="n">id</span> <span class="o">=</span> <span class="n">paperwork_1</span><span class="p">.</span><span class="n">manager_id</span>
<span class="k">WHERE</span> <span class="n">employee</span><span class="p">.</span><span class="n">id</span> <span class="k">IN</span> <span class="p">(</span><span class="o">?</span><span class="p">)</span> <span class="k">ORDER</span> <span class="k">BY</span> <span class="n">employee</span><span class="p">.</span><span class="n">id</span>
<span class="p">(</span><span class="mi">3</span><span class="p">,)</span></pre></div>
</div>
<p>Note that selectin polymorphic loading has similar caveats as that of
selectin relationship loading; for entities that make use of a composite
primary key, the database in use must support tuples with “IN”, currently
known to work with MySQL and PostgreSQL.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.2.</span></p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The selectin polymorphic loading feature should be considered
as <strong>experimental</strong> within early releases of the 1.2 series.</p>
</div>
<div class="section" id="combining-selectin-and-with-polymorphic">
<span id="polymorphic-selectin-and-withpoly"></span><h3>Combining selectin and with_polymorphic<a class="headerlink" href="#combining-selectin-and-with-polymorphic" title="Permalink to this headline">¶</a></h3>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>works as of 1.2.0b3</p>
</div>
<p>With careful planning, selectin loading can be applied against a hierarchy
that itself uses “with_polymorphic”. A particular use case is that of
using selectin loading to load a joined-inheritance subtable, which then
uses “with_polymorphic” to refer to further sub-classes, which may be
joined- or single-table inheritance. If we added a class <code class="docutils literal notranslate"><span class="pre">VicePresident</span></code> that
extends <code class="docutils literal notranslate"><span class="pre">Manager</span></code> using single-table inheritance, we could ensure that
a load of <code class="docutils literal notranslate"><span class="pre">Manager</span></code> also fully loads <code class="docutils literal notranslate"><span class="pre">VicePresident</span></code> subtypes at the same time:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># use "Employee" example from the enclosing section</span>
<span class="k">class</span> <span class="nc">Manager</span><span class="p">(</span><span class="n">Employee</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'manager'</span>
<span class="nb">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">ForeignKey</span><span class="p">(</span><span class="s1">'employee.id'</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">manager_name</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="mi">30</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'polymorphic_load'</span><span class="p">:</span> <span class="s1">'selectin'</span><span class="p">,</span>
<span class="s1">'polymorphic_identity'</span><span class="p">:</span> <span class="s1">'manager'</span><span class="p">,</span>
<span class="p">}</span>
<span class="k">class</span> <span class="nc">VicePresident</span><span class="p">(</span><span class="n">Manager</span><span class="p">):</span>
<span class="n">vp_info</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="mi">30</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span>
<span class="s2">"polymorphic_load"</span><span class="p">:</span> <span class="s2">"inline"</span><span class="p">,</span>
<span class="s2">"polymorphic_identity"</span><span class="p">:</span> <span class="s2">"vp"</span>
<span class="p">}</span></pre></div>
</div>
<p>Above, we add a <code class="docutils literal notranslate"><span class="pre">vp_info</span></code> column to the <code class="docutils literal notranslate"><span class="pre">manager</span></code> table, local to the
<code class="docutils literal notranslate"><span class="pre">VicePresident</span></code> subclass. This subclass is linked to the polymorphic
identity <code class="docutils literal notranslate"><span class="pre">"vp"</span></code> which refers to rows which have this data. By setting the
load style to “inline”, it means that a load of <code class="docutils literal notranslate"><span class="pre">Manager</span></code> objects will also
ensure that the <code class="docutils literal notranslate"><span class="pre">vp_info</span></code> column is queried for in the same SELECT statement.
A query against <code class="docutils literal notranslate"><span class="pre">Employee</span></code> that encounters a <code class="docutils literal notranslate"><span class="pre">Manager</span></code> row would emit
similarly to the following:</p>
<div class="highlight-sql notranslate"><div class="highlight"><pre><span></span><span class="k">SELECT</span> <span class="n">employee</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">employee_id</span><span class="p">,</span> <span class="n">employee</span><span class="p">.</span><span class="n">name</span> <span class="k">AS</span> <span class="n">employee_name</span><span class="p">,</span>
<span class="n">employee</span><span class="p">.</span><span class="k">type</span> <span class="k">AS</span> <span class="n">employee_type</span>
<span class="k">FROM</span> <span class="n">employee</span>
<span class="p">)</span>
<span class="k">SELECT</span> <span class="n">manager</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">manager_id</span><span class="p">,</span> <span class="n">employee</span><span class="p">.</span><span class="n">id</span> <span class="k">AS</span> <span class="n">employee_id</span><span class="p">,</span>
<span class="n">employee</span><span class="p">.</span><span class="k">type</span> <span class="k">AS</span> <span class="n">employee_type</span><span class="p">,</span>
<span class="n">manager</span><span class="p">.</span><span class="n">manager_name</span> <span class="k">AS</span> <span class="n">manager_manager_name</span><span class="p">,</span>
<span class="n">manager</span><span class="p">.</span><span class="n">vp_info</span> <span class="k">AS</span> <span class="n">manager_vp_info</span>
<span class="k">FROM</span> <span class="n">employee</span> <span class="k">JOIN</span> <span class="n">manager</span> <span class="k">ON</span> <span class="n">employee</span><span class="p">.</span><span class="n">id</span> <span class="o">=</span> <span class="n">manager</span><span class="p">.</span><span class="n">id</span>
<span class="k">WHERE</span> <span class="n">employee</span><span class="p">.</span><span class="n">id</span> <span class="k">IN</span> <span class="p">(</span><span class="o">?</span><span class="p">)</span> <span class="k">ORDER</span> <span class="k">BY</span> <span class="n">employee</span><span class="p">.</span><span class="n">id</span>
<span class="p">(</span><span class="mi">1</span><span class="p">,)</span></pre></div>
</div>
<p>Combining “selectin” polymorhic loading with query-time
<a class="reference internal" href="#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> usage is also possible (though this is very
outer-space stuff!); assuming the above mappings had no <code class="docutils literal notranslate"><span class="pre">polymorphic_load</span></code>
set up, we could get the same result as follows:</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">with_polymorphic</span><span class="p">,</span> <span class="n">selectin_polymorphic</span>
<span class="n">manager_poly</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span><span class="n">Manager</span><span class="p">,</span> <span class="p">[</span><span class="n">VicePresident</span><span class="p">])</span>
<span class="n">s</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Employee</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span>
<span class="n">selectin_polymorphic</span><span class="p">(</span><span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">manager_poly</span><span class="p">]))</span><span class="o">.</span><span class="n">all</span><span class="p">()</span></pre></div>
</div>
</div>
</div>
<div class="section" id="referring-to-specific-subtypes-on-relationships">
<span id="inheritance-of-type"></span><h2>Referring to specific subtypes on relationships<a class="headerlink" href="#referring-to-specific-subtypes-on-relationships" title="Permalink to this headline">¶</a></h2>
<p>Mapped attributes which correspond to a <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> are used
in querying in order to refer to the linkage between two mappings. Common
uses for this are to refer to a <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> in <a class="reference internal" href="query.html#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>
as well as in loader options 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>. When using
<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> where the target class is an inheritance hierarchy,
the API allows that the join, eager load, or other linkage should target a specific
subclass, alias, or <a class="reference internal" href="#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> alias, of that class hierarchy,
rather than the class directly targeted by the <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>The <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.PropComparator.of_type" title="sqlalchemy.orm.interfaces.PropComparator.of_type"><code class="xref py py-func docutils literal notranslate"><span class="pre">of_type()</span></code></a> method allows the
construction of joins along <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> paths while
narrowing the criterion to specific derived aliases or subclasses. Suppose the
<code class="docutils literal notranslate"><span class="pre">employees</span></code> table represents a collection of employees which are associated
with a <code class="docutils literal notranslate"><span class="pre">Company</span></code> object. We’ll add a <code class="docutils literal notranslate"><span class="pre">company_id</span></code> column to the
<code class="docutils literal notranslate"><span class="pre">employees</span></code> table and a new table <code class="docutils literal notranslate"><span class="pre">companies</span></code>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Company</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">'company'</span>
<span class="nb">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">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">name</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="mi">50</span><span class="p">))</span>
<span class="n">employees</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s2">"Employee"</span><span class="p">,</span>
<span class="n">backref</span><span class="o">=</span><span class="s1">'company'</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Employee</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">'employee'</span>
<span class="nb">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">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="nb">type</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="mi">20</span><span class="p">))</span>
<span class="n">company_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">ForeignKey</span><span class="p">(</span><span class="s1">'company.id'</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'polymorphic_on'</span><span class="p">:</span><span class="nb">type</span><span class="p">,</span>
<span class="s1">'polymorphic_identity'</span><span class="p">:</span><span class="s1">'employee'</span><span class="p">,</span>
<span class="p">}</span>
<span class="k">class</span> <span class="nc">Engineer</span><span class="p">(</span><span class="n">Employee</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'engineer'</span>
<span class="nb">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">ForeignKey</span><span class="p">(</span><span class="s1">'employee.id'</span><span class="p">),</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">engineer_info</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="mi">50</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'polymorphic_identity'</span><span class="p">:</span><span class="s1">'engineer'</span><span class="p">}</span>
<span class="k">class</span> <span class="nc">Manager</span><span class="p">(</span><span class="n">Employee</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'manager'</span>
<span class="nb">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">ForeignKey</span><span class="p">(</span><span class="s1">'employee.id'</span><span class="p">),</span> <span class="n">primary_key</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">manager_data</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="mi">50</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'polymorphic_identity'</span><span class="p">:</span><span class="s1">'manager'</span><span class="p">}</span></pre></div>
</div>
<p>When querying from <code class="docutils literal notranslate"><span class="pre">Company</span></code> onto the <code class="docutils literal notranslate"><span class="pre">Employee</span></code> relationship, the
<a class="reference internal" href="query.html#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 as well as operators like <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.PropComparator.any" title="sqlalchemy.orm.interfaces.PropComparator.any"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PropComparator.any()</span></code></a>
and <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.PropComparator.has" title="sqlalchemy.orm.interfaces.PropComparator.has"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PropComparator.has()</span></code></a> will create
a join from <code class="docutils literal notranslate"><span class="pre">company</span></code> to <code class="docutils literal notranslate"><span class="pre">employee</span></code>, without including <code class="docutils literal notranslate"><span class="pre">engineer</span></code> or
<code class="docutils literal notranslate"><span class="pre">manager</span></code> in the mix. If we wish to have criterion which is specifically
against the <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> class, we can tell those methods to join or subquery
against the set of columns representing the subclass using the
<a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.PropComparator.of_type" title="sqlalchemy.orm.interfaces.PropComparator.of_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">of_type()</span></code></a> operator:</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">Company</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">Company</span><span class="o">.</span><span class="n">employees</span><span class="o">.</span><span class="n">of_type</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">engineer_info</span><span class="o">==</span><span class="s1">'someinfo'</span><span class="p">)</span></pre></div>
</div>
<p>Similarly, to join from <code class="docutils literal notranslate"><span class="pre">Company</span></code> to the polymorphic entity that includes both
<code class="docutils literal notranslate"><span class="pre">Engineer</span></code> and <code class="docutils literal notranslate"><span class="pre">Manager</span></code> columns:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">manager_and_engineer</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span>
<span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Manager</span><span class="p">,</span> <span class="n">Engineer</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">Company</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">Company</span><span class="o">.</span><span class="n">employees</span><span class="o">.</span><span class="n">of_type</span><span class="p">(</span><span class="n">manager_and_engineer</span><span class="p">))</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span>
<span class="n">or_</span><span class="p">(</span>
<span class="n">manager_and_engineer</span><span class="o">.</span><span class="n">Engineer</span><span class="o">.</span><span class="n">engineer_info</span> <span class="o">==</span> <span class="s1">'someinfo'</span><span class="p">,</span>
<span class="n">manager_and_engineer</span><span class="o">.</span><span class="n">Manager</span><span class="o">.</span><span class="n">manager_data</span> <span class="o">==</span> <span class="s1">'somedata'</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.PropComparator.any" title="sqlalchemy.orm.interfaces.PropComparator.any"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PropComparator.any()</span></code></a> and <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.PropComparator.has" title="sqlalchemy.orm.interfaces.PropComparator.has"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PropComparator.has()</span></code></a> operators also
can be used with <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.PropComparator.of_type" title="sqlalchemy.orm.interfaces.PropComparator.of_type"><code class="xref py py-func docutils literal notranslate"><span class="pre">of_type()</span></code></a>,
such as when the embedded criterion is in terms of a subclass:</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">Company</span><span class="p">)</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span>
<span class="n">Company</span><span class="o">.</span><span class="n">employees</span><span class="o">.</span><span class="n">of_type</span><span class="p">(</span><span class="n">Engineer</span><span class="p">)</span><span class="o">.</span>
<span class="nb">any</span><span class="p">(</span><span class="n">Engineer</span><span class="o">.</span><span class="n">engineer_info</span><span class="o">==</span><span class="s1">'someinfo'</span><span class="p">)</span>
<span class="p">)</span><span class="o">.</span><span class="n">all</span><span class="p">()</span></pre></div>
</div>
<div class="section" id="eager-loading-of-specific-or-polymorphic-subtypes">
<span id="eagerloading-polymorphic-subtypes"></span><h3>Eager Loading of Specific or Polymorphic Subtypes<a class="headerlink" href="#eager-loading-of-specific-or-polymorphic-subtypes" title="Permalink to this headline">¶</a></h3>
<p>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">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>, <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> and
other eagerloader options support
paths which make use of <code class="xref py py-func docutils literal notranslate"><span class="pre">of_type()</span></code>.
Below, we load <code class="docutils literal notranslate"><span class="pre">Company</span></code> rows while eagerly loading related <code class="docutils literal notranslate"><span class="pre">Engineer</span></code>
objects, querying the <code class="docutils literal notranslate"><span class="pre">employee</span></code> and <code class="docutils literal notranslate"><span class="pre">engineer</span></code> tables simultaneously:</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">Company</span><span class="p">)</span><span class="o">.</span>\
<span class="n">options</span><span class="p">(</span>
<span class="n">subqueryload</span><span class="p">(</span><span class="n">Company</span><span class="o">.</span><span class="n">employees</span><span class="o">.</span><span class="n">of_type</span><span class="p">(</span><span class="n">Engineer</span><span class="p">))</span><span class="o">.</span>
<span class="n">subqueryload</span><span class="p">(</span><span class="n">Engineer</span><span class="o">.</span><span class="n">machines</span><span class="p">)</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>As is the case with <a class="reference internal" href="query.html#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>, <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.PropComparator.of_type" title="sqlalchemy.orm.interfaces.PropComparator.of_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">of_type()</span></code></a>
can be used to combine eager loading and <a class="reference internal" href="#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>,
so that all sub-attributes of all referenced subtypes
can be loaded:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">manager_and_engineer</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span>
<span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Manager</span><span class="p">,</span> <span class="n">Engineer</span><span class="p">],</span>
<span class="n">flat</span><span class="o">=</span><span class="kc">True</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">Company</span><span class="p">)</span><span class="o">.</span>\
<span class="n">options</span><span class="p">(</span>
<span class="n">joinedload</span><span class="p">(</span>
<span class="n">Company</span><span class="o">.</span><span class="n">employees</span><span class="o">.</span><span class="n">of_type</span><span class="p">(</span><span class="n">manager_and_engineer</span><span class="p">)</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>When using <a class="reference internal" href="#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> in conjunction with
<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>, the <a class="reference internal" href="#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> object must be against
an “aliased” object, that is an instance of <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>, so that the
polymorphic selectable is aliased (an informative error message is raised
otherwise).</p>
<p>The typical way to do this is to include the
<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.with_polymorphic.params.aliased" title="sqlalchemy.orm.query.Query.with_polymorphic"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">with_polymorphic.aliased</span></code></a> or <code class="xref py py-paramref docutils literal notranslate"><span class="pre">flat</span></code> flag, which will
apply this aliasing automatically. However, if the
<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.with_polymorphic.params.selectable" title="sqlalchemy.orm.query.Query.with_polymorphic"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">with_polymorphic.selectable</span></code></a> argument is being used to pass an
object that is already 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> object then this flag should
<strong>not</strong> be set. The “flat” option implies the “aliased” option and is an
alternate form of aliasing against join objects that produces fewer
subqueries.</p>
</div>
<p>Once <a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.PropComparator.of_type" title="sqlalchemy.orm.interfaces.PropComparator.of_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">of_type()</span></code></a> is the target of the eager load,
that’s the entity we would use for subsequent chaining, not the original class
or derived class. If we wanted to further eager load a collection on the
eager-loaded <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> class, we access this class from the namespace of the
<a class="reference internal" href="#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> object:</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">Company</span><span class="p">)</span><span class="o">.</span>\
<span class="n">options</span><span class="p">(</span>
<span class="n">joinedload</span><span class="p">(</span><span class="n">Company</span><span class="o">.</span><span class="n">employees</span><span class="o">.</span><span class="n">of_type</span><span class="p">(</span><span class="n">manager_and_engineer</span><span class="p">))</span><span class="o">.</span>\
<span class="n">subqueryload</span><span class="p">(</span><span class="n">manager_and_engineer</span><span class="o">.</span><span class="n">Engineer</span><span class="o">.</span><span class="n">computers</span><span class="p">)</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
</div>
</div>
<div class="section" id="loading-objects-with-joined-table-inheritance">
<span id="loading-joined-inheritance"></span><h2>Loading objects with joined table inheritance<a class="headerlink" href="#loading-objects-with-joined-table-inheritance" title="Permalink to this headline">¶</a></h2>
<p>When using joined table inheritance, if we query for a specific subclass
that represents a JOIN of two tables such as our <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> example
from the inheritance section, the SQL emitted is a join:</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="n">all</span><span class="p">()</span></pre></div>
</div>
<p>The above query will emit SQL like:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><div class='show_sql'>
SELECT employee.id AS employee_id,
employee.name AS employee_name, employee.type AS employee_type,
engineer.name AS engineer_name
FROM employee JOIN engineer
ON employee.id = engineer.id</div></pre></div>
</div>
<p>We will then get a collection of <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> objects back, which will
contain all columns from <code class="docutils literal notranslate"><span class="pre">employee</span></code> and <code class="docutils literal notranslate"><span class="pre">engineer</span></code> loaded.</p>
<p>However, when emitting a <a class="reference internal" href="query.html#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> against a base class, the behavior
is to load only from the base table:</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">Employee</span><span class="p">)</span><span class="o">.</span><span class="n">all</span><span class="p">()</span></pre></div>
</div>
<p>Above, the default behavior would be to SELECT only from the <code class="docutils literal notranslate"><span class="pre">employee</span></code>
table and not from any “sub” tables (<code class="docutils literal notranslate"><span class="pre">engineer</span></code> and <code class="docutils literal notranslate"><span class="pre">manager</span></code>, in our
previous examples):</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><div class='show_sql'>
SELECT employee.id AS employee_id,
employee.name AS employee_name, employee.type AS employee_type
FROM employee
[]</div></pre></div>
</div>
<p>After a collection of <code class="docutils literal notranslate"><span class="pre">Employee</span></code> objects has been returned from the
query, and as attributes are requested from those <code class="docutils literal notranslate"><span class="pre">Employee</span></code> objects which are
represented in either the <code class="docutils literal notranslate"><span class="pre">engineer</span></code> or <code class="docutils literal notranslate"><span class="pre">manager</span></code> child tables, a second
load is issued for the columns in that related row, if the data was not
already loaded. So above, after accessing the objects you’d see further SQL
issued along the lines of:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><div class='show_sql'>
SELECT manager.id AS manager_id,
manager.manager_data AS manager_manager_data
FROM manager
WHERE ? = manager.id
[5]
SELECT engineer.id AS engineer_id,
engineer.engineer_info AS engineer_engineer_info
FROM engineer
WHERE ? = engineer.id
[2]</div></pre></div>
</div>
<p>The <a class="reference internal" href="#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 and related configuration options allow us to instead emit a JOIN up
front which will conditionally load against <code class="docutils literal notranslate"><span class="pre">employee</span></code>, <code class="docutils literal notranslate"><span class="pre">engineer</span></code>, or
<code class="docutils literal notranslate"><span class="pre">manager</span></code>, very much like joined eager loading works for relationships,
removing the necessity for a second per-entity load:</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">with_polymorphic</span>
<span class="n">eng_plus_manager</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span><span class="n">Employee</span><span class="p">,</span> <span class="p">[</span><span class="n">Engineer</span><span class="p">,</span> <span class="n">Manager</span><span class="p">])</span>
<span class="n">query</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">eng_plus_manager</span><span class="p">)</span></pre></div>
</div>
<p>The above produces a query which joins the <code class="docutils literal notranslate"><span class="pre">employee</span></code> table to both the
<code class="docutils literal notranslate"><span class="pre">engineer</span></code> and <code class="docutils literal notranslate"><span class="pre">manager</span></code> tables like the following:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><span class="n">query</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<div class='show_sql'>
SELECT employee.id AS employee_id,
engineer.id AS engineer_id,
manager.id AS manager_id,
employee.name AS employee_name,
employee.type AS employee_type,
engineer.engineer_info AS engineer_engineer_info,
manager.manager_data AS manager_manager_data
FROM employee
LEFT OUTER JOIN engineer
ON employee.id = engineer.id
LEFT OUTER JOIN manager
ON employee.id = manager.id
[]</div></pre></div>
</div>
<p>The section <a class="reference internal" href="#with-polymorphic"><span class="std std-ref">Using with_polymorphic</span></a> discusses the <a class="reference internal" href="#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 and its configurational variants.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#with-polymorphic"><span class="std std-ref">Using with_polymorphic</span></a></p>
</div>
</div>
<div class="section" id="loading-objects-with-single-table-inheritance">
<span id="loading-single-inheritance"></span><h2>Loading objects with single table inheritance<a class="headerlink" href="#loading-objects-with-single-table-inheritance" title="Permalink to this headline">¶</a></h2>
<p>In modern Declarative, single inheritance mappings produce <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a>
objects that are mapped only to a subclass, and not available from the
superclass, even though they are present on the same table.
In our example from <a class="reference internal" href="inheritance.html#single-inheritance"><span class="std std-ref">Single Table Inheritance</span></a>, the <code class="docutils literal notranslate"><span class="pre">Manager</span></code> mapping for example had a
<a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><code class="xref py py-class docutils literal notranslate"><span class="pre">Column</span></code></a> specified:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Manager</span><span class="p">(</span><span class="n">Employee</span><span class="p">):</span>
<span class="n">manager_data</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="mi">50</span><span class="p">))</span>
<span class="n">__mapper_args__</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'polymorphic_identity'</span><span class="p">:</span><span class="s1">'manager'</span>
<span class="p">}</span></pre></div>
</div>
<p>Above, there would be no <code class="docutils literal notranslate"><span class="pre">Employee.manager_data</span></code>
attribute, even though the <code class="docutils literal notranslate"><span class="pre">employee</span></code> table has a <code class="docutils literal notranslate"><span class="pre">manager_data</span></code> column.
A query against <code class="docutils literal notranslate"><span class="pre">Manager</span></code> will include this column in the query, as well
as an IN clause to limit rows only to <code class="docutils literal notranslate"><span class="pre">Manager</span></code> objects:</p>
<div class="highlight-python+sql 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">Manager</span><span class="p">)</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<div class='show_sql'>
SELECT
employee.id AS employee_id,
employee.name AS employee_name,
employee.type AS employee_type,
employee.manager_data AS employee_manager_data
FROM employee
WHERE employee.type IN (?)
('manager',)</div></pre></div>
</div>
<p>However, in a similar way to that of joined table inheritance, a query
against <code class="docutils literal notranslate"><span class="pre">Employee</span></code> will only query for columns mapped to <code class="docutils literal notranslate"><span class="pre">Employee</span></code>:</p>
<div class="highlight-python+sql 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">Employee</span><span class="p">)</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<div class='show_sql'>
SELECT employee.id AS employee_id,
employee.name AS employee_name,
employee.type AS employee_type
FROM employee</div></pre></div>
</div>
<p>If we get back an instance of <code class="docutils literal notranslate"><span class="pre">Manager</span></code> from our result, accessing
additional columns only mapped to <code class="docutils literal notranslate"><span class="pre">Manager</span></code> emits a lazy load
for those columns, in a similar way to joined inheritance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>SELECT employee.manager_data AS employee_manager_data
FROM employee
WHERE employee.id = ? AND employee.type IN (?)</pre></div>
</div>
<p>The <a class="reference internal" href="#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 serves a similar role as joined
inheritance in the case of single inheritance; it allows both for eager loading
of subclass attributes as well as specification of subclasses in a query,
just without the overhead of using OUTER JOIN:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">employee_poly</span> <span class="o">=</span> <span class="n">with_polymorphic</span><span class="p">(</span><span class="n">Employee</span><span class="p">,</span> <span class="s1">'*'</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">employee_poly</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span>
<span class="n">or_</span><span class="p">(</span>
<span class="n">employee_poly</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s1">'a'</span><span class="p">,</span>
<span class="n">employee_poly</span><span class="o">.</span><span class="n">Manager</span><span class="o">.</span><span class="n">manager_data</span> <span class="o">==</span> <span class="s1">'b'</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Above, our query remains against a single table however we can refer to the
columns present in <code class="docutils literal notranslate"><span class="pre">Manager</span></code> or <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> using the “polymorphic” namespace.
Since we specified <code class="docutils literal notranslate"><span class="pre">"*"</span></code> for the entities, both <code class="docutils literal notranslate"><span class="pre">Engineer</span></code> and
<code class="docutils literal notranslate"><span class="pre">Manager</span></code> will be loaded at once. SQL emitted would be:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><span class="n">q</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
<div class='show_sql'>
SELECT
employee.id AS employee_id, employee.name AS employee_name,
employee.type AS employee_type,
employee.manager_data AS employee_manager_data,
employee.engineer_info AS employee_engineer_info
FROM employee
WHERE employee.name = :name_1
OR employee.manager_data = :manager_data_1</div></pre></div>
</div>
</div>
<div class="section" id="inheritance-loading-api">
<h2>Inheritance Loading API<a class="headerlink" href="#inheritance-loading-api" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="sqlalchemy.orm.with_polymorphic">
<code class="descclassname">sqlalchemy.orm.</code><code class="descname">with_polymorphic</code><span class="sig-paren">(</span><em>base</em>, <em>classes</em>, <em>selectable=False</em>, <em>flat=False</em>, <em>polymorphic_on=None</em>, <em>aliased=False</em>, <em>innerjoin=False</em>, <em>_use_mapper_path=False</em>, <em>_existing_alias=None</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.with_polymorphic" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an <a class="reference internal" href="query.html#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> construct which specifies
columns for descendant mappers of the given base.</p>
<p>Using this method will ensure that each descendant mapper’s
tables are included in the FROM clause, and will allow filter()
criterion to be used against those tables. The resulting
instances will also have those columns already loaded so that
no “post fetch” of those columns will be required.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#with-polymorphic"><span class="std std-ref">Using with_polymorphic</span></a> - full discussion of
<a class="reference internal" href="#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>.</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.with_polymorphic.params.base"></span><strong>base</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.with_polymorphic.params.base">¶</a> – Base class to be aliased.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.with_polymorphic.params.classes"></span><strong>classes</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.with_polymorphic.params.classes">¶</a> – a single class or mapper, or list of
class/mappers, which inherit from the base class.
Alternatively, it may also be the string <code class="docutils literal notranslate"><span class="pre">'*'</span></code>, in which case
all descending mapped classes will be added to the FROM clause.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.with_polymorphic.params.aliased"></span><strong>aliased</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.with_polymorphic.params.aliased">¶</a> – when True, the selectable will be wrapped in an
alias, that is <code class="docutils literal notranslate"><span class="pre">(SELECT</span> <span class="pre">*</span> <span class="pre">FROM</span> <span class="pre"><fromclauses>)</span> <span class="pre">AS</span> <span class="pre">anon_1</span></code>.
This can be important when using the with_polymorphic()
to create the target of a JOIN on a backend that does not
support parenthesized joins, such as SQLite and older
versions of MySQL. However if the
<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.with_polymorphic.params.selectable" title="sqlalchemy.orm.query.Query.with_polymorphic"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">with_polymorphic.selectable</span></code></a> parameter is in use
with an existing <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, then you should not
set this flag.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.with_polymorphic.params.flat"></span><strong>flat</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.with_polymorphic.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>
<p>Setting <code class="docutils literal notranslate"><span class="pre">flat</span></code> to <code class="docutils literal notranslate"><span class="pre">True</span></code> implies the <code class="docutils literal notranslate"><span class="pre">aliased</span></code> flag is
also <code class="docutils literal notranslate"><span class="pre">True</span></code>.</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.with_polymorphic.params.selectable"></span><strong>selectable</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.with_polymorphic.params.selectable">¶</a> – a table or select() statement that will
be used in place of the generated FROM clause. This argument is
required if any of the desired classes use concrete table
inheritance, since SQLAlchemy currently cannot generate UNIONs
among tables automatically. If used, the <code class="docutils literal notranslate"><span class="pre">selectable</span></code> argument
must represent the full set of tables and columns mapped by every
mapped class. Otherwise, the unaccounted mapped columns will
result in their table being appended directly to the FROM clause
which will usually lead to incorrect results.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.with_polymorphic.params.polymorphic_on"></span><strong>polymorphic_on</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.with_polymorphic.params.polymorphic_on">¶</a> – a column to be used as the “discriminator”
column for the given selectable. If not given, the polymorphic_on
attribute of the base classes’ mapper will be used, if any. This
is useful for mappings that don’t have polymorphic loading
behavior by default.</p></li>
<li><p><span class="target" id="sqlalchemy.orm.with_polymorphic.params.innerjoin"></span><strong>innerjoin</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.orm.with_polymorphic.params.innerjoin">¶</a> – if True, an INNER JOIN will be used. This should
only be specified if querying for one specific subtype only</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.selectin_polymorphic">
<code class="descclassname">sqlalchemy.orm.</code><code class="descname">selectin_polymorphic</code><span class="sig-paren">(</span><em>base_cls</em>, <em>classes</em><span class="sig-paren">)</span><a class="headerlink" href="#sqlalchemy.orm.selectin_polymorphic" title="Permalink to this definition">¶</a></dt>
<dd><p>Indicate an eager load should take place for all attributes
specific to a subclass.</p>
<p>This uses an additional SELECT with IN against all matched primary
key values, and is the per-query analogue to the <code class="docutils literal notranslate"><span class="pre">"selectin"</span></code>
setting on the <a class="reference internal" href="mapping_api.html#sqlalchemy.orm.mapper.params.polymorphic_load" title="sqlalchemy.orm.mapper"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">mapper.polymorphic_load</span></code></a> parameter.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 1.2.</span></p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><span class="xref std std-ref">inheritance_polymorphic_load</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links, withsidebar">
Previous:
<a href="loading_relationships.html" title="previous chapter">Relationship Loading Techniques</a>
Next:
<a href="constructors.html" title="next chapter">Constructors and Object Initialization</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
>
843
