Classe « Session »

Méthode sqlalchemy.orm.Session.bulk_insert_mappings

Signature de la méthode bulk_insert_mappings

def bulk_insert_mappings(self, mapper, mappings, return_defaults=False, render_nulls=False) 

Description

bulk_insert_mappings.__doc__

Perform a bulk insert of the given list of mapping dictionaries.

        The bulk insert feature allows plain Python dictionaries to be used as
        the source of simple INSERT operations which can be more easily
        grouped together into higher performing "executemany"
        operations.  Using dictionaries, there is no "history" or session
        state management features in use, reducing latency when inserting
        large numbers of simple rows.

        The values within the dictionaries as given are typically passed
        without modification into Core :meth:`_expression.Insert` constructs,
        after
        organizing the values within them across the tables to which
        the given mapper is mapped.

        .. versionadded:: 1.0.0

        .. warning::

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

            **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 mapper: a mapped class, or the actual :class:`_orm.Mapper`
         object,
         representing the single kind of object represented within the mapping
         list.

        :param mappings: a sequence of dictionaries, each one containing the
         state of the mapped row to be inserted, in terms of the attribute
         names on the mapped class.   If the mapping refers to multiple tables,
         such as a joined-inheritance mapping, each dictionary must contain all
         keys to be populated into all tables.

        :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_insert_mappings.return_defaults`
         **greatly reduces the performance gains** of the method overall.
         If the rows
         to be inserted only refer to a single table, then there is no
         reason this flag should be set as the returned default information
         is not used.

        :param render_nulls: When True, a value of ``None`` will result
         in a NULL value being included in the INSERT statement, rather
         than the column being omitted from the INSERT.   This allows all
         the rows being INSERTed to have the identical set of columns which
         allows the full set of rows to be batched to the DBAPI.  Normally,
         each column-set that contains a different combination of NULL values
         than the previous row must omit a different series of columns from
         the rendered INSERT statement, which means it must be emitted as a
         separate statement.   By passing this flag, the full set of rows
         are guaranteed to be batchable into one batch; the cost however is
         that server-side defaults which are invoked by an omitted column will
         be skipped, so care must be taken to ensure that these are not
         necessary.

         .. warning::

            When this flag is set, **server side default SQL values will
            not be invoked** for those columns that are inserted as NULL;
            the NULL value will be sent explicitly.   Care must be taken
            to ensure that no server-side default functions need to be
            invoked for the operation as a whole.

         .. versionadded:: 1.1

        .. seealso::

            :ref:`bulk_operations`

            :meth:`.Session.bulk_save_objects`

            :meth:`.Session.bulk_update_mappings`