# sql/selectable.py

# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors

# <see AUTHORS file>

#

# This module is part of SQLAlchemy and is released under

# the MIT License: https://www.opensource.org/licenses/mit-license.php

"""The :class:`_expression.FromClause` class of SQL expression elements,

representing

SQL tables and derived rowsets.

"""

from __future__ import annotations

import collections

from enum import Enum

import itertools

import os

from typing import AbstractSet

from typing import Any as TODO_Any

from typing import Any

from typing import Callable

from typing import cast

from typing import Collection

from typing import Dict

from typing import Generic

from typing import Iterable

from typing import Iterator

from typing import List

from typing import Literal

from typing import NamedTuple

from typing import NoReturn

from typing import Optional

from typing import overload

from typing import Protocol

from typing import Sequence

from typing import Set

from typing import Tuple

from typing import Type

from typing import TYPE_CHECKING

from typing import TypeVar

from typing import Union

from . import cache_key

from . import coercions

from . import operators

from . import roles

from . import traversals

from . import type_api

from . import visitors

from ._annotated_cols import _ColClauseCC_co

from ._annotated_cols import _KeyColCC_co

from ._annotated_cols import _TC_co

from ._annotated_cols import HasRowPos

from ._typing import _ColumnsClauseArgument

from ._typing import _no_kw

from ._typing import _T

from ._typing import _Ts

from ._typing import is_column_element

from ._typing import is_select_statement

from ._typing import is_subquery

from ._typing import is_table

from ._typing import is_text_clause

from .annotation import Annotated

from .annotation import SupportsCloneAnnotations

from .base import _clone

from .base import _cloned_difference

from .base import _cloned_intersection

from .base import _entity_namespace_key_search_all

from .base import _EntityNamespace

from .base import _expand_cloned

from .base import _from_objects

from .base import _generative

from .base import _never_select_column

from .base import _NoArg

from .base import _select_iterables

from .base import CacheableOptions

from .base import ColumnCollection

from .base import ColumnSet

from .base import CompileState

from .base import DedupeColumnCollection

from .base import DialectKWArgs

from .base import Executable

from .base import ExecutableStatement

from .base import Generative

from .base import HasCompileState

from .base import HasMemoized

from .base import HasSyntaxExtensions

from .base import Immutable

from .base import SyntaxExtension

from .base import WriteableColumnCollection

from .coercions import _document_text_coercion

from .elements import _anonymous_label

from .elements import BindParameter

from .elements import BooleanClauseList

from .elements import ClauseElement

from .elements import ClauseList

from .elements import ColumnClause

from .elements import ColumnElement

from .elements import DQLDMLClauseElement

from .elements import GroupedElement

from .elements import literal_column

from .elements import TableValuedColumn

from .elements import TextClause

from .elements import UnaryExpression

from .operators import OperatorType

from .sqltypes import NULLTYPE

from .visitors import _TraverseInternalsType

from .visitors import InternalTraversal

from .visitors import prefix_anon_map

from .. import exc

from .. import util

from ..util import HasMemoized_ro_memoized_attribute

from ..util import warn_deprecated

from ..util.typing import Self

from ..util.typing import TupleAny

from ..util.typing import Unpack

and_ = BooleanClauseList.and_

if TYPE_CHECKING:

from ._typing import _ColumnExpressionArgument

from ._typing import _ColumnExpressionOrStrLabelArgument

from ._typing import _FromClauseArgument

from ._typing import _JoinTargetArgument

from ._typing import _LimitOffsetType

from ._typing import _MAYBE_ENTITY

from ._typing import _NOT_ENTITY

from ._typing import _OnClauseArgument

from ._typing import _OnlyColumnArgument

from ._typing import _SelectStatementForCompoundArgument

from ._typing import _T0

from ._typing import _T1

from ._typing import _T2

from ._typing import _T3

from ._typing import _T4

from ._typing import _T5

from ._typing import _T6

from ._typing import _T7

from ._typing import _TextCoercedExpressionArgument

from ._typing import _TypedColumnClauseArgument as _TCCA

from ._typing import _TypeEngineArgument

from .base import _AmbiguousTableNameMap

from .base import ExecutableOption

from .base import ReadOnlyColumnCollection

from .cache_key import _CacheKeyTraversalType

from .compiler import SQLCompiler

from .ddl import CreateTableAs

from .dml import Delete

from .dml import Update

from .elements import AbstractTextClause

from .elements import BinaryExpression

from .elements import KeyedColumnElement

from .elements import Label

from .elements import NamedColumn

from .functions import Function

from .schema import ForeignKey

from .schema import ForeignKeyConstraint

from .schema import MetaData

from .sqltypes import TableValueType

from .type_api import TypeEngine

from .visitors import _CloneCallableType

_ColumnsClauseElement = Union["FromClause", ColumnElement[Any], "TextClause"]

_LabelConventionCallable = Callable[

[Union["ColumnElement[Any]", "AbstractTextClause"]], Optional[str]

]

class _JoinTargetProtocol(Protocol):

@util.ro_non_memoized_property

def _from_objects(self) -> List[FromClause]: ...

@util.ro_non_memoized_property

def entity_namespace(self) -> _EntityNamespace: ...

_JoinTargetElement = Union["FromClause", _JoinTargetProtocol]

_OnClauseElement = Union["ColumnElement[bool]", _JoinTargetProtocol]

_ForUpdateOfArgument = Union[

# single column, Table, ORM entity

Union[

"_ColumnExpressionArgument[Any]",

"_FromClauseArgument",

],

# or sequence of column, Table, ORM entity

Sequence[

Union[

"_ColumnExpressionArgument[Any]",

"_FromClauseArgument",

]

],

]

_SetupJoinsElement = Tuple[

_JoinTargetElement,

Optional[_OnClauseElement],

Optional["FromClause"],

Dict[str, Any],

]

_SelectIterable = Iterable[Union["ColumnElement[Any]", "AbstractTextClause"]]

class _OffsetLimitParam(BindParameter[int]):

inherit_cache = True

@property

def _limit_offset_value(self) -> Optional[int]:

return self.effective_value

class ReturnsRows(roles.ReturnsRowsRole, DQLDMLClauseElement):

"""The base-most class for Core constructs that have some concept of

columns that can represent rows.

While the SELECT statement and TABLE are the primary things we think

of in this category, DML like INSERT, UPDATE and DELETE can also specify

RETURNING which means they can be used in CTEs and other forms, and

PostgreSQL has functions that return rows also.

.. versionadded:: 1.4

"""

_is_returns_rows = True

# sub-elements of returns_rows

_is_from_clause = False

_is_select_base = False

_is_select_statement = False

_is_lateral = False

@property

def selectable(self) -> ReturnsRows:

return self

@util.ro_non_memoized_property

def _all_selected_columns(self) -> _SelectIterable:

"""A sequence of column expression objects that represents the

"selected" columns of this :class:`_expression.ReturnsRows`.

This is typically equivalent to .exported_columns except it is

delivered in the form of a straight sequence and not keyed

:class:`_expression.ColumnCollection`.

"""

raise NotImplementedError()

def is_derived_from(self, fromclause: Optional[FromClause]) -> bool:

"""Return ``True`` if this :class:`.ReturnsRows` is

'derived' from the given :class:`.FromClause`.

An example would be an Alias of a Table is derived from that Table.

"""

raise NotImplementedError()

def _generate_fromclause_column_proxies(

self,

fromclause: FromClause,

columns: WriteableColumnCollection[str, KeyedColumnElement[Any]],

primary_key: ColumnSet,

foreign_keys: Set[KeyedColumnElement[Any]],

) -> None:

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

raise NotImplementedError()

def _refresh_for_new_column(self, column: ColumnElement[Any]) -> None:

"""reset internal collections for an incoming column being added."""

raise NotImplementedError()

@property

def exported_columns(self) -> ReadOnlyColumnCollection[Any, Any]:

"""A :class:`_expression.ColumnCollection`

that represents the "exported"

columns of this :class:`_expression.ReturnsRows`.

The "exported" columns represent the collection of

:class:`_expression.ColumnElement`

expressions that are rendered by this SQL

construct. There are primary varieties which are the

"FROM clause columns" of a FROM clause, such as a table, join,

or subquery, the "SELECTed columns", which are the columns in

the "columns clause" of a SELECT statement, and the RETURNING

columns in a DML statement..

.. versionadded:: 1.4

.. seealso::

:attr:`_expression.FromClause.exported_columns`

:attr:`_expression.SelectBase.exported_columns`

"""

raise NotImplementedError()

class ExecutableReturnsRows(ExecutableStatement, ReturnsRows):

"""base for executable statements that return rows."""

class TypedReturnsRows(ExecutableReturnsRows, Generic[Unpack[_Ts]]):

"""base for a typed executable statements that return rows."""

class Selectable(ReturnsRows):

"""Mark a class as being selectable."""

__visit_name__ = "selectable"

is_selectable = True

def _refresh_for_new_column(self, column: ColumnElement[Any]) -> None:

raise NotImplementedError()

def lateral(self, name: Optional[str] = None) -> LateralFromClause:

"""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.

.. seealso::

:ref:`tutorial_lateral_correlation` - overview of usage.

"""

return Lateral._construct(self, name=name)

@util.deprecated(

"1.4",

message="The :meth:`.Selectable.replace_selectable` method is "

"deprecated, and will be removed in a future release. Similar "

"functionality is available via the sqlalchemy.sql.visitors module.",

)

@util.preload_module("sqlalchemy.sql.util")

def replace_selectable(self, old: FromClause, alias: Alias) -> Self:

"""Replace all occurrences of :class:`_expression.FromClause`

'old' with the given :class:`_expression.Alias`

object, returning a copy of this :class:`_expression.FromClause`.

"""

return util.preloaded.sql_util.ClauseAdapter(alias).traverse(self)

def corresponding_column(

self, column: KeyedColumnElement[Any], require_embedded: bool = False

) -> Optional[KeyedColumnElement[Any]]:

"""Given a :class:`_expression.ColumnElement`, return the exported

:class:`_expression.ColumnElement` object from the

:attr:`_expression.Selectable.exported_columns`

collection of this :class:`_expression.Selectable`

which corresponds to that

original :class:`_expression.ColumnElement` via a common ancestor

column.

:param column: the target :class:`_expression.ColumnElement`

to be matched.

:param require_embedded: only return corresponding columns for

the given :class:`_expression.ColumnElement`, if the given

:class:`_expression.ColumnElement`

is actually present within a sub-element

of this :class:`_expression.Selectable`.

Normally the column will match if

it merely shares a common ancestor with one of the exported

columns of this :class:`_expression.Selectable`.

.. seealso::

:attr:`_expression.Selectable.exported_columns` - the

:class:`_expression.ColumnCollection`

that is used for the operation.

:meth:`_expression.ColumnCollection.corresponding_column`

- implementation

method.

"""

return self.exported_columns.corresponding_column(

column, require_embedded

)

class HasPrefixes:

_prefixes: Tuple[Tuple[DQLDMLClauseElement, str], ...] = ()

_has_prefixes_traverse_internals: _TraverseInternalsType = [

("_prefixes", InternalTraversal.dp_prefix_sequence)

]

@_generative

@_document_text_coercion(

"prefixes",

":meth:`_expression.HasPrefixes.prefix_with`",

":paramref:`.HasPrefixes.prefix_with.*prefixes`",

)

def prefix_with(

self,

*prefixes: _TextCoercedExpressionArgument[Any],

dialect: str = "*",

) -> Self:

r"""Add one or more expressions following the statement keyword, i.e.

SELECT, INSERT, UPDATE, or DELETE. Generative.

This is used to support backend-specific prefix keywords such as those

provided by MySQL.

E.g.::

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

# MySQL 5.7 optimizer hints

stmt = select(table).prefix_with("/*+ BKA(t1) */", dialect="mysql")

Multiple prefixes can be specified by multiple calls

to :meth:`_expression.HasPrefixes.prefix_with`.

:param \*prefixes: textual or :class:`_expression.ClauseElement`

construct which

will be rendered following the INSERT, UPDATE, or DELETE

keyword.

:param dialect: optional string dialect name which will

limit rendering of this prefix to only that dialect.

"""

self._prefixes = self._prefixes + tuple(

[

(coercions.expect(roles.StatementOptionRole, p), dialect)

for p in prefixes

]

)

return self

class HasSuffixes:

_suffixes: Tuple[Tuple[DQLDMLClauseElement, str], ...] = ()

_has_suffixes_traverse_internals: _TraverseInternalsType = [

("_suffixes", InternalTraversal.dp_prefix_sequence)

]

@_generative

@_document_text_coercion(

"suffixes",

":meth:`_expression.HasSuffixes.suffix_with`",

":paramref:`.HasSuffixes.suffix_with.*suffixes`",

)

def suffix_with(

self,

*suffixes: _TextCoercedExpressionArgument[Any],

dialect: str = "*",

) -> Self:

r"""Add one or more expressions following the statement as a whole.

This is used to support backend-specific suffix keywords on

certain constructs.

E.g.::

stmt = (

select(col1, col2)

.cte()

.suffix_with(

"cycle empno set y_cycle to 1 default 0", dialect="oracle"

)

)

Multiple suffixes can be specified by multiple calls

to :meth:`_expression.HasSuffixes.suffix_with`.

:param \*suffixes: textual or :class:`_expression.ClauseElement`

construct which

will be rendered following the target clause.

:param dialect: Optional string dialect name which will

limit rendering of this suffix to only that dialect.

"""

self._suffixes = self._suffixes + tuple(

[

(coercions.expect(roles.StatementOptionRole, p), dialect)

for p in suffixes

]

)

return self

class HasHints:

_hints: util.immutabledict[Tuple[FromClause, str], str] = (

util.immutabledict()

)

_statement_hints: Tuple[Tuple[str, str], ...] = ()

_has_hints_traverse_internals: _TraverseInternalsType = [

("_statement_hints", InternalTraversal.dp_statement_hint_list),

("_hints", InternalTraversal.dp_table_hint_list),

]

@_generative

def with_statement_hint(self, text: str, dialect_name: str = "*") -> Self:

"""Add a statement hint to this :class:`_expression.Select` or

other selectable object.

.. tip::

:meth:`_expression.Select.with_statement_hint` generally adds hints

**at the trailing end** of a SELECT statement. To place

dialect-specific hints such as optimizer hints at the **front** of

the SELECT statement after the SELECT keyword, use the

:meth:`_expression.Select.prefix_with` method for an open-ended

space, or for table-specific hints the

:meth:`_expression.Select.with_hint` may be used, which places

hints in a dialect-specific location.

This method is similar to :meth:`_expression.Select.with_hint` except

that it does not require an individual table, and instead applies to

the statement as a whole.

Hints here are specific to the backend database and may include

directives such as isolation levels, file directives, fetch directives,

etc.

.. seealso::

:meth:`_expression.Select.with_hint`

:meth:`_expression.Select.prefix_with` - generic SELECT prefixing

which also can suit some database-specific HINT syntaxes such as

MySQL or Oracle Database optimizer hints

"""

return self._with_hint(None, text, dialect_name)

@_generative

def with_hint(

self,

selectable: _FromClauseArgument,

text: str,

dialect_name: str = "*",

) -> Self:

r"""Add an indexing or other executional context hint for the given

selectable to this :class:`_expression.Select` or other selectable

object.

.. tip::

The :meth:`_expression.Select.with_hint` method adds hints that are

**specific to a single table** to a statement, in a location that

is **dialect-specific**. To add generic optimizer hints to the

**beginning** of a statement ahead of the SELECT keyword such as

for MySQL or Oracle Database, use the

:meth:`_expression.Select.prefix_with` method. To add optimizer

hints to the **end** of a statement such as for PostgreSQL, use the

:meth:`_expression.Select.with_statement_hint` method.

The text of the hint is rendered in the appropriate

location for the database backend in use, relative

to the given :class:`_schema.Table` or :class:`_expression.Alias`

passed as the

``selectable`` argument. The dialect implementation

typically uses Python string substitution syntax

with the token ``%(name)s`` to render the name of

the table or alias. E.g. when using Oracle Database, the

following::

select(mytable).with_hint(mytable, "index(%(name)s ix_mytable)")

Would render SQL as:

.. sourcecode:: sql

select /*+ index(mytable ix_mytable) */ ... from mytable

The ``dialect_name`` option will limit the rendering of a particular

hint to a particular backend. Such as, to add hints for both Oracle

Database and MSSql simultaneously::

select(mytable).with_hint(

mytable, "index(%(name)s ix_mytable)", "oracle"

).with_hint(mytable, "WITH INDEX ix_mytable", "mssql")

.. seealso::

:meth:`_expression.Select.with_statement_hint`

:meth:`_expression.Select.prefix_with` - generic SELECT prefixing

which also can suit some database-specific HINT syntaxes such as

MySQL or Oracle Database optimizer hints

"""

return self._with_hint(selectable, text, dialect_name)

def _with_hint(

self,

selectable: Optional[_FromClauseArgument],

text: str,

dialect_name: str,

) -> Self:

if selectable is None:

self._statement_hints += ((dialect_name, text),)

else:

self._hints = self._hints.union(

{

(

coercions.expect(roles.FromClauseRole, selectable),

dialect_name,

): text

}

)

return self

class FromClause(

roles.AnonymizedFromClauseRole, Generic[_KeyColCC_co], Selectable

):

"""Represent an element that can be used within the ``FROM``

clause of a ``SELECT`` statement.

The most common forms of :class:`_expression.FromClause` are the

:class:`_schema.Table` and the :func:`_expression.select` constructs. Key

features common to all :class:`_expression.FromClause` objects include:

* a :attr:`.c` collection, which provides per-name access to a collection

of :class:`_expression.ColumnElement` objects.

* a :attr:`.primary_key` attribute, which is a collection of all those

:class:`_expression.ColumnElement`

objects that indicate the ``primary_key`` flag.

* Methods to generate various derivations of a "from" clause, including

:meth:`_expression.FromClause.alias`,

:meth:`_expression.FromClause.join`,

:meth:`_expression.FromClause.select`.

"""

__visit_name__ = "fromclause"

named_with_column = False

@util.ro_non_memoized_property

def _hide_froms(self) -> Iterable[FromClause]:

return ()

_is_clone_of: Optional[FromClause[_KeyColCC_co]]

_columns: WriteableColumnCollection[Any, Any]

schema: Optional[str] = None

"""Define the 'schema' attribute for this :class:`_expression.FromClause`.

This is typically ``None`` for most objects except that of

:class:`_schema.Table`, where it is taken as the value of the

:paramref:`_schema.Table.schema` argument.

"""

is_selectable = True

_is_from_clause = True

_is_join = False

_use_schema_map = False

def with_cols(self, type_: Type[_TC_co]) -> FromClause[_TC_co]:

"""Cast this :class:`.FromClause` to be generic on a specific a

:class:`_schema.TypedColumns` subclass.

At runtime returns self unchanged, without performing any validation.

"""

return self # type: ignore

@overload

def select(

self: FromClause[HasRowPos[Unpack[_Ts]]], # type: ignore[type-var]

) -> Select[Unpack[_Ts]]: ...

@overload

def select(self) -> Select[Unpack[TupleAny]]: ...

def select(self) -> Select[Unpack[TupleAny]]:

r"""Return a SELECT of this :class:`_expression.FromClause`.

e.g.::

stmt = some_table.select().where(some_table.c.id == 5)

.. seealso::

:func:`_expression.select` - general purpose

method which allows for arbitrary column lists.

"""

return Select(self)

def join(

self,

right: _FromClauseArgument,

onclause: Optional[_ColumnExpressionArgument[bool]] = None,

isouter: bool = False,

full: bool = False,

) -> Join:

"""Return a :class:`_expression.Join` from this

:class:`_expression.FromClause`

to another :class:`FromClause`.

E.g.::

from sqlalchemy import join

j = user_table.join(

address_table, user_table.c.id == address_table.c.user_id

)

stmt = select(user_table).select_from(j)

would emit SQL along the lines of:

.. sourcecode:: sql

SELECT user.id, user.name FROM user

JOIN address ON user.id = address.user_id

:param right: the right side of the join; this is any

:class:`_expression.FromClause` object such as a

:class:`_schema.Table` object, and

may also be a selectable-compatible object such as an ORM-mapped

class.

:param onclause: a SQL expression representing the ON clause of the

join. If left at ``None``, :meth:`_expression.FromClause.join`

will attempt to

join the two tables based on a foreign key relationship.

:param isouter: if True, render a LEFT OUTER JOIN, instead of JOIN.

:param full: if True, render a FULL OUTER JOIN, instead of LEFT OUTER

JOIN. Implies :paramref:`.FromClause.join.isouter`.

.. seealso::

:func:`_expression.join` - standalone function

:class:`_expression.Join` - the type of object produced

"""

return Join(self, right, onclause, isouter, full)

def outerjoin(

self,

right: _FromClauseArgument,

onclause: Optional[_ColumnExpressionArgument[bool]] = None,

full: bool = False,

) -> Join:

"""Return a :class:`_expression.Join` from this

:class:`_expression.FromClause`

to another :class:`FromClause`, with the "isouter" flag set to

True.

E.g.::

from sqlalchemy import outerjoin

j = user_table.outerjoin(

address_table, user_table.c.id == address_table.c.user_id

)

The above is equivalent to::

j = user_table.join(

address_table, user_table.c.id == address_table.c.user_id, isouter=True

)

:param right: the right side of the join; this is any

:class:`_expression.FromClause` object such as a

:class:`_schema.Table` object, and

may also be a selectable-compatible object such as an ORM-mapped

class.

:param onclause: a SQL expression representing the ON clause of the

join. If left at ``None``, :meth:`_expression.FromClause.join`

will attempt to

join the two tables based on a foreign key relationship.

:param full: if True, render a FULL OUTER JOIN, instead of

LEFT OUTER JOIN.

.. seealso::

:meth:`_expression.FromClause.join`

:class:`_expression.Join`

""" # noqa: E501

return Join(self, right, onclause, True, full)

def alias(

self, name: Optional[str] = None, flat: bool = False

) -> NamedFromClause[_KeyColCC_co]:

"""Return an alias of this :class:`_expression.FromClause`.

E.g.::

a2 = some_table.alias("a2")

The above code creates an :class:`_expression.Alias`

object which can be used

as a FROM clause in any SELECT statement.

.. seealso::

:ref:`tutorial_using_aliases`

:func:`_expression.alias`

"""

return Alias._construct(self, name=name)

def tablesample(

self,

sampling: Union[float, Function[Any]],

name: Optional[str] = None,

seed: Optional[roles.ExpressionElementRole[Any]] = None,

) -> TableSample:

"""Return a TABLESAMPLE alias of this :class:`_expression.FromClause`.

The return value is the :class:`_expression.TableSample`

construct also

provided by the top-level :func:`_expression.tablesample` function.

.. seealso::

:func:`_expression.tablesample` - usage guidelines and parameters

"""

return TableSample._construct(

self, sampling=sampling, name=name, seed=seed

)

def is_derived_from(self, fromclause: Optional[FromClause]) -> bool:

"""Return ``True`` if this :class:`_expression.FromClause` is

'derived' from the given ``FromClause``.

An example would be an Alias of a Table is derived from that Table.

"""

# this is essentially an "identity" check in the base class.

# Other constructs override this to traverse through

# contained elements.

return fromclause in self._cloned_set

def _is_lexical_equivalent(self, other: FromClause) -> bool:

"""Return ``True`` if this :class:`_expression.FromClause` and

the other represent the same lexical identity.

This tests if either one is a copy of the other, or

if they are the same via annotation identity.

"""

return bool(self._cloned_set.intersection(other._cloned_set))

@util.ro_non_memoized_property

def description(self) -> str:

"""A brief description of this :class:`_expression.FromClause`.

Used primarily for error message formatting.

"""

return getattr(self, "name", self.__class__.__name__ + " object")

def _generate_fromclause_column_proxies(

self,

fromclause: FromClause,

columns: WriteableColumnCollection[str, KeyedColumnElement[Any]],

primary_key: ColumnSet,

foreign_keys: Set[KeyedColumnElement[Any]],

) -> None:

columns._populate_separate_keys(

col._make_proxy(

fromclause, primary_key=primary_key, foreign_keys=foreign_keys

)

for col in self.c

)

@util.ro_non_memoized_property

def exported_columns(self) -> _KeyColCC_co:

"""A :class:`_expression.ColumnCollection`

that represents the "exported"

columns of this :class:`_expression.FromClause`.

The "exported" columns for a :class:`_expression.FromClause`

object are synonymous

with the :attr:`_expression.FromClause.columns` collection.

.. versionadded:: 1.4

.. seealso::

:attr:`_expression.Selectable.exported_columns`

:attr:`_expression.SelectBase.exported_columns`

"""

return self.c

@util.ro_non_memoized_property

def columns(self) -> _KeyColCC_co:

"""A named-based collection of :class:`_expression.ColumnElement`

objects maintained by this :class:`_expression.FromClause`.

The :attr:`.columns`, or :attr:`.c` collection, is the gateway

to the construction of SQL expressions using table-bound or

other selectable-bound columns::

select(mytable).where(mytable.c.somecolumn == 5)

:return: a :class:`.ColumnCollection` object.

"""

return self.c

@util.ro_memoized_property

def c(self) -> _KeyColCC_co:

"""

A synonym for :attr:`.FromClause.columns`

:return: a :class:`.ColumnCollection`

"""

if "_columns" not in self.__dict__:

self._setup_collections()

return self._columns.as_readonly() # type: ignore[return-value]

def _setup_collections(self) -> None:

with util.mini_gil:

# detect another thread that raced ahead

if "_columns" in self.__dict__:

assert "primary_key" in self.__dict__

assert "foreign_keys" in self.__dict__

return

_columns: WriteableColumnCollection[Any, Any] = (

WriteableColumnCollection()

)

primary_key = ColumnSet()

foreign_keys: Set[KeyedColumnElement[Any]] = set()

self._populate_column_collection(

columns=_columns,

primary_key=primary_key,

foreign_keys=foreign_keys,

)

# assigning these three collections separately is not itself

# atomic, but greatly reduces the surface for problems

self._columns = _columns

self.primary_key = primary_key # type: ignore

self.foreign_keys = foreign_keys # type: ignore

@util.ro_non_memoized_property

def entity_namespace(self) -> _EntityNamespace:

"""Return a namespace used for name-based access in SQL expressions.

This is the namespace that is used to resolve "filter_by()" type

expressions, such as::

stmt.filter_by(address="some address")

It defaults to the ``.c`` collection, however internally it can

be overridden using the "entity_namespace" annotation to deliver

alternative results.

"""

return self.c

@util.ro_memoized_property

def primary_key(self) -> Iterable[NamedColumn[Any]]:

"""Return the iterable collection of :class:`_schema.Column` objects

which comprise the primary key of this :class:`_selectable.FromClause`.

For a :class:`_schema.Table` object, this collection is represented

by the :class:`_schema.PrimaryKeyConstraint` which itself is an

iterable collection of :class:`_schema.Column` objects.

"""

self._setup_collections()

return self.primary_key

@util.ro_memoized_property

def foreign_keys(self) -> Iterable[ForeignKey]:

"""Return the collection of :class:`_schema.ForeignKey` marker objects