class documentation

class UpdateBase(roles.DMLRole, HasCTE, HasCompileState, DialectKWArgs, HasPrefixes, ReturnsRows, Executable, ClauseElement):

Known subclasses: sqlalchemy.sql.dml.ValuesBase, sqlalchemy.sql.expression.Delete

View In Hierarchy

Form the base for INSERT, UPDATE, and DELETE statements.
Class Method ​_constructor​_20​_deprecations Undocumented
Method ​_generate​_fromclause​_column​_proxies Undocumented
Method ​_set​_bind Undocumented
Method ​_validate​_dialect​_kwargs​_deprecated Undocumented
Method bind Return a 'bind' linked to this .UpdateBase or a _schema.Table associated with it.
Method params Set the parameters for the statement.
Method returning Add a :term:`RETURNING` or equivalent clause to this statement.
Method with​_dialect​_options Add dialect options to this INSERT/UPDATE/DELETE object.
Method with​_hint Add a table hint for a single table to this INSERT/UPDATE/DELETE statement.
Class Variable __visit​_name__ Undocumented
Class Variable ​_execution​_options Undocumented
Class Variable ​_return​_defaults Undocumented
Class Variable ​_return​_defaults​_columns Undocumented
Class Variable ​_returning Undocumented
Class Variable is​_dml Undocumented
Class Variable named​_with​_column Undocumented
Instance Variable ​_bind Undocumented
Instance Variable ​_hints Undocumented
Property ​_all​_selected​_columns A sequence of column expression objects that represents the "selected" columns of this _expression.ReturnsRows.
Property exported​_columns Return the RETURNING columns as a column collection for this statement.

Inherited from StatementRole (via DMLRole):

Class Variable ​_propagate​_attrs Undocumented
Class Variable ​_role​_name Undocumented

Inherited from SQLRole (via DMLRole, StatementRole):

Class Variable allows​_lambda Undocumented
Class Variable uses​_inspection Undocumented

Inherited from HasCTE:

Method add​_cte Add a _sql.CTE to this statement object that will be independently rendered even if not referenced in the statement otherwise.
Method cte Return a new _expression.CTE, or Common Table Expression instance.
Class Variable ​_has​_ctes​_traverse​_internals Undocumented
Class Variable ​_independent​_ctes Undocumented

Inherited from ReturnsRowsRole (via HasCTE, HasCTERole):

Class Variable ​_role​_name Undocumented

Inherited from SQLRole (via HasCTE, HasCTERole, ReturnsRowsRole):

Class Variable allows​_lambda Undocumented
Class Variable uses​_inspection Undocumented

Inherited from HasCompileState:

Class Variable ​_attributes Undocumented
Class Variable ​_compile​_state​_plugin Undocumented

Inherited from Generative (via HasCompileState):

Method ​_generate Undocumented

Inherited from DialectKWArgs:

Class Method argument​_for Add a new kind of dialect-specific keyword argument for this class.
Method ​_kw​_reg​_for​_dialect​_cls Undocumented
Method ​_validate​_dialect​_kwargs Undocumented
Class Variable ​_dialect​_kwargs​_traverse​_internals Undocumented
Class Variable ​_kw​_registry Undocumented
Property dialect​_kwargs A collection of keyword arguments specified as dialect-specific options to this construct.
Property dialect​_options A collection of keyword arguments specified as dialect-specific options to this construct.
Property kwargs A synonym for .DialectKWArgs.dialect_kwargs.

Inherited from HasPrefixes:

Method ​_setup​_prefixes Undocumented
Method prefix​_with Add one or more expressions following the statement keyword, i.e. SELECT, INSERT, UPDATE, or DELETE. Generative.
Class Variable ​_has​_prefixes​_traverse​_internals Undocumented
Instance Variable ​_prefixes Undocumented

Inherited from ReturnsRows:

Class Variable ​_is​_from​_clause Undocumented
Class Variable ​_is​_lateral Undocumented
Class Variable ​_is​_returns​_rows Undocumented
Class Variable ​_is​_select​_statement Undocumented
Property selectable Undocumented

Inherited from ReturnsRowsRole (via ReturnsRows):

Class Variable ​_role​_name Undocumented

Inherited from SQLRole (via ReturnsRows, ReturnsRowsRole):

Class Variable allows​_lambda Undocumented
Class Variable uses​_inspection Undocumented

Inherited from ClauseElement (via ReturnsRows):

Method compare Compare this _expression.ClauseElement to the given _expression.ClauseElement.
Method compile Compile this SQL expression.
Method self​_group Apply a 'grouping' to this _expression.ClauseElement.
Method unique​_params Return a copy with _expression.bindparam elements replaced.
Method __bool__ Undocumented
Method __getstate__ Undocumented
Method __invert__ Undocumented
Method __repr__ Undocumented
Method __str__ Undocumented
Method ​_clone Create a shallow copy of this ClauseElement.
Method ​_cloned​_set Return the set consisting all cloned ancestors of this ClauseElement.
Method ​_compile​_w​_cache Undocumented
Method ​_compiler Return a compiler appropriate for this ClauseElement, given a Dialect.
Method ​_execute​_on​_connection Undocumented
Method ​_negate Undocumented
Method ​_negate​_in​_binary a hook to allow the right side of a binary expression to respond to a negation of the binary expression.
Method ​_replace​_params Undocumented
Method ​_set​_propagate​_attrs Undocumented
Method ​_ungroup Return this _expression.ClauseElement without any groupings.
Method ​_with​_binary​_element​_type in the context of binary expression, convert the type of this object to the one given.
Class Variable ​_cache​_key​_traversal Undocumented
Class Variable ​_from​_objects Undocumented
Class Variable ​_is​_bind​_parameter Undocumented
Class Variable ​_is​_clause​_list Undocumented
Class Variable ​_is​_clone​_of Undocumented
Class Variable ​_is​_from​_container Undocumented
Class Variable ​_is​_immutable Undocumented
Class Variable ​_is​_lambda​_element Undocumented
Class Variable ​_is​_select​_container Undocumented
Class Variable ​_is​_singleton​_constant Undocumented
Class Variable ​_is​_text​_clause Undocumented
Class Variable ​_is​_textual Undocumented
Class Variable ​_order​_by​_label​_element Undocumented
Class Variable description Undocumented
Class Variable is​_clause​_element Undocumented
Class Variable is​_selectable Undocumented
Class Variable stringify​_dialect Undocumented
Class Variable supports​_execution Undocumented
Instance Variable ​_propagate​_attrs like annotations, however these propagate outwards liberally as SQL constructs are built, and are set up at construction time.
Property ​_constructor return the 'constructor' for this ClauseElement.
Property entity​_namespace Undocumented

Inherited from SQLRole (via ReturnsRows, ClauseElement):

Class Variable allows​_lambda Undocumented
Class Variable uses​_inspection Undocumented

Inherited from SupportsWrappingAnnotations (via ReturnsRows, ClauseElement):

Method ​_annotate return a copy of this ClauseElement with annotations updated by the given dictionary.
Method ​_deannotate return a copy of this _expression.ClauseElement with annotations removed.
Method ​_with​_annotations return a copy of this ClauseElement with annotations replaced by the given dictionary.

Inherited from SupportsAnnotations (via ReturnsRows, ClauseElement, SupportsWrappingAnnotations):

Property ​_annotations​_cache​_key Undocumented

Inherited from MemoizedHasCacheKey (via ReturnsRows, ClauseElement):

Method ​_generate​_cache​_key return a cache key.

Inherited from HasCacheKey (via ReturnsRows, ClauseElement, MemoizedHasCacheKey):

Class Variable inherit​_cache Indicate if this .HasCacheKey instance should make use of the cache key generation scheme used by its immediate superclass.
Class Method ​_generate​_cache​_attrs generate cache key dispatcher for a new class.
Class Method ​_generate​_cache​_key​_for​_object Undocumented
Method ​_gen​_cache​_key return an optional cache key.
Class Variable __slots__ Undocumented
Class Variable ​_hierarchy​_supports​_caching private attribute which may be set to False to prevent the inherit_cache warning from being emitted for a hierarchy of subclasses.
Class Variable ​_is​_has​_cache​_key Undocumented

Inherited from HasCopyInternals (via ReturnsRows, ClauseElement):

Method ​_copy​_internals Reassign internal elements to be clones of themselves.

Inherited from Traversible (via ReturnsRows, ClauseElement):

Method get​_children Return immediate child .visitors.Traversible elements of this .visitors.Traversible.
Method __class​_getitem__ Undocumented

Inherited from Executable:

Method ​_add​_context​_option Add a context option to this statement.
Method ​_set​_compile​_options Assign the compile options to a new value.
Method ​_update​_compile​_options update the _compile_options with new keys.
Method execute Compile and execute this .Executable.
Method execution​_options Set non-SQL options for the statement which take effect during execution.
Method get​_execution​_options Get the non-SQL options which will take effect during execution.
Method options Apply options to this statement.
Method scalar Compile and execute this .Executable, returning the result's scalar representation.
Class Variable ​_executable​_traverse​_internals Undocumented
Class Variable ​_with​_context​_options Undocumented
Class Variable ​_with​_options Undocumented
Class Variable is​_delete Undocumented
Class Variable is​_insert Undocumented
Class Variable is​_select Undocumented
Class Variable is​_text Undocumented
Class Variable is​_update Undocumented
Class Variable supports​_execution Undocumented
Instance Variable ​_compile​_options Undocumented
Property ​_effective​_plugin​_target Undocumented

Inherited from StatementRole (via Executable):

Class Variable ​_propagate​_attrs Undocumented
Class Variable ​_role​_name Undocumented

Inherited from SQLRole (via Executable, StatementRole):

Class Variable allows​_lambda Undocumented
Class Variable uses​_inspection Undocumented

Inherited from Generative (via Executable):

Method ​_generate Undocumented

Inherited from ClauseElement:

Method compare Compare this _expression.ClauseElement to the given _expression.ClauseElement.
Method compile Compile this SQL expression.
Method self​_group Apply a 'grouping' to this _expression.ClauseElement.
Method unique​_params Return a copy with _expression.bindparam elements replaced.
Method __bool__ Undocumented
Method __getstate__ Undocumented
Method __invert__ Undocumented
Method __repr__ Undocumented
Method __str__ Undocumented
Method ​_clone Create a shallow copy of this ClauseElement.
Method ​_cloned​_set Return the set consisting all cloned ancestors of this ClauseElement.
Method ​_compile​_w​_cache Undocumented
Method ​_compiler Return a compiler appropriate for this ClauseElement, given a Dialect.
Method ​_execute​_on​_connection Undocumented
Method ​_negate Undocumented
Method ​_negate​_in​_binary a hook to allow the right side of a binary expression to respond to a negation of the binary expression.
Method ​_replace​_params Undocumented
Method ​_set​_propagate​_attrs Undocumented
Method ​_ungroup Return this _expression.ClauseElement without any groupings.
Method ​_with​_binary​_element​_type in the context of binary expression, convert the type of this object to the one given.
Class Variable ​_cache​_key​_traversal Undocumented
Class Variable ​_from​_objects Undocumented
Class Variable ​_is​_bind​_parameter Undocumented
Class Variable ​_is​_clause​_list Undocumented
Class Variable ​_is​_clone​_of Undocumented
Class Variable ​_is​_from​_clause Undocumented
Class Variable ​_is​_from​_container Undocumented
Class Variable ​_is​_immutable Undocumented
Class Variable ​_is​_lambda​_element Undocumented
Class Variable ​_is​_returns​_rows Undocumented
Class Variable ​_is​_select​_container Undocumented
Class Variable ​_is​_select​_statement Undocumented
Class Variable ​_is​_singleton​_constant Undocumented
Class Variable ​_is​_text​_clause Undocumented
Class Variable ​_is​_textual Undocumented
Class Variable ​_order​_by​_label​_element Undocumented
Class Variable description Undocumented
Class Variable is​_clause​_element Undocumented
Class Variable is​_selectable Undocumented
Class Variable stringify​_dialect Undocumented
Class Variable supports​_execution Undocumented
Instance Variable ​_propagate​_attrs like annotations, however these propagate outwards liberally as SQL constructs are built, and are set up at construction time.
Property ​_constructor return the 'constructor' for this ClauseElement.
Property entity​_namespace Undocumented

Inherited from SQLRole (via ClauseElement):

Class Variable allows​_lambda Undocumented
Class Variable uses​_inspection Undocumented

Inherited from SupportsWrappingAnnotations (via ClauseElement):

Method ​_annotate return a copy of this ClauseElement with annotations updated by the given dictionary.
Method ​_deannotate return a copy of this _expression.ClauseElement with annotations removed.
Method ​_with​_annotations return a copy of this ClauseElement with annotations replaced by the given dictionary.

Inherited from SupportsAnnotations (via ClauseElement, SupportsWrappingAnnotations):

Property ​_annotations​_cache​_key Undocumented

Inherited from MemoizedHasCacheKey (via ClauseElement):

Method ​_generate​_cache​_key return a cache key.

Inherited from HasCacheKey (via ClauseElement, MemoizedHasCacheKey):

Class Variable inherit​_cache Indicate if this .HasCacheKey instance should make use of the cache key generation scheme used by its immediate superclass.
Class Method ​_generate​_cache​_attrs generate cache key dispatcher for a new class.
Class Method ​_generate​_cache​_key​_for​_object Undocumented
Method ​_gen​_cache​_key return an optional cache key.
Class Variable __slots__ Undocumented
Class Variable ​_hierarchy​_supports​_caching private attribute which may be set to False to prevent the inherit_cache warning from being emitted for a hierarchy of subclasses.
Class Variable ​_is​_has​_cache​_key Undocumented

Inherited from HasCopyInternals (via ClauseElement):

Method ​_copy​_internals Reassign internal elements to be clones of themselves.

Inherited from Traversible (via ClauseElement):

Method get​_children Return immediate child .visitors.Traversible elements of this .visitors.Traversible.
Method __class​_getitem__ Undocumented
@classmethod
def _constructor_20_deprecations(cls, fn_name, clsname, names):

Undocumented

def _generate_fromclause_column_proxies(self, fromclause):

Undocumented

def _set_bind(self, bind):

Undocumented

def _validate_dialect_kwargs_deprecated(self, dialect_kw):

Undocumented

def bind(self):
Return a 'bind' linked to this .UpdateBase or a _schema.Table associated with it.
def params(self, *arg, **kw):

Set the parameters for the statement.

This method raises NotImplementedError on the base class, and is overridden by .ValuesBase to provide the SET/VALUES clause of UPDATE and INSERT.

@_generative
def returning(self, *cols):

Add a :term:`RETURNING` or equivalent clause to this statement.

e.g.:

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)
UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

The method may be invoked multiple times to add new entries to the list of expressions to be returned.

New in version 1.4.0b2: The method may be invoked multiple times to add new entries to the list of expressions to be returned.

The given collection of column expressions should be derived from the table that is the target of the INSERT, UPDATE, or DELETE. While _schema.Column objects are typical, the elements can also be expressions:

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)
INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

Upon compilation, a RETURNING clause, or database equivalent, will be rendered within the statement. For INSERT and UPDATE, the values are the newly inserted/updated values. For DELETE, the values are those of the rows which were deleted.

Upon execution, the values of the columns to be returned are made available via the result set and can be iterated using _engine.CursorResult.fetchone and similar. For DBAPIs which do not natively support returning values (i.e. cx_oracle), SQLAlchemy will approximate this behavior at the result level so that a reasonable amount of behavioral neutrality is provided.

Note that not all databases/DBAPIs support RETURNING. For those backends with no support, an exception is raised upon compilation and/or execution. For those who do support it, the functionality across backends varies greatly, including restrictions on executemany() and other statements which return multiple rows. Please read the documentation notes for the database in use in order to determine the availability of RETURNING.

See Also

.ValuesBase.return_defaults - an alternative method tailored towards efficient fetching of server-side defaults and triggers for single-row INSERTs or UPDATEs.

:ref:`tutorial_insert_returning` - in the :ref:`unified_tutorial`

@_generative
def with_dialect_options(self, **opt):

Add dialect options to this INSERT/UPDATE/DELETE object.

e.g.:

upd = table.update().dialect_options(mysql_limit=10)
@_generative
def with_hint(self, text, selectable=None, dialect_name='*'):

Add a table hint for a single table to this INSERT/UPDATE/DELETE statement.

Note

.UpdateBase.with_hint currently applies only to Microsoft SQL Server. For MySQL INSERT/UPDATE/DELETE hints, use .UpdateBase.prefix_with.

The text of the hint is rendered in the appropriate location for the database backend in use, relative to the _schema.Table that is the subject of this statement, or optionally to that of the given _schema.Table passed as the selectable argument.

The dialect_name option will limit the rendering of a particular hint to a particular backend. Such as, to add a hint that only takes effect for SQL Server:

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
Parameters
textText of the hint.
selectableoptional _schema.Table that specifies an element of the FROM clause within an UPDATE or DELETE to be the subject of the hint - applies only to certain backends.
dialect​_namedefaults to *, if specified as the name of a particular dialect, will apply these hints only when that dialect is in use.
_execution_options =
_return_defaults: bool =

Undocumented

_return_defaults_columns =

Undocumented

_returning: tuple =
is_dml: bool =

Undocumented

named_with_column: bool =

Undocumented

_hints =

Undocumented

@property
_all_selected_columns =

A sequence of column expression objects that represents the "selected" columns of this _expression.ReturnsRows.

This is typically equivalent to .exported_columns except it is delivered in the form of a straight sequence and not keyed _expression.ColumnCollection.

@property
exported_columns =

Return the RETURNING columns as a column collection for this statement.

New in version 1.4.