class TextClause(roles.DDLConstraintColumnRole, roles.DDLExpressionRole, roles.StatementOptionRole, roles.WhereHavingRole, roles.OrderByRole, roles.FromClauseRole, roles.SelectStatementRole, roles.InElementRole, Generative, Executable, DQLDMLClauseElement, roles.BinaryElementRole[
Represent a literal SQL text fragment. E.g.:: from sqlalchemy import text t = text("SELECT * FROM users") result = connection.execute(t) The :class:`_expression.TextClause` construct is produced using the :func:`_expression.text` function; see that function for full documentation. .. seealso:: :func:`_expression.text`
Method | __and__ |
Undocumented |
Method | __init__ |
Undocumented |
Method | bindparams |
Establish the values and/or types of bound parameters within this :class:`_expression.TextClause` construct. |
Method | columns |
Turn this :class:`_expression.TextClause` object into a :class:`_expression.TextualSelect` object that serves the same role as a SELECT statement. |
Method | self |
Apply a 'grouping' to this :class:`_expression.ClauseElement`. |
Class Variable | __visit |
Undocumented |
Class Variable | key |
Undocumented |
Instance Variable | text |
Undocumented |
Property | comparator |
Undocumented |
Property | type |
Undocumented |
Class Variable | _allow |
Undocumented |
Class Variable | _bind |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _label |
Undocumented |
Class Variable | _render |
Undocumented |
Class Variable | _traverse |
Undocumented |
Instance Variable | _bindparams |
Undocumented |
Property | _hide |
Undocumented |
Property | _is |
Undocumented |
Property | _select |
Undocumented |
Inherited from DDLConstraintColumnRole
:
Class Variable | __slots__ |
Undocumented |
Class Variable | _role |
Undocumented |
Inherited from FromClauseRole
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
):
Class Variable | named |
Undocumented |
Class Variable | _is |
Undocumented |
Inherited from AllowsLambdaRole
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
):
Class Variable | allows |
Undocumented |
Inherited from UsesInspection
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
):
Class Variable | uses |
Undocumented |
Class Variable | _post |
Undocumented |
Inherited from SelectStatementRole
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
):
Method | subquery |
Undocumented |
Inherited from Generative
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
):
Method | _generate |
Undocumented |
Inherited from Executable
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
):
Method | execution |
Set non-SQL options for the statement which take effect during execution. |
Method | get |
Get the non-SQL options which will take effect during execution. |
Method | options |
Apply options to this statement. |
Class Variable | is |
Undocumented |
Class Variable | is |
Undocumented |
Class Variable | is |
Undocumented |
Class Variable | is |
Undocumented |
Class Variable | is |
Undocumented |
Class Variable | is |
Undocumented |
Class Variable | supports |
Undocumented |
Method | _add |
Add a context option to this statement. |
Method | _compile |
Undocumented |
Method | _execute |
Undocumented |
Method | _execute |
Undocumented |
Method | _set |
Assign the compile options to a new value. |
Method | _update |
update the _compile_options with new keys. |
Class Variable | _executable |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _with |
Undocumented |
Class Variable | _with |
Undocumented |
Instance Variable | _compile |
Undocumented |
Instance Variable | _execution |
Undocumented |
Property | _all |
Undocumented |
Property | _effective |
Undocumented |
Inherited from StatementRole
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
):
Property | _propagate |
Undocumented |
Inherited from DQLDMLClauseElement
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
, StatementRole
, ReturnsRowsRole
):
Method | compile |
Compile this SQL expression. |
Method | _compiler |
Return a compiler appropriate for this ClauseElement, given a Dialect. |
Inherited from ClauseElement
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
, StatementRole
, ReturnsRowsRole
, 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 |
Return immediate child :class:`.visitors.HasTraverseInternals` elements of this :class:`.visitors.HasTraverseInternals`. |
Method | params |
Return a copy with :func:`_expression.bindparam` elements replaced. |
Method | unique |
Return a copy with :func:`_expression.bindparam` elements replaced. |
Class Variable | is |
Undocumented |
Class Variable | is |
Undocumented |
Class Variable | negation |
Undocumented |
Property | description |
Undocumented |
Property | entity |
Undocumented |
Method | _clone |
Create a shallow copy of this ClauseElement. |
Method | _cloned |
Return the set consisting all cloned ancestors of this ClauseElement. |
Method | _negate |
Undocumented |
Method | _negate |
a hook to allow the right side of a binary expression to respond to a negation of the binary expression. |
Method | _replace |
Undocumented |
Method | _set |
Undocumented |
Method | _ungroup |
Return this :class:`_expression.ClauseElement` without any groupings. |
Method | _with |
in the context of binary expression, convert the type of this object to the one given. |
Class Variable | _cache |
Undocumented |
Class Variable | _gen |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Property | _constructor |
return the 'constructor' for this ClauseElement. |
Property | _from |
Undocumented |
Property | _order |
Undocumented |
Inherited from SupportsWrappingAnnotations
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
, StatementRole
, ReturnsRowsRole
, DQLDMLClauseElement
, ClauseElement
):
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 |
return a copy of this ClauseElement with annotations replaced by the given dictionary. |
Inherited from SupportsAnnotations
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
, StatementRole
, ReturnsRowsRole
, DQLDMLClauseElement
, ClauseElement
, SupportsWrappingAnnotations
):
Class Variable | proxy |
Undocumented |
Method | _gen |
Undocumented |
Property | _annotations |
Undocumented |
Inherited from MemoizedHasCacheKey
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
, StatementRole
, ReturnsRowsRole
, DQLDMLClauseElement
, ClauseElement
, SupportsWrappingAnnotations
, SupportsAnnotations
):
Method | _generate |
return a cache key. |
Inherited from HasCacheKey
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
, StatementRole
, ReturnsRowsRole
, DQLDMLClauseElement
, ClauseElement
, SupportsWrappingAnnotations
, SupportsAnnotations
, MemoizedHasCacheKey
):
Class Variable | inherit |
Indicate if this :class:`.HasCacheKey` instance should make use of the cache key generation scheme used by its immediate superclass. |
Class Method | _generate |
generate cache key dispatcher for a new class. |
Class Method | _generate |
Undocumented |
Method | _gen |
return an optional cache key. |
Class Variable | _generated |
Undocumented |
Class Variable | _hierarchy |
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 |
Undocumented |
Inherited from HasCopyInternals
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
, StatementRole
, ReturnsRowsRole
, DQLDMLClauseElement
, ClauseElement
, SupportsWrappingAnnotations
, SupportsAnnotations
, MemoizedHasCacheKey
, HasCacheKey
):
Method | _copy |
Reassign internal elements to be clones of themselves. |
Inherited from CompilerElement
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
, StatementRole
, ReturnsRowsRole
, DQLDMLClauseElement
, ClauseElement
, SupportsWrappingAnnotations
, SupportsAnnotations
, MemoizedHasCacheKey
, HasCacheKey
, HasCopyInternals
, ExternallyTraversible
, HasTraverseInternals
):
Method | __str__ |
Undocumented |
Class Variable | stringify |
Undocumented |
Inherited from Visitable
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
, StatementRole
, ReturnsRowsRole
, DQLDMLClauseElement
, ClauseElement
, SupportsWrappingAnnotations
, SupportsAnnotations
, MemoizedHasCacheKey
, HasCacheKey
, HasCopyInternals
, ExternallyTraversible
, HasTraverseInternals
, CompilerElement
):
Method | __class |
Undocumented |
Method | __init |
Undocumented |
Class Method | _generate |
Undocumented |
Method | _compiler |
Undocumented |
Class Variable | _original |
Undocumented |
Inherited from ExpressionElementRole
(via DDLConstraintColumnRole
, DDLExpressionRole
, StatementOptionRole
, WhereHavingRole
, OnClauseRole
, OrderByRole
, FromClauseRole
, ColumnsClauseRole
, JoinTargetRole
, AllowsLambdaRole
, ByOfRole
, UsesInspection
, ColumnListRole
, StructuralRole
, SelectStatementRole
, InElementRole
, Generative
, Executable
, StatementRole
, ReturnsRowsRole
, DQLDMLClauseElement
, ClauseElement
, SupportsWrappingAnnotations
, SupportsAnnotations
, MemoizedHasCacheKey
, HasCacheKey
, HasCopyInternals
, ExternallyTraversible
, HasTraverseInternals
, CompilerElement
, Visitable
, BinaryElementRole
):
Method | label |
Undocumented |
def bindparams(self, *binds:
BindParameter[ Any]
, **names_to_values: Any
) -> Self
:
(source)
¶
Establish the values and/or types of bound parameters within this :class:`_expression.TextClause` construct. Given a text construct such as:: from sqlalchemy import text stmt = text("SELECT id, name FROM user WHERE name=:name " "AND timestamp=:timestamp") the :meth:`_expression.TextClause.bindparams` method can be used to establish the initial value of ``:name`` and ``:timestamp``, using simple keyword arguments:: stmt = stmt.bindparams(name='jack', timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5)) Where above, new :class:`.BindParameter` objects will be generated with the names ``name`` and ``timestamp``, and values of ``jack`` and ``datetime.datetime(2012, 10, 8, 15, 12, 5)``, respectively. The types will be inferred from the values given, in this case :class:`.String` and :class:`.DateTime`. When specific typing behavior is needed, the positional ``*binds`` argument can be used in which to specify :func:`.bindparam` constructs directly. These constructs must include at least the ``key`` argument, then an optional value and type:: from sqlalchemy import bindparam stmt = stmt.bindparams( bindparam('name', value='jack', type_=String), bindparam('timestamp', type_=DateTime) ) Above, we specified the type of :class:`.DateTime` for the ``timestamp`` bind, and the type of :class:`.String` for the ``name`` bind. In the case of ``name`` we also set the default value of ``"jack"``. Additional bound parameters can be supplied at statement execution time, e.g.:: result = connection.execute(stmt, timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5)) The :meth:`_expression.TextClause.bindparams` method can be called repeatedly, where it will re-use existing :class:`.BindParameter` objects to add new information. For example, we can call :meth:`_expression.TextClause.bindparams` first with typing information, and a second time with value information, and it will be combined:: stmt = text("SELECT id, name FROM user WHERE name=:name " "AND timestamp=:timestamp") stmt = stmt.bindparams( bindparam('name', type_=String), bindparam('timestamp', type_=DateTime) ) stmt = stmt.bindparams( name='jack', timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5) ) The :meth:`_expression.TextClause.bindparams` method also supports the concept of **unique** bound parameters. These are parameters that are "uniquified" on name at statement compilation time, so that multiple :func:`_expression.text` constructs may be combined together without the names conflicting. To use this feature, specify the :paramref:`.BindParameter.unique` flag on each :func:`.bindparam` object:: stmt1 = text("select id from table where name=:name").bindparams( bindparam("name", value='name1', unique=True) ) stmt2 = text("select id from table where name=:name").bindparams( bindparam("name", value='name2', unique=True) ) union = union_all( stmt1.columns(column("id")), stmt2.columns(column("id")) ) The above statement will render as:: select id from table where name=:name_1 UNION ALL select id from table where name=:name_2 .. versionadded:: 1.3.11 Added support for the :paramref:`.BindParameter.unique` flag to work with :func:`_expression.text` constructs.
def columns(self, *cols:
_ColumnExpressionArgument[ Any]
, **types: TypeEngine[ Any]
) -> TextualSelect
:
(source)
¶
Turn this :class:`_expression.TextClause` object into a :class:`_expression.TextualSelect` object that serves the same role as a SELECT statement. The :class:`_expression.TextualSelect` is part of the :class:`_expression.SelectBase` hierarchy and can be embedded into another statement by using the :meth:`_expression.TextualSelect.subquery` method to produce a :class:`.Subquery` object, which can then be SELECTed from. This function essentially bridges the gap between an entirely textual SELECT statement and the SQL expression language concept of a "selectable":: from sqlalchemy.sql import column, text stmt = text("SELECT id, name FROM some_table") stmt = stmt.columns(column('id'), column('name')).subquery('st') stmt = select(mytable).\ select_from( mytable.join(stmt, mytable.c.name == stmt.c.name) ).where(stmt.c.id > 5) Above, we pass a series of :func:`_expression.column` elements to the :meth:`_expression.TextClause.columns` method positionally. These :func:`_expression.column` elements now become first class elements upon the :attr:`_expression.TextualSelect.selected_columns` column collection, which then become part of the :attr:`.Subquery.c` collection after :meth:`_expression.TextualSelect.subquery` is invoked. The column expressions we pass to :meth:`_expression.TextClause.columns` may also be typed; when we do so, these :class:`.TypeEngine` objects become the effective return type of the column, so that SQLAlchemy's result-set-processing systems may be used on the return values. This is often needed for types such as date or boolean types, as well as for unicode processing on some dialect configurations:: stmt = text("SELECT id, name, timestamp FROM some_table") stmt = stmt.columns( column('id', Integer), column('name', Unicode), column('timestamp', DateTime) ) for id, name, timestamp in connection.execute(stmt): print(id, name, timestamp) As a shortcut to the above syntax, keyword arguments referring to types alone may be used, if only type conversion is needed:: stmt = text("SELECT id, name, timestamp FROM some_table") stmt = stmt.columns( id=Integer, name=Unicode, timestamp=DateTime ) for id, name, timestamp in connection.execute(stmt): print(id, name, timestamp) The positional form of :meth:`_expression.TextClause.columns` also provides the unique feature of **positional column targeting**, which is particularly useful when using the ORM with complex textual queries. If we specify the columns from our model to :meth:`_expression.TextClause.columns`, the result set will match to those columns positionally, meaning the name or origin of the column in the textual SQL doesn't matter:: stmt = text("SELECT users.id, addresses.id, users.id, " "users.name, addresses.email_address AS email " "FROM users JOIN addresses ON users.id=addresses.user_id " "WHERE users.id = 1").columns( User.id, Address.id, Address.user_id, User.name, Address.email_address ) query = session.query(User).from_statement(stmt).options( contains_eager(User.addresses)) .. versionadded:: 1.1 the :meth:`_expression.TextClause.columns` method now offers positional column targeting in the result set when the column expressions are passed purely positionally. The :meth:`_expression.TextClause.columns` method provides a direct route to calling :meth:`_expression.FromClause.subquery` as well as :meth:`_expression.SelectBase.cte` against a textual SELECT statement:: stmt = stmt.columns(id=Integer, name=String).cte('st') stmt = select(sometable).where(sometable.c.id == stmt.c.id) :param \*cols: A series of :class:`_expression.ColumnElement` objects, typically :class:`_schema.Column` objects from a :class:`_schema.Table` or ORM level column-mapped attributes, representing a set of columns that this textual string will SELECT from. :param \**types: A mapping of string names to :class:`.TypeEngine` type objects indicating the datatypes to use for names that are SELECTed from the textual string. Prefer to use the ``*cols`` argument as it also indicates positional ordering.
Apply a 'grouping' to this :class:`_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 :func:`_expression.select` constructs when placed into the FROM clause of another :func:`_expression.select`. (Note that subqueries should be normally created using the :meth:`_expression.Select.alias` method, as many platforms require nested SELECT statements to be named). As expressions are composed together, the application of :meth:`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 :meth:`self_group` method of :class:`_expression.ClauseElement` just returns self.