diff options
Diffstat (limited to 'lib/sqlalchemy/orm/query.py')
| -rw-r--r-- | lib/sqlalchemy/orm/query.py | 523 |
1 files changed, 300 insertions, 223 deletions
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index e131a4aa3..ce051cdcb 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -7,11 +7,11 @@ """The Query class and support. -Defines the :class:`.Query` class, the central +Defines the :class:`_query.Query` class, the central construct used by the ORM to construct database queries. -The :class:`.Query` class should not be confused with the -:class:`.Select` class, which defines database +The :class:`_query.Query` class should not be confused with the +:class:`_expression.Select` class, which defines database SELECT operations at the SQL (non-ORM) level. ``Query`` differs from ``Select`` in that it returns ORM-mapped objects and interacts with an ORM session, whereas the ``Select`` construct interacts directly with the @@ -70,20 +70,22 @@ _path_registry = PathRegistry.root class Query(Generative): """ORM-level SQL construction object. - :class:`.Query` is the source of all SELECT statements generated by the + :class:`_query.Query` + is the source of all SELECT statements generated by the ORM, both those formulated by end-user query operations as well as by high level internal operations such as related collection loading. It features a generative interface whereby successive calls return a new - :class:`.Query` object, a copy of the former with additional + :class:`_query.Query` object, a copy of the former with additional criteria and options associated with it. - :class:`.Query` objects are normally initially generated using the + :class:`_query.Query` objects are normally initially generated using the :meth:`~.Session.query` method of :class:`.Session`, and in - less common cases by instantiating the :class:`.Query` directly and - associating with a :class:`.Session` using the :meth:`.Query.with_session` + less common cases by instantiating the :class:`_query.Query` directly and + associating with a :class:`.Session` using the + :meth:`_query.Query.with_session` method. - For a full walkthrough of :class:`.Query` usage, see the + For a full walkthrough of :class:`_query.Query` usage, see the :ref:`ormtutorial_toplevel`. """ @@ -131,7 +133,8 @@ class Query(Generative): _bake_ok = True lazy_loaded_from = None - """An :class:`.InstanceState` that is using this :class:`.Query` for a + """An :class:`.InstanceState` that is using this :class:`_query.Query` + for a lazy load operation. The primary rationale for this attribute is to support the horizontal @@ -143,7 +146,8 @@ class Query(Generative): .. note:: - Within the realm of regular :class:`.Query` usage, this attribute is + Within the realm of regular :class:`_query.Query` usage, + this attribute is set by the lazy loader strategy before the query is invoked. However there is no established hook that is available to reliably intercept this value programmatically. It is set by the lazy loading strategy @@ -152,12 +156,14 @@ class Query(Generative): cache SQL compilation, the :meth:`.QueryEvents.before_compile` hook is also not reliable. - Currently, setting the :paramref:`.relationship.bake_queries` to - ``False`` on the target :func:`.relationship`, and then making use of + Currently, setting the :paramref:`_orm.relationship.bake_queries` to + ``False`` on the target :func:`_orm.relationship`, + and then making use of the :meth:`.QueryEvents.before_compile` event hook, is the only available programmatic path to intercepting this attribute. In future releases, there will be new hooks available that allow interception of - the :class:`.Query` before it is executed, rather than before it is + the :class:`_query.Query` before it is executed, + rather than before it is compiled. .. versionadded:: 1.2.9 @@ -165,7 +171,7 @@ class Query(Generative): """ def __init__(self, entities, session=None): - """Construct a :class:`.Query` directly. + """Construct a :class:`_query.Query` directly. E.g.:: @@ -177,16 +183,18 @@ class Query(Generative): :param entities: a sequence of entities and/or SQL expressions. - :param session: a :class:`.Session` with which the :class:`.Query` - will be associated. Optional; a :class:`.Query` can be associated + :param session: a :class:`.Session` with which the + :class:`_query.Query` + will be associated. Optional; a :class:`_query.Query` + can be associated with a :class:`.Session` generatively via the - :meth:`.Query.with_session` method as well. + :meth:`_query.Query.with_session` method as well. .. seealso:: :meth:`.Session.query` - :meth:`.Query.with_session` + :meth:`_query.Query.with_session` """ self.session = session @@ -535,21 +543,23 @@ class Query(Generative): def subquery(self, name=None, with_labels=False, reduce_columns=False): """return the full SELECT statement represented by - this :class:`.Query`, embedded within an :class:`.Alias`. + this :class:`_query.Query`, embedded within an + :class:`_expression.Alias`. Eager JOIN generation within the query is disabled. :param name: string name to be assigned as the alias; - this is passed through to :meth:`.FromClause.alias`. + this is passed through to :meth:`_expression.FromClause.alias`. If ``None``, a name will be deterministically generated at compile time. :param with_labels: if True, :meth:`.with_labels` will be called - on the :class:`.Query` first to apply table-qualified labels + on the :class:`_query.Query` first to apply table-qualified labels to all columns. - :param reduce_columns: if True, :meth:`.Select.reduce_columns` will - be called on the resulting :func:`~.sql.expression.select` construct, + :param reduce_columns: if True, + :meth:`_expression.Select.reduce_columns` will + be called on the resulting :func:`_expression.select` construct, to remove same-named columns where one also refers to the other via foreign key or WHERE clause equivalence. @@ -565,10 +575,10 @@ class Query(Generative): def cte(self, name=None, recursive=False): r"""Return the full SELECT statement represented by this - :class:`.Query` represented as a common table expression (CTE). + :class:`_query.Query` represented as a common table expression (CTE). Parameters and usage are the same as those of the - :meth:`.SelectBase.cte` method; see that method for + :meth:`_expression.SelectBase.cte` method; see that method for further details. Here is the `PostgreSQL WITH @@ -577,7 +587,7 @@ class Query(Generative): Note that, in this example, the ``included_parts`` cte and the ``incl_alias`` alias of it are Core selectables, which means the columns are accessed via the ``.c.`` attribute. The - ``parts_alias`` object is an :func:`.orm.aliased` instance of the + ``parts_alias`` object is an :func:`_orm.aliased` instance of the ``Part`` entity, so column-mapped attributes are available directly:: @@ -615,7 +625,7 @@ class Query(Generative): .. seealso:: - :meth:`.HasCTE.cte` + :meth:`_expression.HasCTE.cte` """ return self.enable_eagerloads(False).statement.cte( @@ -624,7 +634,7 @@ class Query(Generative): def label(self, name): """Return the full SELECT statement represented by this - :class:`.Query`, converted + :class:`_query.Query`, converted to a scalar subquery with a label of the given name. Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.label`. @@ -635,26 +645,27 @@ class Query(Generative): @util.deprecated( "1.4", - "The :meth:`.Query.as_scalar` method is deprecated and will be " + "The :meth:`_query.Query.as_scalar` method is deprecated and will be " "removed in a future release. Please refer to " - ":meth:`.Query.scalar_subquery`.", + ":meth:`_query.Query.scalar_subquery`.", ) def as_scalar(self): """Return the full SELECT statement represented by this - :class:`.Query`, converted to a scalar subquery. + :class:`_query.Query`, converted to a scalar subquery. """ return self.scalar_subquery() def scalar_subquery(self): """Return the full SELECT statement represented by this - :class:`.Query`, converted to a scalar subquery. + :class:`_query.Query`, converted to a scalar subquery. Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.scalar_subquery`. - .. versionchanged:: 1.4 the :meth:`.Query.scalar_subquery` method - replaces the :meth:`.Query.as_scalar` method. + .. versionchanged:: 1.4 the :meth:`_query.Query.scalar_subquery` + method + replaces the :meth:`_query.Query.as_scalar` method. """ return self.enable_eagerloads(False).statement.scalar_subquery() @@ -672,14 +683,15 @@ class Query(Generative): .. seealso:: - :meth:`.Query.is_single_entity` + :meth:`_query.Query.is_single_entity` """ self._only_return_tuples = value @property def is_single_entity(self): - """Indicates if this :class:`.Query` returns tuples or single entities. + """Indicates if this :class:`_query.Query` + returns tuples or single entities. Returns True if this query returns a single entity for each instance in its result list, and False if this query returns a tuple of entities @@ -689,7 +701,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.only_return_tuples` + :meth:`_query.Query.only_return_tuples` """ return ( @@ -711,7 +723,7 @@ class Query(Generative): This is used primarily when nesting the Query's statement into a subquery or other - selectable, or when using :meth:`.Query.yield_per`. + selectable, or when using :meth:`_query.Query.yield_per`. """ self._enable_eagerloads = value @@ -738,12 +750,14 @@ class Query(Generative): When the `Query` actually issues SQL to load rows, it always uses column labeling. - .. note:: The :meth:`.Query.with_labels` method *only* applies - the output of :attr:`.Query.statement`, and *not* to any of - the result-row invoking systems of :class:`.Query` itself, e.g. - :meth:`.Query.first`, :meth:`.Query.all`, etc. To execute - a query using :meth:`.Query.with_labels`, invoke the - :attr:`.Query.statement` using :meth:`.Session.execute`:: + .. note:: The :meth:`_query.Query.with_labels` method *only* applies + the output of :attr:`_query.Query.statement`, and *not* to any of + the result-row invoking systems of :class:`_query.Query` itself, e. + g. + :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc. + To execute + a query using :meth:`_query.Query.with_labels`, invoke the + :attr:`_query.Query.statement` using :meth:`.Session.execute`:: result = session.execute(query.with_labels().statement) @@ -803,9 +817,9 @@ class Query(Generative): ): """Load columns for inheriting classes. - :meth:`.Query.with_polymorphic` applies transformations - to the "main" mapped class represented by this :class:`.Query`. - The "main" mapped class here means the :class:`.Query` + :meth:`_query.Query.with_polymorphic` applies transformations + to the "main" mapped class represented by this :class:`_query.Query`. + The "main" mapped class here means the :class:`_query.Query` object's first argument is a full class, i.e. ``session.query(SomeClass)``. These transformations allow additional tables to be present in the FROM clause so that columns for a @@ -849,7 +863,7 @@ class Query(Generative): (e.g. approximately 1000) is used, even with DBAPIs that buffer rows (which are most). - The :meth:`.Query.yield_per` method **is not compatible + The :meth:`_query.Query.yield_per` method **is not compatible subqueryload eager loading or joinedload eager loading when using collections**. It is potentially compatible with "select in" eager loading, **provided the database driver supports multiple, @@ -858,7 +872,7 @@ class Query(Generative): Therefore in some cases, it may be helpful to disable eager loads, either unconditionally with - :meth:`.Query.enable_eagerloads`:: + :meth:`_query.Query.enable_eagerloads`:: q = sess.query(Object).yield_per(100).enable_eagerloads(False) @@ -898,7 +912,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.enable_eagerloads` + :meth:`_query.Query.enable_eagerloads` """ self._yield_per = count @@ -919,7 +933,7 @@ class Query(Generative): some_object = session.query(VersionedFoo).get( {"id": 5, "version_id": 10}) - :meth:`~.Query.get` is special in that it provides direct + :meth:`_query.Query.get` is special in that it provides direct access to the identity map of the owning :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned @@ -928,28 +942,28 @@ class Query(Generative): If not present, a SELECT is performed in order to locate the object. - :meth:`~.Query.get` also will perform a check if + :meth:`_query.Query.get` also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. - :meth:`~.Query.get` is only used to return a single + :meth:`_query.Query.get` is only used to return a single mapped instance, not multiple instances or individual column constructs, and strictly on a single primary key value. The originating - :class:`.Query` must be constructed in this way, + :class:`_query.Query` must be constructed in this way, i.e. against a single mapped entity, with no additional filtering criterion. Loading - options via :meth:`~.Query.options` may be applied + options via :meth:`_query.Query.options` may be applied however, and will be used if the object is not yet locally present. A lazy-loading, many-to-one attribute configured - by :func:`.relationship`, using a simple + by :func:`_orm.relationship`, using a simple foreign-key-to-primary-key criterion, will also use an - operation equivalent to :meth:`~.Query.get` in order to retrieve + operation equivalent to :meth:`_query.Query.get` in order to retrieve the target value from the local identity map before querying the database. See :doc:`/orm/loading_relationships` for further details on relationship loading. @@ -965,9 +979,11 @@ class Query(Generative): my_object = query.get(5) The tuple form contains primary key values typically in - the order in which they correspond to the mapped :class:`.Table` + the order in which they correspond to the mapped + :class:`_schema.Table` object's primary key columns, or if the - :paramref:`.Mapper.primary_key` configuration parameter were used, in + :paramref:`_orm.Mapper.primary_key` configuration parameter were used + , in the order used for that parameter. For example, if the primary key of a row is represented by the integer digits "5, 10" the call would look like:: @@ -981,7 +997,8 @@ class Query(Generative): my_object = query.get({"id": 5, "version_id": 10}) - .. versionadded:: 1.3 the :meth:`.Query.get` method now optionally + .. versionadded:: 1.3 the :meth:`_query.Query.get` + method now optionally accepts a dictionary of attribute names to values in order to indicate a primary key identifier. @@ -1056,9 +1073,10 @@ class Query(Generative): @_generative def correlate(self, *args): - """Return a :class:`.Query` construct which will correlate the given - FROM clauses to that of an enclosing :class:`.Query` or - :func:`~.expression.select`. + """Return a :class:`_query.Query` + construct which will correlate the given + FROM clauses to that of an enclosing :class:`_query.Query` or + :func:`_expression.select`. The method here accepts mapped classes, :func:`.aliased` constructs, and :func:`.mapper` constructs as arguments, which are resolved into @@ -1066,12 +1084,13 @@ class Query(Generative): constructs. The correlation arguments are ultimately passed to - :meth:`.Select.correlate` after coercion to expression constructs. + :meth:`_expression.Select.correlate` + after coercion to expression constructs. The correlation arguments take effect in such cases - as when :meth:`.Query.from_self` is used, or when - a subquery as returned by :meth:`.Query.subquery` is - embedded in another :func:`~.expression.select` construct. + as when :meth:`_query.Query.from_self` is used, or when + a subquery as returned by :meth:`_query.Query.subquery` is + embedded in another :func:`_expression.select` construct. """ @@ -1099,7 +1118,8 @@ class Query(Generative): @_generative def populate_existing(self): - """Return a :class:`.Query` that will expire and refresh all instances + """Return a :class:`_query.Query` + that will expire and refresh all instances as they are loaded, or reused from the current :class:`.Session`. :meth:`.populate_existing` does not improve behavior when @@ -1117,7 +1137,7 @@ class Query(Generative): subquery loaders to traverse into already-loaded related objects and collections. - Default is that of :attr:`.Query._invoke_all_eagers`. + Default is that of :attr:`_query.Query._invoke_all_eagers`. """ self._invoke_all_eagers = value @@ -1126,18 +1146,19 @@ class Query(Generative): def with_parent(self, instance, property=None, from_entity=None): # noqa """Add filtering criterion that relates the given instance to a child object or collection, using its attribute state - as well as an established :func:`.relationship()` + as well as an established :func:`_orm.relationship()` configuration. The method uses the :func:`.with_parent` function to generate - the clause, the result of which is passed to :meth:`.Query.filter`. + the clause, the result of which is passed to + :meth:`_query.Query.filter`. Parameters are the same as :func:`.with_parent`, with the exception that the given property can be None, in which case a search is - performed against this :class:`.Query` object's target mapper. + performed against this :class:`_query.Query` object's target mapper. :param instance: - An instance which has some :func:`.relationship`. + An instance which has some :func:`_orm.relationship`. :param property: String property name, or class-bound attribute, which indicates @@ -1146,7 +1167,7 @@ class Query(Generative): :param from_entity: Entity in which to consider as the left side. This defaults to the - "zero" entity of the :class:`.Query` itself. + "zero" entity of the :class:`_query.Query` itself. """ relationships = util.preloaded.orm_relationships @@ -1191,13 +1212,18 @@ class Query(Generative): @_generative def with_session(self, session): - """Return a :class:`.Query` that will use the given :class:`.Session`. + """Return a :class:`_query.Query` that will use the given + :class:`.Session`. - While the :class:`.Query` object is normally instantiated using the - :meth:`.Session.query` method, it is legal to build the :class:`.Query` + While the :class:`_query.Query` + object is normally instantiated using the + :meth:`.Session.query` method, it is legal to build the + :class:`_query.Query` directly without necessarily using a :class:`.Session`. Such a - :class:`.Query` object, or any :class:`.Query` already associated - with a different :class:`.Session`, can produce a new :class:`.Query` + :class:`_query.Query` object, or any :class:`_query.Query` + already associated + with a different :class:`.Session`, can produce a new + :class:`_query.Query` object associated with a target session using this method:: from sqlalchemy.orm import Query @@ -1211,7 +1237,7 @@ class Query(Generative): self.session = session @util.deprecated_20( - ":meth:`.Query.from_self`", + ":meth:`_query.Query.from_self`", alternative="The new approach is to use the :func:`.orm.aliased` " "construct in conjunction with a subquery. See the section " ":ref:`Selecting from the query itself as a subquery " @@ -1222,12 +1248,12 @@ class Query(Generative): r"""return a Query that selects from this Query's SELECT statement. - :meth:`.Query.from_self` essentially turns the SELECT statement + :meth:`_query.Query.from_self` essentially turns the SELECT statement into a SELECT of itself. Given a query such as:: q = session.query(User).filter(User.name.like('e%')) - Given the :meth:`.Query.from_self` version:: + Given the :meth:`_query.Query.from_self` version:: q = session.query(User).filter(User.name.like('e%')).from_self() @@ -1241,7 +1267,8 @@ class Query(Generative): FROM "user" WHERE "user".name LIKE :name_1) AS anon_1 - There are lots of cases where :meth:`.Query.from_self` may be useful. + There are lots of cases where :meth:`_query.Query.from_self` + may be useful. A simple one is where above, we may want to apply a row LIMIT to the set of user objects we query against, and then apply additional joins against that row-limited set:: @@ -1266,7 +1293,8 @@ class Query(Generative): **Automatic Aliasing** - Another key behavior of :meth:`.Query.from_self` is that it applies + Another key behavior of :meth:`_query.Query.from_self` + is that it applies **automatic aliasing** to the entities inside the subquery, when they are referenced on the outside. Above, if we continue to refer to the ``User`` entity without any additional aliasing applied @@ -1295,13 +1323,15 @@ class Query(Generative): for simple filters and orderings. More ambitious constructions such as referring to the entity in joins should prefer to use explicit subquery objects, typically making use of the - :meth:`.Query.subquery` method to produce an explicit subquery object. + :meth:`_query.Query.subquery` + method to produce an explicit subquery object. Always test the structure of queries by viewing the SQL to ensure a particular structure does what's expected! **Changing the Entities** - :meth:`.Query.from_self` also includes the ability to modify what + :meth:`_query.Query.from_self` + also includes the ability to modify what columns are being queried. In our example, we want ``User.id`` to be queried by the inner query, so that we can join to the ``Address`` entity on the outside, but we only wanted the outer @@ -1340,8 +1370,9 @@ class Query(Generative): q = q.add_entity(User).from_self().\ options(contains_eager(Address.user)) - We use :meth:`.Query.add_entity` above **before** we call - :meth:`.Query.from_self` so that the ``User`` columns are present + We use :meth:`_query.Query.add_entity` above **before** we call + :meth:`_query.Query.from_self` + so that the ``User`` columns are present in the inner subquery, so that they are available to the :func:`.contains_eager` modifier we are using on the outside, producing: @@ -1457,7 +1488,8 @@ class Query(Generative): @_generative def with_entities(self, *entities): - r"""Return a new :class:`.Query` replacing the SELECT list with the + r"""Return a new :class:`_query.Query` + replacing the SELECT list with the given entities. e.g.:: @@ -1493,8 +1525,9 @@ class Query(Generative): @util.deprecated( "1.4", - ":meth:`.Query.add_column` is deprecated and will be removed in a " - "future release. Please use :meth:`.Query.add_columns`", + ":meth:`_query.Query.add_column` " + "is deprecated and will be removed in a " + "future release. Please use :meth:`_query.Query.add_columns`", ) def add_column(self, column): """Add a column expression to the list of result columns to be @@ -1504,7 +1537,8 @@ class Query(Generative): return self.add_columns(column) def options(self, *args): - """Return a new :class:`.Query` object, applying the given list of + """Return a new :class:`_query.Query` object, + applying the given list of mapper options. Most supplied options regard changing how column- and @@ -1539,7 +1573,7 @@ class Query(Generative): opt.process_query(self) def with_transformation(self, fn): - """Return a new :class:`.Query` object transformed by + """Return a new :class:`_query.Query` object transformed by the given function. E.g.:: @@ -1551,7 +1585,7 @@ class Query(Generative): q = q.with_transformation(filter_something(x==5)) - This allows ad-hoc recipes to be created for :class:`.Query` + This allows ad-hoc recipes to be created for :class:`_query.Query` objects. See the example at :ref:`hybrid_transformers`. """ @@ -1561,17 +1595,18 @@ class Query(Generative): def with_hint(self, selectable, text, dialect_name="*"): """Add an indexing or other executional context hint for the given entity or selectable to - this :class:`.Query`. + this :class:`_query.Query`. Functionality is passed straight through to :meth:`~sqlalchemy.sql.expression.Select.with_hint`, with the addition that ``selectable`` can be a - :class:`.Table`, :class:`.Alias`, or ORM entity / mapped class + :class:`_schema.Table`, :class:`_expression.Alias`, + or ORM entity / mapped class /etc. .. seealso:: - :meth:`.Query.with_statement_hint` + :meth:`_query.Query.with_statement_hint` :meth:.`.Query.prefix_with` - generic SELECT prefixing which also can suit some database-specific HINT syntaxes such as MySQL @@ -1584,19 +1619,21 @@ class Query(Generative): self._with_hints += ((selectable, text, dialect_name),) def with_statement_hint(self, text, dialect_name="*"): - """add a statement hint to this :class:`.Select`. + """add a statement hint to this :class:`_expression.Select`. - This method is similar to :meth:`.Select.with_hint` except that + This method is similar to :meth:`_expression.Select.with_hint` + except that it does not require an individual table, and instead applies to the statement as a whole. - This feature calls down into :meth:`.Select.with_statement_hint`. + This feature calls down into + :meth:`_expression.Select.with_statement_hint`. .. versionadded:: 1.0.0 .. seealso:: - :meth:`.Query.with_hint` + :meth:`_query.Query.with_hint` """ return self.with_hint(None, text, dialect_name) @@ -1608,7 +1645,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.execution_options` + :meth:`_query.Query.execution_options` """ return self._execution_options @@ -1617,7 +1654,7 @@ class Query(Generative): """ Set non-SQL options which take effect during execution. The options are the same as those accepted by - :meth:`.Connection.execution_options`. + :meth:`_engine.Connection.execution_options`. Note that the ``stream_results`` execution option is enabled automatically if the :meth:`~sqlalchemy.orm.query.Query.yield_per()` @@ -1625,7 +1662,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.get_execution_options` + :meth:`_query.Query.get_execution_options` """ self._execution_options = self._execution_options.union(kwargs) @@ -1639,11 +1676,13 @@ class Query(Generative): skip_locked=False, key_share=False, ): - """return a new :class:`.Query` with the specified options for the + """return a new :class:`_query.Query` + with the specified options for the ``FOR UPDATE`` clause. The behavior of this method is identical to that of - :meth:`.SelectBase.with_for_update`. When called with no arguments, + :meth:`_expression.SelectBase.with_for_update`. + When called with no arguments, the resulting ``SELECT`` statement will have a ``FOR UPDATE`` clause appended. When additional arguments are specified, backend-specific options such as ``FOR UPDATE NOWAIT`` or ``LOCK IN SHARE MODE`` @@ -1659,7 +1698,8 @@ class Query(Generative): .. seealso:: - :meth:`.GenerativeSelect.with_for_update` - Core level method with + :meth:`_expression.GenerativeSelect.with_for_update` + - Core level method with full argument and behavioral description. """ @@ -1696,7 +1736,7 @@ class Query(Generative): @_assertions(_no_statement_condition, _no_limit_offset) def filter(self, *criterion): r"""apply the given filtering criterion to a copy - of this :class:`.Query`, using SQL expressions. + of this :class:`_query.Query`, using SQL expressions. e.g.:: @@ -1711,11 +1751,12 @@ class Query(Generative): The criterion is any SQL expression object applicable to the WHERE clause of a select. String expressions are coerced - into SQL expression constructs via the :func:`.text` construct. + into SQL expression constructs via the :func:`_expression.text` + construct. .. seealso:: - :meth:`.Query.filter_by` - filter on keyword expressions. + :meth:`_query.Query.filter_by` - filter on keyword expressions. """ for criterion in list(criterion): @@ -1729,7 +1770,7 @@ class Query(Generative): def filter_by(self, **kwargs): r"""apply the given filtering criterion to a copy - of this :class:`.Query`, using keyword expressions. + of this :class:`_query.Query`, using keyword expressions. e.g.:: @@ -1744,11 +1785,11 @@ class Query(Generative): The keyword expressions are extracted from the primary entity of the query, or the last entity that was the - target of a call to :meth:`.Query.join`. + target of a call to :meth:`_query.Query.join`. .. seealso:: - :meth:`.Query.filter` - filter on SQL expressions. + :meth:`_query.Query.filter` - filter on SQL expressions. """ @@ -1788,7 +1829,7 @@ class Query(Generative): @_assertions(_no_statement_condition, _no_limit_offset) def group_by(self, *criterion): """apply one or more GROUP BY criterion to the query and return - the newly resulting :class:`.Query` + the newly resulting :class:`_query.Query` All existing GROUP BY settings can be suppressed by passing ``None`` - this will suppress any GROUP BY configured @@ -1816,10 +1857,10 @@ class Query(Generative): @_assertions(_no_statement_condition, _no_limit_offset) def having(self, criterion): r"""apply a HAVING criterion to the query and return the - newly resulting :class:`.Query`. + newly resulting :class:`_query.Query`. - :meth:`~.Query.having` is used in conjunction with - :meth:`~.Query.group_by`. + :meth:`_query.Query.having` is used in conjunction with + :meth:`_query.Query.group_by`. HAVING criterion makes it possible to use filters on aggregate functions like COUNT, SUM, AVG, MAX, and MIN, eg.:: @@ -1884,7 +1925,7 @@ class Query(Generative): be rendered on a query called within UNION, EXCEPT, etc. To disable all ORDER BY clauses including those configured on mappers, issue ``query.order_by(None)`` - the resulting - :class:`.Query` object will not render ORDER BY within + :class:`_query.Query` object will not render ORDER BY within its SELECT statement. """ @@ -1936,27 +1977,31 @@ class Query(Generative): return self._set_op(expression.except_all, *q) def join(self, *props, **kwargs): - r"""Create a SQL JOIN against this :class:`.Query` object's criterion - and apply generatively, returning the newly resulting :class:`.Query`. + r"""Create a SQL JOIN against this :class:`_query.Query` + object's criterion + and apply generatively, returning the newly resulting + :class:`_query.Query`. **Simple Relationship Joins** Consider a mapping between two classes ``User`` and ``Address``, with a relationship ``User.addresses`` representing a collection of ``Address`` objects associated with each ``User``. The most - common usage of :meth:`~.Query.join` is to create a JOIN along this + common usage of :meth:`_query.Query.join` + is to create a JOIN along this relationship, using the ``User.addresses`` attribute as an indicator for how this should occur:: q = session.query(User).join(User.addresses) - Where above, the call to :meth:`~.Query.join` along ``User.addresses`` + Where above, the call to :meth:`_query.Query.join` along ``User. + addresses`` will result in SQL equivalent to:: SELECT user.* FROM user JOIN address ON user.id = address.user_id In the above example we refer to ``User.addresses`` as passed to - :meth:`~.Query.join` as the *on clause*, that is, it indicates + :meth:`_query.Query.join` as the *on clause*, that is, it indicates how the "ON" portion of the JOIN should be constructed. For a single-entity query such as the one above (i.e. we start by selecting only from ``User`` and nothing else), the relationship can also be @@ -1964,14 +2009,15 @@ class Query(Generative): q = session.query(User).join("addresses") - :meth:`~.Query.join` can also accommodate multiple + :meth:`_query.Query.join` can also accommodate multiple "on clause" arguments to produce a chain of joins, such as below where a join across four related entities is constructed:: q = session.query(User).join("orders", "items", "keywords") The above would be shorthand for three separate calls to - :meth:`~.Query.join`, each using an explicit attribute to indicate + :meth:`_query.Query.join`, + each using an explicit attribute to indicate the source entity:: q = session.query(User).\ @@ -1981,20 +2027,21 @@ class Query(Generative): **Joins to a Target Entity or Selectable** - A second form of :meth:`~.Query.join` allows any mapped entity + A second form of :meth:`_query.Query.join` allows any mapped entity or core selectable construct as a target. In this usage, - :meth:`~.Query.join` will attempt + :meth:`_query.Query.join` will attempt to create a JOIN along the natural foreign key relationship between two entities:: q = session.query(User).join(Address) - The above calling form of :meth:`~.Query.join` will raise an error if + The above calling form of :meth:`_query.Query.join` + will raise an error if either there are no foreign keys between the two entities, or if there are multiple foreign key linkages between them. In the - above calling form, :meth:`~.Query.join` is called upon to + above calling form, :meth:`_query.Query.join` is called upon to create the "on clause" automatically for us. The target can - be any mapped entity or selectable, such as a :class:`.Table`:: + be any mapped entity or selectable, such as a :class:`_schema.Table`:: q = session.query(User).join(addresses_table) @@ -2025,7 +2072,7 @@ class Query(Generative): WHERE address.email_address = :email_address_1 AND address_1.email_address = :email_address_2 - The two-argument calling form of :meth:`~.Query.join` + The two-argument calling form of :meth:`_query.Query.join` also allows us to construct arbitrary joins with SQL-oriented "on clause" expressions, not relying upon configured relationships at all. Any SQL expression can be passed as the ON clause @@ -2037,9 +2084,10 @@ class Query(Generative): **Advanced Join Targeting and Adaption** There is a lot of flexibility in what the "target" can be when using - :meth:`~.Query.join`. As noted previously, it also accepts - :class:`.Table` constructs and other selectables such as :func:`.alias` - and :func:`~.sql.expression.select` constructs, with either the one or + :meth:`_query.Query.join`. As noted previously, it also accepts + :class:`_schema.Table` constructs and other selectables such as + :func:`.alias` + and :func:`_expression.select` constructs, with either the one or two-argument forms:: addresses_q = select([Address.user_id]).\ @@ -2049,7 +2097,7 @@ class Query(Generative): q = session.query(User).\ join(addresses_q, addresses_q.c.user_id==User.id) - :meth:`~.Query.join` also features the ability to *adapt* a + :meth:`_query.Query.join` also features the ability to *adapt* a :meth:`~sqlalchemy.orm.relationship` -driven ON clause to the target selectable. Below we construct a JOIN from ``User`` to a subquery against ``Address``, allowing the relationship denoted by @@ -2080,12 +2128,12 @@ class Query(Generative): **Controlling what to Join From** - While :meth:`~.Query.join` exclusively deals with the "right" + While :meth:`_query.Query.join` exclusively deals with the "right" side of the JOIN, we can also control the "left" side, in those - cases where it's needed, using :meth:`~.Query.select_from`. + cases where it's needed, using :meth:`_query.Query.select_from`. Below we construct a query against ``Address`` but can still make usage of ``User.addresses`` as our ON clause by instructing - the :class:`.Query` to select first from the ``User`` + the :class:`_query.Query` to select first from the ``User`` entity:: q = session.query(Address).select_from(User).\ @@ -2100,7 +2148,7 @@ class Query(Generative): **Constructing Aliases Anonymously** - :meth:`~.Query.join` can construct anonymous aliases + :meth:`_query.Query.join` can construct anonymous aliases using the ``aliased=True`` flag. This feature is useful when a query is being joined algorithmically, such as when querying self-referentially to an arbitrary depth:: @@ -2110,7 +2158,7 @@ class Query(Generative): When ``aliased=True`` is used, the actual "alias" construct is not explicitly available. To work with it, methods such as - :meth:`.Query.filter` will adapt the incoming entity to + :meth:`_query.Query.filter` will adapt the incoming entity to the last join point:: q = session.query(Node).\ @@ -2119,7 +2167,7 @@ class Query(Generative): When using automatic aliasing, the ``from_joinpoint=True`` argument can allow a multi-node join to be broken into - multiple calls to :meth:`~.Query.join`, so that + multiple calls to :meth:`_query.Query.join`, so that each path along the way can be further filtered:: q = session.query(Node).\ @@ -2129,7 +2177,7 @@ class Query(Generative): filter(Node.name == 'grandchild 1') The filtering aliases above can then be reset back to the - original ``Node`` entity using :meth:`~.Query.reset_joinpoint`:: + original ``Node`` entity using :meth:`_query.Query.reset_joinpoint`:: q = session.query(Node).\ join("children", "children", aliased=True).\ @@ -2148,13 +2196,14 @@ class Query(Generative): A special two-argument calling form of the form ``target, onclause`` is also accepted. :param aliased=False: If True, indicate that the JOIN target should be - anonymously aliased. Subsequent calls to :meth:`~.Query.filter` + anonymously aliased. Subsequent calls to :meth:`_query.Query.filter` and similar will adapt the incoming criterion to the target - alias, until :meth:`~.Query.reset_joinpoint` is called. + alias, until :meth:`_query.Query.reset_joinpoint` is called. :param isouter=False: If True, the join used will be a left outer join, - just as if the :meth:`.Query.outerjoin` method were called. This + just as if the :meth:`_query.Query.outerjoin` method were called. + This flag is here to maintain consistency with the same flag as accepted - by :meth:`.FromClause.join` and other Core constructs. + by :meth:`_expression.FromClause.join` and other Core constructs. .. versionadded:: 1.0.0 @@ -2173,10 +2222,10 @@ class Query(Generative): :ref:`ormtutorial_joins` in the ORM tutorial. :ref:`inheritance_toplevel` for details on how - :meth:`~.Query.join` is used for inheritance relationships. + :meth:`_query.Query.join` is used for inheritance relationships. - :func:`.orm.join` - a standalone ORM-level join function, - used internally by :meth:`.Query.join`, which in previous + :func:`_orm.join` - a standalone ORM-level join function, + used internally by :meth:`_query.Query.join`, which in previous SQLAlchemy versions was the primary ORM-level joining interface. """ @@ -2809,12 +2858,12 @@ class Query(Generative): @_generative @_assertions(_no_statement_condition) def reset_joinpoint(self): - """Return a new :class:`.Query`, where the "join point" has + """Return a new :class:`_query.Query`, where the "join point" has been reset back to the base FROM entities of the query. This method is usually used in conjunction with the - ``aliased=True`` feature of the :meth:`~.Query.join` - method. See the example in :meth:`~.Query.join` for how + ``aliased=True`` feature of the :meth:`_query.Query.join` + method. See the example in :meth:`_query.Query.join` for how this is used. """ @@ -2823,16 +2872,16 @@ class Query(Generative): @_generative @_assertions(_no_clauseelement_condition) def select_from(self, *from_obj): - r"""Set the FROM clause of this :class:`.Query` explicitly. + r"""Set the FROM clause of this :class:`_query.Query` explicitly. - :meth:`.Query.select_from` is often used in conjunction with - :meth:`.Query.join` in order to control which entity is selected + :meth:`_query.Query.select_from` is often used in conjunction with + :meth:`_query.Query.join` in order to control which entity is selected from on the "left" side of the join. The entity or selectable object here effectively replaces the - "left edge" of any calls to :meth:`~.Query.join`, when no + "left edge" of any calls to :meth:`_query.Query.join`, when no joinpoint is otherwise established - usually, the default "join - point" is the leftmost entity in the :class:`~.Query` object's + point" is the leftmost entity in the :class:`_query.Query` object's list of entities to be selected. A typical example:: @@ -2849,8 +2898,9 @@ class Query(Generative): :param \*from_obj: collection of one or more entities to apply to the FROM clause. Entities can be mapped classes, - :class:`.AliasedClass` objects, :class:`.Mapper` objects - as well as core :class:`.FromClause` elements like subqueries. + :class:`.AliasedClass` objects, :class:`_orm.Mapper` objects + as well as core :class:`_expression.FromClause` + elements like subqueries. .. versionchanged:: 0.9 This method no longer applies the given FROM object @@ -2861,9 +2911,9 @@ class Query(Generative): .. seealso:: - :meth:`~.Query.join` + :meth:`_query.Query.join` - :meth:`.Query.select_entity_from` + :meth:`_query.Query.select_entity_from` """ @@ -2872,15 +2922,16 @@ class Query(Generative): @_generative @_assertions(_no_clauseelement_condition) def select_entity_from(self, from_obj): - r"""Set the FROM clause of this :class:`.Query` to a + r"""Set the FROM clause of this :class:`_query.Query` to a core selectable, applying it as a replacement FROM clause for corresponding mapped entities. - The :meth:`.Query.select_entity_from` method supplies an alternative + The :meth:`_query.Query.select_entity_from` + method supplies an alternative approach to the use case of applying an :func:`.aliased` construct explicitly throughout a query. Instead of referring to the :func:`.aliased` construct explicitly, - :meth:`.Query.select_entity_from` automatically *adapts* all + :meth:`_query.Query.select_entity_from` automatically *adapts* all occurrences of the entity to the target selectable. Given a case for :func:`.aliased` such as selecting ``User`` @@ -2894,7 +2945,8 @@ class Query(Generative): Above, we apply the ``user_alias`` object explicitly throughout the query. When it's not feasible for ``user_alias`` to be referenced - explicitly in many places, :meth:`.Query.select_entity_from` may be + explicitly in many places, :meth:`_query.Query.select_entity_from` + may be used at the start of the query to adapt the existing ``User`` entity:: q = session.query(User).\ @@ -2912,11 +2964,12 @@ class Query(Generative): WHERE "user".id = :id_1) AS anon_1 WHERE anon_1.name = :name_1 - The :meth:`.Query.select_entity_from` method is similar to the - :meth:`.Query.select_from` method, in that it sets the FROM clause + The :meth:`_query.Query.select_entity_from` method is similar to the + :meth:`_query.Query.select_from` method, + in that it sets the FROM clause of the query. The difference is that it additionally applies adaptation to the other parts of the query that refer to the - primary entity. If above we had used :meth:`.Query.select_from` + primary entity. If above we had used :meth:`_query.Query.select_from` instead, the SQL generated would have been: .. sourcecode:: sql @@ -2928,24 +2981,30 @@ class Query(Generative): WHERE "user".id = :id_1) AS anon_1 WHERE "user".name = :name_1 - To supply textual SQL to the :meth:`.Query.select_entity_from` method, - we can make use of the :func:`.text` construct. However, the - :func:`.text` construct needs to be aligned with the columns of our + To supply textual SQL to the :meth:`_query.Query.select_entity_from` + method, + we can make use of the :func:`_expression.text` construct. However, + the + :func:`_expression.text` + construct needs to be aligned with the columns of our entity, which is achieved by making use of the - :meth:`.TextClause.columns` method:: + :meth:`_expression.TextClause.columns` method:: text_stmt = text("select id, name from user").columns( User.id, User.name).subquery() q = session.query(User).select_entity_from(text_stmt) - :meth:`.Query.select_entity_from` itself accepts an :func:`.aliased` + :meth:`_query.Query.select_entity_from` itself accepts an + :func:`.aliased` object, so that the special options of :func:`.aliased` such as :paramref:`.aliased.adapt_on_names` may be used within the - scope of the :meth:`.Query.select_entity_from` method's adaptation + scope of the :meth:`_query.Query.select_entity_from` + method's adaptation services. Suppose a view ``user_view`` also returns rows from ``user``. If - we reflect this view into a :class:`.Table`, this view has no - relationship to the :class:`.Table` to which we are mapped, however + we reflect this view into a :class:`_schema.Table`, this view has no + relationship to the :class:`_schema.Table` to which we are mapped, + however we can use name matching to select from it:: user_view = Table('user_view', metadata, @@ -2956,19 +3015,21 @@ class Query(Generative): select_entity_from(user_view_alias).\ order_by(User.name) - .. versionchanged:: 1.1.7 The :meth:`.Query.select_entity_from` + .. versionchanged:: 1.1.7 The :meth:`_query.Query.select_entity_from` method now accepts an :func:`.aliased` object as an alternative - to a :class:`.FromClause` object. + to a :class:`_expression.FromClause` object. - :param from_obj: a :class:`.FromClause` object that will replace - the FROM clause of this :class:`.Query`. It also may be an instance + :param from_obj: a :class:`_expression.FromClause` + object that will replace + the FROM clause of this :class:`_query.Query`. + It also may be an instance of :func:`.aliased`. .. seealso:: - :meth:`.Query.select_from` + :meth:`_query.Query.select_from` """ @@ -3006,8 +3067,8 @@ class Query(Generative): @_generative @_assertions(_no_statement_condition) def slice(self, start, stop): - """Computes the "slice" of the :class:`.Query` represented by - the given indices and returns the resulting :class:`.Query`. + """Computes the "slice" of the :class:`_query.Query` represented by + the given indices and returns the resulting :class:`_query.Query`. The start and stop indices behave like the argument to Python's built-in :func:`range` function. This method provides an @@ -3030,9 +3091,9 @@ class Query(Generative): .. seealso:: - :meth:`.Query.limit` + :meth:`_query.Query.limit` - :meth:`.Query.offset` + :meth:`_query.Query.offset` """ if start is not None and stop is not None: @@ -3082,9 +3143,10 @@ class Query(Generative): columns clause of the SELECT statement, to satisfy the common need of the database backend that ORDER BY columns be part of the SELECT list when DISTINCT is used. These columns *are not* added to the - list of columns actually fetched by the :class:`.Query`, however, + list of columns actually fetched by the :class:`_query.Query`, + however, so would not affect results. The columns are passed through when - using the :attr:`.Query.statement` accessor, however. + using the :attr:`_query.Query.statement` accessor, however. .. deprecated:: 2.0 This logic is deprecated and will be removed in SQLAlchemy 2.0. See :ref:`migration_20_query_distinct` @@ -3127,7 +3189,7 @@ class Query(Generative): .. seealso:: - :meth:`.HasPrefixes.prefix_with` + :meth:`_expression.HasPrefixes.prefix_with` """ if self._prefixes: @@ -3147,9 +3209,9 @@ class Query(Generative): .. seealso:: - :meth:`.Query.prefix_with` + :meth:`_query.Query.prefix_with` - :meth:`.HasSuffixes.suffix_with` + :meth:`_expression.HasSuffixes.suffix_with` """ if self._suffixes: @@ -3158,11 +3220,13 @@ class Query(Generative): self._suffixes = suffixes def all(self): - """Return the results represented by this :class:`.Query` as a list. + """Return the results represented by this :class:`_query.Query` + as a list. This results in an execution of the underlying SQL statement. - .. warning:: The :class:`.Query` object, when asked to return either + .. warning:: The :class:`_query.Query` object, + when asked to return either a sequence or iterator that consists of full ORM-mapped entities, will **deduplicate entries based on primary key**. See the FAQ for more details. @@ -3181,10 +3245,11 @@ class Query(Generative): This method bypasses all internal statement compilation, and the statement is executed without modification. - The statement is typically either a :func:`~.expression.text` - or :func:`~.expression.select` construct, and should return the set + The statement is typically either a :func:`_expression.text` + or :func:`_expression.select` construct, and should return the set of columns - appropriate to the entity class represented by this :class:`.Query`. + appropriate to the entity class represented by this + :class:`_query.Query`. .. seealso:: @@ -3204,14 +3269,15 @@ class Query(Generative): (note this may consist of multiple result rows if join-loaded collections are present). - Calling :meth:`.Query.first` results in an execution of the underlying + Calling :meth:`_query.Query.first` + results in an execution of the underlying query. .. seealso:: - :meth:`.Query.one` + :meth:`_query.Query.one` - :meth:`.Query.one_or_none` + :meth:`_query.Query.one_or_none` """ if self._statement is not None: @@ -3232,18 +3298,19 @@ class Query(Generative): rows are returned for a query that returns only scalar values as opposed to full identity-mapped entities. - Calling :meth:`.Query.one_or_none` results in an execution of the + Calling :meth:`_query.Query.one_or_none` + results in an execution of the underlying query. .. versionadded:: 1.0.9 - Added :meth:`.Query.one_or_none` + Added :meth:`_query.Query.one_or_none` .. seealso:: - :meth:`.Query.first` + :meth:`_query.Query.first` - :meth:`.Query.one` + :meth:`_query.Query.one` """ ret = list(self) @@ -3271,9 +3338,9 @@ class Query(Generative): .. seealso:: - :meth:`.Query.first` + :meth:`_query.Query.first` - :meth:`.Query.one_or_none` + :meth:`_query.Query.one_or_none` """ try: @@ -3365,7 +3432,7 @@ class Query(Generative): @property def column_descriptions(self): """Return metadata about the columns which would be - returned by this :class:`.Query`. + returned by this :class:`_query.Query`. Format is a list of dictionaries:: @@ -3435,7 +3502,7 @@ class Query(Generative): util.warn_deprecated( "Using the Query.instances() method without a context " "is deprecated and will be disallowed in a future release. " - "Please make use of :meth:`.Query.from_statement` " + "Please make use of :meth:`_query.Query.from_statement` " "for linking ORM results to arbitrary select constructs.", version="1.4", ) @@ -3444,9 +3511,10 @@ class Query(Generative): return loading.instances(self, result_proxy, context) def merge_result(self, iterator, load=True): - """Merge a result into this :class:`.Query` object's Session. + """Merge a result into this :class:`_query.Query` object's Session. - Given an iterator returned by a :class:`.Query` of the same structure + Given an iterator returned by a :class:`_query.Query` + of the same structure as this one, return an identical iterator of results, with all mapped instances merged into the session using :meth:`.Session.merge`. This is an optimized method which will merge all mapped instances, @@ -3455,14 +3523,15 @@ class Query(Generative): explicitly for each value. The structure of the results is determined based on the column list of - this :class:`.Query` - if these do not correspond, unchecked errors + this :class:`_query.Query` - if these do not correspond, + unchecked errors will occur. The 'load' argument is the same as that of :meth:`.Session.merge`. - For an example of how :meth:`~.Query.merge_result` is used, see + For an example of how :meth:`_query.Query.merge_result` is used, see the source code for the example :ref:`examples_caching`, where - :meth:`~.Query.merge_result` is used to efficiently restore state + :meth:`_query.Query.merge_result` is used to efficiently restore state from a cache back into a target :class:`.Session`. """ @@ -3544,7 +3613,8 @@ class Query(Generative): ) AS anon_1 The above SQL returns a single row, which is the aggregate value - of the count function; the :meth:`.Query.count` method then returns + of the count function; the :meth:`_query.Query.count` + method then returns that single integer value. .. warning:: @@ -3552,7 +3622,8 @@ class Query(Generative): It is important to note that the value returned by count() is **not the same as the number of ORM objects that this Query would return from a method such as the .all() method**. - The :class:`.Query` object, when asked to return full entities, + The :class:`_query.Query` object, + when asked to return full entities, will **deduplicate entries based on primary key**, meaning if the same primary key value would appear in the results more than once, only one object of that primary key would be present. This does @@ -3602,7 +3673,8 @@ class Query(Generative): sess.query(User).filter(User.age == 25).\ delete(synchronize_session='evaluate') - .. warning:: The :meth:`.Query.delete` method is a "bulk" operation, + .. warning:: The :meth:`_query.Query.delete` + method is a "bulk" operation, which bypasses ORM unit-of-work automation in favor of greater performance. **Please read all caveats and warnings below.** @@ -3702,7 +3774,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.update` + :meth:`_query.Query.update` :ref:`inserts_and_updates` - Core SQL tutorial @@ -3726,7 +3798,8 @@ class Query(Generative): update({"age": User.age - 10}, synchronize_session='evaluate') - .. warning:: The :meth:`.Query.update` method is a "bulk" operation, + .. warning:: The :meth:`_query.Query.update` + method is a "bulk" operation, which bypasses ORM unit-of-work automation in favor of greater performance. **Please read all caveats and warnings below.** @@ -3768,7 +3841,8 @@ class Query(Generative): string collations between the database and Python. :param update_args: Optional dictionary, if present will be passed - to the underlying :func:`.update` construct as the ``**kw`` for + to the underlying :func:`_expression.update` + construct as the ``**kw`` for the object. May be used to pass dialect-specific arguments such as ``mysql_limit``, as well as other special arguments such as :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`. @@ -3834,7 +3908,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.delete` + :meth:`_query.Query.delete` :ref:`inserts_and_updates` - Core SQL tutorial @@ -4272,11 +4346,13 @@ class _MapperEntity(_QueryEntity): @inspection._self_inspects class Bundle(InspectionAttr): - """A grouping of SQL expressions that are returned by a :class:`.Query` + """A grouping of SQL expressions that are returned by a + :class:`_query.Query` under one namespace. The :class:`.Bundle` essentially allows nesting of the tuple-based - results returned by a column-oriented :class:`.Query` object. It also + results returned by a column-oriented :class:`_query.Query` object. + It also is extensible via simple subclassing, where the primary capability to override is that of how the set of expressions should be returned, allowing post-processing as well as custom return types, without @@ -4765,7 +4841,8 @@ class QueryContext(object): class AliasOption(interfaces.MapperOption): def __init__(self, alias): - r"""Return a :class:`.MapperOption` that will indicate to the :class:`.Query` + r"""Return a :class:`.MapperOption` that will indicate to the + :class:`_query.Query` that the main table has been aliased. This is a seldom-used option to suit the @@ -4793,7 +4870,7 @@ class AliasOption(interfaces.MapperOption): results = query.from_statement(statement).all() :param alias: is the string name of an alias, or a - :class:`~.sql.expression.Alias` object representing + :class:`_expression.Alias` object representing the alias. """ |