1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
Querying
— SQLAlchemy 0.6.3 Documentation</title>
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../_static/docs.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '0.6.3',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<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/init.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="top" title="SQLAlchemy 0.6.3 Documentation" href="../../index.html" />
<link rel="up" title="sqlalchemy.orm" href="index.html" />
<link rel="next" title="Sessions" href="sessions.html" />
<link rel="prev" title="Collection Mapping" href="collections.html" />
</head>
<body>
<h1>SQLAlchemy 0.6.3 Documentation</h1>
<div id="search">
Search:
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" size="18" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<div class="versionheader">
Version: <span class="versionnum">0.6.3</span> Last Updated: 07/15/2010 12:35:47
</div>
<div class="clearboth"></div>
<div class="topnav">
<div id="pagecontrol">
<a href="../index.html">API Reference</a>
|
<a href="../../genindex.html">Index</a>
<div class="sourcelink">(<a href="../../_sources/reference/orm/query.txt">view source)</div>
</div>
<div class="navbanner">
<a class="totoc" href="../../index.html">Table of Contents</a>
» <a href="../index.html" title="API Reference">API Reference</a>
» <a href="index.html" title="sqlalchemy.orm">sqlalchemy.orm</a>
»
Querying
<div class="prevnext">
Previous:
<a href="collections.html" title="previous chapter">Collection Mapping</a>
Next:
<a href="sessions.html" title="next chapter">Sessions</a>
</div>
<h2>
Querying
</h2>
</div>
<ul>
<li><a class="reference internal" href="#">Querying</a><ul>
<li><a class="reference internal" href="#the-query-object">The Query Object</a></li>
<li><a class="reference internal" href="#orm-specific-query-constructs">ORM-Specific Query Constructs</a></li>
<li><a class="reference internal" href="#query-options">Query Options</a></li>
</ul>
</li>
</ul>
<div class="clearboth"></div>
</div>
<div class="document">
<div class="body">
<div class="section" id="module-sqlalchemy.orm">
<span id="querying"></span><span id="query-api-toplevel"></span><h1>Querying<a class="headerlink" href="#module-sqlalchemy.orm" title="Permalink to this headline">¶</a></h1>
<div class="section" id="the-query-object">
<h2>The Query Object<a class="headerlink" href="#the-query-object" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt></a> is produced in terms of a given <a class="reference internal" href="sessions.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal"><span class="pre">Session</span></tt></a>, using the <tt class="xref py py-func docutils literal"><span class="pre">query()</span></tt> function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">q</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">SomeMappedClass</span><span class="p">)</span></pre></div>
</div>
<p>Following is the full interface for the <tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt> object.</p>
<dl class="class">
<dt id="sqlalchemy.orm.query.Query">
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.query.</tt><tt class="descname">Query</tt><big>(</big><em>entities</em>, <em>session=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query" title="Permalink to this definition">¶</a></dt>
<dd><p>ORM-level SQL construction object.</p>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.__init__">
<tt class="descname">__init__</tt><big>(</big><em>entities</em>, <em>session=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.__init__" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.add_column">
<tt class="descname">add_column</tt><big>(</big><em>column</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.add_column" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a column expression to the list of result columns</p>
<p>Deprecated.
to be returned.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.add_columns">
<tt class="descname">add_columns</tt><big>(</big><em>*column</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.add_columns" title="Permalink to this definition">¶</a></dt>
<dd><p>Add one or more column expressions to the list
of result columns to be returned.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.add_entity">
<tt class="descname">add_entity</tt><big>(</big><em>entity</em>, <em>alias=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.add_entity" title="Permalink to this definition">¶</a></dt>
<dd><p>add a mapped entity to the list of result columns
to be returned.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.all">
<tt class="descname">all</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.all" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the results represented by this <tt class="docutils literal"><span class="pre">Query</span></tt> as a list.</p>
<p>This results in an execution of the underlying query.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.autoflush">
<tt class="descname">autoflush</tt><big>(</big><em>setting</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.autoflush" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a Query with a specific ‘autoflush’ setting.</p>
<p>Note that a Session with autoflush=False will
not autoflush, even if this flag is set to True at the
Query level. Therefore this flag is usually used only
to disable autoflush for a specific Query.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Query.column_descriptions">
<tt class="descname">column_descriptions</tt><a class="headerlink" href="#sqlalchemy.orm.query.Query.column_descriptions" title="Permalink to this definition">¶</a></dt>
<dd><p>Return metadata about the columns which would be
returned by this <tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt>.</p>
<p>Format is a list of dictionaries:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">user_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">'user2'</span><span class="p">)</span>
<span class="n">q</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">user_alias</span><span class="p">)</span>
<span class="c"># this expression:</span>
<span class="n">q</span><span class="o">.</span><span class="n">columns</span>
<span class="c"># would return:</span>
<span class="p">[</span>
<span class="p">{</span>
<span class="s">'name'</span><span class="p">:</span><span class="s">'User'</span><span class="p">,</span>
<span class="s">'type'</span><span class="p">:</span><span class="n">User</span><span class="p">,</span>
<span class="s">'aliased'</span><span class="p">:</span><span class="bp">False</span><span class="p">,</span>
<span class="s">'expr'</span><span class="p">:</span><span class="n">User</span><span class="p">,</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="s">'name'</span><span class="p">:</span><span class="s">'id'</span><span class="p">,</span>
<span class="s">'type'</span><span class="p">:</span><span class="n">Integer</span><span class="p">(),</span>
<span class="s">'aliased'</span><span class="p">:</span><span class="bp">False</span><span class="p">,</span>
<span class="s">'expr'</span><span class="p">:</span><span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">,</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="s">'name'</span><span class="p">:</span><span class="s">'user2'</span><span class="p">,</span>
<span class="s">'type'</span><span class="p">:</span><span class="n">User</span><span class="p">,</span>
<span class="s">'aliased'</span><span class="p">:</span><span class="bp">True</span><span class="p">,</span>
<span class="s">'expr'</span><span class="p">:</span><span class="n">user_alias</span>
<span class="p">}</span>
<span class="p">]</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.correlate">
<tt class="descname">correlate</tt><big>(</big><em>*args</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.correlate" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.count">
<tt class="descname">count</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.count" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a count of rows this Query would return.</p>
<p>For simple entity queries, count() issues
a SELECT COUNT, and will specifically count the primary
key column of the first entity only. If the query uses
LIMIT, OFFSET, or DISTINCT, count() will wrap the statement
generated by this Query in a subquery, from which a SELECT COUNT
is issued, so that the contract of “how many rows
would be returned?” is honored.</p>
<p>For queries that request specific columns or expressions,
count() again makes no assumptions about those expressions
and will wrap everything in a subquery. Therefore,
<tt class="docutils literal"><span class="pre">Query.count()</span></tt> is usually not what you want in this case.
To count specific columns, often in conjunction with
GROUP BY, use <tt class="docutils literal"><span class="pre">func.count()</span></tt> as an individual column expression
instead of <tt class="docutils literal"><span class="pre">Query.count()</span></tt>. See the ORM tutorial
for an example.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.delete">
<tt class="descname">delete</tt><big>(</big><em>synchronize_session='evaluate'</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.delete" title="Permalink to this definition">¶</a></dt>
<dd><p>Perform a bulk delete query.</p>
<p>Deletes rows matched by this query from the database.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>synchronize_session</strong> – <p>chooses the strategy for the removal of
matched objects from the session. Valid values are:</p>
<p>False - don’t synchronize the session. This option is the most
efficient and is reliable once the session is expired, which
typically occurs after a commit(), or explicitly using
expire_all(). Before the expiration, objects may still remain in
the session which were in fact deleted which can lead to confusing
results if they are accessed via get() or already loaded
collections.</p>
<p>‘fetch’ - performs a select query before the delete to find
objects that are matched by the delete query and need to be
removed from the session. Matched objects are removed from the
session.</p>
<p>‘evaluate’ - Evaluate the query’s criteria in Python straight on
the objects in the session. If evaluation of the criteria isn’t
implemented, an error is raised. In that case you probably
want to use the ‘fetch’ strategy as a fallback.</p>
<p>The expression evaluator currently doesn’t account for differing
string collations between the database and Python.</p>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>Returns the number of rows deleted, excluding any cascades.</p>
<p>The method does <em>not</em> offer in-Python cascading of relationships - it
is assumed that ON DELETE CASCADE is configured for any foreign key
references which require it. The Session needs to be expired (occurs
automatically after commit(), or call expire_all()) in order for the
state of dependent objects subject to delete or delete-orphan cascade
to be correctly represented.</p>
<p>Also, the <tt class="docutils literal"><span class="pre">before_delete()</span></tt> and <tt class="docutils literal"><span class="pre">after_delete()</span></tt>
<a class="reference internal" href="interfaces.html#sqlalchemy.orm.interfaces.MapperExtension" title="sqlalchemy.orm.interfaces.MapperExtension"><tt class="xref py py-class docutils literal"><span class="pre">MapperExtension</span></tt></a> methods are not
called from this method. For a delete hook here, use the
<tt class="docutils literal"><span class="pre">after_bulk_delete()</span></tt>
<a class="reference internal" href="interfaces.html#sqlalchemy.orm.interfaces.MapperExtension" title="sqlalchemy.orm.interfaces.MapperExtension"><tt class="xref py py-class docutils literal"><span class="pre">MapperExtension</span></tt></a> method.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.distinct">
<tt class="descname">distinct</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.distinct" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply a <tt class="docutils literal"><span class="pre">DISTINCT</span></tt> to the query and return the newly resulting
<tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.enable_assertions">
<tt class="descname">enable_assertions</tt><big>(</big><em>value</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.enable_assertions" title="Permalink to this definition">¶</a></dt>
<dd><p>Control whether assertions are generated.</p>
<p>When set to False, the returned Query will
not assert its state before certain operations,
including that LIMIT/OFFSET has not been applied
when filter() is called, no criterion exists
when get() is called, and no “from_statement()”
exists when filter()/order_by()/group_by() etc.
is called. This more permissive mode is used by
custom Query subclasses to specify criterion or
other modifiers outside of the usual usage patterns.</p>
<p>Care should be taken to ensure that the usage
pattern is even possible. A statement applied
by from_statement() will override any criterion
set by filter() or order_by(), for example.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.enable_eagerloads">
<tt class="descname">enable_eagerloads</tt><big>(</big><em>value</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.enable_eagerloads" title="Permalink to this definition">¶</a></dt>
<dd><p>Control whether or not eager joins and subqueries are
rendered.</p>
<p>When set to False, the returned Query will not render
eager joins regardless of <a class="reference internal" href="#sqlalchemy.orm.joinedload" title="sqlalchemy.orm.joinedload"><tt class="xref py py-func docutils literal"><span class="pre">joinedload()</span></tt></a>,
<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> options
or mapper-level <tt class="docutils literal"><span class="pre">lazy='joined'</span></tt>/<tt class="docutils literal"><span class="pre">lazy='subquery'</span></tt>
configurations.</p>
<p>This is used primarily when nesting the Query’s
statement into a subquery or other
selectable.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.except_">
<tt class="descname">except_</tt><big>(</big><em>*q</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.except_" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an EXCEPT of this Query against one or more queries.</p>
<p>Works the same way as <a class="reference internal" href="#sqlalchemy.orm.query.Query.union" title="sqlalchemy.orm.query.Query.union"><tt class="xref py py-meth docutils literal"><span class="pre">union()</span></tt></a>. See
that method for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.except_all">
<tt class="descname">except_all</tt><big>(</big><em>*q</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.except_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an EXCEPT ALL of this Query against one or more queries.</p>
<p>Works the same way as <a class="reference internal" href="#sqlalchemy.orm.query.Query.union" title="sqlalchemy.orm.query.Query.union"><tt class="xref py py-meth docutils literal"><span class="pre">union()</span></tt></a>. See
that method for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.execution_options">
<tt class="descname">execution_options</tt><big>(</big><em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.execution_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Set non-SQL options which take effect during execution.</p>
<p>The options are the same as those accepted by
<a class="reference internal" href="../sqlalchemy/expressions.html#sqlalchemy.sql.expression.Executable.execution_options" title="sqlalchemy.sql.expression.Executable.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">sqlalchemy.sql.expression.Executable.execution_options()</span></tt></a>.</p>
<p>Note that the <tt class="docutils literal"><span class="pre">stream_results</span></tt> execution option is enabled
automatically if the <a class="reference internal" href="#sqlalchemy.orm.query.Query.yield_per" title="sqlalchemy.orm.query.Query.yield_per"><tt class="xref py py-meth docutils literal"><span class="pre">yield_per()</span></tt></a>
method is used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.filter">
<tt class="descname">filter</tt><big>(</big><em>criterion</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.filter" title="Permalink to this definition">¶</a></dt>
<dd><p>apply the given filtering criterion to the query and return
the newly resulting <tt class="docutils literal"><span class="pre">Query</span></tt></p>
<p>the criterion is any sql.ClauseElement applicable to the WHERE clause
of a select.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.filter_by">
<tt class="descname">filter_by</tt><big>(</big><em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.filter_by" title="Permalink to this definition">¶</a></dt>
<dd><p>apply the given filtering criterion to the query and return
the newly resulting <tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.first">
<tt class="descname">first</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.first" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the first result of this <tt class="docutils literal"><span class="pre">Query</span></tt> or
None if the result doesn’t contain any row.</p>
<p>first() applies a limit of one within the generated SQL, so that
only one primary entity row is generated on the server side
(note this may consist of multiple result rows if join-loaded
collections are present).</p>
<p>Calling <tt class="docutils literal"><span class="pre">first()</span></tt> results in an execution of the underlying query.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.from_self">
<tt class="descname">from_self</tt><big>(</big><em>*entities</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.from_self" title="Permalink to this definition">¶</a></dt>
<dd><p>return a Query that selects from this Query’s
SELECT statement.</p>
<p>*entities - optional list of entities which will replace
those being selected.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.from_statement">
<tt class="descname">from_statement</tt><big>(</big><em>statement</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.from_statement" title="Permalink to this definition">¶</a></dt>
<dd><p>Execute the given SELECT statement and return results.</p>
<p>This method bypasses all internal statement compilation, and the
statement is executed without modification.</p>
<p>The statement argument is either a string, a <tt class="docutils literal"><span class="pre">select()</span></tt> construct,
or a <tt class="docutils literal"><span class="pre">text()</span></tt> construct, and should return the set of columns
appropriate to the entity class represented by this <tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
<p>Also see the <tt class="docutils literal"><span class="pre">instances()</span></tt> method.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.get">
<tt class="descname">get</tt><big>(</big><em>ident</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an instance of the object based on the
given identifier, or None if not found.</p>
<p>The <cite>ident</cite> argument is a scalar or tuple of primary key column values
in the order of the table def’s primary key columns.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.group_by">
<tt class="descname">group_by</tt><big>(</big><em>*criterion</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.group_by" title="Permalink to this definition">¶</a></dt>
<dd><p>apply one or more GROUP BY criterion to the query and return
the newly resulting <tt class="docutils literal"><span class="pre">Query</span></tt></p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.having">
<tt class="descname">having</tt><big>(</big><em>criterion</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.having" title="Permalink to this definition">¶</a></dt>
<dd><p>apply a HAVING criterion to the query and return the
newly resulting <tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.instances">
<tt class="descname">instances</tt><big>(</big><em>cursor</em>, <em>_Query__context=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.instances" title="Permalink to this definition">¶</a></dt>
<dd><p>Given a ResultProxy cursor as returned by connection.execute(),
return an ORM result as an iterator.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="n">engine</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">"select * from users"</span><span class="p">)</span>
<span class="k">for</span> <span class="n">u</span> <span class="ow">in</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">instances</span><span class="p">(</span><span class="n">result</span><span class="p">):</span>
<span class="k">print</span> <span class="n">u</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.intersect">
<tt class="descname">intersect</tt><big>(</big><em>*q</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.intersect" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an INTERSECT of this Query against one or more queries.</p>
<p>Works the same way as <a class="reference internal" href="#sqlalchemy.orm.query.Query.union" title="sqlalchemy.orm.query.Query.union"><tt class="xref py py-meth docutils literal"><span class="pre">union()</span></tt></a>. See
that method for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.intersect_all">
<tt class="descname">intersect_all</tt><big>(</big><em>*q</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.intersect_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an INTERSECT ALL of this Query against one or more queries.</p>
<p>Works the same way as <a class="reference internal" href="#sqlalchemy.orm.query.Query.union" title="sqlalchemy.orm.query.Query.union"><tt class="xref py py-meth docutils literal"><span class="pre">union()</span></tt></a>. See
that method for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.join">
<tt class="descname">join</tt><big>(</big><em>*props</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.join" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a join against this <tt class="docutils literal"><span class="pre">Query</span></tt> object’s criterion
and apply generatively, returning the newly resulting <tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
<p>Each element in *props may be:</p>
<blockquote>
<ul class="simple">
<li>a string property name, i.e. “rooms”. This will join along the
relationship of the same name from this Query’s “primary” mapper,
if one is present.</li>
<li>a class-mapped attribute, i.e. Houses.rooms. This will create a
join from “Houses” table to that of the “rooms” relationship.</li>
<li>a 2-tuple containing a target class or selectable, and an “ON”
clause. The ON clause can be the property name/ attribute like
above, or a SQL expression.</li>
</ul>
</blockquote>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># join along string attribute names</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="s">'employees'</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="s">'employees'</span><span class="p">,</span> <span class="s">'tasks'</span><span class="p">)</span>
<span class="c"># join the Person entity to an alias of itself,</span>
<span class="c"># along the "friends" relationship</span>
<span class="n">PAlias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">Person</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">Person</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">((</span><span class="n">Palias</span><span class="p">,</span> <span class="n">Person</span><span class="o">.</span><span class="n">friends</span><span class="p">))</span>
<span class="c"># join from Houses to the "rooms" attribute on the</span>
<span class="c"># "Colonials" subclass of Houses, then join to the</span>
<span class="c"># "closets" relationship on Room</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Houses</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">Colonials</span><span class="o">.</span><span class="n">rooms</span><span class="p">,</span> <span class="n">Room</span><span class="o">.</span><span class="n">closets</span><span class="p">)</span>
<span class="c"># join from Company entities to the "employees" collection,</span>
<span class="c"># using "people JOIN engineers" as the target. Then join</span>
<span class="c"># to the "computers" collection on the Engineer entity.</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">people</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">engineers</span><span class="p">),</span> <span class="s">'employees'</span><span class="p">),</span>
<span class="n">Engineer</span><span class="o">.</span><span class="n">computers</span><span class="p">)</span>
<span class="c"># join from Articles to Keywords, using the "keywords" attribute.</span>
<span class="c"># assume this is a many-to-many relationship.</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Article</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">Article</span><span class="o">.</span><span class="n">keywords</span><span class="p">)</span>
<span class="c"># same thing, but spelled out entirely explicitly</span>
<span class="c"># including the association table.</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Article</span><span class="p">)</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
<span class="p">(</span><span class="n">article_keywords</span><span class="p">,</span>
<span class="n">Articles</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="n">article_keywords</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">article_id</span><span class="p">),</span>
<span class="p">(</span><span class="n">Keyword</span><span class="p">,</span> <span class="n">Keyword</span><span class="o">.</span><span class="n">id</span><span class="o">==</span><span class="n">article_keywords</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">keyword_id</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>**kwargs include:</p>
<blockquote>
<p>aliased - when joining, create anonymous aliases of each table.
This is used for self-referential joins or multiple joins to the
same table. Consider usage of the aliased(SomeClass) construct as
a more explicit approach to this.</p>
<p>from_joinpoint - when joins are specified using string property
names, locate the property from the mapper found in the most
recent previous join() call, instead of from the root entity.</p>
</blockquote>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.limit">
<tt class="descname">limit</tt><big>(</big><em>limit</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.limit" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply a <tt class="docutils literal"><span class="pre">LIMIT</span></tt> to the query and return the newly resulting</p>
<p><tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.merge_result">
<tt class="descname">merge_result</tt><big>(</big><em>iterator</em>, <em>load=True</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.merge_result" title="Permalink to this definition">¶</a></dt>
<dd><p>Merge a result into this Query’s Session.</p>
<p>Given an iterator returned by a Query of the same structure as this
one, return an identical iterator of results, with all mapped
instances merged into the session using Session.merge(). This is an
optimized method which will merge all mapped instances, preserving the
structure of the result rows and unmapped columns with less method
overhead than that of calling Session.merge() explicitly for each
value.</p>
<p>The structure of the results is determined based on the column list of
this Query - if these do not correspond, unchecked errors will occur.</p>
<p>The ‘load’ argument is the same as that of Session.merge().</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.offset">
<tt class="descname">offset</tt><big>(</big><em>offset</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.offset" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply an <tt class="docutils literal"><span class="pre">OFFSET</span></tt> to the query and return the newly resulting
<tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.one">
<tt class="descname">one</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.one" title="Permalink to this definition">¶</a></dt>
<dd><p>Return exactly one result or raise an exception.</p>
<p>Raises <tt class="docutils literal"><span class="pre">sqlalchemy.orm.exc.NoResultFound</span></tt> if the query selects
no rows. Raises <tt class="docutils literal"><span class="pre">sqlalchemy.orm.exc.MultipleResultsFound</span></tt>
if multiple object identities are returned, or if multiple
rows are returned for a query that does not return object
identities.</p>
<p>Note that an entity query, that is, one which selects one or
more mapped classes as opposed to individual column attributes,
may ultimately represent many rows but only one row of
unique entity or entities - this is a successful result for one().</p>
<p>Calling <tt class="docutils literal"><span class="pre">one()</span></tt> results in an execution of the underlying query.
As of 0.6, <tt class="docutils literal"><span class="pre">one()</span></tt> fully fetches all results instead of applying
any kind of limit, so that the “unique”-ing of entities does not
conceal multiple object identities.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.options">
<tt class="descname">options</tt><big>(</big><em>*args</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.options" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new Query object, applying the given list of
MapperOptions.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.order_by">
<tt class="descname">order_by</tt><big>(</big><em>*criterion</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.order_by" title="Permalink to this definition">¶</a></dt>
<dd><p>apply one or more ORDER BY criterion to the query and return
the newly resulting <tt class="docutils literal"><span class="pre">Query</span></tt></p>
<p>All existing ORDER BY settings can be suppressed by
passing <tt class="xref docutils literal"><span class="pre">None</span></tt> - this will suppress any ORDER BY configured
on mappers as well.</p>
<p>Alternatively, an existing ORDER BY setting on the Query
object can be entirely cancelled by passing <tt class="xref docutils literal"><span class="pre">False</span></tt>
as the value - use this before calling methods where
an ORDER BY is invalid.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.outerjoin">
<tt class="descname">outerjoin</tt><big>(</big><em>*props</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.outerjoin" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a left outer join against this <tt class="docutils literal"><span class="pre">Query</span></tt> object’s criterion
and apply generatively, retunring the newly resulting <tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
<p>Usage is the same as the <tt class="docutils literal"><span class="pre">join()</span></tt> method.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.params">
<tt class="descname">params</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.params" title="Permalink to this definition">¶</a></dt>
<dd><p>add values for bind parameters which may have been
specified in filter().</p>
<p>parameters may be specified using **kwargs, or optionally a single
dictionary as the first positional argument. The reason for both is
that **kwargs is convenient, however some parameter dictionaries
contain unicode keys in which case **kwargs cannot be used.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.populate_existing">
<tt class="descname">populate_existing</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.populate_existing" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a Query that will refresh all instances loaded.</p>
<p>This includes all entities accessed from the database, including
secondary entities, eagerly-loaded collection items.</p>
<p>All changes present on entities which are already present in the
session will be reset and the entities will all be marked “clean”.</p>
<p>An alternative to populate_existing() is to expire the Session
fully using session.expire_all().</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.reset_joinpoint">
<tt class="descname">reset_joinpoint</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.reset_joinpoint" title="Permalink to this definition">¶</a></dt>
<dd><p>return a new Query reset the ‘joinpoint’ of this Query reset
back to the starting mapper. Subsequent generative calls will
be constructed from the new joinpoint.</p>
<p>Note that each call to join() or outerjoin() also starts from
the root.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.scalar">
<tt class="descname">scalar</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.scalar" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the first element of the first result or None
if no rows present. If multiple rows are returned,
raises MultipleResultsFound.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Item</span><span class="p">)</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
<span class="go"><Item></span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Item</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
<span class="go">1</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Item</span><span class="o">.</span><span class="n">id</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">Item</span><span class="o">.</span><span class="n">id</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
<span class="go">None</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Item</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">Item</span><span class="o">.</span><span class="n">name</span><span class="p">)</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
<span class="go">1</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">Parent</span><span class="o">.</span><span class="n">id</span><span class="p">))</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span>
<span class="go">20</span></pre></div>
</div>
<p>This results in an execution of the underlying query.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.select_from">
<tt class="descname">select_from</tt><big>(</big><em>*from_obj</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.select_from" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the <cite>from_obj</cite> parameter of the query and return the newly
resulting <tt class="docutils literal"><span class="pre">Query</span></tt>. This replaces the table which this Query selects
from with the given table.</p>
<p><tt class="docutils literal"><span class="pre">select_from()</span></tt> also accepts class arguments. Though usually not
necessary, can ensure that the full selectable of the given mapper is
applied, e.g. for joined-table mappers.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.slice">
<tt class="descname">slice</tt><big>(</big><em>start</em>, <em>stop</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.slice" title="Permalink to this definition">¶</a></dt>
<dd><p>apply LIMIT/OFFSET to the <tt class="docutils literal"><span class="pre">Query</span></tt> based on a ”
“range and return the newly resulting <tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Query.statement">
<tt class="descname">statement</tt><a class="headerlink" href="#sqlalchemy.orm.query.Query.statement" title="Permalink to this definition">¶</a></dt>
<dd><p>The full SELECT statement represented by this Query.</p>
<p>The statement by default will not have disambiguating labels
applied to the construct unless with_labels(True) is called
first.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.subquery">
<tt class="descname">subquery</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.subquery" title="Permalink to this definition">¶</a></dt>
<dd><p>return the full SELECT statement represented by this Query,
embedded within an Alias.</p>
<p>Eager JOIN generation within the query is disabled.</p>
<p>The statement by default will not have disambiguating labels
applied to the construct unless with_labels(True) is called
first.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.union">
<tt class="descname">union</tt><big>(</big><em>*q</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.union" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a UNION of this Query against one or more queries.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">q1</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">SomeClass</span><span class="o">.</span><span class="n">foo</span><span class="o">==</span><span class="s">'bar'</span><span class="p">)</span>
<span class="n">q2</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">)</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">SomeClass</span><span class="o">.</span><span class="n">bar</span><span class="o">==</span><span class="s">'foo'</span><span class="p">)</span>
<span class="n">q3</span> <span class="o">=</span> <span class="n">q1</span><span class="o">.</span><span class="n">union</span><span class="p">(</span><span class="n">q2</span><span class="p">)</span></pre></div>
</div>
<p>The method accepts multiple Query objects so as to control
the level of nesting. A series of <tt class="docutils literal"><span class="pre">union()</span></tt> calls such as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">x</span><span class="o">.</span><span class="n">union</span><span class="p">(</span><span class="n">y</span><span class="p">)</span><span class="o">.</span><span class="n">union</span><span class="p">(</span><span class="n">z</span><span class="p">)</span><span class="o">.</span><span class="n">all</span><span class="p">()</span></pre></div>
</div>
<p>will nest on each <tt class="docutils literal"><span class="pre">union()</span></tt>, and produces:</p>
<div class="highlight-python"><pre>SELECT * FROM (SELECT * FROM (SELECT * FROM X UNION
SELECT * FROM y) UNION SELECT * FROM Z)</pre>
</div>
<p>Whereas:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">x</span><span class="o">.</span><span class="n">union</span><span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">z</span><span class="p">)</span><span class="o">.</span><span class="n">all</span><span class="p">()</span></pre></div>
</div>
<p>produces:</p>
<div class="highlight-python"><pre>SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION
SELECT * FROM Z)</pre>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.union_all">
<tt class="descname">union_all</tt><big>(</big><em>*q</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.union_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a UNION ALL of this Query against one or more queries.</p>
<p>Works the same way as <a class="reference internal" href="#sqlalchemy.orm.query.Query.union" title="sqlalchemy.orm.query.Query.union"><tt class="xref py py-meth docutils literal"><span class="pre">union()</span></tt></a>. See
that method for usage examples.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.update">
<tt class="descname">update</tt><big>(</big><em>values</em>, <em>synchronize_session='evaluate'</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.update" title="Permalink to this definition">¶</a></dt>
<dd><p>Perform a bulk update query.</p>
<p>Updates rows matched by this query in the database.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>values</strong> – a dictionary with attributes names as keys and literal
values or sql expressions as values.</li>
<li><strong>synchronize_session</strong> – <p>chooses the strategy to update the
attributes on objects in the session. Valid values are:</p>
<p>False - don’t synchronize the session. This option is the most
efficient and is reliable once the session is expired, which
typically occurs after a commit(), or explicitly using
expire_all(). Before the expiration, updated objects may still
remain in the session with stale values on their attributes, which
can lead to confusing results.</p>
<p>‘fetch’ - performs a select query before the update to find
objects that are matched by the update query. The updated
attributes are expired on matched objects.</p>
<p>‘evaluate’ - Evaluate the Query’s criteria in Python straight on
the objects in the session. If evaluation of the criteria isn’t
implemented, an exception is raised.</p>
<p>The expression evaluator currently doesn’t account for differing
string collations between the database and Python.</p>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>Returns the number of rows matched by the update.</p>
<p>The method does <em>not</em> offer in-Python cascading of relationships - it
is assumed that ON UPDATE CASCADE is configured for any foreign key
references which require it.</p>
<p>The Session needs to be expired (occurs automatically after commit(),
or call expire_all()) in order for the state of dependent objects
subject foreign key cascade to be correctly represented.</p>
<p>Also, the <tt class="docutils literal"><span class="pre">before_update()</span></tt> and <tt class="docutils literal"><span class="pre">after_update()</span></tt>
<a class="reference internal" href="interfaces.html#sqlalchemy.orm.interfaces.MapperExtension" title="sqlalchemy.orm.interfaces.MapperExtension"><tt class="xref py py-class docutils literal"><span class="pre">MapperExtension</span></tt></a> methods are not
called from this method. For an update hook here, use the
<tt class="docutils literal"><span class="pre">after_bulk_update()</span></tt>
<a class="reference internal" href="interfaces.html#sqlalchemy.orm.interfaces.SessionExtension" title="sqlalchemy.orm.interfaces.SessionExtension"><tt class="xref py py-class docutils literal"><span class="pre">SessionExtension</span></tt></a> method.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.value">
<tt class="descname">value</tt><big>(</big><em>column</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.value" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a scalar result corresponding to the given
column expression.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.values">
<tt class="descname">values</tt><big>(</big><em>*columns</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.values" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an iterator yielding result tuples corresponding
to the given list of columns</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.orm.query.Query.whereclause">
<tt class="descname">whereclause</tt><a class="headerlink" href="#sqlalchemy.orm.query.Query.whereclause" title="Permalink to this definition">¶</a></dt>
<dd><p>The WHERE criterion for this Query.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_hint">
<tt class="descname">with_hint</tt><big>(</big><em>selectable</em>, <em>text</em>, <em>dialect_name=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_hint" title="Permalink to this definition">¶</a></dt>
<dd><p>Add an indexing hint for the given entity or selectable to
this <tt class="xref py py-class docutils literal"><span class="pre">Query</span></tt>.</p>
<p>Functionality is passed straight through to
<a class="reference internal" href="../sqlalchemy/expressions.html#sqlalchemy.sql.expression.Select.with_hint" title="sqlalchemy.sql.expression.Select.with_hint"><tt class="xref py py-meth docutils literal"><span class="pre">with_hint()</span></tt></a>,
with the addition that <tt class="docutils literal"><span class="pre">selectable</span></tt> can be a
<tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt>, <tt class="xref py py-class docutils literal"><span class="pre">Alias</span></tt>, or ORM entity / mapped class
/etc.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_labels">
<tt class="descname">with_labels</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_labels" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply column labels to the return value of Query.statement.</p>
<p>Indicates that this Query’s <cite>statement</cite> accessor should return
a SELECT statement that applies labels to all columns in the
form <tablename>_<columnname>; this is commonly used to
disambiguate columns from multiple tables which have the same
name.</p>
<p>When the <cite>Query</cite> actually issues SQL to load rows, it always
uses column labeling.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_lockmode">
<tt class="descname">with_lockmode</tt><big>(</big><em>mode</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_lockmode" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new Query object with the specified locking mode.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_parent">
<tt class="descname">with_parent</tt><big>(</big><em>instance</em>, <em>property=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_parent" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a join criterion corresponding to a relationship to the given
parent instance.</p>
<dl class="docutils">
<dt>instance</dt>
<dd>a persistent or detached instance which is related to class
represented by this query.</dd>
<dt>property</dt>
<dd>string name of the property which relates this query’s class to the
instance. if None, the method will attempt to find a suitable
property.</dd>
</dl>
<p>Currently, this method only works with immediate parent relationships,
but in the future may be enhanced to work across a chain of parent
mappers.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.with_polymorphic">
<tt class="descname">with_polymorphic</tt><big>(</big><em>cls_or_mappers</em>, <em>selectable=None</em>, <em>discriminator=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.with_polymorphic" title="Permalink to this definition">¶</a></dt>
<dd><p>Load columns for descendant mappers of this Query’s mapper.</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>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>cls_or_mappers</strong> – a single class or mapper, or list of
class/mappers, which inherit from this Query’s mapper.
Alternatively, it may also be the string <tt class="docutils literal"><span class="pre">'*'</span></tt>, in which case
all descending mappers will be added to the FROM clause.</li>
<li><strong>selectable</strong> – 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 mappers use concrete table
inheritance, since SQLAlchemy currently cannot generate UNIONs
among tables automatically. If used, the <tt class="docutils literal"><span class="pre">selectable</span></tt> argument
must represent the full set of tables and columns mapped by every
desired mapper. Otherwise, the unaccounted mapped columns will
result in their table being appended directly to the FROM clause
which will usually lead to incorrect results.</li>
<li><strong>discriminator</strong> – a column to be used as the “discriminator”
column for the given selectable. If not given, the polymorphic_on
attribute of the mapper will be used, if any. This is useful for
mappers that don’t have polymorphic loading behavior by default,
such as concrete table mappers.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.orm.query.Query.yield_per">
<tt class="descname">yield_per</tt><big>(</big><em>count</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.query.Query.yield_per" title="Permalink to this definition">¶</a></dt>
<dd><p>Yield only <tt class="docutils literal"><span class="pre">count</span></tt> rows at a time.</p>
<p>WARNING: use this method with caution; if the same instance is present
in more than one batch of rows, end-user changes to attributes will be
overwritten.</p>
<p>In particular, it’s usually impossible to use this setting with
eagerly loaded collections (i.e. any lazy=’joined’ or ‘subquery’)
since those collections will be cleared for a new load when
encountered in a subsequent result batch. In the case of ‘subquery’
loading, the full result for all rows is fetched which generally
defeats the purpose of <a class="reference internal" href="#sqlalchemy.orm.query.Query.yield_per" title="sqlalchemy.orm.query.Query.yield_per"><tt class="xref py py-meth docutils literal"><span class="pre">yield_per()</span></tt></a>.</p>
<p>Also note that many DBAPIs do not “stream” results, pre-buffering
all rows before making them available, including mysql-python and
psycopg2. <a class="reference internal" href="#sqlalchemy.orm.query.Query.yield_per" title="sqlalchemy.orm.query.Query.yield_per"><tt class="xref py py-meth docutils literal"><span class="pre">yield_per()</span></tt></a> will also
set the <tt class="docutils literal"><span class="pre">stream_results</span></tt> execution
option to <tt class="xref docutils literal"><span class="pre">True</span></tt>, which currently is only understood by psycopg2
and causes server side cursors to be used.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="orm-specific-query-constructs">
<h2>ORM-Specific Query Constructs<a class="headerlink" href="#orm-specific-query-constructs" title="Permalink to this headline">¶</a></h2>
<dl class="attribute">
<dt id="sqlalchemy.orm.aliased">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">aliased</tt><a class="headerlink" href="#sqlalchemy.orm.aliased" title="Permalink to this definition">¶</a></dt>
<dd><p>alias of <tt class="xref py py-class docutils literal"><span class="pre">AliasedClass</span></tt></p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.orm.util.AliasedClass">
<em class="property">class </em><tt class="descclassname">sqlalchemy.orm.util.</tt><tt class="descname">AliasedClass</tt><big>(</big><em>cls</em>, <em>alias=None</em>, <em>name=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.util.AliasedClass" title="Permalink to this definition">¶</a></dt>
<dd><p>Represents an “aliased” form of a mapped class for usage with Query.</p>
<p>The ORM equivalent of a <a class="reference internal" href="../sqlalchemy/expressions.html#sqlalchemy.sql.expression.alias" title="sqlalchemy.sql.expression.alias"><tt class="xref py py-func docutils literal"><span class="pre">sqlalchemy.sql.expression.alias()</span></tt></a>
construct, this object mimics the mapped class using a
__getattr__ scheme and maintains a reference to a
real <a class="reference internal" href="../sqlalchemy/expressions.html#sqlalchemy.sql.expression.Alias" title="sqlalchemy.sql.expression.Alias"><tt class="xref py py-class docutils literal"><span class="pre">Alias</span></tt></a> object.</p>
<p>Usage is via the <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><tt class="xref py py-class docutils literal"><span class="pre">aliased()</span></tt></a> synonym:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># find all pairs of users with the same name</span>
<span class="n">user_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">User</span><span class="p">)</span>
<span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">user_alias</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">((</span><span class="n">user_alias</span><span class="p">,</span> <span class="n">User</span><span class="o">.</span><span class="n">id</span> <span class="o">></span> <span class="n">user_alias</span><span class="o">.</span><span class="n">id</span><span class="p">))</span><span class="o">.</span>\
<span class="nb">filter</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">name</span><span class="o">==</span><span class="n">user_alias</span><span class="o">.</span><span class="n">name</span><span class="p">)</span></pre></div>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.join">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">join</tt><big>(</big><em>left</em>, <em>right</em>, <em>onclause=None</em>, <em>isouter=False</em>, <em>join_to_left=True</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.join" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an inner join between left and right clauses.</p>
<p>In addition to the interface provided by
<a class="reference internal" href="../sqlalchemy/expressions.html#sqlalchemy.sql.expression.join" title="sqlalchemy.sql.expression.join"><tt class="xref py py-func docutils literal"><span class="pre">join()</span></tt></a>, left and right may be mapped
classes or AliasedClass instances. The onclause may be a
string name of a relationship(), or a class-bound descriptor
representing a relationship.</p>
<p>join_to_left indicates to attempt aliasing the ON clause,
in whatever form it is passed, to the selectable
passed as the left side. If False, the onclause
is used as is.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.outerjoin">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">outerjoin</tt><big>(</big><em>left</em>, <em>right</em>, <em>onclause=None</em>, <em>join_to_left=True</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.outerjoin" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a left outer join between left and right clauses.</p>
<p>In addition to the interface provided by
<a class="reference internal" href="../sqlalchemy/expressions.html#sqlalchemy.sql.expression.outerjoin" title="sqlalchemy.sql.expression.outerjoin"><tt class="xref py py-func docutils literal"><span class="pre">outerjoin()</span></tt></a>, left and right may be
mapped classes or AliasedClass instances. The onclause may be a string
name of a relationship(), or a class-bound descriptor representing a
relationship.</p>
</dd></dl>
</div>
<div class="section" id="query-options">
<h2>Query Options<a class="headerlink" href="#query-options" title="Permalink to this headline">¶</a></h2>
<p>Options which are passed to <tt class="docutils literal"><span class="pre">query.options()</span></tt>, to affect the behavior of loading.</p>
<dl class="function">
<dt id="sqlalchemy.orm.contains_alias">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">contains_alias</tt><big>(</big><em>alias</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.contains_alias" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <tt class="docutils literal"><span class="pre">MapperOption</span></tt> that will indicate to the query that
the main table has been aliased.</p>
<p><cite>alias</cite> is the string name or <tt class="docutils literal"><span class="pre">Alias</span></tt> object representing the
alias.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.contains_eager">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">contains_eager</tt><big>(</big><em>*keys</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.contains_eager" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <tt class="docutils literal"><span class="pre">MapperOption</span></tt> that will indicate to the query that
the given attribute should be eagerly loaded from columns currently
in the query.</p>
<p>Used with <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><tt class="xref py py-meth docutils literal"><span class="pre">options()</span></tt></a>.</p>
<p>The option is used in conjunction with an explicit join that loads
the desired rows, i.e.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Order</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">(</span><span class="n">Order</span><span class="o">.</span><span class="n">user</span><span class="p">)</span><span class="o">.</span>\
<span class="n">options</span><span class="p">(</span><span class="n">contains_eager</span><span class="p">(</span><span class="n">Order</span><span class="o">.</span><span class="n">user</span><span class="p">))</span></pre></div>
</div>
<p>The above query would join from the <tt class="docutils literal"><span class="pre">Order</span></tt> entity to its related
<tt class="docutils literal"><span class="pre">User</span></tt> entity, and the returned <tt class="docutils literal"><span class="pre">Order</span></tt> objects would have the
<tt class="docutils literal"><span class="pre">Order.user</span></tt> attribute pre-populated.</p>
<p><a class="reference internal" href="#sqlalchemy.orm.contains_eager" title="sqlalchemy.orm.contains_eager"><tt class="xref py py-func docutils literal"><span class="pre">contains_eager()</span></tt></a> also accepts an <cite>alias</cite> argument, which
is the string name of an alias, an <a class="reference internal" href="../sqlalchemy/expressions.html#sqlalchemy.sql.expression.alias" title="sqlalchemy.sql.expression.alias"><tt class="xref py py-func docutils literal"><span class="pre">alias()</span></tt></a>
construct, or an <a class="reference internal" href="#sqlalchemy.orm.aliased" title="sqlalchemy.orm.aliased"><tt class="xref py py-func docutils literal"><span class="pre">aliased()</span></tt></a> construct. Use this
when the eagerly-loaded rows are to come from an aliased table:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">user_alias</span> <span class="o">=</span> <span class="n">aliased</span><span class="p">(</span><span class="n">User</span><span class="p">)</span>
<span class="n">sess</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">Order</span><span class="p">)</span><span class="o">.</span>\
<span class="n">join</span><span class="p">((</span><span class="n">user_alias</span><span class="p">,</span> <span class="n">Order</span><span class="o">.</span><span class="n">user</span><span class="p">))</span><span class="o">.</span>\
<span class="n">options</span><span class="p">(</span><span class="n">contains_eager</span><span class="p">(</span><span class="n">Order</span><span class="o">.</span><span class="n">user</span><span class="p">,</span> <span class="n">alias</span><span class="o">=</span><span class="n">user_alias</span><span class="p">))</span></pre></div>
</div>
<p>See also <a class="reference internal" href="#sqlalchemy.orm.eagerload" title="sqlalchemy.orm.eagerload"><tt class="xref py py-func docutils literal"><span class="pre">eagerload()</span></tt></a> for the “automatic” version of this
functionality.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.defer">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">defer</tt><big>(</big><em>*keys</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.defer" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <tt class="docutils literal"><span class="pre">MapperOption</span></tt> that will convert the column property of the
given name into a deferred load.</p>
<p>Used with <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><tt class="xref py py-meth docutils literal"><span class="pre">options()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.eagerload">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">eagerload</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.eagerload" title="Permalink to this definition">¶</a></dt>
<dd><p>A synonym for <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>.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.eagerload_all">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">eagerload_all</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.eagerload_all" title="Permalink to this definition">¶</a></dt>
<dd><p>A synonym for <a class="reference internal" href="#sqlalchemy.orm.joinedload_all" title="sqlalchemy.orm.joinedload_all"><tt class="xref py py-func docutils literal"><span class="pre">joinedload_all()</span></tt></a></p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.extension">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">extension</tt><big>(</big><em>ext</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.extension" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <tt class="docutils literal"><span class="pre">MapperOption</span></tt> that will insert the given
<tt class="docutils literal"><span class="pre">MapperExtension</span></tt> to the beginning of the list of extensions
that will be called in the context of the <tt class="docutils literal"><span class="pre">Query</span></tt>.</p>
<p>Used with <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><tt class="xref py py-meth docutils literal"><span class="pre">options()</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.joinedload">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">joinedload</tt><big>(</big><em>*keys</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.joinedload" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <tt class="docutils literal"><span class="pre">MapperOption</span></tt> that will convert the property of the given
name into an joined eager load.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is known as <a class="reference internal" href="#sqlalchemy.orm.eagerload" title="sqlalchemy.orm.eagerload"><tt class="xref py py-func docutils literal"><span class="pre">eagerload()</span></tt></a> in all versions
of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 series.
<a class="reference internal" href="#sqlalchemy.orm.eagerload" title="sqlalchemy.orm.eagerload"><tt class="xref py py-func docutils literal"><span class="pre">eagerload()</span></tt></a> will remain available for
the foreseeable future in order to enable cross-compatibility.</p>
</div>
<p>Used with <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><tt class="xref py py-meth docutils literal"><span class="pre">options()</span></tt></a>.</p>
<p>examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># joined-load the "orders" colleciton on "User"</span>
<span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">joinedload</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="c"># joined-load the "keywords" collection on each "Item",</span>
<span class="c"># but not the "items" collection on "Order" - those </span>
<span class="c"># remain lazily loaded.</span>
<span class="n">query</span><span class="p">(</span><span class="n">Order</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">joinedload</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>
<span class="c"># to joined-load across both, use joinedload_all()</span>
<span class="n">query</span><span class="p">(</span><span class="n">Order</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">joinedload_all</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>
</div>
<p><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> also accepts a keyword argument <cite>innerjoin=True</cite> which
indicates using an inner join instead of an outer:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">query</span><span class="p">(</span><span class="n">Order</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">joinedload</span><span class="p">(</span><span class="n">Order</span><span class="o">.</span><span class="n">user</span><span class="p">,</span> <span class="n">innerjoin</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span></pre></div>
</div>
<p>Note that the join created by <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 aliased such that
no other aspects of the query will affect what it loads. To use joined eager
loading with a join that is constructed manually using <a class="reference internal" href="#sqlalchemy.orm.query.Query.join" title="sqlalchemy.orm.query.Query.join"><tt class="xref py py-meth docutils literal"><span class="pre">join()</span></tt></a>
or <a class="reference internal" href="#sqlalchemy.orm.join" title="sqlalchemy.orm.join"><tt class="xref py py-func docutils literal"><span class="pre">join()</span></tt></a>, see <a class="reference internal" href="#sqlalchemy.orm.contains_eager" title="sqlalchemy.orm.contains_eager"><tt class="xref py py-func docutils literal"><span class="pre">contains_eager()</span></tt></a>.</p>
<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>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.joinedload_all">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">joinedload_all</tt><big>(</big><em>*keys</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.joinedload_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <tt class="docutils literal"><span class="pre">MapperOption</span></tt> that will convert all properties along the
given dot-separated path into an joined eager load.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is known as <a class="reference internal" href="#sqlalchemy.orm.eagerload_all" title="sqlalchemy.orm.eagerload_all"><tt class="xref py py-func docutils literal"><span class="pre">eagerload_all()</span></tt></a> in all versions
of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 series.
<a class="reference internal" href="#sqlalchemy.orm.eagerload_all" title="sqlalchemy.orm.eagerload_all"><tt class="xref py py-func docutils literal"><span class="pre">eagerload_all()</span></tt></a> will remain available for
the foreseeable future in order to enable cross-compatibility.</p>
</div>
<p>Used with <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><tt class="xref py py-meth docutils literal"><span class="pre">options()</span></tt></a>.</p>
<p>For example:</p>
<div class="highlight-python"><pre>query.options(joinedload_all('orders.items.keywords'))...</pre>
</div>
<p>will set all of ‘orders’, ‘orders.items’, and ‘orders.items.keywords’ to
load in one joined eager load.</p>
<p>Individual descriptors are accepted as arguments as well:</p>
<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>
</div>
<p>The keyword arguments accept a flag <cite>innerjoin=True|False</cite> which will
override the value of the <cite>innerjoin</cite> flag specified on the relationship().</p>
<p>See also: <a class="reference internal" href="#sqlalchemy.orm.subqueryload_all" title="sqlalchemy.orm.subqueryload_all"><tt class="xref py py-func docutils literal"><span class="pre">subqueryload_all()</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>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.lazyload">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">lazyload</tt><big>(</big><em>*keys</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.lazyload" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <tt class="docutils literal"><span class="pre">MapperOption</span></tt> that will convert the property of the given
name into a lazy load.</p>
<p>Used with <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><tt class="xref py py-meth docutils literal"><span class="pre">options()</span></tt></a>.</p>
<p>See also: <a class="reference internal" href="#sqlalchemy.orm.eagerload" title="sqlalchemy.orm.eagerload"><tt class="xref py py-func docutils literal"><span class="pre">eagerload()</span></tt></a>, <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></p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.subqueryload">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">subqueryload</tt><big>(</big><em>*keys</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.subqueryload" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <tt class="docutils literal"><span class="pre">MapperOption</span></tt> that will convert the property
of the given name into an subquery eager load.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is new as of SQLAlchemy version 0.6beta3.</p>
</div>
<p>Used with <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><tt class="xref py py-meth docutils literal"><span class="pre">options()</span></tt></a>.</p>
<p>examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># subquery-load the "orders" colleciton on "User"</span>
<span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">subqueryload</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="c"># subquery-load the "keywords" collection on each "Item",</span>
<span class="c"># but not the "items" collection on "Order" - those </span>
<span class="c"># remain lazily loaded.</span>
<span class="n">query</span><span class="p">(</span><span class="n">Order</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">subqueryload</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>
<span class="c"># to subquery-load across both, use subqueryload_all()</span>
<span class="n">query</span><span class="p">(</span><span class="n">Order</span><span class="p">)</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">subqueryload_all</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>
</div>
<p>See also: <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>, <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>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.subqueryload_all">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">subqueryload_all</tt><big>(</big><em>*keys</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.subqueryload_all" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <tt class="docutils literal"><span class="pre">MapperOption</span></tt> that will convert all properties along the
given dot-separated path into a subquery eager load.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is new as of SQLAlchemy version 0.6beta3.</p>
</div>
<p>Used with <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><tt class="xref py py-meth docutils literal"><span class="pre">options()</span></tt></a>.</p>
<p>For example:</p>
<div class="highlight-python"><pre>query.options(subqueryload_all('orders.items.keywords'))...</pre>
</div>
<p>will set all of ‘orders’, ‘orders.items’, and ‘orders.items.keywords’ to
load in one subquery eager load.</p>
<p>Individual descriptors are accepted as arguments as well:</p>
<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> <span class="n">Item</span><span class="o">.</span><span class="n">keywords</span><span class="p">))</span></pre></div>
</div>
<p>See also: <a class="reference internal" href="#sqlalchemy.orm.joinedload_all" title="sqlalchemy.orm.joinedload_all"><tt class="xref py py-func docutils literal"><span class="pre">joinedload_all()</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>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.orm.undefer">
<tt class="descclassname">sqlalchemy.orm.</tt><tt class="descname">undefer</tt><big>(</big><em>*keys</em><big>)</big><a class="headerlink" href="#sqlalchemy.orm.undefer" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <tt class="docutils literal"><span class="pre">MapperOption</span></tt> that will convert the column property of the
given name into a non-deferred (regular column) load.</p>
<p>Used with <a class="reference internal" href="#sqlalchemy.orm.query.Query.options" title="sqlalchemy.orm.query.Query.options"><tt class="xref py py-meth docutils literal"><span class="pre">options()</span></tt></a>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="bottomnav">
<div class="prevnext">
Previous:
<a href="collections.html" title="previous chapter">Collection Mapping</a>
Next:
<a href="sessions.html" title="next chapter">Sessions</a>
</div>
<div class="doc_copyright">
© Copyright 2007, 2008, 2009, 2010, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0b2+.
</div>
</div>
</body>
</html>
|
