Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# orm/context.py
2# Copyright (C) 2005-2025 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
7# mypy: ignore-errors
9from __future__ import annotations
11import collections
12import itertools
13from typing import Any
14from typing import cast
15from typing import Dict
16from typing import Iterable
17from typing import List
18from typing import Optional
19from typing import Set
20from typing import Tuple
21from typing import Type
22from typing import TYPE_CHECKING
23from typing import TypeVar
24from typing import Union
26from . import attributes
27from . import interfaces
28from . import loading
29from .base import _is_aliased_class
30from .interfaces import ORMColumnDescription
31from .interfaces import ORMColumnsClauseRole
32from .path_registry import PathRegistry
33from .util import _entity_corresponds_to
34from .util import _ORMJoin
35from .util import _TraceAdaptRole
36from .util import AliasedClass
37from .util import Bundle
38from .util import ORMAdapter
39from .util import ORMStatementAdapter
40from .. import exc as sa_exc
41from .. import future
42from .. import inspect
43from .. import sql
44from .. import util
45from ..sql import coercions
46from ..sql import expression
47from ..sql import roles
48from ..sql import util as sql_util
49from ..sql import visitors
50from ..sql._typing import is_dml
51from ..sql._typing import is_insert_update
52from ..sql._typing import is_select_base
53from ..sql.base import _select_iterables
54from ..sql.base import CacheableOptions
55from ..sql.base import CompileState
56from ..sql.base import Executable
57from ..sql.base import Generative
58from ..sql.base import Options
59from ..sql.dml import UpdateBase
60from ..sql.elements import GroupedElement
61from ..sql.elements import TextClause
62from ..sql.selectable import CompoundSelectState
63from ..sql.selectable import LABEL_STYLE_DISAMBIGUATE_ONLY
64from ..sql.selectable import LABEL_STYLE_NONE
65from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL
66from ..sql.selectable import Select
67from ..sql.selectable import SelectLabelStyle
68from ..sql.selectable import SelectState
69from ..sql.selectable import TypedReturnsRows
70from ..sql.visitors import InternalTraversal
71from ..util.typing import TupleAny
72from ..util.typing import TypeVarTuple
73from ..util.typing import Unpack
76if TYPE_CHECKING:
77 from ._typing import _InternalEntityType
78 from ._typing import OrmExecuteOptionsParameter
79 from .loading import _PostLoad
80 from .mapper import Mapper
81 from .query import Query
82 from .session import _BindArguments
83 from .session import Session
84 from ..engine import Result
85 from ..engine.interfaces import _CoreSingleExecuteParams
86 from ..sql._typing import _ColumnsClauseArgument
87 from ..sql.compiler import SQLCompiler
88 from ..sql.dml import _DMLTableElement
89 from ..sql.elements import ColumnElement
90 from ..sql.selectable import _JoinTargetElement
91 from ..sql.selectable import _LabelConventionCallable
92 from ..sql.selectable import _SetupJoinsElement
93 from ..sql.selectable import ExecutableReturnsRows
94 from ..sql.selectable import SelectBase
95 from ..sql.type_api import TypeEngine
97_T = TypeVar("_T", bound=Any)
98_Ts = TypeVarTuple("_Ts")
99_path_registry = PathRegistry.root
101_EMPTY_DICT = util.immutabledict()
104LABEL_STYLE_LEGACY_ORM = SelectLabelStyle.LABEL_STYLE_LEGACY_ORM
107class QueryContext:
108 __slots__ = (
109 "top_level_context",
110 "compile_state",
111 "query",
112 "user_passed_query",
113 "params",
114 "load_options",
115 "bind_arguments",
116 "execution_options",
117 "session",
118 "autoflush",
119 "populate_existing",
120 "invoke_all_eagers",
121 "version_check",
122 "refresh_state",
123 "create_eager_joins",
124 "propagated_loader_options",
125 "attributes",
126 "runid",
127 "partials",
128 "post_load_paths",
129 "identity_token",
130 "yield_per",
131 "loaders_require_buffering",
132 "loaders_require_uniquing",
133 )
135 runid: int
136 post_load_paths: Dict[PathRegistry, _PostLoad]
137 compile_state: _ORMCompileState
139 class default_load_options(Options):
140 _only_return_tuples = False
141 _populate_existing = False
142 _version_check = False
143 _invoke_all_eagers = True
144 _autoflush = True
145 _identity_token = None
146 _yield_per = None
147 _refresh_state = None
148 _lazy_loaded_from = None
149 _legacy_uniquing = False
150 _sa_top_level_orm_context = None
151 _is_user_refresh = False
153 def __init__(
154 self,
155 compile_state: CompileState,
156 statement: Union[
157 Select[Unpack[TupleAny]],
158 FromStatement[Unpack[TupleAny]],
159 UpdateBase,
160 ],
161 user_passed_query: Union[
162 Select[Unpack[TupleAny]],
163 FromStatement[Unpack[TupleAny]],
164 UpdateBase,
165 ],
166 params: _CoreSingleExecuteParams,
167 session: Session,
168 load_options: Union[
169 Type[QueryContext.default_load_options],
170 QueryContext.default_load_options,
171 ],
172 execution_options: Optional[OrmExecuteOptionsParameter] = None,
173 bind_arguments: Optional[_BindArguments] = None,
174 ):
175 self.load_options = load_options
176 self.execution_options = execution_options or _EMPTY_DICT
177 self.bind_arguments = bind_arguments or _EMPTY_DICT
178 self.compile_state = compile_state
179 self.query = statement
181 # the query that the end user passed to Session.execute() or similar.
182 # this is usually the same as .query, except in the bulk_persistence
183 # routines where a separate FromStatement is manufactured in the
184 # compile stage; this allows differentiation in that case.
185 self.user_passed_query = user_passed_query
187 self.session = session
188 self.loaders_require_buffering = False
189 self.loaders_require_uniquing = False
190 self.params = params
191 self.top_level_context = load_options._sa_top_level_orm_context
193 cached_options = compile_state.select_statement._with_options
194 uncached_options = user_passed_query._with_options
196 # see issue #7447 , #8399 for some background
197 # propagated loader options will be present on loaded InstanceState
198 # objects under state.load_options and are typically used by
199 # LazyLoader to apply options to the SELECT statement it emits.
200 # For compile state options (i.e. loader strategy options), these
201 # need to line up with the ".load_path" attribute which in
202 # loader.py is pulled from context.compile_state.current_path.
203 # so, this means these options have to be the ones from the
204 # *cached* statement that's travelling with compile_state, not the
205 # *current* statement which won't match up for an ad-hoc
206 # AliasedClass
207 self.propagated_loader_options = tuple(
208 opt._adapt_cached_option_to_uncached_option(self, uncached_opt)
209 for opt, uncached_opt in zip(cached_options, uncached_options)
210 if opt.propagate_to_loaders
211 )
213 self.attributes = dict(compile_state.attributes)
215 self.autoflush = load_options._autoflush
216 self.populate_existing = load_options._populate_existing
217 self.invoke_all_eagers = load_options._invoke_all_eagers
218 self.version_check = load_options._version_check
219 self.refresh_state = load_options._refresh_state
220 self.yield_per = load_options._yield_per
221 self.identity_token = load_options._identity_token
223 def _get_top_level_context(self) -> QueryContext:
224 return self.top_level_context or self
227_orm_load_exec_options = util.immutabledict(
228 {"_result_disable_adapt_to_context": True}
229)
232class _AbstractORMCompileState(CompileState):
233 is_dml_returning = False
235 def _init_global_attributes(
236 self, statement, compiler, *, toplevel, process_criteria_for_toplevel
237 ):
238 self.attributes = {}
240 if compiler is None:
241 # this is the legacy / testing only ORM _compile_state() use case.
242 # there is no need to apply criteria options for this.
243 self.global_attributes = {}
244 assert toplevel
245 return
246 else:
247 self.global_attributes = ga = compiler._global_attributes
249 if toplevel:
250 ga["toplevel_orm"] = True
252 if process_criteria_for_toplevel:
253 for opt in statement._with_options:
254 if opt._is_criteria_option:
255 opt.process_compile_state(self)
257 return
258 elif ga.get("toplevel_orm", False):
259 return
261 stack_0 = compiler.stack[0]
263 try:
264 toplevel_stmt = stack_0["selectable"]
265 except KeyError:
266 pass
267 else:
268 for opt in toplevel_stmt._with_options:
269 if opt._is_compile_state and opt._is_criteria_option:
270 opt.process_compile_state(self)
272 ga["toplevel_orm"] = True
274 @classmethod
275 def create_for_statement(
276 cls,
277 statement: Executable,
278 compiler: SQLCompiler,
279 **kw: Any,
280 ) -> CompileState:
281 """Create a context for a statement given a :class:`.Compiler`.
283 This method is always invoked in the context of SQLCompiler.process().
285 For a Select object, this would be invoked from
286 SQLCompiler.visit_select(). For the special FromStatement object used
287 by Query to indicate "Query.from_statement()", this is called by
288 FromStatement._compiler_dispatch() that would be called by
289 SQLCompiler.process().
290 """
291 return super().create_for_statement(statement, compiler, **kw)
293 @classmethod
294 def orm_pre_session_exec(
295 cls,
296 session,
297 statement,
298 params,
299 execution_options,
300 bind_arguments,
301 is_pre_event,
302 ):
303 raise NotImplementedError()
305 @classmethod
306 def orm_execute_statement(
307 cls,
308 session,
309 statement,
310 params,
311 execution_options,
312 bind_arguments,
313 conn,
314 ) -> Result:
315 result = conn.execute(
316 statement, params or {}, execution_options=execution_options
317 )
318 return cls.orm_setup_cursor_result(
319 session,
320 statement,
321 params,
322 execution_options,
323 bind_arguments,
324 result,
325 )
327 @classmethod
328 def orm_setup_cursor_result(
329 cls,
330 session,
331 statement,
332 params,
333 execution_options,
334 bind_arguments,
335 result,
336 ):
337 raise NotImplementedError()
340class _AutoflushOnlyORMCompileState(_AbstractORMCompileState):
341 """ORM compile state that is a passthrough, except for autoflush."""
343 @classmethod
344 def orm_pre_session_exec(
345 cls,
346 session,
347 statement,
348 params,
349 execution_options,
350 bind_arguments,
351 is_pre_event,
352 ):
353 # consume result-level load_options. These may have been set up
354 # in an ORMExecuteState hook
355 (
356 load_options,
357 execution_options,
358 ) = QueryContext.default_load_options.from_execution_options(
359 "_sa_orm_load_options",
360 {
361 "autoflush",
362 },
363 execution_options,
364 statement._execution_options,
365 )
367 if not is_pre_event and load_options._autoflush:
368 session._autoflush()
370 return statement, execution_options
372 @classmethod
373 def orm_setup_cursor_result(
374 cls,
375 session,
376 statement,
377 params,
378 execution_options,
379 bind_arguments,
380 result,
381 ):
382 return result
385class _ORMCompileState(_AbstractORMCompileState):
386 class default_compile_options(CacheableOptions):
387 _cache_key_traversal = [
388 ("_use_legacy_query_style", InternalTraversal.dp_boolean),
389 ("_for_statement", InternalTraversal.dp_boolean),
390 ("_bake_ok", InternalTraversal.dp_boolean),
391 ("_current_path", InternalTraversal.dp_has_cache_key),
392 ("_enable_single_crit", InternalTraversal.dp_boolean),
393 ("_enable_eagerloads", InternalTraversal.dp_boolean),
394 ("_only_load_props", InternalTraversal.dp_plain_obj),
395 ("_set_base_alias", InternalTraversal.dp_boolean),
396 ("_for_refresh_state", InternalTraversal.dp_boolean),
397 ("_render_for_subquery", InternalTraversal.dp_boolean),
398 ("_is_star", InternalTraversal.dp_boolean),
399 ]
401 # set to True by default from Query._statement_20(), to indicate
402 # the rendered query should look like a legacy ORM query. right
403 # now this basically indicates we should use tablename_columnname
404 # style labels. Generally indicates the statement originated
405 # from a Query object.
406 _use_legacy_query_style = False
408 # set *only* when we are coming from the Query.statement
409 # accessor, or a Query-level equivalent such as
410 # query.subquery(). this supersedes "toplevel".
411 _for_statement = False
413 _bake_ok = True
414 _current_path = _path_registry
415 _enable_single_crit = True
416 _enable_eagerloads = True
417 _only_load_props = None
418 _set_base_alias = False
419 _for_refresh_state = False
420 _render_for_subquery = False
421 _is_star = False
423 attributes: Dict[Any, Any]
424 global_attributes: Dict[Any, Any]
426 statement: Union[
427 Select[Unpack[TupleAny]], FromStatement[Unpack[TupleAny]], UpdateBase
428 ]
429 select_statement: Union[
430 Select[Unpack[TupleAny]], FromStatement[Unpack[TupleAny]]
431 ]
432 _entities: List[_QueryEntity]
433 _polymorphic_adapters: Dict[_InternalEntityType, ORMAdapter]
434 compile_options: Union[
435 Type[default_compile_options], default_compile_options
436 ]
437 _primary_entity: Optional[_QueryEntity]
438 use_legacy_query_style: bool
439 _label_convention: _LabelConventionCallable
440 primary_columns: List[ColumnElement[Any]]
441 secondary_columns: List[ColumnElement[Any]]
442 dedupe_columns: Set[ColumnElement[Any]]
443 create_eager_joins: List[
444 # TODO: this structure is set up by JoinedLoader
445 TupleAny
446 ]
447 current_path: PathRegistry = _path_registry
448 _has_mapper_entities = False
450 def __init__(self, *arg, **kw):
451 raise NotImplementedError()
453 @classmethod
454 def create_for_statement(
455 cls,
456 statement: Executable,
457 compiler: SQLCompiler,
458 **kw: Any,
459 ) -> _ORMCompileState:
460 return cls._create_orm_context(
461 cast("Union[Select, FromStatement]", statement),
462 toplevel=not compiler.stack,
463 compiler=compiler,
464 **kw,
465 )
467 @classmethod
468 def _create_orm_context(
469 cls,
470 statement: Union[Select, FromStatement],
471 *,
472 toplevel: bool,
473 compiler: Optional[SQLCompiler],
474 **kw: Any,
475 ) -> _ORMCompileState:
476 raise NotImplementedError()
478 def _append_dedupe_col_collection(self, obj, col_collection):
479 dedupe = self.dedupe_columns
480 if obj not in dedupe:
481 dedupe.add(obj)
482 col_collection.append(obj)
484 @classmethod
485 def _column_naming_convention(
486 cls, label_style: SelectLabelStyle, legacy: bool
487 ) -> _LabelConventionCallable:
488 if legacy:
490 def name(col, col_name=None):
491 if col_name:
492 return col_name
493 else:
494 return getattr(col, "key")
496 return name
497 else:
498 return SelectState._column_naming_convention(label_style)
500 @classmethod
501 def get_column_descriptions(cls, statement):
502 return _column_descriptions(statement)
504 @classmethod
505 def orm_pre_session_exec(
506 cls,
507 session,
508 statement,
509 params,
510 execution_options,
511 bind_arguments,
512 is_pre_event,
513 ):
514 # consume result-level load_options. These may have been set up
515 # in an ORMExecuteState hook
516 (
517 load_options,
518 execution_options,
519 ) = QueryContext.default_load_options.from_execution_options(
520 "_sa_orm_load_options",
521 {
522 "populate_existing",
523 "autoflush",
524 "yield_per",
525 "identity_token",
526 "sa_top_level_orm_context",
527 },
528 execution_options,
529 statement._execution_options,
530 )
532 # default execution options for ORM results:
533 # 1. _result_disable_adapt_to_context=True
534 # this will disable the ResultSetMetadata._adapt_to_context()
535 # step which we don't need, as we have result processors cached
536 # against the original SELECT statement before caching.
538 if "sa_top_level_orm_context" in execution_options:
539 ctx = execution_options["sa_top_level_orm_context"]
540 execution_options = ctx.query._execution_options.merge_with(
541 ctx.execution_options, execution_options
542 )
544 if not execution_options:
545 execution_options = _orm_load_exec_options
546 else:
547 execution_options = execution_options.union(_orm_load_exec_options)
549 # would have been placed here by legacy Query only
550 if load_options._yield_per:
551 execution_options = execution_options.union(
552 {"yield_per": load_options._yield_per}
553 )
555 if (
556 getattr(statement._compile_options, "_current_path", None)
557 and len(statement._compile_options._current_path) > 10
558 and execution_options.get("compiled_cache", True) is not None
559 ):
560 execution_options: util.immutabledict[str, Any] = (
561 execution_options.union(
562 {
563 "compiled_cache": None,
564 "_cache_disable_reason": "excess depth for "
565 "ORM loader options",
566 }
567 )
568 )
570 bind_arguments["clause"] = statement
572 # new in 1.4 - the coercions system is leveraged to allow the
573 # "subject" mapper of a statement be propagated to the top
574 # as the statement is built. "subject" mapper is the generally
575 # standard object used as an identifier for multi-database schemes.
577 # we are here based on the fact that _propagate_attrs contains
578 # "compile_state_plugin": "orm". The "plugin_subject"
579 # needs to be present as well.
581 try:
582 plugin_subject = statement._propagate_attrs["plugin_subject"]
583 except KeyError:
584 assert False, "statement had 'orm' plugin but no plugin_subject"
585 else:
586 if plugin_subject:
587 bind_arguments["mapper"] = plugin_subject.mapper
589 if not is_pre_event and load_options._autoflush:
590 session._autoflush()
592 return statement, execution_options
594 @classmethod
595 def orm_setup_cursor_result(
596 cls,
597 session,
598 statement,
599 params,
600 execution_options,
601 bind_arguments,
602 result,
603 ):
604 execution_context = result.context
605 compile_state = execution_context.compiled.compile_state
607 # cover edge case where ORM entities used in legacy select
608 # were passed to session.execute:
609 # session.execute(legacy_select([User.id, User.name]))
610 # see test_query->test_legacy_tuple_old_select
612 load_options = execution_options.get(
613 "_sa_orm_load_options", QueryContext.default_load_options
614 )
616 if compile_state.compile_options._is_star:
617 return result
619 querycontext = QueryContext(
620 compile_state,
621 statement,
622 statement,
623 params,
624 session,
625 load_options,
626 execution_options,
627 bind_arguments,
628 )
629 return loading.instances(result, querycontext)
631 @property
632 def _lead_mapper_entities(self):
633 """return all _MapperEntity objects in the lead entities collection.
635 Does **not** include entities that have been replaced by
636 with_entities(), with_only_columns()
638 """
639 return [
640 ent for ent in self._entities if isinstance(ent, _MapperEntity)
641 ]
643 def _create_with_polymorphic_adapter(self, ext_info, selectable):
644 """given MapperEntity or ORMColumnEntity, setup polymorphic loading
645 if called for by the Mapper.
647 As of #8168 in 2.0.0rc1, polymorphic adapters, which greatly increase
648 the complexity of the query creation process, are not used at all
649 except in the quasi-legacy cases of with_polymorphic referring to an
650 alias and/or subquery. This would apply to concrete polymorphic
651 loading, and joined inheritance where a subquery is
652 passed to with_polymorphic (which is completely unnecessary in modern
653 use).
655 TODO: What is a "quasi-legacy" case? Do we need this method with
656 2.0 style select() queries or not? Why is with_polymorphic referring
657 to an alias or subquery "legacy" ?
659 """
660 if (
661 not ext_info.is_aliased_class
662 and ext_info.mapper.persist_selectable
663 not in self._polymorphic_adapters
664 ):
665 for mp in ext_info.mapper.iterate_to_root():
666 self._mapper_loads_polymorphically_with(
667 mp,
668 ORMAdapter(
669 _TraceAdaptRole.WITH_POLYMORPHIC_ADAPTER,
670 mp,
671 equivalents=mp._equivalent_columns,
672 selectable=selectable,
673 ),
674 )
676 def _mapper_loads_polymorphically_with(self, mapper, adapter):
677 for m2 in mapper._with_polymorphic_mappers or [mapper]:
678 self._polymorphic_adapters[m2] = adapter
680 for m in m2.iterate_to_root():
681 self._polymorphic_adapters[m.local_table] = adapter
683 @classmethod
684 def _create_entities_collection(cls, query, legacy):
685 raise NotImplementedError(
686 "this method only works for ORMSelectCompileState"
687 )
690class _DMLReturningColFilter:
691 """a base for an adapter used for the DML RETURNING cases
693 Has a subset of the interface used by
694 :class:`.ORMAdapter` and is used for :class:`._QueryEntity`
695 instances to set up their columns as used in RETURNING for a
696 DML statement.
698 """
700 __slots__ = ("mapper", "columns", "__weakref__")
702 def __init__(self, target_mapper, immediate_dml_mapper):
703 if (
704 immediate_dml_mapper is not None
705 and target_mapper.local_table
706 is not immediate_dml_mapper.local_table
707 ):
708 # joined inh, or in theory other kinds of multi-table mappings
709 self.mapper = immediate_dml_mapper
710 else:
711 # single inh, normal mappings, etc.
712 self.mapper = target_mapper
713 self.columns = self.columns = util.WeakPopulateDict(
714 self.adapt_check_present # type: ignore
715 )
717 def __call__(self, col, as_filter):
718 for cc in sql_util._find_columns(col):
719 c2 = self.adapt_check_present(cc)
720 if c2 is not None:
721 return col
722 else:
723 return None
725 def adapt_check_present(self, col):
726 raise NotImplementedError()
729class _DMLBulkInsertReturningColFilter(_DMLReturningColFilter):
730 """an adapter used for the DML RETURNING case specifically
731 for ORM bulk insert (or any hypothetical DML that is splitting out a class
732 hierarchy among multiple DML statements....ORM bulk insert is the only
733 example right now)
735 its main job is to limit the columns in a RETURNING to only a specific
736 mapped table in a hierarchy.
738 """
740 def adapt_check_present(self, col):
741 mapper = self.mapper
742 prop = mapper._columntoproperty.get(col, None)
743 if prop is None:
744 return None
745 return mapper.local_table.c.corresponding_column(col)
748class _DMLUpdateDeleteReturningColFilter(_DMLReturningColFilter):
749 """an adapter used for the DML RETURNING case specifically
750 for ORM enabled UPDATE/DELETE
752 its main job is to limit the columns in a RETURNING to include
753 only direct persisted columns from the immediate selectable, not
754 expressions like column_property(), or to also allow columns from other
755 mappers for the UPDATE..FROM use case.
757 """
759 def adapt_check_present(self, col):
760 mapper = self.mapper
761 prop = mapper._columntoproperty.get(col, None)
762 if prop is not None:
763 # if the col is from the immediate mapper, only return a persisted
764 # column, not any kind of column_property expression
765 return mapper.persist_selectable.c.corresponding_column(col)
767 # if the col is from some other mapper, just return it, assume the
768 # user knows what they are doing
769 return col
772@sql.base.CompileState.plugin_for("orm", "orm_from_statement")
773class _ORMFromStatementCompileState(_ORMCompileState):
774 _from_obj_alias = None
775 _has_mapper_entities = False
777 statement_container: FromStatement
778 requested_statement: Union[SelectBase, TextClause, UpdateBase]
779 dml_table: Optional[_DMLTableElement] = None
781 _has_orm_entities = False
782 multi_row_eager_loaders = False
783 eager_adding_joins = False
784 compound_eager_adapter = None
786 extra_criteria_entities = _EMPTY_DICT
787 eager_joins = _EMPTY_DICT
789 @classmethod
790 def _create_orm_context(
791 cls,
792 statement: Union[Select, FromStatement],
793 *,
794 toplevel: bool,
795 compiler: Optional[SQLCompiler],
796 **kw: Any,
797 ) -> _ORMFromStatementCompileState:
798 statement_container = statement
800 assert isinstance(statement_container, FromStatement)
802 if compiler is not None and compiler.stack:
803 raise sa_exc.CompileError(
804 "The ORM FromStatement construct only supports being "
805 "invoked as the topmost statement, as it is only intended to "
806 "define how result rows should be returned."
807 )
809 self = cls.__new__(cls)
810 self._primary_entity = None
812 self.use_legacy_query_style = (
813 statement_container._compile_options._use_legacy_query_style
814 )
815 self.statement_container = self.select_statement = statement_container
816 self.requested_statement = statement = statement_container.element
818 if statement.is_dml:
819 self.dml_table = statement.table
820 self.is_dml_returning = True
822 self._entities = []
823 self._polymorphic_adapters = {}
825 self.compile_options = statement_container._compile_options
827 if (
828 self.use_legacy_query_style
829 and isinstance(statement, expression.SelectBase)
830 and not statement._is_textual
831 and not statement.is_dml
832 and statement._label_style is LABEL_STYLE_NONE
833 ):
834 self.statement = statement.set_label_style(
835 LABEL_STYLE_TABLENAME_PLUS_COL
836 )
837 else:
838 self.statement = statement
840 self._label_convention = self._column_naming_convention(
841 (
842 statement._label_style
843 if not statement._is_textual and not statement.is_dml
844 else LABEL_STYLE_NONE
845 ),
846 self.use_legacy_query_style,
847 )
849 _QueryEntity.to_compile_state(
850 self,
851 statement_container._raw_columns,
852 self._entities,
853 is_current_entities=True,
854 )
856 self.current_path = statement_container._compile_options._current_path
858 self._init_global_attributes(
859 statement_container,
860 compiler,
861 process_criteria_for_toplevel=False,
862 toplevel=True,
863 )
865 if statement_container._with_options:
866 for opt in statement_container._with_options:
867 if opt._is_compile_state:
868 opt.process_compile_state(self)
870 if statement_container._compile_state_funcs:
871 for fn, key in statement_container._compile_state_funcs:
872 fn(self)
874 self.primary_columns = []
875 self.secondary_columns = []
876 self.dedupe_columns = set()
877 self.create_eager_joins = []
878 self._fallback_from_clauses = []
880 self.order_by = None
882 if isinstance(self.statement, expression.TextClause):
883 # TextClause has no "column" objects at all. for this case,
884 # we generate columns from our _QueryEntity objects, then
885 # flip on all the "please match no matter what" parameters.
886 self.extra_criteria_entities = {}
888 for entity in self._entities:
889 entity.setup_compile_state(self)
891 compiler._ordered_columns = compiler._textual_ordered_columns = (
892 False
893 )
895 # enable looser result column matching. this is shown to be
896 # needed by test_query.py::TextTest
897 compiler._loose_column_name_matching = True
899 for c in self.primary_columns:
900 compiler.process(
901 c,
902 within_columns_clause=True,
903 add_to_result_map=compiler._add_to_result_map,
904 )
905 else:
906 # for everyone else, Select, Insert, Update, TextualSelect, they
907 # have column objects already. After much
908 # experimentation here, the best approach seems to be, use
909 # those columns completely, don't interfere with the compiler
910 # at all; just in ORM land, use an adapter to convert from
911 # our ORM columns to whatever columns are in the statement,
912 # before we look in the result row. Adapt on names
913 # to accept cases such as issue #9217, however also allow
914 # this to be overridden for cases such as #9273.
915 self._from_obj_alias = ORMStatementAdapter(
916 _TraceAdaptRole.ADAPT_FROM_STATEMENT,
917 self.statement,
918 adapt_on_names=statement_container._adapt_on_names,
919 )
921 return self
923 def _adapt_col_list(self, cols, current_adapter):
924 return cols
926 def _get_current_adapter(self):
927 return None
929 def setup_dml_returning_compile_state(self, dml_mapper):
930 """used by BulkORMInsert, Update, Delete to set up a handler
931 for RETURNING to return ORM objects and expressions
933 """
934 target_mapper = self.statement._propagate_attrs.get(
935 "plugin_subject", None
936 )
938 if self.statement.is_insert:
939 adapter = _DMLBulkInsertReturningColFilter(
940 target_mapper, dml_mapper
941 )
942 elif self.statement.is_update or self.statement.is_delete:
943 adapter = _DMLUpdateDeleteReturningColFilter(
944 target_mapper, dml_mapper
945 )
946 else:
947 adapter = None
949 if self.compile_options._is_star and (len(self._entities) != 1):
950 raise sa_exc.CompileError(
951 "Can't generate ORM query that includes multiple expressions "
952 "at the same time as '*'; query for '*' alone if present"
953 )
955 for entity in self._entities:
956 entity.setup_dml_returning_compile_state(self, adapter)
959class FromStatement(GroupedElement, Generative, TypedReturnsRows[Unpack[_Ts]]):
960 """Core construct that represents a load of ORM objects from various
961 :class:`.ReturnsRows` and other classes including:
963 :class:`.Select`, :class:`.TextClause`, :class:`.TextualSelect`,
964 :class:`.CompoundSelect`, :class`.Insert`, :class:`.Update`,
965 and in theory, :class:`.Delete`.
967 """
969 __visit_name__ = "orm_from_statement"
971 _compile_options = _ORMFromStatementCompileState.default_compile_options
973 _compile_state_factory = _ORMFromStatementCompileState.create_for_statement
975 _for_update_arg = None
977 element: Union[ExecutableReturnsRows, TextClause]
979 _adapt_on_names: bool
981 _traverse_internals = [
982 ("_raw_columns", InternalTraversal.dp_clauseelement_list),
983 ("element", InternalTraversal.dp_clauseelement),
984 ] + Executable._executable_traverse_internals
986 _cache_key_traversal = _traverse_internals + [
987 ("_compile_options", InternalTraversal.dp_has_cache_key)
988 ]
990 is_from_statement = True
992 def __init__(
993 self,
994 entities: Iterable[_ColumnsClauseArgument[Any]],
995 element: Union[ExecutableReturnsRows, TextClause],
996 _adapt_on_names: bool = True,
997 ):
998 self._raw_columns = [
999 coercions.expect(
1000 roles.ColumnsClauseRole,
1001 ent,
1002 apply_propagate_attrs=self,
1003 post_inspect=True,
1004 )
1005 for ent in util.to_list(entities)
1006 ]
1007 self.element = element
1008 self.is_dml = element.is_dml
1009 self.is_select = element.is_select
1010 self.is_delete = element.is_delete
1011 self.is_insert = element.is_insert
1012 self.is_update = element.is_update
1013 self._label_style = (
1014 element._label_style if is_select_base(element) else None
1015 )
1016 self._adapt_on_names = _adapt_on_names
1018 def _compiler_dispatch(self, compiler, **kw):
1019 """provide a fixed _compiler_dispatch method.
1021 This is roughly similar to using the sqlalchemy.ext.compiler
1022 ``@compiles`` extension.
1024 """
1026 compile_state = self._compile_state_factory(self, compiler, **kw)
1028 toplevel = not compiler.stack
1030 if toplevel:
1031 compiler.compile_state = compile_state
1033 return compiler.process(compile_state.statement, **kw)
1035 @property
1036 def column_descriptions(self):
1037 """Return a :term:`plugin-enabled` 'column descriptions' structure
1038 referring to the columns which are SELECTed by this statement.
1040 See the section :ref:`queryguide_inspection` for an overview
1041 of this feature.
1043 .. seealso::
1045 :ref:`queryguide_inspection` - ORM background
1047 """
1048 meth = cast(
1049 _ORMSelectCompileState, SelectState.get_plugin_class(self)
1050 ).get_column_descriptions
1051 return meth(self)
1053 def _ensure_disambiguated_names(self):
1054 return self
1056 def get_children(self, **kw):
1057 yield from itertools.chain.from_iterable(
1058 element._from_objects for element in self._raw_columns
1059 )
1060 yield from super().get_children(**kw)
1062 @property
1063 def _all_selected_columns(self):
1064 return self.element._all_selected_columns
1066 @property
1067 def _return_defaults(self):
1068 return self.element._return_defaults if is_dml(self.element) else None
1070 @property
1071 def _returning(self):
1072 return self.element._returning if is_dml(self.element) else None
1074 @property
1075 def _inline(self):
1076 return self.element._inline if is_insert_update(self.element) else None
1079@sql.base.CompileState.plugin_for("orm", "compound_select")
1080class _CompoundSelectCompileState(
1081 _AutoflushOnlyORMCompileState, CompoundSelectState
1082):
1083 pass
1086@sql.base.CompileState.plugin_for("orm", "select")
1087class _ORMSelectCompileState(_ORMCompileState, SelectState):
1088 _already_joined_edges = ()
1090 _memoized_entities = _EMPTY_DICT
1092 _from_obj_alias = None
1093 _has_mapper_entities = False
1095 _has_orm_entities = False
1096 multi_row_eager_loaders = False
1097 eager_adding_joins = False
1098 compound_eager_adapter = None
1100 correlate = None
1101 correlate_except = None
1102 _where_criteria = ()
1103 _having_criteria = ()
1105 @classmethod
1106 def _create_orm_context(
1107 cls,
1108 statement: Union[Select, FromStatement],
1109 *,
1110 toplevel: bool,
1111 compiler: Optional[SQLCompiler],
1112 **kw: Any,
1113 ) -> _ORMSelectCompileState:
1115 self = cls.__new__(cls)
1117 select_statement = statement
1119 # if we are a select() that was never a legacy Query, we won't
1120 # have ORM level compile options.
1121 statement._compile_options = cls.default_compile_options.safe_merge(
1122 statement._compile_options
1123 )
1125 if select_statement._execution_options:
1126 # execution options should not impact the compilation of a
1127 # query, and at the moment subqueryloader is putting some things
1128 # in here that we explicitly don't want stuck in a cache.
1129 self.select_statement = select_statement._clone()
1130 self.select_statement._execution_options = util.immutabledict()
1131 else:
1132 self.select_statement = select_statement
1134 # indicates this select() came from Query.statement
1135 self.for_statement = select_statement._compile_options._for_statement
1137 # generally if we are from Query or directly from a select()
1138 self.use_legacy_query_style = (
1139 select_statement._compile_options._use_legacy_query_style
1140 )
1142 self._entities = []
1143 self._primary_entity = None
1144 self._polymorphic_adapters = {}
1146 self.compile_options = select_statement._compile_options
1148 if not toplevel:
1149 # for subqueries, turn off eagerloads and set
1150 # "render_for_subquery".
1151 self.compile_options += {
1152 "_enable_eagerloads": False,
1153 "_render_for_subquery": True,
1154 }
1156 # determine label style. we can make different decisions here.
1157 # at the moment, trying to see if we can always use DISAMBIGUATE_ONLY
1158 # rather than LABEL_STYLE_NONE, and if we can use disambiguate style
1159 # for new style ORM selects too.
1160 if (
1161 self.use_legacy_query_style
1162 and self.select_statement._label_style is LABEL_STYLE_LEGACY_ORM
1163 ):
1164 if not self.for_statement:
1165 self.label_style = LABEL_STYLE_TABLENAME_PLUS_COL
1166 else:
1167 self.label_style = LABEL_STYLE_DISAMBIGUATE_ONLY
1168 else:
1169 self.label_style = self.select_statement._label_style
1171 if select_statement._memoized_select_entities:
1172 self._memoized_entities = {
1173 memoized_entities: _QueryEntity.to_compile_state(
1174 self,
1175 memoized_entities._raw_columns,
1176 [],
1177 is_current_entities=False,
1178 )
1179 for memoized_entities in (
1180 select_statement._memoized_select_entities
1181 )
1182 }
1184 # label_convention is stateful and will yield deduping keys if it
1185 # sees the same key twice. therefore it's important that it is not
1186 # invoked for the above "memoized" entities that aren't actually
1187 # in the columns clause
1188 self._label_convention = self._column_naming_convention(
1189 statement._label_style, self.use_legacy_query_style
1190 )
1192 _QueryEntity.to_compile_state(
1193 self,
1194 select_statement._raw_columns,
1195 self._entities,
1196 is_current_entities=True,
1197 )
1199 self.current_path = select_statement._compile_options._current_path
1201 self.eager_order_by = ()
1203 self._init_global_attributes(
1204 select_statement,
1205 compiler,
1206 toplevel=toplevel,
1207 process_criteria_for_toplevel=False,
1208 )
1210 if toplevel and (
1211 select_statement._with_options
1212 or select_statement._memoized_select_entities
1213 ):
1214 for (
1215 memoized_entities
1216 ) in select_statement._memoized_select_entities:
1217 for opt in memoized_entities._with_options:
1218 if opt._is_compile_state:
1219 opt.process_compile_state_replaced_entities(
1220 self,
1221 [
1222 ent
1223 for ent in self._memoized_entities[
1224 memoized_entities
1225 ]
1226 if isinstance(ent, _MapperEntity)
1227 ],
1228 )
1230 for opt in self.select_statement._with_options:
1231 if opt._is_compile_state:
1232 opt.process_compile_state(self)
1234 # uncomment to print out the context.attributes structure
1235 # after it's been set up above
1236 # self._dump_option_struct()
1238 if select_statement._compile_state_funcs:
1239 for fn, key in select_statement._compile_state_funcs:
1240 fn(self)
1242 self.primary_columns = []
1243 self.secondary_columns = []
1244 self.dedupe_columns = set()
1245 self.eager_joins = {}
1246 self.extra_criteria_entities = {}
1247 self.create_eager_joins = []
1248 self._fallback_from_clauses = []
1250 # normalize the FROM clauses early by themselves, as this makes
1251 # it an easier job when we need to assemble a JOIN onto these,
1252 # for select.join() as well as joinedload(). As of 1.4 there are now
1253 # potentially more complex sets of FROM objects here as the use
1254 # of lambda statements for lazyload, load_on_pk etc. uses more
1255 # cloning of the select() construct. See #6495
1256 self.from_clauses = self._normalize_froms(
1257 info.selectable for info in select_statement._from_obj
1258 )
1260 # this is a fairly arbitrary break into a second method,
1261 # so it might be nicer to break up create_for_statement()
1262 # and _setup_for_generate into three or four logical sections
1263 self._setup_for_generate()
1265 SelectState.__init__(self, self.statement, compiler, **kw)
1266 return self
1268 def _dump_option_struct(self):
1269 print("\n---------------------------------------------------\n")
1270 print(f"current path: {self.current_path}")
1271 for key in self.attributes:
1272 if isinstance(key, tuple) and key[0] == "loader":
1273 print(f"\nLoader: {PathRegistry.coerce(key[1])}")
1274 print(f" {self.attributes[key]}")
1275 print(f" {self.attributes[key].__dict__}")
1276 elif isinstance(key, tuple) and key[0] == "path_with_polymorphic":
1277 print(f"\nWith Polymorphic: {PathRegistry.coerce(key[1])}")
1278 print(f" {self.attributes[key]}")
1280 def _setup_for_generate(self):
1281 query = self.select_statement
1283 self.statement = None
1284 self._join_entities = ()
1286 if self.compile_options._set_base_alias:
1287 # legacy Query only
1288 self._set_select_from_alias()
1290 for memoized_entities in query._memoized_select_entities:
1291 if memoized_entities._setup_joins:
1292 self._join(
1293 memoized_entities._setup_joins,
1294 self._memoized_entities[memoized_entities],
1295 )
1297 if query._setup_joins:
1298 self._join(query._setup_joins, self._entities)
1300 current_adapter = self._get_current_adapter()
1302 if query._where_criteria:
1303 self._where_criteria = query._where_criteria
1305 if current_adapter:
1306 self._where_criteria = tuple(
1307 current_adapter(crit, True)
1308 for crit in self._where_criteria
1309 )
1311 # TODO: some complexity with order_by here was due to mapper.order_by.
1312 # now that this is removed we can hopefully make order_by /
1313 # group_by act identically to how they are in Core select.
1314 self.order_by = (
1315 self._adapt_col_list(query._order_by_clauses, current_adapter)
1316 if current_adapter and query._order_by_clauses not in (None, False)
1317 else query._order_by_clauses
1318 )
1320 if query._having_criteria:
1321 self._having_criteria = tuple(
1322 current_adapter(crit, True) if current_adapter else crit
1323 for crit in query._having_criteria
1324 )
1326 self.group_by = (
1327 self._adapt_col_list(
1328 util.flatten_iterator(query._group_by_clauses), current_adapter
1329 )
1330 if current_adapter and query._group_by_clauses not in (None, False)
1331 else query._group_by_clauses or None
1332 )
1334 if self.eager_order_by:
1335 adapter = self.from_clauses[0]._target_adapter
1336 self.eager_order_by = adapter.copy_and_process(self.eager_order_by)
1338 if query._distinct_on:
1339 self.distinct_on = self._adapt_col_list(
1340 query._distinct_on, current_adapter
1341 )
1342 else:
1343 self.distinct_on = ()
1345 self.distinct = query._distinct
1347 self.syntax_extensions = {
1348 key: current_adapter(value, True) if current_adapter else value
1349 for key, value in query._get_syntax_extensions_as_dict().items()
1350 }
1352 if query._correlate:
1353 # ORM mapped entities that are mapped to joins can be passed
1354 # to .correlate, so here they are broken into their component
1355 # tables.
1356 self.correlate = tuple(
1357 util.flatten_iterator(
1358 sql_util.surface_selectables(s) if s is not None else None
1359 for s in query._correlate
1360 )
1361 )
1362 elif query._correlate_except is not None:
1363 self.correlate_except = tuple(
1364 util.flatten_iterator(
1365 sql_util.surface_selectables(s) if s is not None else None
1366 for s in query._correlate_except
1367 )
1368 )
1369 elif not query._auto_correlate:
1370 self.correlate = (None,)
1372 # PART II
1374 self._for_update_arg = query._for_update_arg
1376 if self.compile_options._is_star and (len(self._entities) != 1):
1377 raise sa_exc.CompileError(
1378 "Can't generate ORM query that includes multiple expressions "
1379 "at the same time as '*'; query for '*' alone if present"
1380 )
1381 for entity in self._entities:
1382 entity.setup_compile_state(self)
1384 for rec in self.create_eager_joins:
1385 strategy = rec[0]
1386 strategy(self, *rec[1:])
1388 # else "load from discrete FROMs" mode,
1389 # i.e. when each _MappedEntity has its own FROM
1391 if self.compile_options._enable_single_crit:
1392 self._adjust_for_extra_criteria()
1394 if not self.primary_columns:
1395 if self.compile_options._only_load_props:
1396 assert False, "no columns were included in _only_load_props"
1398 raise sa_exc.InvalidRequestError(
1399 "Query contains no columns with which to SELECT from."
1400 )
1402 if not self.from_clauses:
1403 self.from_clauses = list(self._fallback_from_clauses)
1405 if self.order_by is False:
1406 self.order_by = None
1408 if self._should_nest_selectable:
1409 self.statement = self._compound_eager_statement()
1410 else:
1411 self.statement = self._simple_statement()
1413 if self.for_statement:
1414 ezero = self._mapper_zero()
1415 if ezero is not None:
1416 # TODO: this goes away once we get rid of the deep entity
1417 # thing
1418 self.statement = self.statement._annotate(
1419 {"deepentity": ezero}
1420 )
1422 @classmethod
1423 def _create_entities_collection(cls, query, legacy):
1424 """Creates a partial ORMSelectCompileState that includes
1425 the full collection of _MapperEntity and other _QueryEntity objects.
1427 Supports a few remaining use cases that are pre-compilation
1428 but still need to gather some of the column / adaption information.
1430 """
1431 self = cls.__new__(cls)
1433 self._entities = []
1434 self._primary_entity = None
1435 self._polymorphic_adapters = {}
1437 self._label_convention = self._column_naming_convention(
1438 query._label_style, legacy
1439 )
1441 # entities will also set up polymorphic adapters for mappers
1442 # that have with_polymorphic configured
1443 _QueryEntity.to_compile_state(
1444 self, query._raw_columns, self._entities, is_current_entities=True
1445 )
1446 return self
1448 @classmethod
1449 def determine_last_joined_entity(cls, statement):
1450 setup_joins = statement._setup_joins
1452 return _determine_last_joined_entity(setup_joins, None)
1454 @classmethod
1455 def all_selected_columns(cls, statement):
1456 for element in statement._raw_columns:
1457 if (
1458 element.is_selectable
1459 and "entity_namespace" in element._annotations
1460 ):
1461 ens = element._annotations["entity_namespace"]
1462 if not ens.is_mapper and not ens.is_aliased_class:
1463 yield from _select_iterables([element])
1464 else:
1465 yield from _select_iterables(ens._all_column_expressions)
1466 else:
1467 yield from _select_iterables([element])
1469 @classmethod
1470 def get_columns_clause_froms(cls, statement):
1471 return cls._normalize_froms(
1472 itertools.chain.from_iterable(
1473 (
1474 element._from_objects
1475 if "parententity" not in element._annotations
1476 else [
1477 element._annotations[
1478 "parententity"
1479 ].__clause_element__()
1480 ]
1481 )
1482 for element in statement._raw_columns
1483 )
1484 )
1486 @classmethod
1487 def from_statement(cls, statement, from_statement):
1488 from_statement = coercions.expect(
1489 roles.ReturnsRowsRole,
1490 from_statement,
1491 apply_propagate_attrs=statement,
1492 )
1494 stmt = FromStatement(statement._raw_columns, from_statement)
1496 stmt.__dict__.update(
1497 _with_options=statement._with_options,
1498 _compile_state_funcs=statement._compile_state_funcs,
1499 _execution_options=statement._execution_options,
1500 _propagate_attrs=statement._propagate_attrs,
1501 )
1502 return stmt
1504 def _set_select_from_alias(self):
1505 """used only for legacy Query cases"""
1507 query = self.select_statement # query
1509 assert self.compile_options._set_base_alias
1510 assert len(query._from_obj) == 1
1512 adapter = self._get_select_from_alias_from_obj(query._from_obj[0])
1513 if adapter:
1514 self.compile_options += {"_enable_single_crit": False}
1515 self._from_obj_alias = adapter
1517 def _get_select_from_alias_from_obj(self, from_obj):
1518 """used only for legacy Query cases"""
1520 info = from_obj
1522 if "parententity" in info._annotations:
1523 info = info._annotations["parententity"]
1525 if hasattr(info, "mapper"):
1526 if not info.is_aliased_class:
1527 raise sa_exc.ArgumentError(
1528 "A selectable (FromClause) instance is "
1529 "expected when the base alias is being set."
1530 )
1531 else:
1532 return info._adapter
1534 elif isinstance(info.selectable, sql.selectable.AliasedReturnsRows):
1535 equivs = self._all_equivs()
1536 assert info is info.selectable
1537 return ORMStatementAdapter(
1538 _TraceAdaptRole.LEGACY_SELECT_FROM_ALIAS,
1539 info.selectable,
1540 equivalents=equivs,
1541 )
1542 else:
1543 return None
1545 def _mapper_zero(self):
1546 """return the Mapper associated with the first QueryEntity."""
1547 return self._entities[0].mapper
1549 def _entity_zero(self):
1550 """Return the 'entity' (mapper or AliasedClass) associated
1551 with the first QueryEntity, or alternatively the 'select from'
1552 entity if specified."""
1554 for ent in self.from_clauses:
1555 if "parententity" in ent._annotations:
1556 return ent._annotations["parententity"]
1557 for qent in self._entities:
1558 if qent.entity_zero:
1559 return qent.entity_zero
1561 return None
1563 def _only_full_mapper_zero(self, methname):
1564 if self._entities != [self._primary_entity]:
1565 raise sa_exc.InvalidRequestError(
1566 "%s() can only be used against "
1567 "a single mapped class." % methname
1568 )
1569 return self._primary_entity.entity_zero
1571 def _only_entity_zero(self, rationale=None):
1572 if len(self._entities) > 1:
1573 raise sa_exc.InvalidRequestError(
1574 rationale
1575 or "This operation requires a Query "
1576 "against a single mapper."
1577 )
1578 return self._entity_zero()
1580 def _all_equivs(self):
1581 equivs = {}
1583 for memoized_entities in self._memoized_entities.values():
1584 for ent in [
1585 ent
1586 for ent in memoized_entities
1587 if isinstance(ent, _MapperEntity)
1588 ]:
1589 equivs.update(ent.mapper._equivalent_columns)
1591 for ent in [
1592 ent for ent in self._entities if isinstance(ent, _MapperEntity)
1593 ]:
1594 equivs.update(ent.mapper._equivalent_columns)
1595 return equivs
1597 def _compound_eager_statement(self):
1598 # for eager joins present and LIMIT/OFFSET/DISTINCT,
1599 # wrap the query inside a select,
1600 # then append eager joins onto that
1602 if self.order_by:
1603 # the default coercion for ORDER BY is now the OrderByRole,
1604 # which adds an additional post coercion to ByOfRole in that
1605 # elements are converted into label references. For the
1606 # eager load / subquery wrapping case, we need to un-coerce
1607 # the original expressions outside of the label references
1608 # in order to have them render.
1609 unwrapped_order_by = [
1610 (
1611 elem.element
1612 if isinstance(elem, sql.elements._label_reference)
1613 else elem
1614 )
1615 for elem in self.order_by
1616 ]
1618 order_by_col_expr = sql_util.expand_column_list_from_order_by(
1619 self.primary_columns, unwrapped_order_by
1620 )
1621 else:
1622 order_by_col_expr = []
1623 unwrapped_order_by = None
1625 # put FOR UPDATE on the inner query, where MySQL will honor it,
1626 # as well as if it has an OF so PostgreSQL can use it.
1627 inner = self._select_statement(
1628 self.primary_columns
1629 + [c for c in order_by_col_expr if c not in self.dedupe_columns],
1630 self.from_clauses,
1631 self._where_criteria,
1632 self._having_criteria,
1633 self.label_style,
1634 self.order_by,
1635 for_update=self._for_update_arg,
1636 hints=self.select_statement._hints,
1637 statement_hints=self.select_statement._statement_hints,
1638 correlate=self.correlate,
1639 correlate_except=self.correlate_except,
1640 **self._select_args,
1641 )
1643 inner = inner.alias()
1645 equivs = self._all_equivs()
1647 self.compound_eager_adapter = ORMStatementAdapter(
1648 _TraceAdaptRole.COMPOUND_EAGER_STATEMENT, inner, equivalents=equivs
1649 )
1651 statement = future.select(
1652 *([inner] + self.secondary_columns) # use_labels=self.labels
1653 )
1654 statement._label_style = self.label_style
1656 # Oracle Database however does not allow FOR UPDATE on the subquery,
1657 # and the Oracle Database dialects ignore it, plus for PostgreSQL,
1658 # MySQL we expect that all elements of the row are locked, so also put
1659 # it on the outside (except in the case of PG when OF is used)
1660 if (
1661 self._for_update_arg is not None
1662 and self._for_update_arg.of is None
1663 ):
1664 statement._for_update_arg = self._for_update_arg
1666 from_clause = inner
1667 for eager_join in self.eager_joins.values():
1668 # EagerLoader places a 'stop_on' attribute on the join,
1669 # giving us a marker as to where the "splice point" of
1670 # the join should be
1671 from_clause = sql_util.splice_joins(
1672 from_clause, eager_join, eager_join.stop_on
1673 )
1675 statement.select_from.non_generative(statement, from_clause)
1677 if unwrapped_order_by:
1678 statement.order_by.non_generative(
1679 statement,
1680 *self.compound_eager_adapter.copy_and_process(
1681 unwrapped_order_by
1682 ),
1683 )
1685 statement.order_by.non_generative(statement, *self.eager_order_by)
1686 return statement
1688 def _simple_statement(self):
1689 statement = self._select_statement(
1690 self.primary_columns + self.secondary_columns,
1691 tuple(self.from_clauses) + tuple(self.eager_joins.values()),
1692 self._where_criteria,
1693 self._having_criteria,
1694 self.label_style,
1695 self.order_by,
1696 for_update=self._for_update_arg,
1697 hints=self.select_statement._hints,
1698 statement_hints=self.select_statement._statement_hints,
1699 correlate=self.correlate,
1700 correlate_except=self.correlate_except,
1701 **self._select_args,
1702 )
1704 if self.eager_order_by:
1705 statement.order_by.non_generative(statement, *self.eager_order_by)
1706 return statement
1708 def _select_statement(
1709 self,
1710 raw_columns,
1711 from_obj,
1712 where_criteria,
1713 having_criteria,
1714 label_style,
1715 order_by,
1716 for_update,
1717 hints,
1718 statement_hints,
1719 correlate,
1720 correlate_except,
1721 limit_clause,
1722 offset_clause,
1723 fetch_clause,
1724 fetch_clause_options,
1725 distinct,
1726 distinct_on,
1727 prefixes,
1728 suffixes,
1729 group_by,
1730 independent_ctes,
1731 independent_ctes_opts,
1732 syntax_extensions,
1733 ):
1734 statement = Select._create_raw_select(
1735 _raw_columns=raw_columns,
1736 _from_obj=from_obj,
1737 _label_style=label_style,
1738 )
1740 if where_criteria:
1741 statement._where_criteria = where_criteria
1742 if having_criteria:
1743 statement._having_criteria = having_criteria
1745 if order_by:
1746 statement._order_by_clauses += tuple(order_by)
1748 if distinct_on:
1749 statement._distinct = True
1750 statement._distinct_on = distinct_on
1751 elif distinct:
1752 statement._distinct = True
1754 if group_by:
1755 statement._group_by_clauses += tuple(group_by)
1757 statement._limit_clause = limit_clause
1758 statement._offset_clause = offset_clause
1759 statement._fetch_clause = fetch_clause
1760 statement._fetch_clause_options = fetch_clause_options
1761 statement._independent_ctes = independent_ctes
1762 statement._independent_ctes_opts = independent_ctes_opts
1763 if syntax_extensions:
1764 statement._set_syntax_extensions(**syntax_extensions)
1766 if prefixes:
1767 statement._prefixes = prefixes
1769 if suffixes:
1770 statement._suffixes = suffixes
1772 statement._for_update_arg = for_update
1774 if hints:
1775 statement._hints = hints
1776 if statement_hints:
1777 statement._statement_hints = statement_hints
1779 if correlate:
1780 statement.correlate.non_generative(statement, *correlate)
1782 if correlate_except is not None:
1783 statement.correlate_except.non_generative(
1784 statement, *correlate_except
1785 )
1787 return statement
1789 def _adapt_polymorphic_element(self, element):
1790 if "parententity" in element._annotations:
1791 search = element._annotations["parententity"]
1792 alias = self._polymorphic_adapters.get(search, None)
1793 if alias:
1794 return alias.adapt_clause(element)
1796 if isinstance(element, expression.FromClause):
1797 search = element
1798 elif hasattr(element, "table"):
1799 search = element.table
1800 else:
1801 return None
1803 alias = self._polymorphic_adapters.get(search, None)
1804 if alias:
1805 return alias.adapt_clause(element)
1807 def _adapt_col_list(self, cols, current_adapter):
1808 if current_adapter:
1809 return [current_adapter(o, True) for o in cols]
1810 else:
1811 return cols
1813 def _get_current_adapter(self):
1814 adapters = []
1816 if self._from_obj_alias:
1817 # used for legacy going forward for query set_ops, e.g.
1818 # union(), union_all(), etc.
1819 # 1.4 and previously, also used for from_self(),
1820 # select_entity_from()
1821 #
1822 # for the "from obj" alias, apply extra rule to the
1823 # 'ORM only' check, if this query were generated from a
1824 # subquery of itself, i.e. _from_selectable(), apply adaption
1825 # to all SQL constructs.
1826 adapters.append(
1827 self._from_obj_alias.replace,
1828 )
1830 # this was *hopefully* the only adapter we were going to need
1831 # going forward...however, we unfortunately need _from_obj_alias
1832 # for query.union(), which we can't drop
1833 if self._polymorphic_adapters:
1834 adapters.append(self._adapt_polymorphic_element)
1836 if not adapters:
1837 return None
1839 def _adapt_clause(clause, as_filter):
1840 # do we adapt all expression elements or only those
1841 # tagged as 'ORM' constructs ?
1843 def replace(elem):
1844 for adapter in adapters:
1845 e = adapter(elem)
1846 if e is not None:
1847 return e
1849 return visitors.replacement_traverse(clause, {}, replace)
1851 return _adapt_clause
1853 def _join(self, args, entities_collection):
1854 for right, onclause, from_, flags in args:
1855 isouter = flags["isouter"]
1856 full = flags["full"]
1858 right = inspect(right)
1859 if onclause is not None:
1860 onclause = inspect(onclause)
1862 if isinstance(right, interfaces.PropComparator):
1863 if onclause is not None:
1864 raise sa_exc.InvalidRequestError(
1865 "No 'on clause' argument may be passed when joining "
1866 "to a relationship path as a target"
1867 )
1869 onclause = right
1870 right = None
1871 elif "parententity" in right._annotations:
1872 right = right._annotations["parententity"]
1874 if onclause is None:
1875 if not right.is_selectable and not hasattr(right, "mapper"):
1876 raise sa_exc.ArgumentError(
1877 "Expected mapped entity or "
1878 "selectable/table as join target"
1879 )
1881 if isinstance(onclause, interfaces.PropComparator):
1882 # descriptor/property given (or determined); this tells us
1883 # explicitly what the expected "left" side of the join is.
1885 of_type = getattr(onclause, "_of_type", None)
1887 if right is None:
1888 if of_type:
1889 right = of_type
1890 else:
1891 right = onclause.property
1893 try:
1894 right = right.entity
1895 except AttributeError as err:
1896 raise sa_exc.ArgumentError(
1897 "Join target %s does not refer to a "
1898 "mapped entity" % right
1899 ) from err
1901 left = onclause._parententity
1903 prop = onclause.property
1904 if not isinstance(onclause, attributes.QueryableAttribute):
1905 onclause = prop
1907 # check for this path already present. don't render in that
1908 # case.
1909 if (left, right, prop.key) in self._already_joined_edges:
1910 continue
1912 if from_ is not None:
1913 if (
1914 from_ is not left
1915 and from_._annotations.get("parententity", None)
1916 is not left
1917 ):
1918 raise sa_exc.InvalidRequestError(
1919 "explicit from clause %s does not match left side "
1920 "of relationship attribute %s"
1921 % (
1922 from_._annotations.get("parententity", from_),
1923 onclause,
1924 )
1925 )
1926 elif from_ is not None:
1927 prop = None
1928 left = from_
1929 else:
1930 # no descriptor/property given; we will need to figure out
1931 # what the effective "left" side is
1932 prop = left = None
1934 # figure out the final "left" and "right" sides and create an
1935 # ORMJoin to add to our _from_obj tuple
1936 self._join_left_to_right(
1937 entities_collection,
1938 left,
1939 right,
1940 onclause,
1941 prop,
1942 isouter,
1943 full,
1944 )
1946 def _join_left_to_right(
1947 self,
1948 entities_collection,
1949 left,
1950 right,
1951 onclause,
1952 prop,
1953 outerjoin,
1954 full,
1955 ):
1956 """given raw "left", "right", "onclause" parameters consumed from
1957 a particular key within _join(), add a real ORMJoin object to
1958 our _from_obj list (or augment an existing one)
1960 """
1962 if left is None:
1963 # left not given (e.g. no relationship object/name specified)
1964 # figure out the best "left" side based on our existing froms /
1965 # entities
1966 assert prop is None
1967 (
1968 left,
1969 replace_from_obj_index,
1970 use_entity_index,
1971 ) = self._join_determine_implicit_left_side(
1972 entities_collection, left, right, onclause
1973 )
1974 else:
1975 # left is given via a relationship/name, or as explicit left side.
1976 # Determine where in our
1977 # "froms" list it should be spliced/appended as well as what
1978 # existing entity it corresponds to.
1979 (
1980 replace_from_obj_index,
1981 use_entity_index,
1982 ) = self._join_place_explicit_left_side(entities_collection, left)
1984 if left is right:
1985 raise sa_exc.InvalidRequestError(
1986 "Can't construct a join from %s to %s, they "
1987 "are the same entity" % (left, right)
1988 )
1990 # the right side as given often needs to be adapted. additionally
1991 # a lot of things can be wrong with it. handle all that and
1992 # get back the new effective "right" side
1993 r_info, right, onclause = self._join_check_and_adapt_right_side(
1994 left, right, onclause, prop
1995 )
1997 if not r_info.is_selectable:
1998 extra_criteria = self._get_extra_criteria(r_info)
1999 else:
2000 extra_criteria = ()
2002 if replace_from_obj_index is not None:
2003 # splice into an existing element in the
2004 # self._from_obj list
2005 left_clause = self.from_clauses[replace_from_obj_index]
2007 self.from_clauses = (
2008 self.from_clauses[:replace_from_obj_index]
2009 + [
2010 _ORMJoin(
2011 left_clause,
2012 right,
2013 onclause,
2014 isouter=outerjoin,
2015 full=full,
2016 _extra_criteria=extra_criteria,
2017 )
2018 ]
2019 + self.from_clauses[replace_from_obj_index + 1 :]
2020 )
2021 else:
2022 # add a new element to the self._from_obj list
2023 if use_entity_index is not None:
2024 # make use of _MapperEntity selectable, which is usually
2025 # entity_zero.selectable, but if with_polymorphic() were used
2026 # might be distinct
2027 assert isinstance(
2028 entities_collection[use_entity_index], _MapperEntity
2029 )
2030 left_clause = entities_collection[use_entity_index].selectable
2031 else:
2032 left_clause = left
2034 self.from_clauses = self.from_clauses + [
2035 _ORMJoin(
2036 left_clause,
2037 r_info,
2038 onclause,
2039 isouter=outerjoin,
2040 full=full,
2041 _extra_criteria=extra_criteria,
2042 )
2043 ]
2045 def _join_determine_implicit_left_side(
2046 self, entities_collection, left, right, onclause
2047 ):
2048 """When join conditions don't express the left side explicitly,
2049 determine if an existing FROM or entity in this query
2050 can serve as the left hand side.
2052 """
2054 # when we are here, it means join() was called without an ORM-
2055 # specific way of telling us what the "left" side is, e.g.:
2056 #
2057 # join(RightEntity)
2058 #
2059 # or
2060 #
2061 # join(RightEntity, RightEntity.foo == LeftEntity.bar)
2062 #
2064 r_info = inspect(right)
2066 replace_from_obj_index = use_entity_index = None
2068 if self.from_clauses:
2069 # we have a list of FROMs already. So by definition this
2070 # join has to connect to one of those FROMs.
2072 indexes = sql_util.find_left_clause_to_join_from(
2073 self.from_clauses, r_info.selectable, onclause
2074 )
2076 if len(indexes) == 1:
2077 replace_from_obj_index = indexes[0]
2078 left = self.from_clauses[replace_from_obj_index]
2079 elif len(indexes) > 1:
2080 raise sa_exc.InvalidRequestError(
2081 "Can't determine which FROM clause to join "
2082 "from, there are multiple FROMS which can "
2083 "join to this entity. Please use the .select_from() "
2084 "method to establish an explicit left side, as well as "
2085 "providing an explicit ON clause if not present already "
2086 "to help resolve the ambiguity."
2087 )
2088 else:
2089 raise sa_exc.InvalidRequestError(
2090 "Don't know how to join to %r. "
2091 "Please use the .select_from() "
2092 "method to establish an explicit left side, as well as "
2093 "providing an explicit ON clause if not present already "
2094 "to help resolve the ambiguity." % (right,)
2095 )
2097 elif entities_collection:
2098 # we have no explicit FROMs, so the implicit left has to
2099 # come from our list of entities.
2101 potential = {}
2102 for entity_index, ent in enumerate(entities_collection):
2103 entity = ent.entity_zero_or_selectable
2104 if entity is None:
2105 continue
2106 ent_info = inspect(entity)
2107 if ent_info is r_info: # left and right are the same, skip
2108 continue
2110 # by using a dictionary with the selectables as keys this
2111 # de-duplicates those selectables as occurs when the query is
2112 # against a series of columns from the same selectable
2113 if isinstance(ent, _MapperEntity):
2114 potential[ent.selectable] = (entity_index, entity)
2115 else:
2116 potential[ent_info.selectable] = (None, entity)
2118 all_clauses = list(potential.keys())
2119 indexes = sql_util.find_left_clause_to_join_from(
2120 all_clauses, r_info.selectable, onclause
2121 )
2123 if len(indexes) == 1:
2124 use_entity_index, left = potential[all_clauses[indexes[0]]]
2125 elif len(indexes) > 1:
2126 raise sa_exc.InvalidRequestError(
2127 "Can't determine which FROM clause to join "
2128 "from, there are multiple FROMS which can "
2129 "join to this entity. Please use the .select_from() "
2130 "method to establish an explicit left side, as well as "
2131 "providing an explicit ON clause if not present already "
2132 "to help resolve the ambiguity."
2133 )
2134 else:
2135 raise sa_exc.InvalidRequestError(
2136 "Don't know how to join to %r. "
2137 "Please use the .select_from() "
2138 "method to establish an explicit left side, as well as "
2139 "providing an explicit ON clause if not present already "
2140 "to help resolve the ambiguity." % (right,)
2141 )
2142 else:
2143 raise sa_exc.InvalidRequestError(
2144 "No entities to join from; please use "
2145 "select_from() to establish the left "
2146 "entity/selectable of this join"
2147 )
2149 return left, replace_from_obj_index, use_entity_index
2151 def _join_place_explicit_left_side(self, entities_collection, left):
2152 """When join conditions express a left side explicitly, determine
2153 where in our existing list of FROM clauses we should join towards,
2154 or if we need to make a new join, and if so is it from one of our
2155 existing entities.
2157 """
2159 # when we are here, it means join() was called with an indicator
2160 # as to an exact left side, which means a path to a
2161 # Relationship was given, e.g.:
2162 #
2163 # join(RightEntity, LeftEntity.right)
2164 #
2165 # or
2166 #
2167 # join(LeftEntity.right)
2168 #
2169 # as well as string forms:
2170 #
2171 # join(RightEntity, "right")
2172 #
2173 # etc.
2174 #
2176 replace_from_obj_index = use_entity_index = None
2178 l_info = inspect(left)
2179 if self.from_clauses:
2180 indexes = sql_util.find_left_clause_that_matches_given(
2181 self.from_clauses, l_info.selectable
2182 )
2184 if len(indexes) > 1:
2185 raise sa_exc.InvalidRequestError(
2186 "Can't identify which entity in which to assign the "
2187 "left side of this join. Please use a more specific "
2188 "ON clause."
2189 )
2191 # have an index, means the left side is already present in
2192 # an existing FROM in the self._from_obj tuple
2193 if indexes:
2194 replace_from_obj_index = indexes[0]
2196 # no index, means we need to add a new element to the
2197 # self._from_obj tuple
2199 # no from element present, so we will have to add to the
2200 # self._from_obj tuple. Determine if this left side matches up
2201 # with existing mapper entities, in which case we want to apply the
2202 # aliasing / adaptation rules present on that entity if any
2203 if (
2204 replace_from_obj_index is None
2205 and entities_collection
2206 and hasattr(l_info, "mapper")
2207 ):
2208 for idx, ent in enumerate(entities_collection):
2209 # TODO: should we be checking for multiple mapper entities
2210 # matching?
2211 if isinstance(ent, _MapperEntity) and ent.corresponds_to(left):
2212 use_entity_index = idx
2213 break
2215 return replace_from_obj_index, use_entity_index
2217 def _join_check_and_adapt_right_side(self, left, right, onclause, prop):
2218 """transform the "right" side of the join as well as the onclause
2219 according to polymorphic mapping translations, aliasing on the query
2220 or on the join, special cases where the right and left side have
2221 overlapping tables.
2223 """
2225 l_info = inspect(left)
2226 r_info = inspect(right)
2228 overlap = False
2230 right_mapper = getattr(r_info, "mapper", None)
2231 # if the target is a joined inheritance mapping,
2232 # be more liberal about auto-aliasing.
2233 if right_mapper and (
2234 right_mapper.with_polymorphic
2235 or isinstance(right_mapper.persist_selectable, expression.Join)
2236 ):
2237 for from_obj in self.from_clauses or [l_info.selectable]:
2238 if sql_util.selectables_overlap(
2239 l_info.selectable, from_obj
2240 ) and sql_util.selectables_overlap(
2241 from_obj, r_info.selectable
2242 ):
2243 overlap = True
2244 break
2246 if overlap and l_info.selectable is r_info.selectable:
2247 raise sa_exc.InvalidRequestError(
2248 "Can't join table/selectable '%s' to itself"
2249 % l_info.selectable
2250 )
2252 right_mapper, right_selectable, right_is_aliased = (
2253 getattr(r_info, "mapper", None),
2254 r_info.selectable,
2255 getattr(r_info, "is_aliased_class", False),
2256 )
2258 if (
2259 right_mapper
2260 and prop
2261 and not right_mapper.common_parent(prop.mapper)
2262 ):
2263 raise sa_exc.InvalidRequestError(
2264 "Join target %s does not correspond to "
2265 "the right side of join condition %s" % (right, onclause)
2266 )
2268 # _join_entities is used as a hint for single-table inheritance
2269 # purposes at the moment
2270 if hasattr(r_info, "mapper"):
2271 self._join_entities += (r_info,)
2273 need_adapter = False
2275 # test for joining to an unmapped selectable as the target
2276 if r_info.is_clause_element:
2277 if prop:
2278 right_mapper = prop.mapper
2280 if right_selectable._is_lateral:
2281 # orm_only is disabled to suit the case where we have to
2282 # adapt an explicit correlate(Entity) - the select() loses
2283 # the ORM-ness in this case right now, ideally it would not
2284 current_adapter = self._get_current_adapter()
2285 if current_adapter is not None:
2286 # TODO: we had orm_only=False here before, removing
2287 # it didn't break things. if we identify the rationale,
2288 # may need to apply "_orm_only" annotation here.
2289 right = current_adapter(right, True)
2291 elif prop:
2292 # joining to selectable with a mapper property given
2293 # as the ON clause
2295 if not right_selectable.is_derived_from(
2296 right_mapper.persist_selectable
2297 ):
2298 raise sa_exc.InvalidRequestError(
2299 "Selectable '%s' is not derived from '%s'"
2300 % (
2301 right_selectable.description,
2302 right_mapper.persist_selectable.description,
2303 )
2304 )
2306 # if the destination selectable is a plain select(),
2307 # turn it into an alias().
2308 if isinstance(right_selectable, expression.SelectBase):
2309 right_selectable = coercions.expect(
2310 roles.FromClauseRole, right_selectable
2311 )
2312 need_adapter = True
2314 # make the right hand side target into an ORM entity
2315 right = AliasedClass(right_mapper, right_selectable)
2317 util.warn_deprecated(
2318 "An alias is being generated automatically against "
2319 "joined entity %s for raw clauseelement, which is "
2320 "deprecated and will be removed in a later release. "
2321 "Use the aliased() "
2322 "construct explicitly, see the linked example."
2323 % right_mapper,
2324 "1.4",
2325 code="xaj1",
2326 )
2328 # test for overlap:
2329 # orm/inheritance/relationships.py
2330 # SelfReferentialM2MTest
2331 aliased_entity = right_mapper and not right_is_aliased and overlap
2333 if not need_adapter and aliased_entity:
2334 # there are a few places in the ORM that automatic aliasing
2335 # is still desirable, and can't be automatic with a Core
2336 # only approach. For illustrations of "overlaps" see
2337 # test/orm/inheritance/test_relationships.py. There are also
2338 # general overlap cases with many-to-many tables where automatic
2339 # aliasing is desirable.
2340 right = AliasedClass(right, flat=True)
2341 need_adapter = True
2343 util.warn(
2344 "An alias is being generated automatically against "
2345 "joined entity %s due to overlapping tables. This is a "
2346 "legacy pattern which may be "
2347 "deprecated in a later release. Use the "
2348 "aliased(<entity>, flat=True) "
2349 "construct explicitly, see the linked example." % right_mapper,
2350 code="xaj2",
2351 )
2353 if need_adapter:
2354 # if need_adapter is True, we are in a deprecated case and
2355 # a warning has been emitted.
2356 assert right_mapper
2358 adapter = ORMAdapter(
2359 _TraceAdaptRole.DEPRECATED_JOIN_ADAPT_RIGHT_SIDE,
2360 inspect(right),
2361 equivalents=right_mapper._equivalent_columns,
2362 )
2364 # if an alias() on the right side was generated,
2365 # which is intended to wrap a the right side in a subquery,
2366 # ensure that columns retrieved from this target in the result
2367 # set are also adapted.
2368 self._mapper_loads_polymorphically_with(right_mapper, adapter)
2369 elif (
2370 not r_info.is_clause_element
2371 and not right_is_aliased
2372 and right_mapper._has_aliased_polymorphic_fromclause
2373 ):
2374 # for the case where the target mapper has a with_polymorphic
2375 # set up, ensure an adapter is set up for criteria that works
2376 # against this mapper. Previously, this logic used to
2377 # use the "create_aliases or aliased_entity" case to generate
2378 # an aliased() object, but this creates an alias that isn't
2379 # strictly necessary.
2380 # see test/orm/test_core_compilation.py
2381 # ::RelNaturalAliasedJoinsTest::test_straight
2382 # and similar
2383 self._mapper_loads_polymorphically_with(
2384 right_mapper,
2385 ORMAdapter(
2386 _TraceAdaptRole.WITH_POLYMORPHIC_ADAPTER_RIGHT_JOIN,
2387 right_mapper,
2388 selectable=right_mapper.selectable,
2389 equivalents=right_mapper._equivalent_columns,
2390 ),
2391 )
2392 # if the onclause is a ClauseElement, adapt it with any
2393 # adapters that are in place right now
2394 if isinstance(onclause, expression.ClauseElement):
2395 current_adapter = self._get_current_adapter()
2396 if current_adapter:
2397 onclause = current_adapter(onclause, True)
2399 # if joining on a MapperProperty path,
2400 # track the path to prevent redundant joins
2401 if prop:
2402 self._already_joined_edges += ((left, right, prop.key),)
2404 return inspect(right), right, onclause
2406 @property
2407 def _select_args(self):
2408 return {
2409 "limit_clause": self.select_statement._limit_clause,
2410 "offset_clause": self.select_statement._offset_clause,
2411 "distinct": self.distinct,
2412 "distinct_on": self.distinct_on,
2413 "prefixes": self.select_statement._prefixes,
2414 "suffixes": self.select_statement._suffixes,
2415 "group_by": self.group_by or None,
2416 "fetch_clause": self.select_statement._fetch_clause,
2417 "fetch_clause_options": (
2418 self.select_statement._fetch_clause_options
2419 ),
2420 "independent_ctes": self.select_statement._independent_ctes,
2421 "independent_ctes_opts": (
2422 self.select_statement._independent_ctes_opts
2423 ),
2424 "syntax_extensions": self.syntax_extensions,
2425 }
2427 @property
2428 def _should_nest_selectable(self):
2429 kwargs = self._select_args
2431 if not self.eager_adding_joins:
2432 return False
2434 return (
2435 (
2436 kwargs.get("limit_clause") is not None
2437 and self.multi_row_eager_loaders
2438 )
2439 or (
2440 kwargs.get("offset_clause") is not None
2441 and self.multi_row_eager_loaders
2442 )
2443 or kwargs.get("distinct", False)
2444 or kwargs.get("distinct_on", ())
2445 or kwargs.get("group_by", False)
2446 )
2448 def _get_extra_criteria(self, ext_info):
2449 if (
2450 "additional_entity_criteria",
2451 ext_info.mapper,
2452 ) in self.global_attributes:
2453 return tuple(
2454 ae._resolve_where_criteria(ext_info)
2455 for ae in self.global_attributes[
2456 ("additional_entity_criteria", ext_info.mapper)
2457 ]
2458 if (ae.include_aliases or ae.entity is ext_info)
2459 and ae._should_include(self)
2460 )
2461 else:
2462 return ()
2464 def _adjust_for_extra_criteria(self):
2465 """Apply extra criteria filtering.
2467 For all distinct single-table-inheritance mappers represented in
2468 the columns clause of this query, as well as the "select from entity",
2469 add criterion to the WHERE
2470 clause of the given QueryContext such that only the appropriate
2471 subtypes are selected from the total results.
2473 Additionally, add WHERE criteria originating from LoaderCriteriaOptions
2474 associated with the global context.
2476 """
2478 for fromclause in self.from_clauses:
2479 ext_info = fromclause._annotations.get("parententity", None)
2481 if (
2482 ext_info
2483 and (
2484 ext_info.mapper._single_table_criterion is not None
2485 or ("additional_entity_criteria", ext_info.mapper)
2486 in self.global_attributes
2487 )
2488 and ext_info not in self.extra_criteria_entities
2489 ):
2490 self.extra_criteria_entities[ext_info] = (
2491 ext_info,
2492 ext_info._adapter if ext_info.is_aliased_class else None,
2493 )
2495 _where_criteria_to_add = ()
2497 merged_single_crit = collections.defaultdict(
2498 lambda: (util.OrderedSet(), set())
2499 )
2501 for ext_info, adapter in util.OrderedSet(
2502 self.extra_criteria_entities.values()
2503 ):
2504 if ext_info in self._join_entities:
2505 continue
2507 # assemble single table inheritance criteria.
2508 if (
2509 ext_info.is_aliased_class
2510 and ext_info._base_alias()._is_with_polymorphic
2511 ):
2512 # for a with_polymorphic(), we always include the full
2513 # hierarchy from what's given as the base class for the wpoly.
2514 # this is new in 2.1 for #12395 so that it matches the behavior
2515 # of joined inheritance.
2516 hierarchy_root = ext_info._base_alias()
2517 else:
2518 hierarchy_root = ext_info
2520 single_crit_component = (
2521 hierarchy_root.mapper._single_table_criteria_component
2522 )
2524 if single_crit_component is not None:
2525 polymorphic_on, criteria = single_crit_component
2527 polymorphic_on = polymorphic_on._annotate(
2528 {
2529 "parententity": hierarchy_root,
2530 "parentmapper": hierarchy_root.mapper,
2531 }
2532 )
2534 list_of_single_crits, adapters = merged_single_crit[
2535 (hierarchy_root, polymorphic_on)
2536 ]
2537 list_of_single_crits.update(criteria)
2538 if adapter:
2539 adapters.add(adapter)
2541 # assemble "additional entity criteria", which come from
2542 # with_loader_criteria() options
2543 if not self.compile_options._for_refresh_state:
2544 additional_entity_criteria = self._get_extra_criteria(ext_info)
2545 _where_criteria_to_add += tuple(
2546 adapter.traverse(crit) if adapter else crit
2547 for crit in additional_entity_criteria
2548 )
2550 # merge together single table inheritance criteria keyed to
2551 # top-level mapper / aliasedinsp (which may be a with_polymorphic())
2552 for (ext_info, polymorphic_on), (
2553 merged_crit,
2554 adapters,
2555 ) in merged_single_crit.items():
2556 new_crit = polymorphic_on.in_(merged_crit)
2557 for adapter in adapters:
2558 new_crit = adapter.traverse(new_crit)
2559 _where_criteria_to_add += (new_crit,)
2561 current_adapter = self._get_current_adapter()
2562 if current_adapter:
2563 # finally run all the criteria through the "main" adapter, if we
2564 # have one, and concatenate to final WHERE criteria
2565 for crit in _where_criteria_to_add:
2566 crit = current_adapter(crit, False)
2567 self._where_criteria += (crit,)
2568 else:
2569 # else just concatenate our criteria to the final WHERE criteria
2570 self._where_criteria += _where_criteria_to_add
2573def _column_descriptions(
2574 query_or_select_stmt: Union[Query, Select, FromStatement],
2575 compile_state: Optional[_ORMSelectCompileState] = None,
2576 legacy: bool = False,
2577) -> List[ORMColumnDescription]:
2578 if compile_state is None:
2579 compile_state = _ORMSelectCompileState._create_entities_collection(
2580 query_or_select_stmt, legacy=legacy
2581 )
2582 ctx = compile_state
2583 d = [
2584 {
2585 "name": ent._label_name,
2586 "type": ent.type,
2587 "aliased": getattr(insp_ent, "is_aliased_class", False),
2588 "expr": ent.expr,
2589 "entity": (
2590 getattr(insp_ent, "entity", None)
2591 if ent.entity_zero is not None
2592 and not insp_ent.is_clause_element
2593 else None
2594 ),
2595 }
2596 for ent, insp_ent in [
2597 (_ent, _ent.entity_zero) for _ent in ctx._entities
2598 ]
2599 ]
2600 return d
2603def _legacy_filter_by_entity_zero(
2604 query_or_augmented_select: Union[Query[Any], Select[Unpack[TupleAny]]],
2605) -> Optional[_InternalEntityType[Any]]:
2606 self = query_or_augmented_select
2607 if self._setup_joins:
2608 _last_joined_entity = self._last_joined_entity
2609 if _last_joined_entity is not None:
2610 return _last_joined_entity
2612 if self._from_obj and "parententity" in self._from_obj[0]._annotations:
2613 return self._from_obj[0]._annotations["parententity"]
2615 return _entity_from_pre_ent_zero(self)
2618def _entity_from_pre_ent_zero(
2619 query_or_augmented_select: Union[Query[Any], Select[Unpack[TupleAny]]],
2620) -> Optional[_InternalEntityType[Any]]:
2621 self = query_or_augmented_select
2622 if not self._raw_columns:
2623 return None
2625 ent = self._raw_columns[0]
2627 if "parententity" in ent._annotations:
2628 return ent._annotations["parententity"]
2629 elif isinstance(ent, ORMColumnsClauseRole):
2630 return ent.entity
2631 elif "bundle" in ent._annotations:
2632 return ent._annotations["bundle"]
2633 else:
2634 return ent
2637def _determine_last_joined_entity(
2638 setup_joins: Tuple[_SetupJoinsElement, ...],
2639 entity_zero: Optional[_InternalEntityType[Any]] = None,
2640) -> Optional[Union[_InternalEntityType[Any], _JoinTargetElement]]:
2641 if not setup_joins:
2642 return None
2644 (target, onclause, from_, flags) = setup_joins[-1]
2646 if isinstance(
2647 target,
2648 attributes.QueryableAttribute,
2649 ):
2650 return target.entity
2651 else:
2652 return target
2655class _QueryEntity:
2656 """represent an entity column returned within a Query result."""
2658 __slots__ = ()
2660 supports_single_entity: bool
2662 _non_hashable_value = False
2663 _null_column_type = False
2664 use_id_for_hash = False
2666 _label_name: Optional[str]
2667 type: Union[Type[Any], TypeEngine[Any]]
2668 expr: Union[_InternalEntityType, ColumnElement[Any]]
2669 entity_zero: Optional[_InternalEntityType]
2671 def setup_compile_state(self, compile_state: _ORMCompileState) -> None:
2672 raise NotImplementedError()
2674 def setup_dml_returning_compile_state(
2675 self,
2676 compile_state: _ORMCompileState,
2677 adapter: Optional[_DMLReturningColFilter],
2678 ) -> None:
2679 raise NotImplementedError()
2681 def row_processor(self, context, result):
2682 raise NotImplementedError()
2684 @classmethod
2685 def to_compile_state(
2686 cls, compile_state, entities, entities_collection, is_current_entities
2687 ):
2688 for idx, entity in enumerate(entities):
2689 if entity._is_lambda_element:
2690 if entity._is_sequence:
2691 cls.to_compile_state(
2692 compile_state,
2693 entity._resolved,
2694 entities_collection,
2695 is_current_entities,
2696 )
2697 continue
2698 else:
2699 entity = entity._resolved
2701 if entity.is_clause_element:
2702 if entity.is_selectable:
2703 if "parententity" in entity._annotations:
2704 _MapperEntity(
2705 compile_state,
2706 entity,
2707 entities_collection,
2708 is_current_entities,
2709 )
2710 else:
2711 _ColumnEntity._for_columns(
2712 compile_state,
2713 entity._select_iterable,
2714 entities_collection,
2715 idx,
2716 is_current_entities,
2717 )
2718 else:
2719 if entity._annotations.get("bundle", False):
2720 _BundleEntity(
2721 compile_state,
2722 entity,
2723 entities_collection,
2724 is_current_entities,
2725 )
2726 elif entity._is_clause_list:
2727 # this is legacy only - test_composites.py
2728 # test_query_cols_legacy
2729 _ColumnEntity._for_columns(
2730 compile_state,
2731 entity._select_iterable,
2732 entities_collection,
2733 idx,
2734 is_current_entities,
2735 )
2736 else:
2737 _ColumnEntity._for_columns(
2738 compile_state,
2739 [entity],
2740 entities_collection,
2741 idx,
2742 is_current_entities,
2743 )
2744 elif entity.is_bundle:
2745 _BundleEntity(compile_state, entity, entities_collection)
2747 return entities_collection
2750class _MapperEntity(_QueryEntity):
2751 """mapper/class/AliasedClass entity"""
2753 __slots__ = (
2754 "expr",
2755 "mapper",
2756 "entity_zero",
2757 "is_aliased_class",
2758 "path",
2759 "_extra_entities",
2760 "_label_name",
2761 "_with_polymorphic_mappers",
2762 "selectable",
2763 "_polymorphic_discriminator",
2764 )
2766 expr: _InternalEntityType
2767 mapper: Mapper[Any]
2768 entity_zero: _InternalEntityType
2769 is_aliased_class: bool
2770 path: PathRegistry
2771 _label_name: str
2773 def __init__(
2774 self, compile_state, entity, entities_collection, is_current_entities
2775 ):
2776 entities_collection.append(self)
2777 if is_current_entities:
2778 if compile_state._primary_entity is None:
2779 compile_state._primary_entity = self
2780 compile_state._has_mapper_entities = True
2781 compile_state._has_orm_entities = True
2783 entity = entity._annotations["parententity"]
2784 entity._post_inspect
2785 ext_info = self.entity_zero = entity
2786 entity = ext_info.entity
2788 self.expr = entity
2789 self.mapper = mapper = ext_info.mapper
2791 self._extra_entities = (self.expr,)
2793 if ext_info.is_aliased_class:
2794 self._label_name = ext_info.name
2795 else:
2796 self._label_name = mapper.class_.__name__
2798 self.is_aliased_class = ext_info.is_aliased_class
2799 self.path = ext_info._path_registry
2801 self.selectable = ext_info.selectable
2802 self._with_polymorphic_mappers = ext_info.with_polymorphic_mappers
2803 self._polymorphic_discriminator = ext_info.polymorphic_on
2805 if mapper._should_select_with_poly_adapter:
2806 compile_state._create_with_polymorphic_adapter(
2807 ext_info, self.selectable
2808 )
2810 supports_single_entity = True
2812 _non_hashable_value = True
2813 use_id_for_hash = True
2815 @property
2816 def type(self):
2817 return self.mapper.class_
2819 @property
2820 def entity_zero_or_selectable(self):
2821 return self.entity_zero
2823 def corresponds_to(self, entity):
2824 return _entity_corresponds_to(self.entity_zero, entity)
2826 def _get_entity_clauses(self, compile_state):
2827 adapter = None
2829 if not self.is_aliased_class:
2830 if compile_state._polymorphic_adapters:
2831 adapter = compile_state._polymorphic_adapters.get(
2832 self.mapper, None
2833 )
2834 else:
2835 adapter = self.entity_zero._adapter
2837 if adapter:
2838 if compile_state._from_obj_alias:
2839 ret = adapter.wrap(compile_state._from_obj_alias)
2840 else:
2841 ret = adapter
2842 else:
2843 ret = compile_state._from_obj_alias
2845 return ret
2847 def row_processor(self, context, result):
2848 compile_state = context.compile_state
2849 adapter = self._get_entity_clauses(compile_state)
2851 if compile_state.compound_eager_adapter and adapter:
2852 adapter = adapter.wrap(compile_state.compound_eager_adapter)
2853 elif not adapter:
2854 adapter = compile_state.compound_eager_adapter
2856 if compile_state._primary_entity is self:
2857 only_load_props = compile_state.compile_options._only_load_props
2858 refresh_state = context.refresh_state
2859 else:
2860 only_load_props = refresh_state = None
2862 _instance = loading._instance_processor(
2863 self,
2864 self.mapper,
2865 context,
2866 result,
2867 self.path,
2868 adapter,
2869 only_load_props=only_load_props,
2870 refresh_state=refresh_state,
2871 polymorphic_discriminator=self._polymorphic_discriminator,
2872 )
2874 return _instance, self._label_name, self._extra_entities
2876 def setup_dml_returning_compile_state(
2877 self,
2878 compile_state: _ORMCompileState,
2879 adapter: Optional[_DMLReturningColFilter],
2880 ) -> None:
2881 loading._setup_entity_query(
2882 compile_state,
2883 self.mapper,
2884 self,
2885 self.path,
2886 adapter,
2887 compile_state.primary_columns,
2888 with_polymorphic=self._with_polymorphic_mappers,
2889 only_load_props=compile_state.compile_options._only_load_props,
2890 polymorphic_discriminator=self._polymorphic_discriminator,
2891 )
2893 def setup_compile_state(self, compile_state):
2894 adapter = self._get_entity_clauses(compile_state)
2896 single_table_crit = self.mapper._single_table_criterion
2897 if (
2898 single_table_crit is not None
2899 or ("additional_entity_criteria", self.mapper)
2900 in compile_state.global_attributes
2901 ):
2902 ext_info = self.entity_zero
2903 compile_state.extra_criteria_entities[ext_info] = (
2904 ext_info,
2905 ext_info._adapter if ext_info.is_aliased_class else None,
2906 )
2908 loading._setup_entity_query(
2909 compile_state,
2910 self.mapper,
2911 self,
2912 self.path,
2913 adapter,
2914 compile_state.primary_columns,
2915 with_polymorphic=self._with_polymorphic_mappers,
2916 only_load_props=compile_state.compile_options._only_load_props,
2917 polymorphic_discriminator=self._polymorphic_discriminator,
2918 )
2919 compile_state._fallback_from_clauses.append(self.selectable)
2922class _BundleEntity(_QueryEntity):
2923 _extra_entities = ()
2925 __slots__ = (
2926 "bundle",
2927 "expr",
2928 "type",
2929 "_label_name",
2930 "_entities",
2931 "supports_single_entity",
2932 )
2934 _entities: List[_QueryEntity]
2935 bundle: Bundle
2936 type: Type[Any]
2937 _label_name: str
2938 supports_single_entity: bool
2939 expr: Bundle
2941 def __init__(
2942 self,
2943 compile_state,
2944 expr,
2945 entities_collection,
2946 is_current_entities,
2947 setup_entities=True,
2948 parent_bundle=None,
2949 ):
2950 compile_state._has_orm_entities = True
2952 expr = expr._annotations["bundle"]
2953 if parent_bundle:
2954 parent_bundle._entities.append(self)
2955 else:
2956 entities_collection.append(self)
2958 if isinstance(
2959 expr, (attributes.QueryableAttribute, interfaces.PropComparator)
2960 ):
2961 bundle = expr.__clause_element__()
2962 else:
2963 bundle = expr
2965 self.bundle = self.expr = bundle
2966 self.type = type(bundle)
2967 self._label_name = bundle.name
2968 self._entities = []
2970 if setup_entities:
2971 for expr in bundle.exprs:
2972 if "bundle" in expr._annotations:
2973 _BundleEntity(
2974 compile_state,
2975 expr,
2976 entities_collection,
2977 is_current_entities,
2978 parent_bundle=self,
2979 )
2980 elif isinstance(expr, Bundle):
2981 _BundleEntity(
2982 compile_state,
2983 expr,
2984 entities_collection,
2985 is_current_entities,
2986 parent_bundle=self,
2987 )
2988 else:
2989 _ORMColumnEntity._for_columns(
2990 compile_state,
2991 [expr],
2992 entities_collection,
2993 None,
2994 is_current_entities,
2995 parent_bundle=self,
2996 )
2998 self.supports_single_entity = self.bundle.single_entity
3000 @property
3001 def mapper(self):
3002 ezero = self.entity_zero
3003 if ezero is not None:
3004 return ezero.mapper
3005 else:
3006 return None
3008 @property
3009 def entity_zero(self):
3010 for ent in self._entities:
3011 ezero = ent.entity_zero
3012 if ezero is not None:
3013 return ezero
3014 else:
3015 return None
3017 def corresponds_to(self, entity):
3018 # TODO: we might be able to implement this but for now
3019 # we are working around it
3020 return False
3022 @property
3023 def entity_zero_or_selectable(self):
3024 for ent in self._entities:
3025 ezero = ent.entity_zero_or_selectable
3026 if ezero is not None:
3027 return ezero
3028 else:
3029 return None
3031 def setup_compile_state(self, compile_state):
3032 for ent in self._entities:
3033 ent.setup_compile_state(compile_state)
3035 def setup_dml_returning_compile_state(
3036 self,
3037 compile_state: _ORMCompileState,
3038 adapter: Optional[_DMLReturningColFilter],
3039 ) -> None:
3040 return self.setup_compile_state(compile_state)
3042 def row_processor(self, context, result):
3043 procs, labels, extra = zip(
3044 *[ent.row_processor(context, result) for ent in self._entities]
3045 )
3047 proc = self.bundle.create_row_processor(context.query, procs, labels)
3049 return proc, self._label_name, self._extra_entities
3052class _ColumnEntity(_QueryEntity):
3053 __slots__ = (
3054 "_fetch_column",
3055 "_row_processor",
3056 "raw_column_index",
3057 "translate_raw_column",
3058 )
3060 @classmethod
3061 def _for_columns(
3062 cls,
3063 compile_state,
3064 columns,
3065 entities_collection,
3066 raw_column_index,
3067 is_current_entities,
3068 parent_bundle=None,
3069 ):
3070 for column in columns:
3071 annotations = column._annotations
3072 if "parententity" in annotations:
3073 _entity = annotations["parententity"]
3074 else:
3075 _entity = sql_util.extract_first_column_annotation(
3076 column, "parententity"
3077 )
3079 if _entity:
3080 if "identity_token" in column._annotations:
3081 _IdentityTokenEntity(
3082 compile_state,
3083 column,
3084 entities_collection,
3085 _entity,
3086 raw_column_index,
3087 is_current_entities,
3088 parent_bundle=parent_bundle,
3089 )
3090 else:
3091 _ORMColumnEntity(
3092 compile_state,
3093 column,
3094 entities_collection,
3095 _entity,
3096 raw_column_index,
3097 is_current_entities,
3098 parent_bundle=parent_bundle,
3099 )
3100 else:
3101 _RawColumnEntity(
3102 compile_state,
3103 column,
3104 entities_collection,
3105 raw_column_index,
3106 is_current_entities,
3107 parent_bundle=parent_bundle,
3108 )
3110 @property
3111 def type(self):
3112 return self.column.type
3114 @property
3115 def _non_hashable_value(self):
3116 return not self.column.type.hashable
3118 @property
3119 def _null_column_type(self):
3120 return self.column.type._isnull
3122 def row_processor(self, context, result):
3123 compile_state = context.compile_state
3125 # the resulting callable is entirely cacheable so just return
3126 # it if we already made one
3127 if self._row_processor is not None:
3128 getter, label_name, extra_entities = self._row_processor
3129 if self.translate_raw_column:
3130 extra_entities += (
3131 context.query._raw_columns[self.raw_column_index],
3132 )
3134 return getter, label_name, extra_entities
3136 # retrieve the column that would have been set up in
3137 # setup_compile_state, to avoid doing redundant work
3138 if self._fetch_column is not None:
3139 column = self._fetch_column
3140 else:
3141 # fetch_column will be None when we are doing a from_statement
3142 # and setup_compile_state may not have been called.
3143 column = self.column
3145 # previously, the RawColumnEntity didn't look for from_obj_alias
3146 # however I can't think of a case where we would be here and
3147 # we'd want to ignore it if this is the from_statement use case.
3148 # it's not really a use case to have raw columns + from_statement
3149 if compile_state._from_obj_alias:
3150 column = compile_state._from_obj_alias.columns[column]
3152 if column._annotations:
3153 # annotated columns perform more slowly in compiler and
3154 # result due to the __eq__() method, so use deannotated
3155 column = column._deannotate()
3157 if compile_state.compound_eager_adapter:
3158 column = compile_state.compound_eager_adapter.columns[column]
3160 getter = result._getter(column)
3161 ret = getter, self._label_name, self._extra_entities
3162 self._row_processor = ret
3164 if self.translate_raw_column:
3165 extra_entities = self._extra_entities + (
3166 context.query._raw_columns[self.raw_column_index],
3167 )
3168 return getter, self._label_name, extra_entities
3169 else:
3170 return ret
3173class _RawColumnEntity(_ColumnEntity):
3174 entity_zero = None
3175 mapper = None
3176 supports_single_entity = False
3178 __slots__ = (
3179 "expr",
3180 "column",
3181 "_label_name",
3182 "entity_zero_or_selectable",
3183 "_extra_entities",
3184 )
3186 def __init__(
3187 self,
3188 compile_state,
3189 column,
3190 entities_collection,
3191 raw_column_index,
3192 is_current_entities,
3193 parent_bundle=None,
3194 ):
3195 self.expr = column
3196 self.raw_column_index = raw_column_index
3197 self.translate_raw_column = raw_column_index is not None
3199 if column._is_star:
3200 compile_state.compile_options += {"_is_star": True}
3202 if not is_current_entities or column._is_text_clause:
3203 self._label_name = None
3204 else:
3205 if parent_bundle:
3206 self._label_name = column._proxy_key
3207 else:
3208 self._label_name = compile_state._label_convention(column)
3210 if parent_bundle:
3211 parent_bundle._entities.append(self)
3212 else:
3213 entities_collection.append(self)
3215 self.column = column
3216 self.entity_zero_or_selectable = (
3217 self.column._from_objects[0] if self.column._from_objects else None
3218 )
3219 self._extra_entities = (self.expr, self.column)
3220 self._fetch_column = self._row_processor = None
3222 def corresponds_to(self, entity):
3223 return False
3225 def setup_dml_returning_compile_state(
3226 self,
3227 compile_state: _ORMCompileState,
3228 adapter: Optional[_DMLReturningColFilter],
3229 ) -> None:
3230 return self.setup_compile_state(compile_state)
3232 def setup_compile_state(self, compile_state):
3233 current_adapter = compile_state._get_current_adapter()
3234 if current_adapter:
3235 column = current_adapter(self.column, False)
3236 if column is None:
3237 return
3238 else:
3239 column = self.column
3241 if column._annotations:
3242 # annotated columns perform more slowly in compiler and
3243 # result due to the __eq__() method, so use deannotated
3244 column = column._deannotate()
3246 compile_state.dedupe_columns.add(column)
3247 compile_state.primary_columns.append(column)
3248 self._fetch_column = column
3251class _ORMColumnEntity(_ColumnEntity):
3252 """Column/expression based entity."""
3254 supports_single_entity = False
3256 __slots__ = (
3257 "expr",
3258 "mapper",
3259 "column",
3260 "_label_name",
3261 "entity_zero_or_selectable",
3262 "entity_zero",
3263 "_extra_entities",
3264 )
3266 def __init__(
3267 self,
3268 compile_state,
3269 column,
3270 entities_collection,
3271 parententity,
3272 raw_column_index,
3273 is_current_entities,
3274 parent_bundle=None,
3275 ):
3276 annotations = column._annotations
3278 _entity = parententity
3280 # an AliasedClass won't have proxy_key in the annotations for
3281 # a column if it was acquired using the class' adapter directly,
3282 # such as using AliasedInsp._adapt_element(). this occurs
3283 # within internal loaders.
3285 orm_key = annotations.get("proxy_key", None)
3286 proxy_owner = annotations.get("proxy_owner", _entity)
3287 if orm_key:
3288 self.expr = getattr(proxy_owner.entity, orm_key)
3289 self.translate_raw_column = False
3290 else:
3291 # if orm_key is not present, that means this is an ad-hoc
3292 # SQL ColumnElement, like a CASE() or other expression.
3293 # include this column position from the invoked statement
3294 # in the ORM-level ResultSetMetaData on each execute, so that
3295 # it can be targeted by identity after caching
3296 self.expr = column
3297 self.translate_raw_column = raw_column_index is not None
3299 self.raw_column_index = raw_column_index
3301 if is_current_entities:
3302 if parent_bundle:
3303 self._label_name = orm_key if orm_key else column._proxy_key
3304 else:
3305 self._label_name = compile_state._label_convention(
3306 column, col_name=orm_key
3307 )
3308 else:
3309 self._label_name = None
3311 _entity._post_inspect
3312 self.entity_zero = self.entity_zero_or_selectable = ezero = _entity
3313 self.mapper = mapper = _entity.mapper
3315 if parent_bundle:
3316 parent_bundle._entities.append(self)
3317 else:
3318 entities_collection.append(self)
3320 compile_state._has_orm_entities = True
3322 self.column = column
3324 self._fetch_column = self._row_processor = None
3326 self._extra_entities = (self.expr, self.column)
3328 if mapper._should_select_with_poly_adapter:
3329 compile_state._create_with_polymorphic_adapter(
3330 ezero, ezero.selectable
3331 )
3333 def corresponds_to(self, entity):
3334 if _is_aliased_class(entity):
3335 # TODO: polymorphic subclasses ?
3336 return entity is self.entity_zero
3337 else:
3338 return not _is_aliased_class(
3339 self.entity_zero
3340 ) and entity.common_parent(self.entity_zero)
3342 def setup_dml_returning_compile_state(
3343 self,
3344 compile_state: _ORMCompileState,
3345 adapter: Optional[_DMLReturningColFilter],
3346 ) -> None:
3348 self._fetch_column = column = self.column
3349 if adapter:
3350 column = adapter(column, False)
3352 if column is not None:
3353 compile_state.dedupe_columns.add(column)
3354 compile_state.primary_columns.append(column)
3356 def setup_compile_state(self, compile_state):
3357 current_adapter = compile_state._get_current_adapter()
3358 if current_adapter:
3359 column = current_adapter(self.column, False)
3360 if column is None:
3361 assert compile_state.is_dml_returning
3362 self._fetch_column = self.column
3363 return
3364 else:
3365 column = self.column
3367 ezero = self.entity_zero
3369 single_table_crit = self.mapper._single_table_criterion
3370 if (
3371 single_table_crit is not None
3372 or ("additional_entity_criteria", self.mapper)
3373 in compile_state.global_attributes
3374 ):
3375 compile_state.extra_criteria_entities[ezero] = (
3376 ezero,
3377 ezero._adapter if ezero.is_aliased_class else None,
3378 )
3380 if column._annotations and not column._expression_label:
3381 # annotated columns perform more slowly in compiler and
3382 # result due to the __eq__() method, so use deannotated
3383 column = column._deannotate()
3385 # use entity_zero as the from if we have it. this is necessary
3386 # for polymorphic scenarios where our FROM is based on ORM entity,
3387 # not the FROM of the column. but also, don't use it if our column
3388 # doesn't actually have any FROMs that line up, such as when its
3389 # a scalar subquery.
3390 if set(self.column._from_objects).intersection(
3391 ezero.selectable._from_objects
3392 ):
3393 compile_state._fallback_from_clauses.append(ezero.selectable)
3395 compile_state.dedupe_columns.add(column)
3396 compile_state.primary_columns.append(column)
3397 self._fetch_column = column
3400class _IdentityTokenEntity(_ORMColumnEntity):
3401 translate_raw_column = False
3403 def setup_compile_state(self, compile_state):
3404 pass
3406 def row_processor(self, context, result):
3407 def getter(row):
3408 return context.load_options._identity_token
3410 return getter, self._label_name, self._extra_entities