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 (
1409 self.multi_row_eager_loaders
1410 and self.eager_adding_joins
1411 and self._should_nest_selectable
1412 ):
1413 self.statement = self._compound_eager_statement()
1414 else:
1415 self.statement = self._simple_statement()
1417 if self.for_statement:
1418 ezero = self._mapper_zero()
1419 if ezero is not None:
1420 # TODO: this goes away once we get rid of the deep entity
1421 # thing
1422 self.statement = self.statement._annotate(
1423 {"deepentity": ezero}
1424 )
1426 @classmethod
1427 def _create_entities_collection(cls, query, legacy):
1428 """Creates a partial ORMSelectCompileState that includes
1429 the full collection of _MapperEntity and other _QueryEntity objects.
1431 Supports a few remaining use cases that are pre-compilation
1432 but still need to gather some of the column / adaption information.
1434 """
1435 self = cls.__new__(cls)
1437 self._entities = []
1438 self._primary_entity = None
1439 self._polymorphic_adapters = {}
1441 self._label_convention = self._column_naming_convention(
1442 query._label_style, legacy
1443 )
1445 # entities will also set up polymorphic adapters for mappers
1446 # that have with_polymorphic configured
1447 _QueryEntity.to_compile_state(
1448 self, query._raw_columns, self._entities, is_current_entities=True
1449 )
1450 return self
1452 @classmethod
1453 def determine_last_joined_entity(cls, statement):
1454 setup_joins = statement._setup_joins
1456 return _determine_last_joined_entity(setup_joins, None)
1458 @classmethod
1459 def all_selected_columns(cls, statement):
1460 for element in statement._raw_columns:
1461 if (
1462 element.is_selectable
1463 and "entity_namespace" in element._annotations
1464 ):
1465 ens = element._annotations["entity_namespace"]
1466 if not ens.is_mapper and not ens.is_aliased_class:
1467 yield from _select_iterables([element])
1468 else:
1469 yield from _select_iterables(ens._all_column_expressions)
1470 else:
1471 yield from _select_iterables([element])
1473 @classmethod
1474 def get_columns_clause_froms(cls, statement):
1475 return cls._normalize_froms(
1476 itertools.chain.from_iterable(
1477 (
1478 element._from_objects
1479 if "parententity" not in element._annotations
1480 else [
1481 element._annotations[
1482 "parententity"
1483 ].__clause_element__()
1484 ]
1485 )
1486 for element in statement._raw_columns
1487 )
1488 )
1490 @classmethod
1491 def from_statement(cls, statement, from_statement):
1492 from_statement = coercions.expect(
1493 roles.ReturnsRowsRole,
1494 from_statement,
1495 apply_propagate_attrs=statement,
1496 )
1498 stmt = FromStatement(statement._raw_columns, from_statement)
1500 stmt.__dict__.update(
1501 _with_options=statement._with_options,
1502 _compile_state_funcs=statement._compile_state_funcs,
1503 _execution_options=statement._execution_options,
1504 _propagate_attrs=statement._propagate_attrs,
1505 )
1506 return stmt
1508 def _set_select_from_alias(self):
1509 """used only for legacy Query cases"""
1511 query = self.select_statement # query
1513 assert self.compile_options._set_base_alias
1514 assert len(query._from_obj) == 1
1516 adapter = self._get_select_from_alias_from_obj(query._from_obj[0])
1517 if adapter:
1518 self.compile_options += {"_enable_single_crit": False}
1519 self._from_obj_alias = adapter
1521 def _get_select_from_alias_from_obj(self, from_obj):
1522 """used only for legacy Query cases"""
1524 info = from_obj
1526 if "parententity" in info._annotations:
1527 info = info._annotations["parententity"]
1529 if hasattr(info, "mapper"):
1530 if not info.is_aliased_class:
1531 raise sa_exc.ArgumentError(
1532 "A selectable (FromClause) instance is "
1533 "expected when the base alias is being set."
1534 )
1535 else:
1536 return info._adapter
1538 elif isinstance(info.selectable, sql.selectable.AliasedReturnsRows):
1539 equivs = self._all_equivs()
1540 assert info is info.selectable
1541 return ORMStatementAdapter(
1542 _TraceAdaptRole.LEGACY_SELECT_FROM_ALIAS,
1543 info.selectable,
1544 equivalents=equivs,
1545 )
1546 else:
1547 return None
1549 def _mapper_zero(self):
1550 """return the Mapper associated with the first QueryEntity."""
1551 return self._entities[0].mapper
1553 def _entity_zero(self):
1554 """Return the 'entity' (mapper or AliasedClass) associated
1555 with the first QueryEntity, or alternatively the 'select from'
1556 entity if specified."""
1558 for ent in self.from_clauses:
1559 if "parententity" in ent._annotations:
1560 return ent._annotations["parententity"]
1561 for qent in self._entities:
1562 if qent.entity_zero:
1563 return qent.entity_zero
1565 return None
1567 def _only_full_mapper_zero(self, methname):
1568 if self._entities != [self._primary_entity]:
1569 raise sa_exc.InvalidRequestError(
1570 "%s() can only be used against "
1571 "a single mapped class." % methname
1572 )
1573 return self._primary_entity.entity_zero
1575 def _only_entity_zero(self, rationale=None):
1576 if len(self._entities) > 1:
1577 raise sa_exc.InvalidRequestError(
1578 rationale
1579 or "This operation requires a Query "
1580 "against a single mapper."
1581 )
1582 return self._entity_zero()
1584 def _all_equivs(self):
1585 equivs = {}
1587 for memoized_entities in self._memoized_entities.values():
1588 for ent in [
1589 ent
1590 for ent in memoized_entities
1591 if isinstance(ent, _MapperEntity)
1592 ]:
1593 equivs.update(ent.mapper._equivalent_columns)
1595 for ent in [
1596 ent for ent in self._entities if isinstance(ent, _MapperEntity)
1597 ]:
1598 equivs.update(ent.mapper._equivalent_columns)
1599 return equivs
1601 def _compound_eager_statement(self):
1602 # for eager joins present and LIMIT/OFFSET/DISTINCT,
1603 # wrap the query inside a select,
1604 # then append eager joins onto that
1606 if self.order_by:
1607 # the default coercion for ORDER BY is now the OrderByRole,
1608 # which adds an additional post coercion to ByOfRole in that
1609 # elements are converted into label references. For the
1610 # eager load / subquery wrapping case, we need to un-coerce
1611 # the original expressions outside of the label references
1612 # in order to have them render.
1613 unwrapped_order_by = [
1614 (
1615 elem.element
1616 if isinstance(elem, sql.elements._label_reference)
1617 else elem
1618 )
1619 for elem in self.order_by
1620 ]
1622 order_by_col_expr = sql_util.expand_column_list_from_order_by(
1623 self.primary_columns, unwrapped_order_by
1624 )
1625 else:
1626 order_by_col_expr = []
1627 unwrapped_order_by = None
1629 # put FOR UPDATE on the inner query, where MySQL will honor it,
1630 # as well as if it has an OF so PostgreSQL can use it.
1631 inner = self._select_statement(
1632 self.primary_columns
1633 + [c for c in order_by_col_expr if c not in self.dedupe_columns],
1634 self.from_clauses,
1635 self._where_criteria,
1636 self._having_criteria,
1637 self.label_style,
1638 self.order_by,
1639 for_update=self._for_update_arg,
1640 hints=self.select_statement._hints,
1641 statement_hints=self.select_statement._statement_hints,
1642 correlate=self.correlate,
1643 correlate_except=self.correlate_except,
1644 **self._select_args,
1645 )
1647 inner = inner.alias()
1649 equivs = self._all_equivs()
1651 self.compound_eager_adapter = ORMStatementAdapter(
1652 _TraceAdaptRole.COMPOUND_EAGER_STATEMENT, inner, equivalents=equivs
1653 )
1655 statement = future.select(
1656 *([inner] + self.secondary_columns) # use_labels=self.labels
1657 )
1658 statement._label_style = self.label_style
1660 # Oracle Database however does not allow FOR UPDATE on the subquery,
1661 # and the Oracle Database dialects ignore it, plus for PostgreSQL,
1662 # MySQL we expect that all elements of the row are locked, so also put
1663 # it on the outside (except in the case of PG when OF is used)
1664 if (
1665 self._for_update_arg is not None
1666 and self._for_update_arg.of is None
1667 ):
1668 statement._for_update_arg = self._for_update_arg
1670 from_clause = inner
1671 for eager_join in self.eager_joins.values():
1672 # EagerLoader places a 'stop_on' attribute on the join,
1673 # giving us a marker as to where the "splice point" of
1674 # the join should be
1675 from_clause = sql_util.splice_joins(
1676 from_clause, eager_join, eager_join.stop_on
1677 )
1679 statement.select_from.non_generative(statement, from_clause)
1681 if unwrapped_order_by:
1682 statement.order_by.non_generative(
1683 statement,
1684 *self.compound_eager_adapter.copy_and_process(
1685 unwrapped_order_by
1686 ),
1687 )
1689 statement.order_by.non_generative(statement, *self.eager_order_by)
1690 return statement
1692 def _simple_statement(self):
1693 statement = self._select_statement(
1694 self.primary_columns + self.secondary_columns,
1695 tuple(self.from_clauses) + tuple(self.eager_joins.values()),
1696 self._where_criteria,
1697 self._having_criteria,
1698 self.label_style,
1699 self.order_by,
1700 for_update=self._for_update_arg,
1701 hints=self.select_statement._hints,
1702 statement_hints=self.select_statement._statement_hints,
1703 correlate=self.correlate,
1704 correlate_except=self.correlate_except,
1705 **self._select_args,
1706 )
1708 if self.eager_order_by:
1709 statement.order_by.non_generative(statement, *self.eager_order_by)
1710 return statement
1712 def _select_statement(
1713 self,
1714 raw_columns,
1715 from_obj,
1716 where_criteria,
1717 having_criteria,
1718 label_style,
1719 order_by,
1720 for_update,
1721 hints,
1722 statement_hints,
1723 correlate,
1724 correlate_except,
1725 limit_clause,
1726 offset_clause,
1727 fetch_clause,
1728 fetch_clause_options,
1729 distinct,
1730 distinct_on,
1731 prefixes,
1732 suffixes,
1733 group_by,
1734 independent_ctes,
1735 independent_ctes_opts,
1736 syntax_extensions,
1737 ):
1738 statement = Select._create_raw_select(
1739 _raw_columns=raw_columns,
1740 _from_obj=from_obj,
1741 _label_style=label_style,
1742 )
1744 if where_criteria:
1745 statement._where_criteria = where_criteria
1746 if having_criteria:
1747 statement._having_criteria = having_criteria
1749 if order_by:
1750 statement._order_by_clauses += tuple(order_by)
1752 if distinct_on:
1753 statement._distinct = True
1754 statement._distinct_on = distinct_on
1755 elif distinct:
1756 statement._distinct = True
1758 if group_by:
1759 statement._group_by_clauses += tuple(group_by)
1761 statement._limit_clause = limit_clause
1762 statement._offset_clause = offset_clause
1763 statement._fetch_clause = fetch_clause
1764 statement._fetch_clause_options = fetch_clause_options
1765 statement._independent_ctes = independent_ctes
1766 statement._independent_ctes_opts = independent_ctes_opts
1767 if syntax_extensions:
1768 statement._set_syntax_extensions(**syntax_extensions)
1770 if prefixes:
1771 statement._prefixes = prefixes
1773 if suffixes:
1774 statement._suffixes = suffixes
1776 statement._for_update_arg = for_update
1778 if hints:
1779 statement._hints = hints
1780 if statement_hints:
1781 statement._statement_hints = statement_hints
1783 if correlate:
1784 statement.correlate.non_generative(statement, *correlate)
1786 if correlate_except is not None:
1787 statement.correlate_except.non_generative(
1788 statement, *correlate_except
1789 )
1791 return statement
1793 def _adapt_polymorphic_element(self, element):
1794 if "parententity" in element._annotations:
1795 search = element._annotations["parententity"]
1796 alias = self._polymorphic_adapters.get(search, None)
1797 if alias:
1798 return alias.adapt_clause(element)
1800 if isinstance(element, expression.FromClause):
1801 search = element
1802 elif hasattr(element, "table"):
1803 search = element.table
1804 else:
1805 return None
1807 alias = self._polymorphic_adapters.get(search, None)
1808 if alias:
1809 return alias.adapt_clause(element)
1811 def _adapt_col_list(self, cols, current_adapter):
1812 if current_adapter:
1813 return [current_adapter(o, True) for o in cols]
1814 else:
1815 return cols
1817 def _get_current_adapter(self):
1818 adapters = []
1820 if self._from_obj_alias:
1821 # used for legacy going forward for query set_ops, e.g.
1822 # union(), union_all(), etc.
1823 # 1.4 and previously, also used for from_self(),
1824 # select_entity_from()
1825 #
1826 # for the "from obj" alias, apply extra rule to the
1827 # 'ORM only' check, if this query were generated from a
1828 # subquery of itself, i.e. _from_selectable(), apply adaption
1829 # to all SQL constructs.
1830 adapters.append(
1831 self._from_obj_alias.replace,
1832 )
1834 # this was *hopefully* the only adapter we were going to need
1835 # going forward...however, we unfortunately need _from_obj_alias
1836 # for query.union(), which we can't drop
1837 if self._polymorphic_adapters:
1838 adapters.append(self._adapt_polymorphic_element)
1840 if not adapters:
1841 return None
1843 def _adapt_clause(clause, as_filter):
1844 # do we adapt all expression elements or only those
1845 # tagged as 'ORM' constructs ?
1847 def replace(elem):
1848 for adapter in adapters:
1849 e = adapter(elem)
1850 if e is not None:
1851 return e
1853 return visitors.replacement_traverse(clause, {}, replace)
1855 return _adapt_clause
1857 def _join(self, args, entities_collection):
1858 for right, onclause, from_, flags in args:
1859 isouter = flags["isouter"]
1860 full = flags["full"]
1862 right = inspect(right)
1863 if onclause is not None:
1864 onclause = inspect(onclause)
1866 if isinstance(right, interfaces.PropComparator):
1867 if onclause is not None:
1868 raise sa_exc.InvalidRequestError(
1869 "No 'on clause' argument may be passed when joining "
1870 "to a relationship path as a target"
1871 )
1873 onclause = right
1874 right = None
1875 elif "parententity" in right._annotations:
1876 right = right._annotations["parententity"]
1878 if onclause is None:
1879 if not right.is_selectable and not hasattr(right, "mapper"):
1880 raise sa_exc.ArgumentError(
1881 "Expected mapped entity or "
1882 "selectable/table as join target"
1883 )
1885 if isinstance(onclause, interfaces.PropComparator):
1886 # descriptor/property given (or determined); this tells us
1887 # explicitly what the expected "left" side of the join is.
1889 of_type = getattr(onclause, "_of_type", None)
1891 if right is None:
1892 if of_type:
1893 right = of_type
1894 else:
1895 right = onclause.property
1897 try:
1898 right = right.entity
1899 except AttributeError as err:
1900 raise sa_exc.ArgumentError(
1901 "Join target %s does not refer to a "
1902 "mapped entity" % right
1903 ) from err
1905 left = onclause._parententity
1907 prop = onclause.property
1908 if not isinstance(onclause, attributes.QueryableAttribute):
1909 onclause = prop
1911 # check for this path already present. don't render in that
1912 # case.
1913 if (left, right, prop.key) in self._already_joined_edges:
1914 continue
1916 if from_ is not None:
1917 if (
1918 from_ is not left
1919 and from_._annotations.get("parententity", None)
1920 is not left
1921 ):
1922 raise sa_exc.InvalidRequestError(
1923 "explicit from clause %s does not match left side "
1924 "of relationship attribute %s"
1925 % (
1926 from_._annotations.get("parententity", from_),
1927 onclause,
1928 )
1929 )
1930 elif from_ is not None:
1931 prop = None
1932 left = from_
1933 else:
1934 # no descriptor/property given; we will need to figure out
1935 # what the effective "left" side is
1936 prop = left = None
1938 # figure out the final "left" and "right" sides and create an
1939 # ORMJoin to add to our _from_obj tuple
1940 self._join_left_to_right(
1941 entities_collection,
1942 left,
1943 right,
1944 onclause,
1945 prop,
1946 isouter,
1947 full,
1948 )
1950 def _join_left_to_right(
1951 self,
1952 entities_collection,
1953 left,
1954 right,
1955 onclause,
1956 prop,
1957 outerjoin,
1958 full,
1959 ):
1960 """given raw "left", "right", "onclause" parameters consumed from
1961 a particular key within _join(), add a real ORMJoin object to
1962 our _from_obj list (or augment an existing one)
1964 """
1966 if left is None:
1967 # left not given (e.g. no relationship object/name specified)
1968 # figure out the best "left" side based on our existing froms /
1969 # entities
1970 assert prop is None
1971 (
1972 left,
1973 replace_from_obj_index,
1974 use_entity_index,
1975 ) = self._join_determine_implicit_left_side(
1976 entities_collection, left, right, onclause
1977 )
1978 else:
1979 # left is given via a relationship/name, or as explicit left side.
1980 # Determine where in our
1981 # "froms" list it should be spliced/appended as well as what
1982 # existing entity it corresponds to.
1983 (
1984 replace_from_obj_index,
1985 use_entity_index,
1986 ) = self._join_place_explicit_left_side(entities_collection, left)
1988 if left is right:
1989 raise sa_exc.InvalidRequestError(
1990 "Can't construct a join from %s to %s, they "
1991 "are the same entity" % (left, right)
1992 )
1994 # the right side as given often needs to be adapted. additionally
1995 # a lot of things can be wrong with it. handle all that and
1996 # get back the new effective "right" side
1997 r_info, right, onclause = self._join_check_and_adapt_right_side(
1998 left, right, onclause, prop
1999 )
2001 if not r_info.is_selectable:
2002 extra_criteria = self._get_extra_criteria(r_info)
2003 else:
2004 extra_criteria = ()
2006 if replace_from_obj_index is not None:
2007 # splice into an existing element in the
2008 # self._from_obj list
2009 left_clause = self.from_clauses[replace_from_obj_index]
2011 self.from_clauses = (
2012 self.from_clauses[:replace_from_obj_index]
2013 + [
2014 _ORMJoin(
2015 left_clause,
2016 right,
2017 onclause,
2018 isouter=outerjoin,
2019 full=full,
2020 _extra_criteria=extra_criteria,
2021 )
2022 ]
2023 + self.from_clauses[replace_from_obj_index + 1 :]
2024 )
2025 else:
2026 # add a new element to the self._from_obj list
2027 if use_entity_index is not None:
2028 # make use of _MapperEntity selectable, which is usually
2029 # entity_zero.selectable, but if with_polymorphic() were used
2030 # might be distinct
2031 assert isinstance(
2032 entities_collection[use_entity_index], _MapperEntity
2033 )
2034 left_clause = entities_collection[use_entity_index].selectable
2035 else:
2036 left_clause = left
2038 self.from_clauses = self.from_clauses + [
2039 _ORMJoin(
2040 left_clause,
2041 r_info,
2042 onclause,
2043 isouter=outerjoin,
2044 full=full,
2045 _extra_criteria=extra_criteria,
2046 )
2047 ]
2049 def _join_determine_implicit_left_side(
2050 self, entities_collection, left, right, onclause
2051 ):
2052 """When join conditions don't express the left side explicitly,
2053 determine if an existing FROM or entity in this query
2054 can serve as the left hand side.
2056 """
2058 # when we are here, it means join() was called without an ORM-
2059 # specific way of telling us what the "left" side is, e.g.:
2060 #
2061 # join(RightEntity)
2062 #
2063 # or
2064 #
2065 # join(RightEntity, RightEntity.foo == LeftEntity.bar)
2066 #
2068 r_info = inspect(right)
2070 replace_from_obj_index = use_entity_index = None
2072 if self.from_clauses:
2073 # we have a list of FROMs already. So by definition this
2074 # join has to connect to one of those FROMs.
2076 indexes = sql_util.find_left_clause_to_join_from(
2077 self.from_clauses, r_info.selectable, onclause
2078 )
2080 if len(indexes) == 1:
2081 replace_from_obj_index = indexes[0]
2082 left = self.from_clauses[replace_from_obj_index]
2083 elif len(indexes) > 1:
2084 raise sa_exc.InvalidRequestError(
2085 "Can't determine which FROM clause to join "
2086 "from, there are multiple FROMS which can "
2087 "join to this entity. Please use the .select_from() "
2088 "method to establish an explicit left side, as well as "
2089 "providing an explicit ON clause if not present already "
2090 "to help resolve the ambiguity."
2091 )
2092 else:
2093 raise sa_exc.InvalidRequestError(
2094 "Don't know how to join to %r. "
2095 "Please use the .select_from() "
2096 "method to establish an explicit left side, as well as "
2097 "providing an explicit ON clause if not present already "
2098 "to help resolve the ambiguity." % (right,)
2099 )
2101 elif entities_collection:
2102 # we have no explicit FROMs, so the implicit left has to
2103 # come from our list of entities.
2105 potential = {}
2106 for entity_index, ent in enumerate(entities_collection):
2107 entity = ent.entity_zero_or_selectable
2108 if entity is None:
2109 continue
2110 ent_info = inspect(entity)
2111 if ent_info is r_info: # left and right are the same, skip
2112 continue
2114 # by using a dictionary with the selectables as keys this
2115 # de-duplicates those selectables as occurs when the query is
2116 # against a series of columns from the same selectable
2117 if isinstance(ent, _MapperEntity):
2118 potential[ent.selectable] = (entity_index, entity)
2119 else:
2120 potential[ent_info.selectable] = (None, entity)
2122 all_clauses = list(potential.keys())
2123 indexes = sql_util.find_left_clause_to_join_from(
2124 all_clauses, r_info.selectable, onclause
2125 )
2127 if len(indexes) == 1:
2128 use_entity_index, left = potential[all_clauses[indexes[0]]]
2129 elif len(indexes) > 1:
2130 raise sa_exc.InvalidRequestError(
2131 "Can't determine which FROM clause to join "
2132 "from, there are multiple FROMS which can "
2133 "join to this entity. Please use the .select_from() "
2134 "method to establish an explicit left side, as well as "
2135 "providing an explicit ON clause if not present already "
2136 "to help resolve the ambiguity."
2137 )
2138 else:
2139 raise sa_exc.InvalidRequestError(
2140 "Don't know how to join to %r. "
2141 "Please use the .select_from() "
2142 "method to establish an explicit left side, as well as "
2143 "providing an explicit ON clause if not present already "
2144 "to help resolve the ambiguity." % (right,)
2145 )
2146 else:
2147 raise sa_exc.InvalidRequestError(
2148 "No entities to join from; please use "
2149 "select_from() to establish the left "
2150 "entity/selectable of this join"
2151 )
2153 return left, replace_from_obj_index, use_entity_index
2155 def _join_place_explicit_left_side(self, entities_collection, left):
2156 """When join conditions express a left side explicitly, determine
2157 where in our existing list of FROM clauses we should join towards,
2158 or if we need to make a new join, and if so is it from one of our
2159 existing entities.
2161 """
2163 # when we are here, it means join() was called with an indicator
2164 # as to an exact left side, which means a path to a
2165 # Relationship was given, e.g.:
2166 #
2167 # join(RightEntity, LeftEntity.right)
2168 #
2169 # or
2170 #
2171 # join(LeftEntity.right)
2172 #
2173 # as well as string forms:
2174 #
2175 # join(RightEntity, "right")
2176 #
2177 # etc.
2178 #
2180 replace_from_obj_index = use_entity_index = None
2182 l_info = inspect(left)
2183 if self.from_clauses:
2184 indexes = sql_util.find_left_clause_that_matches_given(
2185 self.from_clauses, l_info.selectable
2186 )
2188 if len(indexes) > 1:
2189 raise sa_exc.InvalidRequestError(
2190 "Can't identify which entity in which to assign the "
2191 "left side of this join. Please use a more specific "
2192 "ON clause."
2193 )
2195 # have an index, means the left side is already present in
2196 # an existing FROM in the self._from_obj tuple
2197 if indexes:
2198 replace_from_obj_index = indexes[0]
2200 # no index, means we need to add a new element to the
2201 # self._from_obj tuple
2203 # no from element present, so we will have to add to the
2204 # self._from_obj tuple. Determine if this left side matches up
2205 # with existing mapper entities, in which case we want to apply the
2206 # aliasing / adaptation rules present on that entity if any
2207 if (
2208 replace_from_obj_index is None
2209 and entities_collection
2210 and hasattr(l_info, "mapper")
2211 ):
2212 for idx, ent in enumerate(entities_collection):
2213 # TODO: should we be checking for multiple mapper entities
2214 # matching?
2215 if isinstance(ent, _MapperEntity) and ent.corresponds_to(left):
2216 use_entity_index = idx
2217 break
2219 return replace_from_obj_index, use_entity_index
2221 def _join_check_and_adapt_right_side(self, left, right, onclause, prop):
2222 """transform the "right" side of the join as well as the onclause
2223 according to polymorphic mapping translations, aliasing on the query
2224 or on the join, special cases where the right and left side have
2225 overlapping tables.
2227 """
2229 l_info = inspect(left)
2230 r_info = inspect(right)
2232 overlap = False
2234 right_mapper = getattr(r_info, "mapper", None)
2235 # if the target is a joined inheritance mapping,
2236 # be more liberal about auto-aliasing.
2237 if right_mapper and (
2238 right_mapper.with_polymorphic
2239 or isinstance(right_mapper.persist_selectable, expression.Join)
2240 ):
2241 for from_obj in self.from_clauses or [l_info.selectable]:
2242 if sql_util.selectables_overlap(
2243 l_info.selectable, from_obj
2244 ) and sql_util.selectables_overlap(
2245 from_obj, r_info.selectable
2246 ):
2247 overlap = True
2248 break
2250 if overlap and l_info.selectable is r_info.selectable:
2251 raise sa_exc.InvalidRequestError(
2252 "Can't join table/selectable '%s' to itself"
2253 % l_info.selectable
2254 )
2256 right_mapper, right_selectable, right_is_aliased = (
2257 getattr(r_info, "mapper", None),
2258 r_info.selectable,
2259 getattr(r_info, "is_aliased_class", False),
2260 )
2262 if (
2263 right_mapper
2264 and prop
2265 and not right_mapper.common_parent(prop.mapper)
2266 ):
2267 raise sa_exc.InvalidRequestError(
2268 "Join target %s does not correspond to "
2269 "the right side of join condition %s" % (right, onclause)
2270 )
2272 # _join_entities is used as a hint for single-table inheritance
2273 # purposes at the moment
2274 if hasattr(r_info, "mapper"):
2275 self._join_entities += (r_info,)
2277 need_adapter = False
2279 # test for joining to an unmapped selectable as the target
2280 if r_info.is_clause_element:
2281 if prop:
2282 right_mapper = prop.mapper
2284 if right_selectable._is_lateral:
2285 # orm_only is disabled to suit the case where we have to
2286 # adapt an explicit correlate(Entity) - the select() loses
2287 # the ORM-ness in this case right now, ideally it would not
2288 current_adapter = self._get_current_adapter()
2289 if current_adapter is not None:
2290 # TODO: we had orm_only=False here before, removing
2291 # it didn't break things. if we identify the rationale,
2292 # may need to apply "_orm_only" annotation here.
2293 right = current_adapter(right, True)
2295 elif prop:
2296 # joining to selectable with a mapper property given
2297 # as the ON clause
2299 if not right_selectable.is_derived_from(
2300 right_mapper.persist_selectable
2301 ):
2302 raise sa_exc.InvalidRequestError(
2303 "Selectable '%s' is not derived from '%s'"
2304 % (
2305 right_selectable.description,
2306 right_mapper.persist_selectable.description,
2307 )
2308 )
2310 # if the destination selectable is a plain select(),
2311 # turn it into an alias().
2312 if isinstance(right_selectable, expression.SelectBase):
2313 right_selectable = coercions.expect(
2314 roles.FromClauseRole, right_selectable
2315 )
2316 need_adapter = True
2318 # make the right hand side target into an ORM entity
2319 right = AliasedClass(right_mapper, right_selectable)
2321 util.warn_deprecated(
2322 "An alias is being generated automatically against "
2323 "joined entity %s for raw clauseelement, which is "
2324 "deprecated and will be removed in a later release. "
2325 "Use the aliased() "
2326 "construct explicitly, see the linked example."
2327 % right_mapper,
2328 "1.4",
2329 code="xaj1",
2330 )
2332 # test for overlap:
2333 # orm/inheritance/relationships.py
2334 # SelfReferentialM2MTest
2335 aliased_entity = right_mapper and not right_is_aliased and overlap
2337 if not need_adapter and aliased_entity:
2338 # there are a few places in the ORM that automatic aliasing
2339 # is still desirable, and can't be automatic with a Core
2340 # only approach. For illustrations of "overlaps" see
2341 # test/orm/inheritance/test_relationships.py. There are also
2342 # general overlap cases with many-to-many tables where automatic
2343 # aliasing is desirable.
2344 right = AliasedClass(right, flat=True)
2345 need_adapter = True
2347 util.warn(
2348 "An alias is being generated automatically against "
2349 "joined entity %s due to overlapping tables. This is a "
2350 "legacy pattern which may be "
2351 "deprecated in a later release. Use the "
2352 "aliased(<entity>, flat=True) "
2353 "construct explicitly, see the linked example." % right_mapper,
2354 code="xaj2",
2355 )
2357 if need_adapter:
2358 # if need_adapter is True, we are in a deprecated case and
2359 # a warning has been emitted.
2360 assert right_mapper
2362 adapter = ORMAdapter(
2363 _TraceAdaptRole.DEPRECATED_JOIN_ADAPT_RIGHT_SIDE,
2364 inspect(right),
2365 equivalents=right_mapper._equivalent_columns,
2366 )
2368 # if an alias() on the right side was generated,
2369 # which is intended to wrap a the right side in a subquery,
2370 # ensure that columns retrieved from this target in the result
2371 # set are also adapted.
2372 self._mapper_loads_polymorphically_with(right_mapper, adapter)
2373 elif (
2374 not r_info.is_clause_element
2375 and not right_is_aliased
2376 and right_mapper._has_aliased_polymorphic_fromclause
2377 ):
2378 # for the case where the target mapper has a with_polymorphic
2379 # set up, ensure an adapter is set up for criteria that works
2380 # against this mapper. Previously, this logic used to
2381 # use the "create_aliases or aliased_entity" case to generate
2382 # an aliased() object, but this creates an alias that isn't
2383 # strictly necessary.
2384 # see test/orm/test_core_compilation.py
2385 # ::RelNaturalAliasedJoinsTest::test_straight
2386 # and similar
2387 self._mapper_loads_polymorphically_with(
2388 right_mapper,
2389 ORMAdapter(
2390 _TraceAdaptRole.WITH_POLYMORPHIC_ADAPTER_RIGHT_JOIN,
2391 right_mapper,
2392 selectable=right_mapper.selectable,
2393 equivalents=right_mapper._equivalent_columns,
2394 ),
2395 )
2396 # if the onclause is a ClauseElement, adapt it with any
2397 # adapters that are in place right now
2398 if isinstance(onclause, expression.ClauseElement):
2399 current_adapter = self._get_current_adapter()
2400 if current_adapter:
2401 onclause = current_adapter(onclause, True)
2403 # if joining on a MapperProperty path,
2404 # track the path to prevent redundant joins
2405 if prop:
2406 self._already_joined_edges += ((left, right, prop.key),)
2408 return inspect(right), right, onclause
2410 @property
2411 def _select_args(self):
2412 return {
2413 "limit_clause": self.select_statement._limit_clause,
2414 "offset_clause": self.select_statement._offset_clause,
2415 "distinct": self.distinct,
2416 "distinct_on": self.distinct_on,
2417 "prefixes": self.select_statement._prefixes,
2418 "suffixes": self.select_statement._suffixes,
2419 "group_by": self.group_by or None,
2420 "fetch_clause": self.select_statement._fetch_clause,
2421 "fetch_clause_options": (
2422 self.select_statement._fetch_clause_options
2423 ),
2424 "independent_ctes": self.select_statement._independent_ctes,
2425 "independent_ctes_opts": (
2426 self.select_statement._independent_ctes_opts
2427 ),
2428 "syntax_extensions": self.syntax_extensions,
2429 }
2431 @property
2432 def _should_nest_selectable(self):
2433 kwargs = self._select_args
2434 return (
2435 kwargs.get("limit_clause") is not None
2436 or kwargs.get("offset_clause") is not None
2437 or kwargs.get("distinct", False)
2438 or kwargs.get("distinct_on", ())
2439 or kwargs.get("group_by", False)
2440 )
2442 def _get_extra_criteria(self, ext_info):
2443 if (
2444 "additional_entity_criteria",
2445 ext_info.mapper,
2446 ) in self.global_attributes:
2447 return tuple(
2448 ae._resolve_where_criteria(ext_info)
2449 for ae in self.global_attributes[
2450 ("additional_entity_criteria", ext_info.mapper)
2451 ]
2452 if (ae.include_aliases or ae.entity is ext_info)
2453 and ae._should_include(self)
2454 )
2455 else:
2456 return ()
2458 def _adjust_for_extra_criteria(self):
2459 """Apply extra criteria filtering.
2461 For all distinct single-table-inheritance mappers represented in
2462 the columns clause of this query, as well as the "select from entity",
2463 add criterion to the WHERE
2464 clause of the given QueryContext such that only the appropriate
2465 subtypes are selected from the total results.
2467 Additionally, add WHERE criteria originating from LoaderCriteriaOptions
2468 associated with the global context.
2470 """
2472 for fromclause in self.from_clauses:
2473 ext_info = fromclause._annotations.get("parententity", None)
2475 if (
2476 ext_info
2477 and (
2478 ext_info.mapper._single_table_criterion is not None
2479 or ("additional_entity_criteria", ext_info.mapper)
2480 in self.global_attributes
2481 )
2482 and ext_info not in self.extra_criteria_entities
2483 ):
2484 self.extra_criteria_entities[ext_info] = (
2485 ext_info,
2486 ext_info._adapter if ext_info.is_aliased_class else None,
2487 )
2489 _where_criteria_to_add = ()
2491 merged_single_crit = collections.defaultdict(
2492 lambda: (util.OrderedSet(), set())
2493 )
2495 for ext_info, adapter in util.OrderedSet(
2496 self.extra_criteria_entities.values()
2497 ):
2498 if ext_info in self._join_entities:
2499 continue
2501 # assemble single table inheritance criteria.
2502 if (
2503 ext_info.is_aliased_class
2504 and ext_info._base_alias()._is_with_polymorphic
2505 ):
2506 # for a with_polymorphic(), we always include the full
2507 # hierarchy from what's given as the base class for the wpoly.
2508 # this is new in 2.1 for #12395 so that it matches the behavior
2509 # of joined inheritance.
2510 hierarchy_root = ext_info._base_alias()
2511 else:
2512 hierarchy_root = ext_info
2514 single_crit_component = (
2515 hierarchy_root.mapper._single_table_criteria_component
2516 )
2518 if single_crit_component is not None:
2519 polymorphic_on, criteria = single_crit_component
2521 polymorphic_on = polymorphic_on._annotate(
2522 {
2523 "parententity": hierarchy_root,
2524 "parentmapper": hierarchy_root.mapper,
2525 }
2526 )
2528 list_of_single_crits, adapters = merged_single_crit[
2529 (hierarchy_root, polymorphic_on)
2530 ]
2531 list_of_single_crits.update(criteria)
2532 if adapter:
2533 adapters.add(adapter)
2535 # assemble "additional entity criteria", which come from
2536 # with_loader_criteria() options
2537 if not self.compile_options._for_refresh_state:
2538 additional_entity_criteria = self._get_extra_criteria(ext_info)
2539 _where_criteria_to_add += tuple(
2540 adapter.traverse(crit) if adapter else crit
2541 for crit in additional_entity_criteria
2542 )
2544 # merge together single table inheritance criteria keyed to
2545 # top-level mapper / aliasedinsp (which may be a with_polymorphic())
2546 for (ext_info, polymorphic_on), (
2547 merged_crit,
2548 adapters,
2549 ) in merged_single_crit.items():
2550 new_crit = polymorphic_on.in_(merged_crit)
2551 for adapter in adapters:
2552 new_crit = adapter.traverse(new_crit)
2553 _where_criteria_to_add += (new_crit,)
2555 current_adapter = self._get_current_adapter()
2556 if current_adapter:
2557 # finally run all the criteria through the "main" adapter, if we
2558 # have one, and concatenate to final WHERE criteria
2559 for crit in _where_criteria_to_add:
2560 crit = current_adapter(crit, False)
2561 self._where_criteria += (crit,)
2562 else:
2563 # else just concatenate our criteria to the final WHERE criteria
2564 self._where_criteria += _where_criteria_to_add
2567def _column_descriptions(
2568 query_or_select_stmt: Union[Query, Select, FromStatement],
2569 compile_state: Optional[_ORMSelectCompileState] = None,
2570 legacy: bool = False,
2571) -> List[ORMColumnDescription]:
2572 if compile_state is None:
2573 compile_state = _ORMSelectCompileState._create_entities_collection(
2574 query_or_select_stmt, legacy=legacy
2575 )
2576 ctx = compile_state
2577 d = [
2578 {
2579 "name": ent._label_name,
2580 "type": ent.type,
2581 "aliased": getattr(insp_ent, "is_aliased_class", False),
2582 "expr": ent.expr,
2583 "entity": (
2584 getattr(insp_ent, "entity", None)
2585 if ent.entity_zero is not None
2586 and not insp_ent.is_clause_element
2587 else None
2588 ),
2589 }
2590 for ent, insp_ent in [
2591 (_ent, _ent.entity_zero) for _ent in ctx._entities
2592 ]
2593 ]
2594 return d
2597def _legacy_filter_by_entity_zero(
2598 query_or_augmented_select: Union[Query[Any], Select[Unpack[TupleAny]]],
2599) -> Optional[_InternalEntityType[Any]]:
2600 self = query_or_augmented_select
2601 if self._setup_joins:
2602 _last_joined_entity = self._last_joined_entity
2603 if _last_joined_entity is not None:
2604 return _last_joined_entity
2606 if self._from_obj and "parententity" in self._from_obj[0]._annotations:
2607 return self._from_obj[0]._annotations["parententity"]
2609 return _entity_from_pre_ent_zero(self)
2612def _entity_from_pre_ent_zero(
2613 query_or_augmented_select: Union[Query[Any], Select[Unpack[TupleAny]]],
2614) -> Optional[_InternalEntityType[Any]]:
2615 self = query_or_augmented_select
2616 if not self._raw_columns:
2617 return None
2619 ent = self._raw_columns[0]
2621 if "parententity" in ent._annotations:
2622 return ent._annotations["parententity"]
2623 elif isinstance(ent, ORMColumnsClauseRole):
2624 return ent.entity
2625 elif "bundle" in ent._annotations:
2626 return ent._annotations["bundle"]
2627 else:
2628 return ent
2631def _determine_last_joined_entity(
2632 setup_joins: Tuple[_SetupJoinsElement, ...],
2633 entity_zero: Optional[_InternalEntityType[Any]] = None,
2634) -> Optional[Union[_InternalEntityType[Any], _JoinTargetElement]]:
2635 if not setup_joins:
2636 return None
2638 (target, onclause, from_, flags) = setup_joins[-1]
2640 if isinstance(
2641 target,
2642 attributes.QueryableAttribute,
2643 ):
2644 return target.entity
2645 else:
2646 return target
2649class _QueryEntity:
2650 """represent an entity column returned within a Query result."""
2652 __slots__ = ()
2654 supports_single_entity: bool
2656 _non_hashable_value = False
2657 _null_column_type = False
2658 use_id_for_hash = False
2660 _label_name: Optional[str]
2661 type: Union[Type[Any], TypeEngine[Any]]
2662 expr: Union[_InternalEntityType, ColumnElement[Any]]
2663 entity_zero: Optional[_InternalEntityType]
2665 def setup_compile_state(self, compile_state: _ORMCompileState) -> None:
2666 raise NotImplementedError()
2668 def setup_dml_returning_compile_state(
2669 self,
2670 compile_state: _ORMCompileState,
2671 adapter: Optional[_DMLReturningColFilter],
2672 ) -> None:
2673 raise NotImplementedError()
2675 def row_processor(self, context, result):
2676 raise NotImplementedError()
2678 @classmethod
2679 def to_compile_state(
2680 cls, compile_state, entities, entities_collection, is_current_entities
2681 ):
2682 for idx, entity in enumerate(entities):
2683 if entity._is_lambda_element:
2684 if entity._is_sequence:
2685 cls.to_compile_state(
2686 compile_state,
2687 entity._resolved,
2688 entities_collection,
2689 is_current_entities,
2690 )
2691 continue
2692 else:
2693 entity = entity._resolved
2695 if entity.is_clause_element:
2696 if entity.is_selectable:
2697 if "parententity" in entity._annotations:
2698 _MapperEntity(
2699 compile_state,
2700 entity,
2701 entities_collection,
2702 is_current_entities,
2703 )
2704 else:
2705 _ColumnEntity._for_columns(
2706 compile_state,
2707 entity._select_iterable,
2708 entities_collection,
2709 idx,
2710 is_current_entities,
2711 )
2712 else:
2713 if entity._annotations.get("bundle", False):
2714 _BundleEntity(
2715 compile_state,
2716 entity,
2717 entities_collection,
2718 is_current_entities,
2719 )
2720 elif entity._is_clause_list:
2721 # this is legacy only - test_composites.py
2722 # test_query_cols_legacy
2723 _ColumnEntity._for_columns(
2724 compile_state,
2725 entity._select_iterable,
2726 entities_collection,
2727 idx,
2728 is_current_entities,
2729 )
2730 else:
2731 _ColumnEntity._for_columns(
2732 compile_state,
2733 [entity],
2734 entities_collection,
2735 idx,
2736 is_current_entities,
2737 )
2738 elif entity.is_bundle:
2739 _BundleEntity(compile_state, entity, entities_collection)
2741 return entities_collection
2744class _MapperEntity(_QueryEntity):
2745 """mapper/class/AliasedClass entity"""
2747 __slots__ = (
2748 "expr",
2749 "mapper",
2750 "entity_zero",
2751 "is_aliased_class",
2752 "path",
2753 "_extra_entities",
2754 "_label_name",
2755 "_with_polymorphic_mappers",
2756 "selectable",
2757 "_polymorphic_discriminator",
2758 )
2760 expr: _InternalEntityType
2761 mapper: Mapper[Any]
2762 entity_zero: _InternalEntityType
2763 is_aliased_class: bool
2764 path: PathRegistry
2765 _label_name: str
2767 def __init__(
2768 self, compile_state, entity, entities_collection, is_current_entities
2769 ):
2770 entities_collection.append(self)
2771 if is_current_entities:
2772 if compile_state._primary_entity is None:
2773 compile_state._primary_entity = self
2774 compile_state._has_mapper_entities = True
2775 compile_state._has_orm_entities = True
2777 entity = entity._annotations["parententity"]
2778 entity._post_inspect
2779 ext_info = self.entity_zero = entity
2780 entity = ext_info.entity
2782 self.expr = entity
2783 self.mapper = mapper = ext_info.mapper
2785 self._extra_entities = (self.expr,)
2787 if ext_info.is_aliased_class:
2788 self._label_name = ext_info.name
2789 else:
2790 self._label_name = mapper.class_.__name__
2792 self.is_aliased_class = ext_info.is_aliased_class
2793 self.path = ext_info._path_registry
2795 self.selectable = ext_info.selectable
2796 self._with_polymorphic_mappers = ext_info.with_polymorphic_mappers
2797 self._polymorphic_discriminator = ext_info.polymorphic_on
2799 if mapper._should_select_with_poly_adapter:
2800 compile_state._create_with_polymorphic_adapter(
2801 ext_info, self.selectable
2802 )
2804 supports_single_entity = True
2806 _non_hashable_value = True
2807 use_id_for_hash = True
2809 @property
2810 def type(self):
2811 return self.mapper.class_
2813 @property
2814 def entity_zero_or_selectable(self):
2815 return self.entity_zero
2817 def corresponds_to(self, entity):
2818 return _entity_corresponds_to(self.entity_zero, entity)
2820 def _get_entity_clauses(self, compile_state):
2821 adapter = None
2823 if not self.is_aliased_class:
2824 if compile_state._polymorphic_adapters:
2825 adapter = compile_state._polymorphic_adapters.get(
2826 self.mapper, None
2827 )
2828 else:
2829 adapter = self.entity_zero._adapter
2831 if adapter:
2832 if compile_state._from_obj_alias:
2833 ret = adapter.wrap(compile_state._from_obj_alias)
2834 else:
2835 ret = adapter
2836 else:
2837 ret = compile_state._from_obj_alias
2839 return ret
2841 def row_processor(self, context, result):
2842 compile_state = context.compile_state
2843 adapter = self._get_entity_clauses(compile_state)
2845 if compile_state.compound_eager_adapter and adapter:
2846 adapter = adapter.wrap(compile_state.compound_eager_adapter)
2847 elif not adapter:
2848 adapter = compile_state.compound_eager_adapter
2850 if compile_state._primary_entity is self:
2851 only_load_props = compile_state.compile_options._only_load_props
2852 refresh_state = context.refresh_state
2853 else:
2854 only_load_props = refresh_state = None
2856 _instance = loading._instance_processor(
2857 self,
2858 self.mapper,
2859 context,
2860 result,
2861 self.path,
2862 adapter,
2863 only_load_props=only_load_props,
2864 refresh_state=refresh_state,
2865 polymorphic_discriminator=self._polymorphic_discriminator,
2866 )
2868 return _instance, self._label_name, self._extra_entities
2870 def setup_dml_returning_compile_state(
2871 self,
2872 compile_state: _ORMCompileState,
2873 adapter: Optional[_DMLReturningColFilter],
2874 ) -> None:
2875 loading._setup_entity_query(
2876 compile_state,
2877 self.mapper,
2878 self,
2879 self.path,
2880 adapter,
2881 compile_state.primary_columns,
2882 with_polymorphic=self._with_polymorphic_mappers,
2883 only_load_props=compile_state.compile_options._only_load_props,
2884 polymorphic_discriminator=self._polymorphic_discriminator,
2885 )
2887 def setup_compile_state(self, compile_state):
2888 adapter = self._get_entity_clauses(compile_state)
2890 single_table_crit = self.mapper._single_table_criterion
2891 if (
2892 single_table_crit is not None
2893 or ("additional_entity_criteria", self.mapper)
2894 in compile_state.global_attributes
2895 ):
2896 ext_info = self.entity_zero
2897 compile_state.extra_criteria_entities[ext_info] = (
2898 ext_info,
2899 ext_info._adapter if ext_info.is_aliased_class else None,
2900 )
2902 loading._setup_entity_query(
2903 compile_state,
2904 self.mapper,
2905 self,
2906 self.path,
2907 adapter,
2908 compile_state.primary_columns,
2909 with_polymorphic=self._with_polymorphic_mappers,
2910 only_load_props=compile_state.compile_options._only_load_props,
2911 polymorphic_discriminator=self._polymorphic_discriminator,
2912 )
2913 compile_state._fallback_from_clauses.append(self.selectable)
2916class _BundleEntity(_QueryEntity):
2917 _extra_entities = ()
2919 __slots__ = (
2920 "bundle",
2921 "expr",
2922 "type",
2923 "_label_name",
2924 "_entities",
2925 "supports_single_entity",
2926 )
2928 _entities: List[_QueryEntity]
2929 bundle: Bundle
2930 type: Type[Any]
2931 _label_name: str
2932 supports_single_entity: bool
2933 expr: Bundle
2935 def __init__(
2936 self,
2937 compile_state,
2938 expr,
2939 entities_collection,
2940 is_current_entities,
2941 setup_entities=True,
2942 parent_bundle=None,
2943 ):
2944 compile_state._has_orm_entities = True
2946 expr = expr._annotations["bundle"]
2947 if parent_bundle:
2948 parent_bundle._entities.append(self)
2949 else:
2950 entities_collection.append(self)
2952 if isinstance(
2953 expr, (attributes.QueryableAttribute, interfaces.PropComparator)
2954 ):
2955 bundle = expr.__clause_element__()
2956 else:
2957 bundle = expr
2959 self.bundle = self.expr = bundle
2960 self.type = type(bundle)
2961 self._label_name = bundle.name
2962 self._entities = []
2964 if setup_entities:
2965 for expr in bundle.exprs:
2966 if "bundle" in expr._annotations:
2967 _BundleEntity(
2968 compile_state,
2969 expr,
2970 entities_collection,
2971 is_current_entities,
2972 parent_bundle=self,
2973 )
2974 elif isinstance(expr, Bundle):
2975 _BundleEntity(
2976 compile_state,
2977 expr,
2978 entities_collection,
2979 is_current_entities,
2980 parent_bundle=self,
2981 )
2982 else:
2983 _ORMColumnEntity._for_columns(
2984 compile_state,
2985 [expr],
2986 entities_collection,
2987 None,
2988 is_current_entities,
2989 parent_bundle=self,
2990 )
2992 self.supports_single_entity = self.bundle.single_entity
2994 @property
2995 def mapper(self):
2996 ezero = self.entity_zero
2997 if ezero is not None:
2998 return ezero.mapper
2999 else:
3000 return None
3002 @property
3003 def entity_zero(self):
3004 for ent in self._entities:
3005 ezero = ent.entity_zero
3006 if ezero is not None:
3007 return ezero
3008 else:
3009 return None
3011 def corresponds_to(self, entity):
3012 # TODO: we might be able to implement this but for now
3013 # we are working around it
3014 return False
3016 @property
3017 def entity_zero_or_selectable(self):
3018 for ent in self._entities:
3019 ezero = ent.entity_zero_or_selectable
3020 if ezero is not None:
3021 return ezero
3022 else:
3023 return None
3025 def setup_compile_state(self, compile_state):
3026 for ent in self._entities:
3027 ent.setup_compile_state(compile_state)
3029 def setup_dml_returning_compile_state(
3030 self,
3031 compile_state: _ORMCompileState,
3032 adapter: Optional[_DMLReturningColFilter],
3033 ) -> None:
3034 return self.setup_compile_state(compile_state)
3036 def row_processor(self, context, result):
3037 procs, labels, extra = zip(
3038 *[ent.row_processor(context, result) for ent in self._entities]
3039 )
3041 proc = self.bundle.create_row_processor(context.query, procs, labels)
3043 return proc, self._label_name, self._extra_entities
3046class _ColumnEntity(_QueryEntity):
3047 __slots__ = (
3048 "_fetch_column",
3049 "_row_processor",
3050 "raw_column_index",
3051 "translate_raw_column",
3052 )
3054 @classmethod
3055 def _for_columns(
3056 cls,
3057 compile_state,
3058 columns,
3059 entities_collection,
3060 raw_column_index,
3061 is_current_entities,
3062 parent_bundle=None,
3063 ):
3064 for column in columns:
3065 annotations = column._annotations
3066 if "parententity" in annotations:
3067 _entity = annotations["parententity"]
3068 else:
3069 _entity = sql_util.extract_first_column_annotation(
3070 column, "parententity"
3071 )
3073 if _entity:
3074 if "identity_token" in column._annotations:
3075 _IdentityTokenEntity(
3076 compile_state,
3077 column,
3078 entities_collection,
3079 _entity,
3080 raw_column_index,
3081 is_current_entities,
3082 parent_bundle=parent_bundle,
3083 )
3084 else:
3085 _ORMColumnEntity(
3086 compile_state,
3087 column,
3088 entities_collection,
3089 _entity,
3090 raw_column_index,
3091 is_current_entities,
3092 parent_bundle=parent_bundle,
3093 )
3094 else:
3095 _RawColumnEntity(
3096 compile_state,
3097 column,
3098 entities_collection,
3099 raw_column_index,
3100 is_current_entities,
3101 parent_bundle=parent_bundle,
3102 )
3104 @property
3105 def type(self):
3106 return self.column.type
3108 @property
3109 def _non_hashable_value(self):
3110 return not self.column.type.hashable
3112 @property
3113 def _null_column_type(self):
3114 return self.column.type._isnull
3116 def row_processor(self, context, result):
3117 compile_state = context.compile_state
3119 # the resulting callable is entirely cacheable so just return
3120 # it if we already made one
3121 if self._row_processor is not None:
3122 getter, label_name, extra_entities = self._row_processor
3123 if self.translate_raw_column:
3124 extra_entities += (
3125 context.query._raw_columns[self.raw_column_index],
3126 )
3128 return getter, label_name, extra_entities
3130 # retrieve the column that would have been set up in
3131 # setup_compile_state, to avoid doing redundant work
3132 if self._fetch_column is not None:
3133 column = self._fetch_column
3134 else:
3135 # fetch_column will be None when we are doing a from_statement
3136 # and setup_compile_state may not have been called.
3137 column = self.column
3139 # previously, the RawColumnEntity didn't look for from_obj_alias
3140 # however I can't think of a case where we would be here and
3141 # we'd want to ignore it if this is the from_statement use case.
3142 # it's not really a use case to have raw columns + from_statement
3143 if compile_state._from_obj_alias:
3144 column = compile_state._from_obj_alias.columns[column]
3146 if column._annotations:
3147 # annotated columns perform more slowly in compiler and
3148 # result due to the __eq__() method, so use deannotated
3149 column = column._deannotate()
3151 if compile_state.compound_eager_adapter:
3152 column = compile_state.compound_eager_adapter.columns[column]
3154 getter = result._getter(column)
3155 ret = getter, self._label_name, self._extra_entities
3156 self._row_processor = ret
3158 if self.translate_raw_column:
3159 extra_entities = self._extra_entities + (
3160 context.query._raw_columns[self.raw_column_index],
3161 )
3162 return getter, self._label_name, extra_entities
3163 else:
3164 return ret
3167class _RawColumnEntity(_ColumnEntity):
3168 entity_zero = None
3169 mapper = None
3170 supports_single_entity = False
3172 __slots__ = (
3173 "expr",
3174 "column",
3175 "_label_name",
3176 "entity_zero_or_selectable",
3177 "_extra_entities",
3178 )
3180 def __init__(
3181 self,
3182 compile_state,
3183 column,
3184 entities_collection,
3185 raw_column_index,
3186 is_current_entities,
3187 parent_bundle=None,
3188 ):
3189 self.expr = column
3190 self.raw_column_index = raw_column_index
3191 self.translate_raw_column = raw_column_index is not None
3193 if column._is_star:
3194 compile_state.compile_options += {"_is_star": True}
3196 if not is_current_entities or column._is_text_clause:
3197 self._label_name = None
3198 else:
3199 if parent_bundle:
3200 self._label_name = column._proxy_key
3201 else:
3202 self._label_name = compile_state._label_convention(column)
3204 if parent_bundle:
3205 parent_bundle._entities.append(self)
3206 else:
3207 entities_collection.append(self)
3209 self.column = column
3210 self.entity_zero_or_selectable = (
3211 self.column._from_objects[0] if self.column._from_objects else None
3212 )
3213 self._extra_entities = (self.expr, self.column)
3214 self._fetch_column = self._row_processor = None
3216 def corresponds_to(self, entity):
3217 return False
3219 def setup_dml_returning_compile_state(
3220 self,
3221 compile_state: _ORMCompileState,
3222 adapter: Optional[_DMLReturningColFilter],
3223 ) -> None:
3224 return self.setup_compile_state(compile_state)
3226 def setup_compile_state(self, compile_state):
3227 current_adapter = compile_state._get_current_adapter()
3228 if current_adapter:
3229 column = current_adapter(self.column, False)
3230 if column is None:
3231 return
3232 else:
3233 column = self.column
3235 if column._annotations:
3236 # annotated columns perform more slowly in compiler and
3237 # result due to the __eq__() method, so use deannotated
3238 column = column._deannotate()
3240 compile_state.dedupe_columns.add(column)
3241 compile_state.primary_columns.append(column)
3242 self._fetch_column = column
3245class _ORMColumnEntity(_ColumnEntity):
3246 """Column/expression based entity."""
3248 supports_single_entity = False
3250 __slots__ = (
3251 "expr",
3252 "mapper",
3253 "column",
3254 "_label_name",
3255 "entity_zero_or_selectable",
3256 "entity_zero",
3257 "_extra_entities",
3258 )
3260 def __init__(
3261 self,
3262 compile_state,
3263 column,
3264 entities_collection,
3265 parententity,
3266 raw_column_index,
3267 is_current_entities,
3268 parent_bundle=None,
3269 ):
3270 annotations = column._annotations
3272 _entity = parententity
3274 # an AliasedClass won't have proxy_key in the annotations for
3275 # a column if it was acquired using the class' adapter directly,
3276 # such as using AliasedInsp._adapt_element(). this occurs
3277 # within internal loaders.
3279 orm_key = annotations.get("proxy_key", None)
3280 proxy_owner = annotations.get("proxy_owner", _entity)
3281 if orm_key:
3282 self.expr = getattr(proxy_owner.entity, orm_key)
3283 self.translate_raw_column = False
3284 else:
3285 # if orm_key is not present, that means this is an ad-hoc
3286 # SQL ColumnElement, like a CASE() or other expression.
3287 # include this column position from the invoked statement
3288 # in the ORM-level ResultSetMetaData on each execute, so that
3289 # it can be targeted by identity after caching
3290 self.expr = column
3291 self.translate_raw_column = raw_column_index is not None
3293 self.raw_column_index = raw_column_index
3295 if is_current_entities:
3296 if parent_bundle:
3297 self._label_name = orm_key if orm_key else column._proxy_key
3298 else:
3299 self._label_name = compile_state._label_convention(
3300 column, col_name=orm_key
3301 )
3302 else:
3303 self._label_name = None
3305 _entity._post_inspect
3306 self.entity_zero = self.entity_zero_or_selectable = ezero = _entity
3307 self.mapper = mapper = _entity.mapper
3309 if parent_bundle:
3310 parent_bundle._entities.append(self)
3311 else:
3312 entities_collection.append(self)
3314 compile_state._has_orm_entities = True
3316 self.column = column
3318 self._fetch_column = self._row_processor = None
3320 self._extra_entities = (self.expr, self.column)
3322 if mapper._should_select_with_poly_adapter:
3323 compile_state._create_with_polymorphic_adapter(
3324 ezero, ezero.selectable
3325 )
3327 def corresponds_to(self, entity):
3328 if _is_aliased_class(entity):
3329 # TODO: polymorphic subclasses ?
3330 return entity is self.entity_zero
3331 else:
3332 return not _is_aliased_class(
3333 self.entity_zero
3334 ) and entity.common_parent(self.entity_zero)
3336 def setup_dml_returning_compile_state(
3337 self,
3338 compile_state: _ORMCompileState,
3339 adapter: Optional[_DMLReturningColFilter],
3340 ) -> None:
3342 self._fetch_column = column = self.column
3343 if adapter:
3344 column = adapter(column, False)
3346 if column is not None:
3347 compile_state.dedupe_columns.add(column)
3348 compile_state.primary_columns.append(column)
3350 def setup_compile_state(self, compile_state):
3351 current_adapter = compile_state._get_current_adapter()
3352 if current_adapter:
3353 column = current_adapter(self.column, False)
3354 if column is None:
3355 assert compile_state.is_dml_returning
3356 self._fetch_column = self.column
3357 return
3358 else:
3359 column = self.column
3361 ezero = self.entity_zero
3363 single_table_crit = self.mapper._single_table_criterion
3364 if (
3365 single_table_crit is not None
3366 or ("additional_entity_criteria", self.mapper)
3367 in compile_state.global_attributes
3368 ):
3369 compile_state.extra_criteria_entities[ezero] = (
3370 ezero,
3371 ezero._adapter if ezero.is_aliased_class else None,
3372 )
3374 if column._annotations and not column._expression_label:
3375 # annotated columns perform more slowly in compiler and
3376 # result due to the __eq__() method, so use deannotated
3377 column = column._deannotate()
3379 # use entity_zero as the from if we have it. this is necessary
3380 # for polymorphic scenarios where our FROM is based on ORM entity,
3381 # not the FROM of the column. but also, don't use it if our column
3382 # doesn't actually have any FROMs that line up, such as when its
3383 # a scalar subquery.
3384 if set(self.column._from_objects).intersection(
3385 ezero.selectable._from_objects
3386 ):
3387 compile_state._fallback_from_clauses.append(ezero.selectable)
3389 compile_state.dedupe_columns.add(column)
3390 compile_state.primary_columns.append(column)
3391 self._fetch_column = column
3394class _IdentityTokenEntity(_ORMColumnEntity):
3395 translate_raw_column = False
3397 def setup_compile_state(self, compile_state):
3398 pass
3400 def row_processor(self, context, result):
3401 def getter(row):
3402 return context.load_options._identity_token
3404 return getter, self._label_name, self._extra_entities