sqlalchemy.sql.elements.UnaryExpression

class documentation

class UnaryExpression(ColumnElement):

Known subclasses: sqlalchemy.sql.selectable.Exists, sqlalchemy.sql.elements.AsBoolean, sqlalchemy.sql.elements.CollectionAggregate

View In Hierarchy

Define a 'unary' expression.

A unary expression has a single column expression and an operator. The operator can be placed on the left (where it is called the 'operator') or right (where it is called the 'modifier') of the column expression.

.UnaryExpression is the basis for several unary operators including those used by .desc, .asc, .distinct, .nulls_first and .nulls_last.

Class Method	`_create_asc`	Produce an ascending `ORDER BY` clause element.
Class Method	`_create_desc`	Produce a descending `ORDER BY` clause element.
Class Method	`_create_distinct`	Produce an column-expression-level unary `DISTINCT` clause.
Class Method	`_create_nulls_first`	Produce the `NULLS FIRST` modifier for an `ORDER BY` expression.
Class Method	`_create_nulls_last`	Produce the `NULLS LAST` modifier for an `ORDER BY` expression.
Method	`__init__`	Undocumented
Method	`_negate`	Undocumented
Method	`self_group`	Apply a 'grouping' to this `_expression.ClauseElement`.
Class Variable	`__visit_name__`	Undocumented
Class Variable	`_traverse_internals`	Undocumented
Instance Variable	`_propagate_attrs`	like annotations, however these propagate outwards liberally as SQL constructs are built, and are set up at construction time.
Instance Variable	`element`	Undocumented
Instance Variable	`modifier`	Undocumented
Instance Variable	`operator`	Undocumented
Instance Variable	`type`	Undocumented
Instance Variable	`wraps_column_expression`	Undocumented
Property	`_from_objects`	Undocumented
Property	`_order_by_label_element`	Undocumented

Inherited from ColumnElement:

Method	`cast`	Produce a type cast, i.e. `CAST(<expression> AS <type>)`.
Method	`label`	Produce a column label, i.e. `<columnname> AS <name>`.
Method	`operate`	Operate on an argument.
Method	`reverse_operate`	Reverse operate on an argument.
Method	`shares_lineage`	Return True if the given `_expression.ColumnElement` has a common ancestor to this `_expression.ColumnElement`.
Class Variable	`foreign_keys`	Undocumented
Class Variable	`key`	The 'key' that in some circumstances refers to this object in a Python namespace.
Class Variable	`primary_key`	Undocumented
Method	`__getattr__`	Undocumented
Method	`_anon_label`	Undocumented
Method	`_bind_param`	Undocumented
Method	`_compare_name_for_result`	Return True if the given column element compares to this one when targeting within a result row.
Method	`_dedupe_anon_label_idx`	label to apply to a column that is anon labeled, but repeated in the SELECT, so that we have to make an "extra anon" label that disambiguates it from the previous appearance.
Method	`_dedupe_anon_tq_label_idx`	Undocumented
Method	`_expression_label`	a suggested label to use in the case that the column has no name, which should be used if possible as the explicit 'AS <label>' where this expression would normally have an anon label.
Method	`_make_proxy`	Create a new `_expression.ColumnElement` representing this `_expression.ColumnElement` as it appears in the select list of a descending selectable.
Method	`_proxy_key`	Undocumented
Method	`_tq_key_label`	A label-based version of 'key' that in some circumstances refers to this object in a Python namespace.
Method	`_uncached_proxy_set`	An 'uncached' version of proxy set.
Method	`comparator`	Undocumented
Class Variable	`_allow_label_resolve`	A flag that can be flipped to prevent a column from being resolvable by string label name.
Class Variable	`_alt_names`	Undocumented
Class Variable	`_is_implicitly_boolean`	Undocumented
Class Variable	`_proxies`	Undocumented
Class Variable	`_render_label_in_columns_clause`	No summary
Class Variable	`_tq_label`	The named label that can be used to target this column in a result set in a "table qualified" context.
Property	`_anon_key_label`	Provides a constant 'anonymous key label' for this ColumnElement.
Property	`_anon_name_label`	Provides a constant 'anonymous label' for this ColumnElement.
Property	`_anon_tq_key_label`	Undocumented
Property	`_anon_tq_label`	Undocumented
Property	`_key_label`	legacy; renamed to _tq_key_label
Property	`_label`	legacy; renamed to _tq_label
Property	`_non_anon_label`	the 'name' that naturally applies this element when rendered in SQL.
Property	`_select_iterable`	Undocumented
Property	`anon_key_label`	Undocumented
Property	`anon_label`	Undocumented
Property	`base_columns`	Undocumented
Property	`expression`	Return a column expression.
Property	`proxy_set`	Undocumented

Inherited from ColumnArgumentOrKeyRole (via ColumnElement):

Class Variable _role_name Undocumented

Inherited from SQLRole (via ColumnElement, ColumnArgumentOrKeyRole, ColumnArgumentRole):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from StatementOptionRole (via ColumnElement):

Class Variable _role_name Undocumented

Inherited from SQLRole (via ColumnElement, StatementOptionRole, StructuralRole):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from WhereHavingRole (via ColumnElement):

Class Variable _role_name Undocumented

Inherited from AllowsLambdaRole (via ColumnElement, WhereHavingRole, OnClauseRole):

Class Variable allows_lambda Undocumented

Inherited from SQLRole (via ColumnElement, WhereHavingRole, OnClauseRole, StructuralRole):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from BinaryElementRole (via ColumnElement):

Class Variable _role_name Undocumented

Inherited from SQLRole (via ColumnElement, BinaryElementRole, ExpressionElementRole):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from OrderByRole (via ColumnElement):

Class Variable _role_name Undocumented

Inherited from AllowsLambdaRole (via ColumnElement, OrderByRole):

Class Variable allows_lambda Undocumented

Inherited from SQLRole (via ColumnElement, OrderByRole, ByOfRole, ColumnListRole):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from ColumnsClauseRole (via ColumnElement):

Class Variable _role_name Undocumented

Inherited from AllowsLambdaRole (via ColumnElement, ColumnsClauseRole):

Class Variable allows_lambda Undocumented

Inherited from UsesInspection (via ColumnElement, ColumnsClauseRole):

Class Variable	`_post_inspect`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from SQLRole (via ColumnElement, ColumnsClauseRole, ColumnListRole):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from LimitOffsetRole (via ColumnElement):

Class Variable _role_name Undocumented

Inherited from SQLRole (via ColumnElement, LimitOffsetRole):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from DMLColumnRole (via ColumnElement):

Class Variable _role_name Undocumented

Inherited from SQLRole (via ColumnElement, DMLColumnRole):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from DDLConstraintColumnRole (via ColumnElement):

Class Variable _role_name Undocumented

Inherited from SQLRole (via ColumnElement, DDLConstraintColumnRole):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from DDLExpressionRole (via ColumnElement):

Class Variable _role_name Undocumented

Inherited from SQLRole (via ColumnElement, DDLExpressionRole, StructuralRole):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from ColumnOperators (via ColumnElement):

Method	`__add__`	Implement the `+` operator.
Method	`__contains__`	Undocumented
Method	`__div__`	Implement the `/` operator.
Method	`__eq__`	Implement the `==` operator.
Method	`__ge__`	Implement the `>=` operator.
Method	`__getitem__`	Implement the [] operator.
Method	`__gt__`	Implement the `>` operator.
Method	`__le__`	Implement the `<=` operator.
Method	`__lshift__`	implement the << operator.
Method	`__lt__`	Implement the `<` operator.
Method	`__mod__`	Implement the `%` operator.
Method	`__mul__`	Implement the `*` operator.
Method	`__ne__`	Implement the `!=` operator.
Method	`__neg__`	Implement the `-` operator.
Method	`__radd__`	Implement the `+` operator in reverse.
Method	`__rdiv__`	Implement the `/` operator in reverse.
Method	`__rmod__`	Implement the `%` operator in reverse.
Method	`__rmul__`	Implement the `*` operator in reverse.
Method	`__rshift__`	implement the >> operator.
Method	`__rsub__`	Implement the `-` operator in reverse.
Method	`__rtruediv__`	Implement the `//` operator in reverse.
Method	`__sub__`	Implement the `-` operator.
Method	`__truediv__`	Implement the `//` operator.
Method	`all_`	Produce an `_expression.all_` clause against the parent object.
Method	`any_`	Produce an `_expression.any_` clause against the parent object.
Method	`asc`	Produce a `_expression.asc` clause against the parent object.
Method	`between`	Produce a `_expression.between` clause against the parent object, given the lower and upper range.
Method	`collate`	Produce a `_expression.collate` clause against the parent object, given the collation string.
Method	`concat`	Implement the 'concat' operator.
Method	`contains`	Implement the 'contains' operator.
Method	`desc`	Produce a `_expression.desc` clause against the parent object.
Method	`distinct`	Produce a `_expression.distinct` clause against the parent object.
Method	`endswith`	Implement the 'endswith' operator.
Method	`ilike`	Implement the `ilike` operator, e.g. case insensitive LIKE.
Method	`in_`	Implement the `in` operator.
Method	`is_`	Implement the `IS` operator.
Method	`is_distinct_from`	Implement the `IS DISTINCT FROM` operator.
Method	`is_not`	Implement the `IS NOT` operator.
Method	`is_not_distinct_from`	Implement the `IS NOT DISTINCT FROM` operator.
Method	`like`	Implement the `like` operator.
Method	`match`	Implements a database-specific 'match' operator.
Method	`not_ilike`	implement the `NOT ILIKE` operator.
Method	`not_in`	implement the `NOT IN` operator.
Method	`not_like`	implement the `NOT LIKE` operator.
Method	`nulls_first`	Produce a `_expression.nulls_first` clause against the parent object.
Method	`nulls_last`	Produce a `_expression.nulls_last` clause against the parent object.
Method	`regexp_match`	Implements a database-specific 'regexp match' operator.
Method	`regexp_replace`	Implements a database-specific 'regexp replace' operator.
Method	`startswith`	Implement the `startswith` operator.
Class Variable	`__slots__`	Undocumented
Class Variable	`timetuple`	Hack, allows datetime objects to be compared on the LHS.

Inherited from Operators (via ColumnElement, ColumnOperators):

Method	`__and__`	Implement the `&` operator.
Method	`__invert__`	Implement the `~` operator.
Method	`__or__`	Implement the `\|` operator.
Method	`bool_op`	Return a custom boolean operator.
Method	`op`	Produce a generic operator function.

Inherited from ClauseElement (via ColumnElement):

Method	`compare`	Compare this `_expression.ClauseElement` to the given `_expression.ClauseElement`.
Method	`compile`	Compile this SQL expression.
Method	`params`	Return a copy with `_expression.bindparam` elements replaced.
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_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	`_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	`bind`	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
Property	`_constructor`	return the 'constructor' for this ClauseElement.
Property	`entity_namespace`	Undocumented

Inherited from SQLRole (via ColumnElement, ClauseElement):

Class Variable	`allows_lambda`	Undocumented
Class Variable	`uses_inspection`	Undocumented

Inherited from SupportsWrappingAnnotations (via ColumnElement, 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 ColumnElement, ClauseElement, SupportsWrappingAnnotations):

Property _annotations_cache_key Undocumented

Inherited from MemoizedHasCacheKey (via ColumnElement, ClauseElement):

Method _generate_cache_key return a cache key.

Inherited from HasCacheKey (via ColumnElement, 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 ColumnElement, ClauseElement):

Method _copy_internals Reassign internal elements to be clones of themselves.

Inherited from Traversible (via ColumnElement, ClauseElement):

Method	`get_children`	Return immediate child `.visitors.Traversible` elements of this `.visitors.Traversible`.
Method	`__class_getitem__`	Undocumented

@classmethod
def _create_asc(cls, column):

Produce an ascending ORDER BY clause element.

e.g.:

from sqlalchemy import asc
stmt = select(users_table).order_by(asc(users_table.c.name))

will produce SQL as:

SELECT id, name FROM user ORDER BY name ASC

The .asc function is a standalone version of the _expression.ColumnElement.asc method available on all SQL expressions, e.g.:

stmt = select(users_table).order_by(users_table.c.name.asc())

See Also

.desc

.nulls_first

.nulls_last

_expression.Select.order_by

Parameters
column	A `_expression.ColumnElement` (e.g. scalar SQL expression) with which to apply the `.asc` operation.

@classmethod
def _create_desc(cls, column):

Produce a descending ORDER BY clause element.

e.g.:

from sqlalchemy import desc

stmt = select(users_table).order_by(desc(users_table.c.name))

will produce SQL as:

SELECT id, name FROM user ORDER BY name DESC

The .desc function is a standalone version of the _expression.ColumnElement.desc method available on all SQL expressions, e.g.:

stmt = select(users_table).order_by(users_table.c.name.desc())

See Also

.asc

.nulls_first

.nulls_last

_expression.Select.order_by

Parameters
column	A `_expression.ColumnElement` (e.g. scalar SQL expression) with which to apply the `.desc` operation.

@classmethod
def _create_distinct(cls, expr):

Produce an column-expression-level unary DISTINCT clause.

This applies the DISTINCT keyword to an individual column expression, and is typically contained within an aggregate function, as in:

from sqlalchemy import distinct, func
stmt = select(func.count(distinct(users_table.c.name)))

The above would produce an expression resembling:

SELECT COUNT(DISTINCT name) FROM user

The .distinct function is also available as a column-level method, e.g. _expression.ColumnElement.distinct, as in:

stmt = select(func.count(users_table.c.name.distinct()))

The .distinct operator is different from the _expression.Select.distinct method of _expression.Select, which produces a SELECT statement with DISTINCT applied to the result set as a whole, e.g. a SELECT DISTINCT expression. See that method for further information.

See Also

_expression.ColumnElement.distinct

_expression.Select.distinct

.func

@classmethod
def _create_nulls_first(cls, column):

Produce the NULLS FIRST modifier for an ORDER BY expression.

.nulls_first is intended to modify the expression produced by .asc or .desc, and indicates how NULL values should be handled when they are encountered during ordering:

from sqlalchemy import desc, nulls_first

stmt = select(users_table).order_by(
    nulls_first(desc(users_table.c.name)))

The SQL expression from the above would resemble:

SELECT id, name FROM user ORDER BY name DESC NULLS FIRST

Like .asc and .desc, .nulls_first is typically invoked from the column expression itself using _expression.ColumnElement.nulls_first, rather than as its standalone function version, as in:

stmt = select(users_table).order_by(
    users_table.c.name.desc().nulls_first())

Changed in version 1.4: .nulls_first is renamed from .nullsfirst in previous releases. The previous name remains available for backwards compatibility.

See Also

.asc

.desc

.nulls_last

_expression.Select.order_by

@classmethod
def _create_nulls_last(cls, column):

Produce the NULLS LAST modifier for an ORDER BY expression.

.nulls_last is intended to modify the expression produced by .asc or .desc, and indicates how NULL values should be handled when they are encountered during ordering:

from sqlalchemy import desc, nulls_last

stmt = select(users_table).order_by(
    nulls_last(desc(users_table.c.name)))

The SQL expression from the above would resemble:

SELECT id, name FROM user ORDER BY name DESC NULLS LAST

Like .asc and .desc, .nulls_last is typically invoked from the column expression itself using _expression.ColumnElement.nulls_last, rather than as its standalone function version, as in:

stmt = select(users_table).order_by(
    users_table.c.name.desc().nulls_last())

Changed in version 1.4: .nulls_last is renamed from .nullslast in previous releases. The previous name remains available for backwards compatibility.

See Also

.asc

.desc

.nulls_first

_expression.Select.order_by

def __init__(self, element, operator=None, modifier=None, type_=None, wraps_column_expression=False):

overridden in sqlalchemy.sql.selectable.Exists, sqlalchemy.sql.elements.AsBoolean

Undocumented

def _negate(self):

overrides sqlalchemy.sql.expression.ColumnElement._negate

overridden in sqlalchemy.sql.elements.AsBoolean

Undocumented

def self_group(self, against=None):

overrides sqlalchemy.sql.expression.ColumnElement.self_group

overridden in sqlalchemy.sql.elements.AsBoolean

Apply a 'grouping' to this _expression.ClauseElement.

This method is overridden by subclasses to return a "grouping" construct, i.e. parenthesis. In particular it's used by "binary" expressions to provide a grouping around themselves when placed into a larger expression, as well as by _expression.select constructs when placed into the FROM clause of another _expression.select. (Note that subqueries should be normally created using the _expression.Select.alias method, as many platforms require nested SELECT statements to be named).

As expressions are composed together, the application of self_group is automatic - end-user code should never need to use this method directly. Note that SQLAlchemy's clause constructs take operator precedence into account - so parenthesis might not be needed, for example, in an expression like x OR (y AND z) - AND takes precedence over OR.

The base self_group method of _expression.ClauseElement just returns self.

__visit_name__: str =

overrides sqlalchemy.sql.expression.ColumnElement.__visit_name__

Undocumented

_traverse_internals =

Undocumented

_propagate_attrs =

overrides sqlalchemy.sql.expression.ClauseElement._propagate_attrs

like annotations, however these propagate outwards liberally as SQL constructs are built, and are set up at construction time.

element =

overridden in sqlalchemy.sql.elements.AsBoolean

Undocumented

modifier =

overridden in sqlalchemy.sql.elements.AsBoolean

Undocumented

operator =

overridden in sqlalchemy.sql.elements.AsBoolean

Undocumented

type =

overrides sqlalchemy.sql.expression.ColumnElement.type

overridden in sqlalchemy.sql.elements.AsBoolean

Undocumented

wraps_column_expression =

overridden in sqlalchemy.sql.elements.AsBoolean

Undocumented

@property
_from_objects =

overrides sqlalchemy.sql.expression.ClauseElement._from_objects

overridden in sqlalchemy.sql.selectable.Exists

Undocumented

@property
_order_by_label_element =

overrides sqlalchemy.sql.expression.ClauseElement._order_by_label_element

Undocumented