Function orm_insert_sentinel

lib/sqlalchemy/orm/_orm_constructors.py:398–445

Provides a surrogate :func:`_orm.mapped_column` that generates a so-called :term:`sentinel` column, allowing efficient bulk inserts with deterministic RETURNING sorting for tables that don't otherwise have qualifying primary key configurations. Use of :func:`_orm.orm_insert_sentinel

(
    name: Optional[str] = None,
    type_: Optional[_TypeEngineArgument[Any]] = None,
    *,
    default: Optional[Any] = None,
    omit_from_statements: bool = True,
)

def orm_insert_sentinel(
    name: Optional[str] = None,
    type_: Optional[_TypeEngineArgument[Any]] = None,
    *,
    default: Optional[Any] = None,
    omit_from_statements: bool = True,
) -> MappedColumn[Any]:
    """Provides a surrogate :func:`_orm.mapped_column` that generates
    a so-called :term:`sentinel` column, allowing efficient bulk
    inserts with deterministic RETURNING sorting for tables that don't
    otherwise have qualifying primary key configurations.

    Use of :func:`_orm.orm_insert_sentinel` is analogous to the use of the
    :func:`_schema.insert_sentinel` construct within a Core
    :class:`_schema.Table` construct.

    Guidelines for adding this construct to a Declarative mapped class
    are the same as that of the :func:`_schema.insert_sentinel` construct;
    the database table itself also needs to have a column with this name
    present.

    For background on how this object is used, see the section
    :ref:`engine_insertmanyvalues_sentinel_columns` as part of the
    section :ref:`engine_insertmanyvalues`.

    .. seealso::

        :func:`_schema.insert_sentinel`

        :ref:`engine_insertmanyvalues`

        :ref:`engine_insertmanyvalues_sentinel_columns`


    .. versionadded:: 2.0.10

    """

    return mapped_column(
        name=name,
        default=(
            default if default is not None else _InsertSentinelColumnDefault()
        ),
        _omit_from_statements=omit_from_statements,
        insert_sentinel=True,
        use_existing_column=True,
        nullable=True,
    )


@util.deprecated_params(