hare-orm 0.9.0__py3-none-any.whl

hare/query/statements/select/combined_query.py

@@ -0,0 +1,354 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from copy import copy
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+
+from hare.exceptions import QueryError
+from hare.query.constants import GET_FETCH_LIMIT_FOR_MULTIPLICITY_CHECK
+from hare.query.expressions.value_references.expression_arguments import ExpressionArguments
+from hare.query.expressions.value_references.value_reference_types import RecordedValueReferences
+from hare.query.plans.description.plan_context import PlanContext
+from hare.query.plans.description.plan_description import PlanDescription
+from hare.query.plans.enums import PlanKeyForm
+from hare.query.plans.statement.declared_plan_slots import DeclaredPlanSlots
+from hare.query.plans.statement.statement_plan import StatementPlan
+from hare.query.plans.statement.statement_plan_descriptions import StatementPlanDescriptions
+from hare.query.plans.statement.statement_plans import StatementPlans
+from hare.query.queryset.single_rows.get_exceptions import GetExceptions
+from hare.query.queryset.specification_copying import SpecificationCopying
+from hare.query.rows.model_rows.combined_model_rows import CombinedModelRows
+from hare.query.rows.values_rows.combined_values_rows import CombinedValuesRows
+from hare.query.statements.constants import VALUES_SET_OPERATION_ALIAS
+from hare.query.statements.select.combined.combined_branches import CombinedBranches
+from hare.query.statements.select.combined.combined_derived_queries import CombinedDerivedQueries
+from hare.query.statements.select.combined.combined_plan_descriptions import CombinedPlanDescriptions
+from hare.query.statements.select.rows_query import RowsQuery
+from hare.query.statements.select.select_query import SelectQuery
+from hare.query.statements.select.values_query import ValuesQuery
+from hare.sql import Order
+from hare.sql.builder.queries.query_builder import QueryBuilder
+from hare.sql.builder.queries.set_operation_query import SetOperationQuery
+from hare.sql.enums import SetOperation
+
+if TYPE_CHECKING:
+    from hare.dialects.base.client.database_client import DatabaseClient
+    from hare.fields.field import Field
+    from hare.query.queryset.combination.combination import Combination
+    from hare.query.queryset.queryset import QuerySet
+    from hare.query.queryset.single_rows.get_exception_argument import GetExceptionArgument
+    from hare.query.relation_loading.prefetching.prefetch import Prefetch
+    from hare.query.statements.summary.aggregate_query import AggregateQuery
+    from hare.query.statements.summary.count_query import CountQuery
+    from hare.query.statements.summary.exists_query import ExistsQuery
+    from hare.query.statements.write.update_query import UpdateQuery
+
+
+class CombinedQuery(RowsQuery[Any]):
+    """Builds and runs the SQL of a queryset combining querysets - ``union()``, ``intersection()`` and
+    ``difference()``. Each branch is built by the query of its own rows; an ordered or sliced
+    branch, and a nested set operation, combines as a derived table. The combined rows are selected
+    from the set operation as a derived table.
+    """
+
+    #: Each branch's structure as it is built in, the operations, the ordering of the combined rows
+    #: and their slice, bound.
+    plan_slots: ClassVar[DeclaredPlanSlots] = (
+        ("_combines_values", PlanKeyForm.VALUE),
+        *StatementPlanDescriptions.HEAD_SLOTS,
+        (CombinedPlanDescriptions.get_branches_plan_description, PlanKeyForm.DESCRIBED),
+        ("_set_operations", PlanKeyForm.VALUE),
+        ("_orderings", PlanKeyForm.TUPLE),
+        ("_limit", PlanKeyForm.BOUND),
+        ("_offset", PlanKeyForm.BOUND_WHEN_TRUE),
+        ("_is_none", PlanKeyForm.VALUE),
+        (StatementPlanDescriptions.get_zone_structure, PlanKeyForm.METHOD),
+    )
+
+    def __init__(self, source_queryset: QuerySet[Any, Any]) -> None:
+        """Takes the branches, ordering, slice and connection of a queryset combining querysets.
+
+        Args:
+            source_queryset: The queryset.
+
+        Raises:
+            QueryError: Model instances are combined with ``.values()``/``.values_list()`` rows.
+        """
+        # Local import: the queryset package imports the query statements.
+        from hare.query.queryset.combination.queryset_combination import QuerySetCombination
+
+        SpecificationCopying.copy_specification(source_queryset, self)
+        self._init_build_state()
+        combination = cast("Combination", source_queryset._combination)
+        self._source_queryset = source_queryset
+        #: Whether the rows are the values the branches select, not model instances.
+        self._combines_values = QuerySetCombination.selects_values(source_queryset)
+        self._branches: tuple[SelectQuery[Any] | CombinedQuery, ...] = tuple(
+            CombinedBranches.get_branch_query(self, branch) for branch in combination.branches
+        )
+        # The operation combining each branch after the first with everything before it, in order.
+        self._set_operations: tuple[SetOperation, ...] = combination.set_operations
+        self._prefetched_relations: tuple[str | Prefetch, ...] = combination.prefetched_relations
+        #: How the rows of the last build are read.
+        self._rows: CombinedValuesRows | CombinedModelRows = self._get_rows()
+
+    def _get_rows(self) -> CombinedValuesRows | CombinedModelRows:
+        """A reader of the combined rows, for one build."""
+        if self._combines_values:
+            return CombinedValuesRows(cast("ValuesQuery", CombinedBranches.get_first_leaf(self)))
+        return CombinedModelRows(self.model, CombinedBranches.get_models(self), self._prefetched_relations)
+
+    # --- the branches ---------------------------------------------------------------------------
+
+    # --- the build ------------------------------------------------------------------------------
+
+    def _prepare_build(self) -> None:
+        self._rows = self._get_rows()
+
+    def _keeps_plan_built_into_another(self) -> bool:
+        # Every branch records its own values - one keeping no plan records an empty reference.
+        return True
+
+    def get_plan_description(self, context: PlanContext) -> PlanDescription | None:
+        return self._get_scoped_copy()._describe_statement(True)
+
+    def _get_plan(self) -> tuple[PlanDescription | None, StatementPlan | None]:
+        # The branches' descriptions decide whether the statement keeps a plan.
+        description = self._describe_statement(False)
+        if description is None:
+            return None, None
+        return description, StatementPlans.find(description.structure)
+
+    def _restore_from_plan(self, plan: StatementPlan) -> None:
+        self._rows.restore(plan.result_reading)
+
+    def _get_plan_record(self) -> dict[str, Any]:
+        return {"result_reading": self._rows.get_result_reading()}
+
+    def _build_statement(
+        self, value_wrapper_references: RecordedValueReferences | None, *, records_for_caller: bool
+    ) -> bool:
+        combined_query: QueryBuilder | SetOperationQuery | None = None
+        # Every branch's with_cte() CTEs are hoisted to the combined statement as a whole - a
+        # WITH clause rendered on a branch would land after UNION/INTERSECT/EXCEPT.
+        with_clauses: list[Any] = []
+        # name -> (the first branch's CTE, the with_cte() body it was built from)
+        with_clauses_by_name: dict[str, tuple[Any, Any]] = {}
+        for branch_index, branch in enumerate(self._branches):
+            branch_query, cte_bodies_by_name = CombinedBranches.get_branch_statement(
+                self, branch, branch_index, value_wrapper_references
+            )
+            CombinedBranches.hoist_with_clauses(branch_query, cte_bodies_by_name, with_clauses, with_clauses_by_name)
+            branch_query = copy(branch_query)
+            branch_query._with = []
+            branch_query.wrap_set_operation_queries = False
+            if combined_query is None:
+                combined_query = branch_query
+            else:
+                combined_query = CombinedBranches.combine(self, combined_query, branch_query, branch_index)
+        derived_table = cast("QueryBuilder | SetOperationQuery", combined_query).as_(VALUES_SET_OPERATION_ALIAS)
+        rows = self._rows
+        query = self._connection.query_class.from_(derived_table).select(
+            *(derived_table.field(alias).as_(alias) for alias in rows.get_output_aliases())
+        )
+        for field_name, order in self._orderings:
+            query = query.orderby(derived_table.field(rows.get_ordering_alias(field_name)), order=order)
+        if self._limit is not None:
+            query._limit = query._wrapper_class(self._limit)
+        if self._offset:
+            query._offset = query._wrapper_class(self._offset)
+        query._with = with_clauses
+        self.query = query
+        if value_wrapper_references is not None:
+            # The slice is among the values - bound per query.
+            for attribute, slice_bound_term in (("_limit", query._limit), ("_offset", query._offset)):
+                if slice_bound_term is not None:
+                    ExpressionArguments.record_literal(value_wrapper_references, self, attribute, slice_bound_term)
+        return True
+
+    # --- running --------------------------------------------------------------------------------
+
+    async def _execute(self) -> Any:
+        sql, parameters = self._get_parameterized_sql()
+        rows = await self._rows.read(self, sql, parameters)
+        return self._get_single_or_list_result(rows)
+
+    def _get_default_iteration_orderings(self) -> list[tuple[str, Order]]:
+        # Worked out with the tie-breaker - the combined columns are known once the statement is
+        # built.
+        return []
+
+    def _get_orderings_with_tie_breaker(self) -> list[tuple[str, Order]]:
+        """The ordering - unordered, by the primary key for model instances and by every output
+        column for values - with every combined column appended as a tie-breaker."""
+        built_query = self._get_execution_query()
+        built_query._make_query()
+        query_orderings = list(self._orderings) or built_query._rows.get_default_orderings()
+        ordering_names = {field_name for field_name, _order in query_orderings}
+        return [
+            *query_orderings,
+            *((name, Order.ASC) for name in built_query._rows.get_output_names() if name not in ordering_names),
+        ]
+
+    def _stream_batches(self, connection: DatabaseClient, chunk_size: int) -> AsyncGenerator[list[Any]]:
+        return cast(
+            "AsyncGenerator[list[Any]]",
+            self._rows.stream_batches(self, connection, *self._get_parameterized_sql(), chunk_size),
+        )
+
+    # --- the rows as a derived table ---------------------------------------------------------------
+
+    def _get_rows_query(self, *, sliced: bool) -> CombinedQuery:
+        """A copy to select from as a derived table, returning a list.
+
+        Args:
+            sliced: Keep the slice and ordering.
+
+        Returns:
+            The copy.
+        """
+        query = copy(self)
+        query._single = False
+        query._raise_does_not_exist = False
+        query._prefetched_relations = ()
+        if not sliced:
+            query._limit = None
+            query._offset = None
+            query._orderings = []
+        return query
+
+    def _get_output_columns(self) -> list[tuple[str, str, str, Field[Any] | None]]:
+        """The combined columns of the built query, to read from it as a derived table - see
+        ``ValuesQuery._get_output_columns()``."""
+        return self._rows.get_output_columns()
+
+    def _get_output_names(self) -> list[str]:
+        """The output names of the combined values, in output order."""
+        return self._rows.get_output_names()
+
+    def _get_count_query(self) -> CountQuery:
+        """The number of rows the query returns, counted over the query as a derived table."""
+        from hare.query.statements.summary.count_query import CountQuery
+
+        return CountQuery(self, rows_query=self._get_rows_query(sliced=False))
+
+    def _get_exists_query(self) -> ExistsQuery:
+        """Whether the query returns any row."""
+        from hare.query.statements.summary.exists_query import ExistsQuery
+
+        return ExistsQuery(self, rows_query=self._get_rows_query(sliced=False))
+
+    def _get_aggregate_query(self, **kwargs: Any) -> AggregateQuery:
+        """Aggregates over the combined rows - a metric reads the combined columns: the output
+        names of values, the fields and annotations of model instances.
+
+        Raises:
+            QueryError: A metric reads anything but the combined columns.
+        """
+        from hare.query.statements.summary.aggregate_query import AggregateQuery
+
+        return AggregateQuery(self, kwargs, rows_query=self._get_rows_query(sliced=True))
+
+    def _get_field_values_query(
+        self, field_name: str, value_wrapper_references: RecordedValueReferences | None = None
+    ) -> QueryBuilder:
+        """One column of combined model instances, as a query to embed - a queryset combining
+        querysets passed as an ``__in`` filter value (``filter(pk__in=a.union(b))``).
+
+        Args:
+            field_name: The field to select, ``"pk"`` included.
+            value_wrapper_references: The list of the enclosing query the value references go into.
+
+        Returns:
+            The query selecting that column from the combined rows.
+
+        Raises:
+            QueryError: The model has a composite primary key.
+            FieldError: The combined rows don't select the field.
+        """
+        primary_key_attribute = self.model._meta.primary_key_attribute
+        if field_name == "pk":
+            self.model._meta.raise_if_no_primary_key("a union used as an __in filter value")
+            if isinstance(primary_key_attribute, tuple):
+                raise QueryError(
+                    f"{self.model.__name__} has a composite primary key - a union can't be used as a "
+                    "single-column __in filter value."
+                )
+            field_name = primary_key_attribute
+        return CombinedDerivedQueries.get_fields_values_query(self, (field_name,), value_wrapper_references)
+
+    # --- the queryset's methods -----------------------------------------------------------------
+
+    def _get_update_query(self, **kwargs: Any) -> UpdateQuery:
+        """Rejected, like Django.
+
+        Raises:
+            QueryError: Always - the combined rows aren't rows of one table.
+        """
+        raise QueryError(
+            "update() can't be used on a union()/intersection()/difference() - call it on each "
+            "queryset before combining them."
+        )
+
+    def _get_first(self, *, reverse: bool) -> QuerySet[Any, Any]:
+        """The first (or last) combined row - in the ordering, else by the primary key for model
+        instances and by every output column for values.
+
+        Args:
+            reverse: Take the last row.
+
+        Returns:
+            The single-row queryset.
+
+        Raises:
+            QueryError: ``last()`` of sliced rows.
+        """
+        if reverse and (self._limit is not None or self._offset):
+            raise QueryError("last() can't be used on a sliced set operation - call it before slicing.")
+        orderings = list(self._orderings) or self._rows.get_default_orderings()
+        queryset = self._source_queryset._clone()
+        queryset._orderings = [(name, order.get_reversed()) for name, order in orderings] if reverse else orderings
+        queryset._single = True
+        queryset._limit = 1 if self._limit is None else min(self._limit, 1)
+        return queryset
+
+    def _get_single_queryset(
+        self,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        *,
+        does_not_exist_exception: GetExceptionArgument,
+        multiple_objects_returned_exception: GetExceptionArgument,
+    ) -> QuerySet[Any, Any]:
+        """The one combined row. Conditions filter every branch before they are combined - a row
+        condition gives the same rows before or after UNION/INTERSECT/EXCEPT.
+
+        Args:
+            args: ``Q`` conditions.
+            kwargs: Filter keyword arguments.
+            does_not_exist_exception: As ``get()`` takes it.
+            multiple_objects_returned_exception: As ``get()`` takes it.
+
+        Returns:
+            The single-row queryset.
+
+        Raises:
+            QueryError: Conditions are given for sliced rows - they depend on the rows the
+                conditions drop.
+        """
+        queryset = self._source_queryset._clone()
+        if args or kwargs:
+            if self._limit is not None or self._offset:
+                raise QueryError(
+                    "get() with conditions can't be used on a sliced union - the conditions "
+                    "filter the branches, before the slice. Pass them before slicing."
+                )
+            queryset = CombinedDerivedQueries.get_changed_branches_queryset(
+                queryset, lambda branch: branch.filter(*args, **kwargs)
+            )
+        queryset._single = True
+        queryset._raise_does_not_exist = does_not_exist_exception is not None
+        GetExceptions.set_get_exceptions(queryset, does_not_exist_exception, multiple_objects_returned_exception)
+        fetch_limit = 1 if multiple_objects_returned_exception is None else GET_FETCH_LIMIT_FOR_MULTIPLICITY_CHECK
+        queryset._limit = fetch_limit if self._limit is None else min(self._limit, fetch_limit)
+        return queryset

hare/query/statements/select/model_rows/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

hare/query/statements/select/model_rows/instance_hydration.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from hare.core.caching.model_cache import ModelCache
+from hare.exceptions import FieldError
+from hare.query.relation_loading.prefetching.prefetch_request import PrefetchRequest
+from hare.query.rows.model_rows.model_rows import ModelRows
+from hare.query.statements.building.query_annotations import QueryAnnotations
+from hare.sql.terms.field import Field
+
+if TYPE_CHECKING:
+    from hare.models import Model
+    from hare.query.rows.native.hydration_layout import HydrationEntry
+    from hare.query.statements.select.model_rows_query import ModelRowsQuery
+    from hare.sql.builder.queries.query_builder import QueryBuilder
+    from hare.sql.terms.term import Term
+
+
+class InstanceHydration:
+    """How the rows of a query become model instances: the positional decode plan of the selected
+    columns, the reader of the rows, what the loaded instances get prefetched, and the refusal of an
+    annotation that would overwrite a field or a property of an instance."""
+
+    #: model -> (its basequery_all_fields, the column-name key of that query's SELECT list) - see
+    #: get_all_fields_selects_key().
+    ALL_FIELDS_SELECTS_KEY_CACHE: ClassVar[ModelCache[tuple[QueryBuilder, tuple[str | None, ...]]]] = ModelCache()
+
+    @staticmethod
+    def check_no_annotation_field_collision(query: ModelRowsQuery[Any]) -> None:
+        """Refuses an annotation named like a field or a property of the model - it would overwrite it on the
+        instance.
+
+        Args:
+            query: The query.
+
+        Raises:
+            FieldError: An annotation collides.
+        """
+        if not query._annotations:
+            return
+        # An annotation named like a field, or like a property of the model (`pk`), would overwrite
+        # it on the hydrated instance. An .alias() is never selected and can't collide.
+        reserved_names = InstanceHydration.get_reserved_attribute_names(query.model)
+        alias_keys = query._alias_keys
+        colliding_keys = [key for key in query._annotations if key in reserved_names and key not in alias_keys]
+        if colliding_keys:
+            raise FieldError(
+                f"annotate() key(s) {sorted(colliding_keys)} collide with existing field(s) or "
+                f"reserved attribute(s) on model {query.model.__name__} - fetching full model instances "
+                "would silently corrupt hydration. Use a different annotation name, or "
+                ".values()/.values_list()."
+            )
+
+    @staticmethod
+    @ModelCache.fact()
+    def get_reserved_attribute_names(model: type[Model]) -> frozenset[str]:
+        """The names an instance's attributes take - its fields and the properties defined on the
+        model class and its bases (``pk``) - a fact of the model.
+
+        Args:
+            model: The model class.
+
+        Returns:
+            The names.
+        """
+        property_names = (
+            name
+            for klass in model.__mro__
+            for name, attribute in vars(klass).items()
+            if isinstance(attribute, property)
+        )
+        return frozenset([*model._meta.fields_map, *property_names])
+
+    @staticmethod
+    def get_model_rows_reader(query: ModelRowsQuery[Any]) -> ModelRows:
+        """How this query's rows are read into instances - shared by ``_execute()`` and
+        ``stream()``.
+
+        Args:
+            query: The model rows query.
+
+        Returns:
+            The reader.
+        """
+        return ModelRows(
+            query.model,
+            query._connection,
+            select_related_buckets=query._select_related_positions,
+            decode_plan=query._decode_plan,
+            decode_plan_is_partial=query._decode_plan_is_partial,
+            # An .alias() key is never selected - there's no column to read it from.
+            annotations=list(query._annotations.keys() - query._alias_keys),
+            annotation_fields=QueryAnnotations.get_annotation_fields(query),
+        )
+
+    @staticmethod
+    def get_prefetch_request(query: ModelRowsQuery[Any]) -> PrefetchRequest | None:
+        """What the instances this queryset loads get prefetched, with the settings of this
+        queryset the prefetch queries take over - None when nothing is prefetched.
+
+        Args:
+            query: The model rows query.
+
+        Returns:
+            The request, or None.
+        """
+        if not (query._prefetch_map or query._prefetch_queries):
+            return None
+        return PrefetchRequest(
+            query._prefetch_map,
+            query._prefetch_queries,
+            visibility=query._visibility,
+            select_for_update=query._select_for_update,
+            select_for_update_nowait=query._select_for_update_nowait,
+            select_for_update_skip_locked=query._select_for_update_skip_locked,
+            select_for_update_strength=query._select_for_update_strength,
+            db_explicitly_chosen=query._connection_explicitly_chosen,
+        )
+
+    @staticmethod
+    def build_decode_plan(
+        query: ModelRowsQuery[Any], base_selects: tuple[Term, ...]
+    ) -> tuple[HydrationEntry, ...] | None:
+        """The positional decode plan of the base model's selected columns (``base_selects``, taken
+        before annotations and joins are added). None when rows aren't read by position.
+
+        Args:
+            query: The model rows query.
+            base_selects: The base model's selected columns.
+        """
+        if len(query._select_related_positions) != 1 or not query.features.supports_positional_rows:
+            return None
+        entry_by_column = query.model._meta.get_hydration_layout(query._connection).entry_by_column
+        plan: list[HydrationEntry] = []
+        for term in base_selects:
+            if not isinstance(term, Field):
+                return None
+            entry = entry_by_column.get(term.name)
+            if entry is None:
+                return None
+            plan.append(entry)
+        return tuple(plan)
+
+    @staticmethod
+    def get_all_fields_selects_key(model: type[Model]) -> tuple[str | None, ...]:
+        """The column names of ``model``'s every-column SELECT list - part of the decode plans' key and
+        of the plan key. Kept per model beside the query it was read from.
+
+        Args:
+            model: The model.
+
+        Returns:
+            One name per selected term, None for a term that isn't a plain column.
+        """
+        basequery_all_fields = model._meta.basequery_all_fields
+        cached = InstanceHydration.ALL_FIELDS_SELECTS_KEY_CACHE.get(model)
+        if cached is not None and cached[0] is basequery_all_fields:
+            return cached[1]
+        selects_key = tuple(term.name if isinstance(term, Field) else None for term in basequery_all_fields._selects)
+        InstanceHydration.ALL_FIELDS_SELECTS_KEY_CACHE[model] = (basequery_all_fields, selects_key)
+        return selects_key

hare/query/statements/select/model_rows/model_rows_plan_descriptions.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from hare.query.expressions.subqueries.outer_scope import OuterScope
+from hare.query.plans.description.plan_context import PlanContext
+from hare.query.plans.description.plan_description import PlanDescription
+from hare.query.plans.description.plan_parts import PlanParts
+from hare.query.plans.plan_origins import PlanOrigins
+from hare.query.plans.statement.statement_plan import StatementPlan
+from hare.query.plans.statement.statement_plan_descriptions import StatementPlanDescriptions
+from hare.query.plans.statement.statement_plans import StatementPlans
+from hare.query.queryset.options.query_options import QueryOptions
+from hare.query.statements.select.model_rows.select_related_joins import SelectRelatedJoins
+
+if TYPE_CHECKING:
+    from hare.query.statements.select.model_rows_query import ModelRowsQuery
+
+
+class ModelRowsPlanDescriptions:
+    """The plan description of a query of model instances: a plain query takes the short key, any other
+    one the full description, with the extra conditions of select_related() in join order."""
+
+    @staticmethod
+    def has_plain_query_state(query: ModelRowsQuery[Any]) -> bool:
+        """Whether the query selects every column of its model and has only filters, ordering, a plain
+        ``.distinct()`` and a slice - it then takes the short plan key.
+
+        Args:
+            query: The model rows query.
+
+        Returns:
+            True for a plain query.
+        """
+        if query._select_related or query._effective_fields_for_select or query._annotations:
+            return False
+        options = query._options
+        return options is QueryOptions.DEFAULT or not (
+            options.select_related_extra_conditions
+            or options.cursor_values
+            or options.before_cursor_values
+            or options.distinct_on
+            or options.select_for_update
+        )
+
+    @staticmethod
+    def get_extra_conditions_plan_description(query: ModelRowsQuery[Any]) -> PlanDescription | None:
+        """Describes the ``Select(relation, extra_condition=Q(...))`` conditions in join order -
+        two queries selecting the same relations with other conditions never share a plan.
+
+        Args:
+            query: The model rows query.
+
+        Returns:
+            The description, None when a condition keeps no plan.
+        """
+        paths_and_conditions = SelectRelatedJoins.select_related_extra_conditions_in_join_order(query)
+        if not paths_and_conditions:
+            return PlanDescription((), [])
+        conditions_description = StatementPlanDescriptions.get_conditions_plan_description(
+            [extra_condition for _path, extra_condition in paths_and_conditions], PlanContext.EMPTY
+        )
+        if conditions_description is None:
+            return None
+        return PlanDescription(
+            (tuple(path for path, _extra_condition in paths_and_conditions), conditions_description.structure),
+            conditions_description.values,
+            # Bound into each JOIN the conditions are folded into - none of a relation the query
+            # doesn't cross.
+            PlanParts.get_optional_origins(conditions_description, []) if PlanOrigins.records else None,
+        )
+
+    @staticmethod
+    def get_queryset_plan_description(
+        query: ModelRowsQuery[Any], built_into_another: bool = False
+    ) -> tuple[PlanDescription | None, StatementPlan | None]:
+        """Describes this query - the structure is the plan key - and finds the plan under it. A plain
+        query takes the short key of ``plain_plan_slots`` and its plan is looked up first; any other
+        one the key of ``plan_slots``.
+
+        Args:
+            query: The model rows query.
+            built_into_another: Whether the query is built into another one: the key leaves out the
+                dialect, and no plan is looked up.
+
+        Returns:
+            The description, None for a query that keeps no plan, and the plan found.
+        """
+        plan: StatementPlan | None = None
+        if ModelRowsPlanDescriptions.has_plain_query_state(query):
+            description = query._describe_plain_statement(built_into_another)
+            if description is None:
+                return None, None
+            # A plan kept under the key is the answer to whether the query keeps one - except
+            # inside a correlated subquery, where that also depends on the enclosing query.
+            if not built_into_another and OuterScope.current_expression_context.get() is None:
+                plan = StatementPlans.find_for_model(query.model, description.structure)
+            if plan is None and not StatementPlanDescriptions.query_state_is_plannable(query):
+                return None, None
+            return description, plan
+        if not StatementPlanDescriptions.query_state_is_plannable(query):
+            return None, None
+        description = query._describe_statement(built_into_another)
+        if description is None:
+            return None, None
+        if not built_into_another:
+            plan = StatementPlans.find_for_model(query.model, description.structure)
+        return description, plan