Function insert_sentinel

lib/sqlalchemy/sql/schema.py:2705–2752

Provides a surrogate :class:`_schema.Column` that will act as a dedicated insert :term:`sentinel` column, allowing efficient bulk inserts with deterministic RETURNING sorting for tables that don't otherwise have qualifying primary key configurations. Adding this column to a :class:`

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

def insert_sentinel(
    name: Optional[str] = None,
    type_: Optional[_TypeEngineArgument[_T]] = None,
    *,
    default: Optional[Any] = None,
    omit_from_statements: bool = True,
) -> Column[Any]:
    """Provides a surrogate :class:`_schema.Column` that will act as a
    dedicated insert :term:`sentinel` column, allowing efficient bulk
    inserts with deterministic RETURNING sorting for tables that
    don't otherwise have qualifying primary key configurations.

    Adding this column to a :class:`.Table` object requires that a
    corresponding database table actually has this column present, so if adding
    it to an existing model, existing database tables would need to be migrated
    (e.g. using ALTER TABLE or similar) to include this column.

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

    The :class:`_schema.Column` returned will be a nullable integer column by
    default and make use of a sentinel-specific default generator used only in
    "insertmanyvalues" operations.

    .. seealso::

        :func:`_orm.orm_insert_sentinel`

        :paramref:`_schema.Column.insert_sentinel`

        :ref:`engine_insertmanyvalues`

        :ref:`engine_insertmanyvalues_sentinel_columns`


    .. versionadded:: 2.0.10

    """
    return Column(
        name=name,
        type_=type_api.INTEGERTYPE if type_ is None else type_,
        default=(
            default if default is not None else _InsertSentinelColumnDefault()
        ),
        _omit_from_statements=omit_from_statements,
        insert_sentinel=True,
    )


class ForeignKey(DialectKWArgs, SchemaItem):