sqlalchemy.sql.selectable.SelectBase

class documentation

class SelectBase(roles.SelectStatementRole, roles.DMLSelectRole, roles.CompoundElementRole, roles.InElementRole, HasCTE, SupportsCloneAnnotations, Selectable): (source)

Known subclasses: sqlalchemy.sql.selectable.GenerativeSelect, sqlalchemy.sql.selectable.SelectStatementGrouping, sqlalchemy.sql.selectable.TextualSelect

View In Hierarchy

Base class for SELECT statements. This includes :class:`_expression.Select`, :class:`_expression.CompoundSelect` and :class:`_expression.TextualSelect`.

Method alias Return a named subquery against this :class:`_expression.SelectBase`.
Method as_scalar Undocumented
Method exists Return an :class:`_sql.Exists` representation of this selectable, which can be used as a column expression.
Method get_label_style Retrieve the current label style.
Method label Return a 'scalar' representation of this selectable, embedded as a subquery with a label.
Method lateral Return a LATERAL alias of this :class:`_expression.Selectable`.
Method scalar_subquery Return a 'scalar' representation of this selectable, which can be used as a column expression.
Method select Undocumented
Method set_label_style Return a new selectable with the specified label style.
Method subquery Return a subquery of this :class:`_expression.SelectBase`.
Class Variable is_select Undocumented
Property c Undocumented
Property columns Undocumented
Property exported_columns A :class:`_expression.ColumnCollection` that represents the "exported" columns of this :class:`_expression.Selectable`, not including :class:`_sql.TextClause` constructs.
Property selected_columns A :class:`_expression.ColumnCollection` representing the columns that this SELECT statement or similar construct returns in its result set.
Method _ensure_disambiguated_names Ensure that the names generated by this selectbase will be disambiguated in some way, if possible.
Method _generate_fromclause_column_proxies Populate columns into an :class:`.AliasedReturnsRows` object.
Method _implicit_subquery Undocumented
Method _refresh_for_new_column reset internal collections for an incoming column being added.
Method _scalar_type Undocumented
Class Variable _is_select_base Undocumented
Property _all_selected_columns A sequence of expressions that correspond to what is rendered in the columns clause, including :class:`_sql.TextClause` constructs.

Inherited from SelectStatementRole:

Class Variable __slots__ Undocumented
Class Variable _role_name Undocumented

Inherited from StatementRole (via SelectStatementRole):

Property _propagate_attrs Undocumented

Inherited from AllowsLambdaRole (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole):

Class Variable allows_lambda Undocumented

Inherited from HasCTE (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole):

Method add_cte Add one or more :class:`_sql.CTE` constructs to this statement.
Method cte Return a new :class:`_expression.CTE`, or Common Table Expression instance.
Class Variable _has_ctes_traverse_internals Undocumented
Class Variable _independent_ctes Undocumented
Class Variable _independent_ctes_opts Undocumented

Inherited from SelectsRows (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole):

Method _generate_columns_plus_names Generate column names as rendered in a SELECT statement by the compiler.

Inherited from SupportsCloneAnnotations (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows):

Method _annotate return a copy of this ClauseElement with annotations updated by the given dictionary.
Method _deannotate return a copy of this :class:`_expression.ClauseElement` with annotations removed.
Method _with_annotations return a copy of this ClauseElement with annotations replaced by the given dictionary.
Class Variable _clone_annotations_traverse_internals Undocumented

Inherited from Selectable (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations):

Method corresponding_column Given a :class:`_expression.ColumnElement`, return the exported :class:`_expression.ColumnElement` object from the :attr:`_expression.Selectable.exported_columns` collection of this :class:`_expression...
Method replace_selectable Replace all occurrences of :class:`_expression.FromClause` 'old' with the given :class:`_expression.Alias` object, returning a copy of this :class:`_expression.FromClause`.
Class Variable __visit_name__ Undocumented
Class Variable is_selectable Undocumented

Inherited from ReturnsRows (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable):

Method is_derived_from Return ``True`` if this :class:`.ReturnsRows` is 'derived' from the given :class:`.FromClause`.
Property selectable Undocumented
Class Variable _is_from_clause Undocumented
Class Variable _is_lateral Undocumented
Class Variable _is_returns_rows Undocumented
Class Variable _is_select_statement Undocumented

Inherited from SQLRole (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable, ReturnsRows, ReturnsRowsRole):

Class Variable uses_inspection Undocumented

Inherited from DQLDMLClauseElement (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable, ReturnsRows, ReturnsRowsRole, SQLRole):

Method compile Compile this SQL expression.
Method _compiler Return a compiler appropriate for this ClauseElement, given a Dialect.

Inherited from ClauseElement (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable, ReturnsRows, ReturnsRowsRole, SQLRole, DQLDMLClauseElement):

Method __bool__ Undocumented
Method __getstate__ Undocumented
Method __invert__ Undocumented
Method __repr__ Undocumented
Method compare Compare this :class:`_expression.ClauseElement` to the given :class:`_expression.ClauseElement`.
Method get_children Return immediate child :class:`.visitors.HasTraverseInternals` elements of this :class:`.visitors.HasTraverseInternals`.
Method params Return a copy with :func:`_expression.bindparam` elements replaced.
Method self_group Apply a 'grouping' to this :class:`_expression.ClauseElement`.
Method unique_params Return a copy with :func:`_expression.bindparam` elements replaced.
Class Variable is_clause_element Undocumented
Class Variable is_dml Undocumented
Class Variable negation_clause Undocumented
Property description Undocumented
Property entity_namespace 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 _execute_on_connection Undocumented
Method _execute_on_scalar an additional hook for subclasses to provide a different implementation for connection.scalar() vs. connection.execute().
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 :class:`_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 _gen_static_annotations_cache_key Undocumented
Class Variable _is_bind_parameter Undocumented
Class Variable _is_clause_list Undocumented
Class Variable _is_clone_of Undocumented
Class Variable _is_column_element Undocumented
Class Variable _is_from_container Undocumented
Class Variable _is_immutable Undocumented
Class Variable _is_keyed_column_element Undocumented
Class Variable _is_lambda_element Undocumented
Class Variable _is_select_container Undocumented
Class Variable _is_singleton_constant Undocumented
Class Variable _is_star Undocumented
Class Variable _is_table Undocumented
Class Variable _is_text_clause Undocumented
Class Variable _is_textual Undocumented
Property _constructor return the 'constructor' for this ClauseElement.
Property _from_objects Undocumented
Property _order_by_label_element Undocumented

Inherited from SupportsAnnotations (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable, ReturnsRows, ReturnsRowsRole, SQLRole, DQLDMLClauseElement, ClauseElement, SupportsWrappingAnnotations):

Class Variable proxy_set Undocumented
Method _gen_annotations_cache_key Undocumented
Property _annotations_cache_key Undocumented

Inherited from MemoizedHasCacheKey (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable, ReturnsRows, ReturnsRowsRole, SQLRole, DQLDMLClauseElement, ClauseElement, SupportsWrappingAnnotations, SupportsAnnotations):

Method _generate_cache_key return a cache key.

Inherited from HasCacheKey (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable, ReturnsRows, ReturnsRowsRole, SQLRole, DQLDMLClauseElement, ClauseElement, SupportsWrappingAnnotations, SupportsAnnotations, MemoizedHasCacheKey):

Class Variable inherit_cache Indicate if this :class:`.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 _generated_cache_key_traversal 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 SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable, ReturnsRows, ReturnsRowsRole, SQLRole, DQLDMLClauseElement, ClauseElement, SupportsWrappingAnnotations, SupportsAnnotations, MemoizedHasCacheKey, HasCacheKey):

Method _copy_internals Reassign internal elements to be clones of themselves.

Inherited from HasTraverseInternals (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable, ReturnsRows, ReturnsRowsRole, SQLRole, DQLDMLClauseElement, ClauseElement, SupportsWrappingAnnotations, SupportsAnnotations, MemoizedHasCacheKey, HasCacheKey, HasCopyInternals, ExternallyTraversible):

Class Variable _traverse_internals Undocumented

Inherited from CompilerElement (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable, ReturnsRows, ReturnsRowsRole, SQLRole, DQLDMLClauseElement, ClauseElement, SupportsWrappingAnnotations, SupportsAnnotations, MemoizedHasCacheKey, HasCacheKey, HasCopyInternals, ExternallyTraversible, HasTraverseInternals):

Method __str__ Undocumented
Class Variable stringify_dialect Undocumented
Class Variable supports_execution Undocumented

Inherited from Visitable (via SelectStatementRole, StatementRole, DMLSelectRole, CompoundElementRole, AllowsLambdaRole, InElementRole, HasCTE, HasCTERole, SelectsRows, SupportsCloneAnnotations, Selectable, ReturnsRows, ReturnsRowsRole, SQLRole, DQLDMLClauseElement, ClauseElement, SupportsWrappingAnnotations, SupportsAnnotations, MemoizedHasCacheKey, HasCacheKey, HasCopyInternals, ExternallyTraversible, HasTraverseInternals, CompilerElement):

Method __class_getitem__ Undocumented
Method __init_subclass__ Undocumented
Class Method _generate_compiler_dispatch Undocumented
Method _compiler_dispatch Undocumented
Class Variable _original_compiler_dispatch Undocumented
def alias(self, name: Optional[str] = None, flat: bool = False) -> Subquery: (source)

Return a named subquery against this :class:`_expression.SelectBase`. For a :class:`_expression.SelectBase` (as opposed to a :class:`_expression.FromClause`), this returns a :class:`.Subquery` object which behaves mostly the same as the :class:`_expression.Alias` object that is used with a :class:`_expression.FromClause`. .. versionchanged:: 1.4 The :meth:`_expression.SelectBase.alias` method is now a synonym for the :meth:`_expression.SelectBase.subquery` method.

@util.deprecated('1.4', 'The :meth:`_expression.SelectBase.as_scalar` method is deprecated and will be removed in a future release. Please refer to :meth:`_expression.SelectBase.scalar_subquery`.')
def as_scalar(self) -> ScalarSelect[Any]: (source)

Undocumented

def exists(self) -> Exists: (source)

Return an :class:`_sql.Exists` representation of this selectable, which can be used as a column expression. The returned object is an instance of :class:`_sql.Exists`. .. seealso:: :func:`_sql.exists` :ref:`tutorial_exists` - in the :term:`2.0 style` tutorial. .. versionadded:: 1.4

def get_label_style(self) -> SelectLabelStyle: (source)
overridden in sqlalchemy.sql.selectable.GenerativeSelect, sqlalchemy.sql.selectable.SelectStatementGrouping

Retrieve the current label style. Implemented by subclasses.

def label(self, name: Optional[str]) -> Label[Any]: (source)

Return a 'scalar' representation of this selectable, embedded as a subquery with a label. .. seealso:: :meth:`_expression.SelectBase.scalar_subquery`.

def lateral(self, name: Optional[str] = None) -> LateralFromClause: (source)
overrides sqlalchemy.sql.selectable.Selectable.lateral

Return a LATERAL alias of this :class:`_expression.Selectable`. The return value is the :class:`_expression.Lateral` construct also provided by the top-level :func:`_expression.lateral` function. .. versionadded:: 1.1 .. seealso:: :ref:`tutorial_lateral_correlation` - overview of usage.

def scalar_subquery(self) -> ScalarSelect[Any]: (source)
overridden in sqlalchemy.sql.selectable.Select

Return a 'scalar' representation of this selectable, which can be used as a column expression. The returned object is an instance of :class:`_sql.ScalarSelect`. Typically, a select statement which has only one column in its columns clause is eligible to be used as a scalar expression. The scalar subquery can then be used in the WHERE clause or columns clause of an enclosing SELECT. Note that the scalar subquery differentiates from the FROM-level subquery that can be produced using the :meth:`_expression.SelectBase.subquery` method. .. versionchanged: 1.4 - the ``.as_scalar()`` method was renamed to :meth:`_expression.SelectBase.scalar_subquery`. .. seealso:: :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial

@util.deprecated('1.4', 'The :meth:`_expression.SelectBase.select` method is deprecated and will be removed in a future release; this method implicitly creates a subquery that should be explicit. Please call :meth:`_expression.SelectBase.subquery` first in order to create a subquery, which then can be selected.')
def select(self, *arg: Any, **kw: Any) -> Select[Any]: (source)

Undocumented

def set_label_style(self, style: SelectLabelStyle) -> Self: (source)
overridden in sqlalchemy.sql.selectable.GenerativeSelect, sqlalchemy.sql.selectable.SelectStatementGrouping, sqlalchemy.sql.selectable.TextualSelect

Return a new selectable with the specified label style. Implemented by subclasses.

def subquery(self, name: Optional[str] = None) -> Subquery: (source)
overrides sqlalchemy.sql.roles.SelectStatementRole.subquery

Return a subquery of this :class:`_expression.SelectBase`. A subquery is from a SQL perspective a parenthesized, named construct that can be placed in the FROM clause of another SELECT statement. Given a SELECT statement such as:: stmt = select(table.c.id, table.c.name) The above statement might look like:: SELECT table.id, table.name FROM table The subquery form by itself renders the same way, however when embedded into the FROM clause of another SELECT statement, it becomes a named sub-element:: subq = stmt.subquery() new_stmt = select(subq) The above renders as:: SELECT anon_1.id, anon_1.name FROM (SELECT table.id, table.name FROM table) AS anon_1 Historically, :meth:`_expression.SelectBase.subquery` is equivalent to calling the :meth:`_expression.FromClause.alias` method on a FROM object; however, as a :class:`_expression.SelectBase` object is not directly FROM object, the :meth:`_expression.SelectBase.subquery` method provides clearer semantics. .. versionadded:: 1.4

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

Undocumented

@property
@util.deprecated('1.4', 'The :attr:`_expression.SelectBase.c` and :attr:`_expression.SelectBase.columns` attributes are deprecated and will be removed in a future release; these attributes implicitly create a subquery that should be explicit. Please call :meth:`_expression.SelectBase.subquery` first in order to create a subquery, which then contains this attribute. To access the columns that this SELECT object SELECTs from, use the :attr:`_expression.SelectBase.selected_columns` attribute.')
c: ReadOnlyColumnCollection[str, KeyedColumnElement[Any]] = (source)

Undocumented

@property
columns: ReadOnlyColumnCollection[str, KeyedColumnElement[Any]] = (source)

Undocumented

@property
exported_columns: ReadOnlyColumnCollection[str, ColumnElement[Any]] = (source)
overrides sqlalchemy.sql.selectable.ReturnsRows.exported_columns

A :class:`_expression.ColumnCollection` that represents the "exported" columns of this :class:`_expression.Selectable`, not including :class:`_sql.TextClause` constructs. The "exported" columns for a :class:`_expression.SelectBase` object are synonymous with the :attr:`_expression.SelectBase.selected_columns` collection. .. versionadded:: 1.4 .. seealso:: :attr:`_expression.Select.exported_columns` :attr:`_expression.Selectable.exported_columns` :attr:`_expression.FromClause.exported_columns`

@util.ro_non_memoized_property
selected_columns: ColumnCollection[str, ColumnElement[Any]] = (source)
overridden in sqlalchemy.sql.selectable.CompoundSelect, sqlalchemy.sql.selectable.Select, sqlalchemy.sql.selectable.SelectStatementGrouping, sqlalchemy.sql.selectable.TextualSelect

A :class:`_expression.ColumnCollection` representing the columns that this SELECT statement or similar construct returns in its result set. This collection differs from the :attr:`_expression.FromClause.columns` collection of a :class:`_expression.FromClause` in that the columns within this collection cannot be directly nested inside another SELECT statement; a subquery must be applied first which provides for the necessary parenthesization required by SQL. .. note:: The :attr:`_sql.SelectBase.selected_columns` collection does not include expressions established in the columns clause using the :func:`_sql.text` construct; these are silently omitted from the collection. To use plain textual column expressions inside of a :class:`_sql.Select` construct, use the :func:`_sql.literal_column` construct. .. seealso:: :attr:`_sql.Select.selected_columns` .. versionadded:: 1.4

def _ensure_disambiguated_names(self) -> Self: (source)
overridden in sqlalchemy.sql.selectable.CompoundSelect, sqlalchemy.sql.selectable.Select, sqlalchemy.sql.selectable.SelectStatementGrouping, sqlalchemy.sql.selectable.TextualSelect

Ensure that the names generated by this selectbase will be disambiguated in some way, if possible.

def _generate_fromclause_column_proxies(self, subquery: FromClause, *, proxy_compound_columns: Optional[Iterable[Sequence[ColumnElement[Any]]]] = None): (source)
overrides sqlalchemy.sql.selectable.ReturnsRows._generate_fromclause_column_proxies
overridden in sqlalchemy.sql.selectable.CompoundSelect, sqlalchemy.sql.selectable.Select, sqlalchemy.sql.selectable.SelectStatementGrouping, sqlalchemy.sql.selectable.TextualSelect

Populate columns into an :class:`.AliasedReturnsRows` object.

@HasMemoized.memoized_attribute
def _implicit_subquery(self) -> Subquery: (source)

Undocumented

def _refresh_for_new_column(self, column: ColumnElement[Any]): (source)
overrides sqlalchemy.sql.selectable.Selectable._refresh_for_new_column
overridden in sqlalchemy.sql.selectable.CompoundSelect

reset internal collections for an incoming column being added.

def _scalar_type(self) -> TypeEngine[Any]: (source)
overridden in sqlalchemy.sql.selectable.CompoundSelect, sqlalchemy.sql.selectable.Select, sqlalchemy.sql.selectable.TextualSelect

Undocumented

_is_select_base: bool = (source)
overrides sqlalchemy.sql.selectable.ReturnsRows._is_select_base

Undocumented

@util.ro_non_memoized_property
_all_selected_columns: _SelectIterable = (source)
overrides sqlalchemy.sql.selectable.ReturnsRows._all_selected_columns
overridden in sqlalchemy.sql.selectable.CompoundSelect, sqlalchemy.sql.selectable.Select, sqlalchemy.sql.selectable.SelectStatementGrouping, sqlalchemy.sql.selectable.TextualSelect

A sequence of expressions that correspond to what is rendered in the columns clause, including :class:`_sql.TextClause` constructs. .. versionadded:: 1.4.12 .. seealso:: :attr:`_sql.SelectBase.exported_columns`