From: Mike Bayer Date: Fri, 30 Oct 2020 03:21:13 +0000 (-0400) Subject: rename "bulk" UPDATE and DELETE to not use the word "bulk" X-Git-Tag: rel_1_4_0b1~12 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=163a97c6d57db09d6405124dae9b877bc9629721;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git rename "bulk" UPDATE and DELETE to not use the word "bulk" This term confuses this feature with the lesser used "bulk insert/update" feature, and also "bulk" is not as descriptive here as only a single statement is run; there's not a large set of data passed in. For now call it UPDATE/DELETE with arbitrary WHERE clause, or ORM-enabled UPDATE/DELETE. Change-Id: I317fcda9d73d4c2dd250031a745dd3d72e4f1fc6 --- diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst index 7004e3edd1..79af8f27fe 100644 --- a/doc/build/orm/session_basics.rst +++ b/doc/build/orm/session_basics.rst @@ -524,10 +524,10 @@ Further discussion on the refresh / expire concept can be found at -.. _bulk_update_delete: +.. _orm_expression_update_delete: -Bulk UPDATE and DELETE ----------------------- +UPDATE and DELETE with arbitrary WHERE clause +--------------------------------------------- The sections above on :meth:`_orm.Session.flush` and :meth:`_orm.Session.delete` detail how rows can be inserted, updated and deleted in the database, @@ -536,7 +536,7 @@ objets in the application. The :class:`_orm.Session` can also emit UPDATE and DELETE statements with arbitrary WHERE clauses as well, and at the same time refresh locally present objects which match those rows. -To emit a bulk UPDATE in :term:`1.x style`, the :meth:`_query.Query.update` method +To emit an ORM-enabled UPDATE in :term:`1.x style`, the :meth:`_query.Query.update` method may be used:: session.query(User).filter(User.nane == "squidward").\ @@ -550,7 +550,7 @@ via a separate SELECT statement or via RETURNING if the backend database support objects locally present in memory will be updated in memory based on these primary key identities. -For bulk UPDATEs in :term:`2.0 style`, :meth:`_orm.Session.execute` is used with the +For ORM-enabled UPDATEs in :term:`2.0 style`, :meth:`_orm.Session.execute` is used with the Core :class:`_sql.Update` construct. The :meth:`_orm.Session` must be configured with :paramref:`_orm.Session.future` set to ``True``:: @@ -570,12 +570,12 @@ DELETEs work in the same way as UPDATE except there is no "values / set" clause established. When synchronize_session is used, matching objects within the :class:`_orm.Session` will be marked as deleted and expunged. -Bulk delete, :term:`1.x style`:: +ORM-enabled delete, :term:`1.x style`:: session.query(User).filter(User.nane == "squidward").\ delete(synchronize_session="fetch") -Bulk delete, :term:`2.0 style`. The :meth:`_orm.Session` must +ORM-enabled delete, :term:`2.0 style`. The :meth:`_orm.Session` must be configured with :paramref:`_orm.Session.future` set to ``True``:: session = Session(future=True) @@ -586,7 +586,7 @@ be configured with :paramref:`_orm.Session.future` set to ``True``:: session.execute(stmt) -With both the 1.x and 2.0 form of bulk updates and deletes, the following +With both the 1.x and 2.0 form of ORM-enabled updates and deletes, the following values for ``synchronize_session`` are supported: * ``False`` - don't synchronize the session. This option is the most @@ -623,11 +623,11 @@ values for ``synchronize_session`` are supported: value of ``True``. -.. warning:: **Additional Caveats for bulk updates and deletes** +.. warning:: **Additional Caveats for ORM-enabled updates and deletes** - The bulk UPDATE and DELETE features bypass ORM unit-of-work automation in - favor being able to emit a single UPDATE or DELETE statement at once - without complexity. + The ORM-enabled UPDATE and DELETE features bypass ORM unit-of-work + automation in favor being able to emit a single UPDATE or DELETE statement + that matches multiple rows at once without complexity. * The operations do not offer in-Python cascading of relationships - it is assumed that ON UPDATE CASCADE and/or @@ -649,7 +649,7 @@ values for ``synchronize_session`` are supported: statement emitted which may reduce performance. Use SQL echoing when developing to evaluate the impact of SQL emitted. - * Bulk UPDATEs and DELETEs do not handle joined table inheritance + * ORM-enabled UPDATEs and DELETEs do not handle joined table inheritance automatically. If the operation is against multiple tables, typically individual UPDATE / DELETE statements against the individual tables should be used. Some databases support multiple table UPDATEs. @@ -670,7 +670,7 @@ values for ``synchronize_session`` are supported: UPDATE or DELETE statement being emitted, as well as taken into account during the "synchronize" process. - * In order to intercept bulk UPDATE and DELETE operations with event + * In order to intercept ORM-enabled UPDATE and DELETE operations with event handlers, use the :meth:`_orm.SessionEvents.do_orm_execute` event. diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index 4e11ebb8c6..a0e100a816 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -1798,7 +1798,8 @@ class SessionEvents(event.Events): ), ) def after_bulk_update(self, update_context): - """Execute after a bulk update operation to the session. + """Execute after an ORM UPDATE against a WHERE expression has been + invoked. This is called as a result of the :meth:`_query.Query.update` method. @@ -1837,7 +1838,8 @@ class SessionEvents(event.Events): ), ) def after_bulk_delete(self, delete_context): - """Execute after a bulk delete operation to the session. + """Execute after ORM DELETE against a WHERE expression has been + invoked. This is called as a result of the :meth:`_query.Query.delete` method. diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index df1a048f31..277dda6fb8 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -3033,7 +3033,7 @@ class Query( return self._from_self(col).scalar() def delete(self, synchronize_session="evaluate"): - r"""Perform a bulk delete query. + r"""Perform a DELETE with an arbitrary WHERE clause. Deletes rows matched by this query from the database. @@ -3047,20 +3047,21 @@ class Query( .. warning:: - See the section :ref:`bulk_update_delete` for important caveats - and warnings, including limitations when using bulk UPDATE + See the section :ref:`orm_expression_update_delete` for important + caveats and warnings, including limitations when using bulk UPDATE and DELETE with mapper inheritance configurations. :param synchronize_session: chooses the strategy to update the attributes on objects in the session. See the section - :ref:`bulk_update_delete` for a discussion of these strategies. + :ref:`orm_expression_update_delete` for a discussion of these + strategies. :return: the count of rows matched as returned by the database's "row count" feature. .. seealso:: - :ref:`bulk_update_delete` + :ref:`orm_expression_update_delete` """ @@ -3087,7 +3088,7 @@ class Query( return result.rowcount def update(self, values, synchronize_session="evaluate", update_args=None): - r"""Perform a bulk update query. + r"""Perform an UPDATE with an arbitrary WHERE clause. Updates rows matched by this query in the database. @@ -3101,9 +3102,9 @@ class Query( .. warning:: - See the section :ref:`bulk_update_delete` for important caveats - and warnings, including limitations when using bulk UPDATE - and DELETE with mapper inheritance configurations. + See the section :ref:`orm_expression_update_delete` for important + caveats and warnings, including limitations when using arbitrary + UPDATE and DELETE with mapper inheritance configurations. :param values: a dictionary with attributes names, or alternatively mapped attributes or SQL expressions, as keys, and literal @@ -3117,7 +3118,8 @@ class Query( :param synchronize_session: chooses the strategy to update the attributes on objects in the session. See the section - :ref:`bulk_update_delete` for a discussion of these strategies. + :ref:`orm_expression_update_delete` for a discussion of these + strategies. :param update_args: Optional dictionary, if present will be passed to the underlying :func:`_expression.update` @@ -3132,7 +3134,7 @@ class Query( .. seealso:: - :ref:`bulk_update_delete` + :ref:`orm_expression_update_delete` """