← Back to branch summary

~ubuntu-branches/debian/jessie/sqlalchemy/jessie

« back to all changes in this revision

Viewing changes to doc/orm/loading.html

  • Committer: Package Import Robot
  • Author(s): Piotr Ożarowski, Jakub Wilk, Piotr Ożarowski
  • Date: 2013-07-06 20:53:52 UTC
  • mfrom: (1.4.23) (16.1.17 experimental)
  • Revision ID: package-import@ubuntu.com-20130706205352-ryppl1eto3illd79
Tags: 0.8.2-1
[ Jakub Wilk ]
* Use canonical URIs for Vcs-* fields.

[ Piotr Ożarowski ]
* New upstream release
* Upload to unstable
* Build depend on python3-all instead of -dev, extensions are not built for
  Python 3.X 

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/orm/loading.html
10
10
    
11
11
                Relationship Loading Techniques
12
12
             — 
13
 
    SQLAlchemy 0.7 Documentation
 
13
    SQLAlchemy 0.8 Documentation
14
14
 
15
15
        </title>
16
16
        
20
20
    <script type="text/javascript">
21
21
      var DOCUMENTATION_OPTIONS = {
22
22
          URL_ROOT:    '../',
23
 
          VERSION:     '0.7.9',
 
23
          VERSION:     '0.8.2',
24
24
          COLLAPSE_MODINDEX: false,
25
25
          FILE_SUFFIX: '.html'
26
26
      };
32
32
    <link rel="index" title="Index" href="../genindex.html" />
33
33
    <link rel="search" title="Search" href="../search.html" />
34
34
        <link rel="copyright" title="Copyright" href="../copyright.html" />
35
 
    <link rel="top" title="SQLAlchemy 0.7 Documentation" href="../index.html" />
 
35
    <link rel="top" title="SQLAlchemy 0.8 Documentation" href="../index.html" />
36
36
        <link rel="up" title="SQLAlchemy ORM" href="index.html" />
37
37
        <link rel="next" title="ORM Events" href="events.html" />
38
38
        <link rel="prev" title="Querying" href="query.html" />
55
55
 
56
56
 
57
57
<div id="docs-header">
58
 
    <h1>SQLAlchemy 0.7 Documentation</h1>
 
58
    <h1>SQLAlchemy 0.8 Documentation</h1>
59
59
 
60
60
    <div id="docs-search">
61
61
    Search:
67
67
    </div>
68
68
 
69
69
    <div id="docs-version-header">
70
 
        Release: <span class="version-num">0.7.9</span> | Release Date: October 1, 2012
 
70
        Release: <span class="version-num">0.8.2</span> | Release Date: July 3, 2013
71
71
 
72
72
 
73
73
    </div>
93
93
    </div>
94
94
 
95
95
    <div id="docs-navigation-banner">
96
 
        <a href="../index.html">SQLAlchemy 0.7 Documentation</a>
 
96
        <a href="../index.html">SQLAlchemy 0.8 Documentation</a>
97
97
                » <a href="index.html" title="SQLAlchemy ORM">SQLAlchemy ORM</a>
98
98
        » 
99
99
                Relationship Loading Techniques
149
149
    <div id="docs-body" class="withsidebar" >
150
150
        
151
151
<div class="section" id="relationship-loading-techniques">
152
 
<span id="loading-toplevel"></span><h1>Relationship Loading Techniques<a class="headerlink" href="#relationship-loading-techniques" title="Permalink to this headline">¶</a></h1>
 
152
<h1>Relationship Loading Techniques<a class="headerlink" href="#relationship-loading-techniques" title="Permalink to this headline">¶</a></h1>
153
153
<p>A big part of SQLAlchemy is providing a wide range of control over how related objects get loaded when querying.   This behavior
154
154
can be configured at mapper construction time using the <tt class="docutils literal"><span class="pre">lazy</span></tt> parameter to the <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal"><span class="pre">relationship()</span></tt></a> function,
155
155
as well as by using options with the <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> object.</p>
687
687
it <strong>does not affect the query results</strong>.   An <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.order_by" title="sqlalchemy.orm.query.Query.order_by"><tt class="xref py py-meth docutils literal"><span class="pre">Query.order_by()</span></tt></a>
688
688
or <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.filter" title="sqlalchemy.orm.query.Query.filter"><tt class="xref py py-meth docutils literal"><span class="pre">Query.filter()</span></tt></a> call <strong>cannot</strong> reference these aliased
689
689
tables - so-called &#8220;user space&#8221; joins are constructed using
690
 
<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><tt class="xref py py-meth docutils literal"><span class="pre">Query.join()</span></tt></a>.   The rationale for this is that <a class="reference internal" href="#sqlalchemy.orm.joinedload" title="sqlalchemy.orm.joinedload"><tt class="xref py py-func docutils literal"><span class="pre">joinedload()</span></tt></a> is only
691
 
applied in order to affect how related objects or collections are loaded
692
 
as an optimizing detail - it can be added or removed with no impact
693
 
on actual results.   See the section <a class="reference internal" href="#zen-of-eager-loading"><em>The Zen of Eager Loading</em></a> for
694
 
a detailed description of how this is used, including how to use a single
695
 
explicit JOIN for filtering/ordering and eager loading simultaneously.</p>
 
690
<a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><tt class="xref py py-meth docutils literal"><span class="pre">Query.join()</span></tt></a>.   The rationale for this is that
 
691
<a class="reference internal" href="#sqlalchemy.orm.joinedload" title="sqlalchemy.orm.joinedload"><tt class="xref py py-func docutils literal"><span class="pre">joinedload()</span></tt></a> is only applied in order to affect how related
 
692
objects or collections are loaded as an optimizing detail - it can be
 
693
added or removed with no impact on actual results.   See the section
 
694
<a class="reference internal" href="#zen-of-eager-loading"><em>The Zen of Eager Loading</em></a> for a detailed description of how this is
 
695
used, including how to use a single explicit JOIN for
 
696
filtering/ordering and eager loading simultaneously.</p>
696
697
</div>
697
698
<p>See also:  <a class="reference internal" href="#sqlalchemy.orm.subqueryload" title="sqlalchemy.orm.subqueryload"><tt class="xref py py-func docutils literal"><span class="pre">subqueryload()</span></tt></a>, <a class="reference internal" href="#sqlalchemy.orm.lazyload" title="sqlalchemy.orm.lazyload"><tt class="xref py py-func docutils literal"><span class="pre">lazyload()</span></tt></a></p>
698
699
</dd></dl>
712
713
<p>For example:</p>
713
714
<div class="highlight-python"><pre>query.options(joinedload_all('orders.items.keywords'))...</pre>
714
715
</div>
715
 
<p>will set all of <tt class="docutils literal"><span class="pre">orders</span></tt>, <tt class="docutils literal"><span class="pre">orders.items</span></tt>, and <tt class="docutils literal"><span class="pre">orders.items.keywords</span></tt> to
716
 
load in one joined eager load.</p>
 
716
<p>will set all of <tt class="docutils literal"><span class="pre">orders</span></tt>, <tt class="docutils literal"><span class="pre">orders.items</span></tt>, and
 
717
<tt class="docutils literal"><span class="pre">orders.items.keywords</span></tt> to load in one joined eager load.</p>
717
718
<p>Individual descriptors are accepted as arguments as well:</p>
718
719
<div class="highlight-python"><div class="highlight"><pre><span class="n">query</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">joinedload_all</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">orders</span><span class="p">,</span> <span class="n">Order</span><span class="o">.</span><span class="n">items</span><span class="p">,</span> <span class="n">Item</span><span class="o">.</span><span class="n">keywords</span><span class="p">))</span></pre></div>
719
720
</div>
777
778
<p>For example:</p>
778
779
<div class="highlight-python"><pre>query.options(subqueryload_all('orders.items.keywords'))...</pre>
779
780
</div>
780
 
<p>will set all of <tt class="docutils literal"><span class="pre">orders</span></tt>, <tt class="docutils literal"><span class="pre">orders.items</span></tt>, and <tt class="docutils literal"><span class="pre">orders.items.keywords</span></tt> to
781
 
load in one subquery eager load.</p>
 
781
<p>will set all of <tt class="docutils literal"><span class="pre">orders</span></tt>, <tt class="docutils literal"><span class="pre">orders.items</span></tt>, and
 
782
<tt class="docutils literal"><span class="pre">orders.items.keywords</span></tt> to load in one subquery eager load.</p>
782
783
<p>Individual descriptors are accepted as arguments as well:</p>
783
784
<div class="highlight-python"><div class="highlight"><pre><span class="n">query</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">subqueryload_all</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">orders</span><span class="p">,</span> <span class="n">Order</span><span class="o">.</span><span class="n">items</span><span class="p">,</span>
784
785
<span class="n">Item</span><span class="o">.</span><span class="n">keywords</span><span class="p">))</span></pre></div>
800
801
        <a href="events.html" title="next chapter">ORM Events</a>
801
802
 
802
803
    <div id="docs-copyright">
803
 
        &copy; <a href="../copyright.html">Copyright</a> 2007-2012, the SQLAlchemy authors and contributors.
 
804
        &copy; <a href="../copyright.html">Copyright</a> 2007-2013, the SQLAlchemy authors and contributors.
804
805
        Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
805
806
    </div>
806
807
</div>