sqlalchemy.sql.base.Executable

class documentation

class Executable(roles.StatementRole): (source)

Known subclasses: sqlalchemy.orm.query.Query, sqlalchemy.sql.ddl.ExecutableDDLElement, sqlalchemy.sql.elements.TextClause, sqlalchemy.sql.functions.FunctionElement, sqlalchemy.sql.lambdas.StatementLambdaElement, sqlalchemy.sql.schema.DefaultGenerator, sqlalchemy.sql.selectable.ExecutableReturnsRows, sqlalchemy.sql.elements._IdentifiedClause

View In Hierarchy

Mark a :class:`_expression.ClauseElement` as supporting execution. :class:`.Executable` is a superclass for all "statement" types of objects, including :func:`select`, :func:`delete`, :func:`update`, :func:`insert`, :func:`text`.

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.
Class Variable __visit_name__ Undocumented
Class Variable is_delete Undocumented
Class Variable is_dml 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
Method _add_context_option Add a context option to this statement.
Method _compile_w_cache Undocumented
Method _execute_on_connection Undocumented
Method _execute_on_scalar Undocumented
Method _set_compile_options Assign the compile options to a new value.
Method _update_compile_options update the _compile_options with new keys.
Class Variable _executable_traverse_internals Undocumented
Class Variable _is_default_generator Undocumented
Class Variable _with_context_options Undocumented
Class Variable _with_options Undocumented
Instance Variable _compile_options Undocumented
Instance Variable _execution_options Undocumented
Property _all_selected_columns Undocumented
Property _effective_plugin_target Undocumented

Inherited from StatementRole:

Class Variable __slots__ Undocumented
Class Variable _role_name Undocumented
Property _propagate_attrs Undocumented

Inherited from SQLRole (via StatementRole):

Class Variable allows_lambda Undocumented
Class Variable uses_inspection Undocumented
@overload
def execution_options(self, *, compiled_cache: Optional[CompiledCacheType] = ..., logging_token: str = ..., isolation_level: IsolationLevel = ..., no_parameters: bool = False, stream_results: bool = False, max_row_buffer: int = ..., yield_per: int = ..., insertmanyvalues_page_size: int = ..., schema_translate_map: Optional[SchemaTranslateMapType] = ..., populate_existing: bool = False, autoflush: bool = False, synchronize_session: SynchronizeSessionArgument = ..., dml_strategy: DMLStrategyArgument = ..., is_delete_using: bool = ..., is_update_from: bool = ..., **opt: Any) -> Self:
@overload
def execution_options(self, **opt: Any) -> Self:
@_generative
(source)
overridden in sqlalchemy.orm.query.Query

Set non-SQL options for the statement which take effect during execution. Execution options can be set at many scopes, including per-statement, per-connection, or per execution, using methods such as :meth:`_engine.Connection.execution_options` and parameters which accept a dictionary of options such as :paramref:`_engine.Connection.execute.execution_options` and :paramref:`_orm.Session.execute.execution_options`. The primary characteristic of an execution option, as opposed to other kinds of options such as ORM loader options, is that **execution options never affect the compiled SQL of a query, only things that affect how the SQL statement itself is invoked or how results are fetched**. That is, execution options are not part of what's accommodated by SQL compilation nor are they considered part of the cached state of a statement. The :meth:`_sql.Executable.execution_options` method is :term:`generative`, as is the case for the method as applied to the :class:`_engine.Engine` and :class:`_orm.Query` objects, which means when the method is called, a copy of the object is returned, which applies the given parameters to that new copy, but leaves the original unchanged:: statement = select(table.c.x, table.c.y) new_statement = statement.execution_options(my_option=True) An exception to this behavior is the :class:`_engine.Connection` object, where the :meth:`_engine.Connection.execution_options` method is explicitly **not** generative. The kinds of options that may be passed to :meth:`_sql.Executable.execution_options` and other related methods and parameter dictionaries include parameters that are explicitly consumed by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not defined by SQLAlchemy, which means the methods and/or parameter dictionaries may be used for user-defined parameters that interact with custom code, which may access the parameters using methods such as :meth:`_sql.Executable.get_execution_options` and :meth:`_engine.Connection.get_execution_options`, or within selected event hooks using a dedicated ``execution_options`` event parameter such as :paramref:`_events.ConnectionEvents.before_execute.execution_options` or :attr:`_orm.ORMExecuteState.execution_options`, e.g.:: from sqlalchemy import event @event.listens_for(some_engine, "before_execute") def _process_opt(conn, statement, multiparams, params, execution_options): "run a SQL function before invoking a statement" if execution_options.get("do_special_thing", False): conn.exec_driver_sql("run_special_function()") Within the scope of options that are explicitly recognized by SQLAlchemy, most apply to specific classes of objects and not others. The most common execution options include: * :paramref:`_engine.Connection.execution_options.isolation_level` - sets the isolation level for a connection or a class of connections via an :class:`_engine.Engine`. This option is accepted only by :class:`_engine.Connection` or :class:`_engine.Engine`. * :paramref:`_engine.Connection.execution_options.stream_results` - indicates results should be fetched using a server side cursor; this option is accepted by :class:`_engine.Connection`, by the :paramref:`_engine.Connection.execute.execution_options` parameter on :meth:`_engine.Connection.execute`, and additionally by :meth:`_sql.Executable.execution_options` on a SQL statement object, as well as by ORM constructs like :meth:`_orm.Session.execute`. * :paramref:`_engine.Connection.execution_options.compiled_cache` - indicates a dictionary that will serve as the :ref:`SQL compilation cache <sql_caching>` for a :class:`_engine.Connection` or :class:`_engine.Engine`, as well as for ORM methods like :meth:`_orm.Session.execute`. Can be passed as ``None`` to disable caching for statements. This option is not accepted by :meth:`_sql.Executable.execution_options` as it is inadvisable to carry along a compilation cache within a statement object. * :paramref:`_engine.Connection.execution_options.schema_translate_map` - a mapping of schema names used by the :ref:`Schema Translate Map <schema_translating>` feature, accepted by :class:`_engine.Connection`, :class:`_engine.Engine`, :class:`_sql.Executable`, as well as by ORM constructs like :meth:`_orm.Session.execute`. .. seealso:: :meth:`_engine.Connection.execution_options` :paramref:`_engine.Connection.execute.execution_options` :paramref:`_orm.Session.execute.execution_options` :ref:`orm_queryguide_execution_options` - documentation on all ORM-specific execution options

def get_execution_options(self) -> _ExecuteOptions: (source)
overridden in sqlalchemy.orm.query.Query

Get the non-SQL options which will take effect during execution. .. versionadded:: 1.3 .. seealso:: :meth:`.Executable.execution_options`

@_generative
def options(self, *options: ExecutableOption) -> Self: (source)
overridden in sqlalchemy.orm.query.Query

Apply options to this statement. In the general sense, options are any kind of Python object that can be interpreted by the SQL compiler for the statement. These options can be consumed by specific dialects or specific kinds of compilers. The most commonly known kind of option are the ORM level options that apply "eager load" and other loading behaviors to an ORM query. However, options can theoretically be used for many other purposes. For background on specific kinds of options for specific kinds of statements, refer to the documentation for those option objects. .. versionchanged:: 1.4 - added :meth:`.Executable.options` to Core statement objects towards the goal of allowing unified Core / ORM querying capabilities. .. seealso:: :ref:`loading_columns` - refers to options specific to the usage of ORM queries :ref:`relationship_loader_options` - refers to options specific to the usage of ORM queries

__visit_name__: str = (source)
overridden in sqlalchemy.dialects.postgresql.CreateDomainType, sqlalchemy.dialects.postgresql.CreateEnumType, sqlalchemy.dialects.postgresql.DropDomainType, sqlalchemy.dialects.postgresql.DropEnumType, sqlalchemy.orm.context.FromStatement, sqlalchemy.sql.ddl.AddConstraint, sqlalchemy.sql.ddl.CreateIndex, sqlalchemy.sql.ddl.CreateSchema, sqlalchemy.sql.ddl.CreateSequence, sqlalchemy.sql.ddl.CreateTable, sqlalchemy.sql.ddl.DDL, sqlalchemy.sql.ddl.DropColumnComment, sqlalchemy.sql.ddl.DropConstraint, sqlalchemy.sql.ddl.DropConstraintComment, sqlalchemy.sql.ddl.DropIndex, sqlalchemy.sql.ddl.DropSchema, sqlalchemy.sql.ddl.DropSequence, sqlalchemy.sql.ddl.DropTable, sqlalchemy.sql.ddl.DropTableComment, sqlalchemy.sql.ddl.SetColumnComment, sqlalchemy.sql.ddl.SetConstraintComment, sqlalchemy.sql.ddl.SetTableComment, sqlalchemy.sql.dml.UpdateBase, sqlalchemy.sql.elements.TextClause, sqlalchemy.sql.functions.Function, sqlalchemy.sql.schema.DefaultGenerator, sqlalchemy.sql.selectable.CompoundSelect, sqlalchemy.sql.selectable.Select, sqlalchemy.sql.selectable.TextualSelect, sqlalchemy.sql.ddl._DropView, sqlalchemy.sql.elements._IdentifiedClause

Undocumented

is_delete: bool = (source)
overridden in sqlalchemy.sql.dml.Delete, sqlalchemy.sql.lambdas.StatementLambdaElement

Undocumented

is_dml: bool = (source)
overridden in sqlalchemy.orm.context.FromStatement, sqlalchemy.sql.dml.UpdateBase, sqlalchemy.sql.lambdas.StatementLambdaElement

Undocumented

is_insert: bool = (source)
overridden in sqlalchemy.sql.dml.Insert, sqlalchemy.sql.lambdas.StatementLambdaElement

Undocumented

is_select: bool = (source)
overridden in sqlalchemy.sql.lambdas.StatementLambdaElement, sqlalchemy.sql.selectable.TextualSelect

Undocumented

is_text: bool = (source)
overridden in sqlalchemy.sql.lambdas.StatementLambdaElement, sqlalchemy.sql.selectable.TextualSelect

Undocumented

is_update: bool = (source)
overridden in sqlalchemy.sql.dml.Update, sqlalchemy.sql.lambdas.StatementLambdaElement

Undocumented

supports_execution: bool = (source)

Undocumented

@_generative
def _add_context_option(self, callable_: Callable[[CompileState], None], cache_args: Any) -> Self: (source)

Add a context option to this statement. These are callable functions that will be given the CompileState object upon compilation. A second argument cache_args is required, which will be combined with the ``__code__`` identity of the function itself in order to produce a cache key.

def _compile_w_cache(self, dialect: Dialect, *, compiled_cache: Optional[CompiledCacheType], column_keys: List[str], for_executemany: bool = False, schema_translate_map: Optional[SchemaTranslateMapType] = None, **kw: Any) -> Tuple[Compiled, Optional[Sequence[BindParameter[Any]]], CacheStats]: (source)

Undocumented

def _execute_on_connection(self, connection: Connection, distilled_params: _CoreMultiExecuteParams, execution_options: CoreExecuteOptionsParameter) -> CursorResult[Any]: (source)
overridden in sqlalchemy.sql.ddl.ExecutableDDLElement, sqlalchemy.sql.functions.FunctionElement, sqlalchemy.sql.lambdas.StatementLambdaElement, sqlalchemy.sql.schema.DefaultGenerator

Undocumented

def _execute_on_scalar(self, connection: Connection, distilled_params: _CoreMultiExecuteParams, execution_options: CoreExecuteOptionsParameter) -> Any: (source)
overridden in sqlalchemy.sql.schema.DefaultGenerator

Undocumented

@_generative
def _set_compile_options(self, compile_options: CacheableOptions) -> Self: (source)

Assign the compile options to a new value. :param compile_options: appropriate CacheableOptions structure

@_generative
def _update_compile_options(self, options: CacheableOptions) -> Self: (source)

update the _compile_options with new keys.

_executable_traverse_internals = (source)

Undocumented

_is_default_generator: bool = (source)
overridden in sqlalchemy.sql.schema.DefaultGenerator

Undocumented

_with_context_options: Tuple[Tuple[Callable[[CompileState], None], Any], ...] = (source)

Undocumented

_with_options: Tuple[ExecutableOption, ...] = (source)
overridden in sqlalchemy.orm.query.Query, sqlalchemy.sql.lambdas.StatementLambdaElement

Undocumented

_compile_options = (source)

Undocumented

_execution_options = (source)
overridden in sqlalchemy.orm.query.Query, sqlalchemy.sql.lambdas.StatementLambdaElement

Undocumented

@util.ro_non_memoized_property
_all_selected_columns = (source)
overridden in sqlalchemy.orm.context.FromStatement, sqlalchemy.sql.dml.UpdateBase, sqlalchemy.sql.functions.FunctionElement, sqlalchemy.sql.lambdas.StatementLambdaElement, sqlalchemy.sql.selectable.CompoundSelect, sqlalchemy.sql.selectable.Select, sqlalchemy.sql.selectable.TextualSelect

Undocumented

@property
_effective_plugin_target: str = (source)
overridden in sqlalchemy.sql.lambdas.StatementLambdaElement

Undocumented