Bulk Operations
===============
-.. deepalchemy:: Bulk operations are essentially lower-functionality versions
+.. tip::
+
+ Bulk operations are essentially lower-functionality versions
of the Unit of Work's facilities for emitting INSERT and UPDATE statements
on primary key targeted rows. These routines were added to suit some
cases where many rows being inserted or updated could be run into the
- database without as much of the usual unit of work overhead, in that
- most unit of work features are **disabled**.
+ database without as much of the usual unit of work overhead, by bypassing
+ a large portion of the functionality that the unit of work provides.
+
+ SQLAlchemy 2.0 features new and improved bulk techniques with clarified
+ behavior, better integration with ORM objects as well as INSERT/UPDATE/DELETE
+ statements, and new capabilities. They additionally repair some long lived
+ performance issues that plagued both regular unit of work and "bulk" routines,
+ most notably in the area of INSERT operations.
+
+ For these reasons, the previous bulk methods move into legacy status, which
+ is revised from the original plan that "bulk" features were to be deprecated
+ entirely.
- There is **usually no need to use these routines, and they are not easy
- to use as there are many missing behaviors that are usually expected when
- using ORM objects**; for efficient
- bulk inserts, it's better to use the Core :class:`_sql.Insert` construct
- directly. Please read all caveats at :ref:`bulk_operations_caveats`.
+ When using the legacy 1.4 versions of these features, please read all
+ caveats at :ref:`bulk_operations_caveats`, as they are not always obvious.
.. note:: Bulk INSERT and UPDATE should not be confused with the
more common feature known as :ref:`orm_expression_update_delete`. This
s = Session()
objects = [User(name="u1"), User(name="u2"), User(name="u3")]
s.bulk_save_objects(objects)
+ s.commit()
For :meth:`.Session.bulk_insert_mappings`, and :meth:`.Session.bulk_update_mappings`,
dictionaries are passed::
s.bulk_insert_mappings(User, [dict(name="u1"), dict(name="u2"), dict(name="u3")])
+ s.commit()
.. seealso::
as an alternative newer mass-insert features such as
:ref:`orm_dml_returning_objects`.
- .. warning::
+ .. legacy::
The bulk save feature allows for a lower-latency INSERT/UPDATE
of rows at the expense of most other unit-of-work features.
Features such as object management, relationship handling,
- and SQL clause support are **silently omitted** in favor of raw
+ and SQL clause support are silently omitted in favor of raw
INSERT/UPDATES of records.
- Please note that newer versions of SQLAlchemy are **greatly
- improving the efficiency** of the standard flush process. It is
- **strongly recommended** to not use the bulk methods as they
- represent a forking of SQLAlchemy's functionality and are slowly
- being moved into legacy status. New features such as
- :ref:`orm_dml_returning_objects` are both more efficient than
- the "bulk" methods and provide more predictable functionality.
+ In SQLAlchemy 2.0, improved versions of the bulk insert/update
+ methods are introduced, with clearer behavior and
+ documentation, new capabilities, and much better performance.
- **Please read the list of caveats at**
+ For 1.4 use, **please read the list of caveats at**
:ref:`bulk_operations_caveats` **before using this method, and
fully test and confirm the functionality of all code developed
using these systems.**
.. versionadded:: 1.0.0
- .. warning::
+ .. legacy::
The bulk insert feature allows for a lower-latency INSERT
of rows at the expense of most other unit-of-work features.
Features such as object management, relationship handling,
- and SQL clause support are **silently omitted** in favor of raw
+ and SQL clause support are silently omitted in favor of raw
INSERT of records.
- Please note that newer versions of SQLAlchemy are **greatly
- improving the efficiency** of the standard flush process. It is
- **strongly recommended** to not use the bulk methods as they
- represent a forking of SQLAlchemy's functionality and are slowly
- being moved into legacy status. New features such as
- :ref:`orm_dml_returning_objects` are both more efficient than
- the "bulk" methods and provide more predictable functionality.
+ In SQLAlchemy 2.0, improved versions of the bulk insert/update
+ methods are introduced, with clearer behavior and
+ documentation, new capabilities, and much better performance.
- **Please read the list of caveats at**
+ For 1.4 use, **please read the list of caveats at**
:ref:`bulk_operations_caveats` **before using this method, and
fully test and confirm the functionality of all code developed
using these systems.**
.. versionadded:: 1.0.0
- .. warning::
+ .. legacy::
The bulk update feature allows for a lower-latency UPDATE
of rows at the expense of most other unit-of-work features.
Features such as object management, relationship handling,
- and SQL clause support are **silently omitted** in favor of raw
+ and SQL clause support are silently omitted in favor of raw
UPDATES of records.
- Please note that newer versions of SQLAlchemy are **greatly
- improving the efficiency** of the standard flush process. It is
- **strongly recommended** to not use the bulk methods as they
- represent a forking of SQLAlchemy's functionality and are slowly
- being moved into legacy status. New features such as
- :ref:`orm_dml_returning_objects` are both more efficient than
- the "bulk" methods and provide more predictable functionality.
+ In SQLAlchemy 2.0, improved versions of the bulk insert/update
+ methods are introduced, with clearer behavior and
+ documentation, new capabilities, and much better performance.
- **Please read the list of caveats at**
+ For 1.4 use, **please read the list of caveats at**
:ref:`bulk_operations_caveats` **before using this method, and
fully test and confirm the functionality of all code developed
using these systems.**
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
