Classe « Session »

Méthode sqlalchemy.orm.Session.bulk_save_objects

Signature de la méthode bulk_save_objects

def bulk_save_objects(self, objects, return_defaults=False, update_changed_only=True, preserve_order=True) 

Description

bulk_save_objects.__doc__

Perform a bulk save of the given list of objects.

        The bulk save feature allows mapped objects to be used as the
        source of simple INSERT and UPDATE operations which can be more easily
        grouped together into higher performing "executemany"
        operations; the extraction of data from the objects is also performed
        using a lower-latency process that ignores whether or not attributes
        have actually been modified in the case of UPDATEs, and also ignores
        SQL expressions.

        The objects as given are not added to the session and no additional
        state is established on them. If the
        :paramref:`_orm.Session.bulk_save_objects.return_defaults` flag is set,
        then server-generated primary key values will be assigned to the
        returned objects, but **not server side defaults**; this is a
        limitation in the implementation. If stateful objects are desired,
        please use the standard :meth:`_orm.Session.add_all` approach or
        as an alternative newer mass-insert features such as
        :ref:`orm_dml_returning_objects`.

        .. warning::

            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
            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.

            **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.**

        :param objects: a sequence of mapped object instances.  The mapped
         objects are persisted as is, and are **not** associated with the
         :class:`.Session` afterwards.

         For each object, whether the object is sent as an INSERT or an
         UPDATE is dependent on the same rules used by the :class:`.Session`
         in traditional operation; if the object has the
         :attr:`.InstanceState.key`
         attribute set, then the object is assumed to be "detached" and
         will result in an UPDATE.  Otherwise, an INSERT is used.

         In the case of an UPDATE, statements are grouped based on which
         attributes have changed, and are thus to be the subject of each
         SET clause.  If ``update_changed_only`` is False, then all
         attributes present within each object are applied to the UPDATE
         statement, which may help in allowing the statements to be grouped
         together into a larger executemany(), and will also reduce the
         overhead of checking history on attributes.

        :param return_defaults: when True, rows that are missing values which
         generate defaults, namely integer primary key defaults and sequences,
         will be inserted **one at a time**, so that the primary key value
         is available.  In particular this will allow joined-inheritance
         and other multi-table mappings to insert correctly without the need
         to provide primary key values ahead of time; however,
         :paramref:`.Session.bulk_save_objects.return_defaults` **greatly
         reduces the performance gains** of the method overall.  It is strongly
         advised to please use the standard :meth:`_orm.Session.add_all`
         approach.

        :param update_changed_only: when True, UPDATE statements are rendered
         based on those attributes in each state that have logged changes.
         When False, all attributes present are rendered into the SET clause
         with the exception of primary key attributes.

        :param preserve_order: when True, the order of inserts and updates
         matches exactly the order in which the objects are given.   When
         False, common types of objects are grouped into inserts
         and updates, to allow for more batching opportunities.

         .. versionadded:: 1.3

        .. seealso::

            :ref:`bulk_operations`

            :meth:`.Session.bulk_insert_mappings`

            :meth:`.Session.bulk_update_mappings`